Documentation

Hardware control

The Hardware control example series will show how you can use the hardware API. The example is split into four different parts which illustrate the different features of the API, both native and Javascript. At the end of the series, you will have a complete overview of the API.

Camera Settings

The first part of the series will present a general overview of what is possible with the Wikitude SDK.

Camera Position

The camera position defines if the front, back or default camera should be started. This can be set by using ArchitectStartupConfiguration.setCameraPosition or AR.hardware.camera.position.

Camera Focus Mode

The camera focus mode defines which focus mode is used internally by the camera. It can be set by using ArchitectStartupConfiguration.setCameraFocusMode or AR.hardware.camera.focusMode. The camera focus mode can be one of the following modes:

  • Continuous: Is the default if the device supports it, in this mode the camera will try to refocus automatically when necessary.
  • Once: Can force the camera to refocus once on the current view. If you need to change focus you can set this value again. Each time the value ONCE is set, the camera tries to focus on the current scene again
  • OFF: Is disabling auto focus and will set the focus to infinity focus if not specified by the manual focus distance. This mode is a prerequisite for setting the manual focus distance.

Manual Camera Focus

The manual camera focus allows to set the focus manually and is only available if the camera2 is enabled in the ArchitectStartupConfiguration and the device supports it. To check if manual focus is available use AR.hardware.camera.manualFocusAvailable. The focus distance ranges from 0 to 1 where 0 is closest focus possible and 1 is at infinity focus. It can be set by usingArchitectStartupConfiguration.setCameraManualFocusDistance or AR.hardware.camera.focusDistance.

Camera2 API usage

The SDK can use either the legacy camera API (deprecated Google sind Android 5.0+) or the new camera2 API. The camera2 API enables a lot more manual camera features like the manual focus. Since the camera2 API is not fully working on some devices it is disabled by default and can be enabled by usingNativeStartupConfiguration.setCamera2Enabled.

Exclusive camera2 features currently are:

  • Manual Focus

Camera Resolution

It can be set by using ArchitectStartupConfiguration.setCameraResolution and not be changed during runtime. The recommended values are the following:

Recommendations Geo Image Tracking Extended Tracking Cloud Recognition Instant Tracking
CameraSettings.CameraResolution AUTO AUTO SD_640x480 SD_640x480 SD_640x480

This setting will only be used on armv8 devices, all other architectures will default to SD_640x480 .

Camera Zoom

Digital zoom can be controlled by using AR.hardware.camera.zoom.

Flashlight

The flashlight can be turned on and off by using AR.hardware.camera.flashlight.

Front Camera

The second part of the series will present a set of POIs in the 8 compass directions using the front camera of the device, if available. The POIs are loaded from a local JSON file, using a different offset value for each POI to put them around the user in different directions.

The example Retrieving POI Data already explained how to load POI data from a local resource and display them in the augmented reality view.

This example shows how to initialize the ARchitectView using the front camera of the device.

The SDK can be configured to start with an active front camera using a ArchitectStartupConfiguration as a parameter to the onCreate() method. An example implementation looks like the following:

     @Override
    public void onCreate( final Bundle savedInstanceState ) {
        super.onCreate( savedInstanceState );

        final ArchitectStartupConfiguration config = new ArchitectStartupConfiguration();
        config.setLicenseKey(licenseKey);
        config.setFeatures(ArchitectStartupConfiguration.Features.Geo);
        config.setCameraPosition(ArchitectStartupConfiguration.CameraPosition.FRONT);
        config.setCameraResolution(CameraSettings.CameraResolution.AUTO);

        this.architectView.onCreate( config );
    }

If the device has no front camera, the default system camera will be used.

Camera Switching

The second part uses the same POIs, but starts the augmented reality view with the default configuration.

The user can then switch between front facing and rear camera by pressing the button "Switch Camera". The button is defined in index.html and calls World.switchCam() on click:

    /*
     * Switch between front and back camera
     */
    switchCam: function switchCamFn() {
        if (AR.hardware.camera.position == AR.CONST.CAMERA_POSITION.FRONT) {
            AR.hardware.camera.position = AR.CONST.CAMERA_POSITION.BACK
        } else {
            AR.hardware.camera.position = AR.CONST.CAMERA_POSITION.FRONT            
        }
    }
view source code on GitHub

The Marker constructor function also sets the mirrored flag of the marker title and description. See marker.js for details about how this is implemented: the odd-numbered POIs have mirrored titles, and even-numbered POIs have mirrored descriptions.

