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 or back camera should be started. This can be set by using WTWTArchitectStartupConfiguration.captureDevicePosition 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 WTArchitectStartupConfiguration.captureDeviceFocusMode 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 the specified manual focus distance.

Manual Camera Focus

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 usingWTArchitectStartupConfiguration.captureDeviceFocusDistance or AR.hardware.camera.focusDistance.

Camera Resolution

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

Recommendations Geo Image Tracking Extended Tracking Cloud Recognition Instant Tracking
WTCaptureDeviceResolution 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 Frame Rate

The camera frame rate can be set to either 30 or 60 fps. If 60 fps is selected the camera resolution may be changed for the 60 fps to be possible.

The first supported combination is used by the SDK:

  • FullHD 60 fps
  • HD 60 fps
  • SD 60 fps
  • FullHD 30 fps
  • HD 30 fps
  • SD 30 fps

It can be set by using WTArchitectStartupConfiguration.targetFrameRate.

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 first 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 the WTStartupConfiguration object provided in the -start:completion: method. The first block that is passed to the -start:completion method provides an already pre configured startup configuration object which can be used to change any default values. Before the SDK starts rendering, the object is used to determine which settings are overwritten. An example implementation looks like the following:

[self.architectView start:^(WTStartupConfiguration *configuration) {
    configuration.captureDevicePosition = AVCaptureDevicePositionFront; // The front camera is used when the SDK starts
} completion:^(BOOL isRunning, NSError *error) {
    if ( !isRunning )
    {
        NSLog(@"Wikitude SDK is not started. Reason: %@", [error localizedDescription]);
    }            
}];

The second block can be used to react on any errors that occurred during startup. It provides a BOOL reflecting the running state and a NSError object in case the SDK does not run

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.