This flag has no effect when viewing the AR scene through the rear camera. When using the front facing camera, all objects are mirrored like the camera image, except Label and HTMLDrawable object. By setting the mirrored flag you can override the default behaviour.

Advanced Features

The third example shows how to use the remaining functionality of the hardware access API.

By pressing the button "Camera Info" the user can obtain information about which hardware feature are available on the device camera:

    // display camera info panel
    showCamInfo: function showCamInfoFn() {
        // update panel values
        var features = AR.hardware.camera.features;

        $("#camera-focus-modes").html(features.focusModes.join());
        $("#camera-positions").html(features.positions.join());
        $("#camera-zoom-max").html(Math.round(features.zoomRange.max));

        // show panel
        $("#panel-caminfo").panel("open", 123);
    }    
view source code on GitHub

When the user presses the button "Camera Control" another panel is shown, with more controls available to the user.

  • Zoom initially set to 1: the zoom factor ranges between 1 and a maximum value, which depends on the device capabilities.
  • Autofocus: when checked, the continuous autofocus function of the camera is active. By disabling it, the camera locks the focus on the currently framed object.
  • Manual Focus Distance: initially set to 0: the manual focus distance ranges between 0.0 and 1.0.
  • Flashlight: by checking this box, the user can turn the flashlight on and off.

To use the camera zoom, you can read or change the value of AR.hardware.camera.zoom:

    // updates values shown in "control panel"
    updateRangeValues: function updateRangeValuesFn() {

        // get current slider value (0..100);
        var slider_value = $("#panel-zoom-range").val();

        // zoom level (1 up to max available)
        var maxRangeValue = Math.round((AR.hardware.camera.features.zoomRange.max - 1) * (slider_value / 100) + 1);

        // update UI labels accordingly
        $("#panel-zoom-value").html(maxRangeValue);

        AR.hardware.camera.zoom = maxRangeValue;
    },
view source code on GitHub

The value of AR.hardware.camera.focusMode represents the focusing mode of the camera and can be set to AR.CONST.CAMERA_FOCUS_MODE.CONTINUOUS or AR.CONST.CAMERA_FOCUS_MODE.ONCE.

Continuous mode is the default if the device supports it, in this mode the camera will try to refocus automatically when necessary.

By setting the focus mode to ONCE you can force the camera to refocus once on the current view. If you need to change focus you can set this value again. Each time the value ONCE is set, the camera tries to focus on the current scene again:

    // updates values shown in "control panel"
    updateFocusMode: function updateFocusModeFn() {

        // get current checkbox status
        var check_value = $("#panel-focus-auto").is(":checked");

        if (check_value) {
            AR.hardware.camera.focusMode = AR.CONST.CAMERA_FOCUS_MODE.CONTINUOUS;
        } else {
            AR.hardware.camera.focusMode = AR.CONST.CAMERA_FOCUS_MODE.ONCE;
        }
    },
view source code on GitHub

To use the manual focus distance, you can read or change the value of AR.hardware.camera.manualfocusdistance:

AR.hardware.camera.manualFocusDistance = parseInt(slider_value) / 100;

Not every device supports this feature, so you can use AR.hardware.camera.manualFocusAvailable to find out if manual focus is available. In our sample we use this to hide the slider if necessary.

if (!AR.hardware.camera.manualFocusAvailable) {
    document.getElementById("panel-focus-distance").style.display = "none";
}
view source code on GitHub

To access the flashlight, you can read or change the value of AR.hardware.camera.flashlight:

    // updates values shown in "control panel"
    updateFlashlight: function updateFlashlightFn() {

        // get current checkbox status
        var check_value = $("#panel-flashlight").is(":checked");
        AR.hardware.camera.flashlight = check_value;
    },
view source code on GitHub

Functionality that is not directly visible through UI controls are touch to focus and touch to expose. This example is setup to use the AR.hardware.camera.setFocusPointOfInterest and AR.hardware.camera.setExposurePointOfInterest APIs to define focus and exposure point of interest for the camera based on user input. The most likely use case of this API is to connect it with the AR.context.onScreenClick callback and use the provided screen coordinate to refocus or reexpose the camera at this coordinate.

AR.context.onScreenClick = function (touchLocation) {
    AR.hardware.camera.setFocusPointOfInterest(touchLocation);
    AR.hardware.camera.setExposurePointOfInterest(touchLocation);
}

It would also be possible to specify the coordinate manually, meaning not to connect it to an actual user interaction.