Hardware Control

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 WTNativeStartupConfiguration.captureDevicePosition or WTCaptureDeviceManager.activeCaptureDevicePosition.

Camera Focus Mode

The camera focus mode defines which focus mode is used internally by the camera. It can be set by using WTNativeStartupConfiguration.captureDeviceFocusMode or WTCaptureDeviceManager.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 using WTNativeStartupConfiguration.captureDeviceFocusDistance or WTCaptureDeviceManager.focusDistance.

Camera Resolution

It can be set by using WTNativeStartupConfiguration.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 WTNativeStartupConfiguration.targetFrameRate.

Camera Zoom

Digital zoom can be controlled by using WTCaptureDeviceManager.zoomLevel. To get the maximum zoom level use WTCaptureDeviceManager.maxZoomLevel.

Flashlight

The flashlight can be turned on and off by using WTCaptureDeviceManager.torchMode.

Focus at point of interest

The camera focus point of intereest can be changed using [WTCaptureDeviceManager focusAtPointOfInterest:]. Specifying a custom focus point of interest might change the focus mode if it's not Once already.

The parameter given to this method call is a coordinate in screen points at which the underlying camera should focus at. The range is from 0/0 to screen.width/screen.height. The actual values can either be choosen manually or received through the usage of a e.g. UIGestureRecognizer subclass or overriding the UIResponder methods -touchesBegan:withEvent:, -touchesMoved:withEvent:, -touchesEnded:withEvent: and converting the given UIToch objects through the UIView method -locationInView: in screen points. Device orientation changes are considered in the internal SDK implementation.

Expose at point of interest

The camera exposure point of interest can be changed using [WTCaptureDeviceManager exposeAtPointOfInterest:]. Specifying a custom exposure point of interest might change the exposure mode if it's not Once already.

Camera Controls

The WTCaptureDeviceManager allows you to change capture device specific settings during an active capture session. It lets you change e.g.

* the capture device position
* the capture device focus mode
* the capture device focus distance
* the capture device zoom level
* the point of interest at which the camera should focus at
* the point of interest at which the camera should expose at

A valid pointer to a WTCaptureDeviceManager object can be retrieved from the WTWikitudeNativeSDK method -captureDeviceManager. Please note that this pointer is only valid if the native SDK is running. If the SDK is currently stopped, changes for the capture device are done using the WTStartupConfiguration object that is passed as argument to the startupHandler when calling -start:completion:.

The sample uses a UIPickerView to let the user select between different camera specific values. This UIPickerView is added to the view hierarchy in the main storyboards camera scene. By default, the picker view is placed behind the OpenGL ES 2 view, so that it is not visible. To show the picker view, the bottom OpenGL ES 2 view constraint is modified and animated, if a button is touched, to unveil the picker view. A standard iOS SDK UIView animation is used to do so. Please refer to the WTCameraControlsViewController -handleCameraControlsPresentation method.

The connection between the UIPickerView and WTCaptureDeviceManager is done by a custom class called WTCameraControlsModel and its delegate object (Which is in this case WTCameraControlsViewController). This custom class WTCameraControlsModel implements the UIPickerView data source and delegate protocol and uses its custom delegate object to retrieve current camera specific values or exposes newly selected values from the picker view. Implementation details of WTCameraControlsModel are not discussed in this guide as it only handles UIKit related functionality. The following snippets shows the previously mentioned object connection. All following snippets can be found in the WTCameraControlsViewController class.

self.cameraControlsPickerModel = [[WTCameraControlsModel alloc] init];
self.cameraControlsPickerModel.delegate = self;
self.cameraControlPicker.dataSource = _cameraControlsPickerModel;
self.cameraControlPicker.delegate = _cameraControlsPickerModel;

The camera controls model knows internally about all possible camera settings and uses these information to load the picker view. Once the picker is loaded and the user selects a different value, the camera controls model delegate is used to propagate the value change. Since the camera controls view controller implements this delegate protocol and also holds a reference to the Wikitude Native SDK, which by itself provides access to the capture device manager), the view controller sets the appropriate capture device value when this camera controls model delegate is called. The following snippet demonstrates this for the capture device position:

- (void)cameraControlsModel:(WTCameraControlsModel *)cameraControlsModel didSelectCameraPosition:(AVCaptureDevicePosition)activeCameraPosition
{
    if ( [self.wikitudeSDK captureDeviceManager] ) {
        [[self.wikitudeSDK captureDeviceManager] setActiveCaptureDevicePosition:activeCameraPosition];
    }
}

Please note that there is a nil check when [self.wikitudeSDK captureDeviceManager] is called. This is because the Wikitude Native SDK could be paused when the picker changes one of its values.

Every time the picker becomes visible again, the camera controls model asks through its delegate object which capture device settings are currently active. The following snippet again demonstrates this for the currently active capture device position.

- (AVCaptureDevicePosition)currentlyActiveCameraPositionForCameraControlsModel:(WTCameraControlsModel *)cameraControlsModel
{
    return [[self.wikitudeSDK captureDeviceManager] activeCaptureDevicePosition];
}

Focus and exposure point of interest are not controlled through UI elements but user input. The example view controller implements the UIResponder method -:touchesEnded:withEvent: and uses the UIView method -locationInView: to convert the UITouch location into view/screen coordinates. This converted point is then given to the Wikitude SDK API.

The following listening shows such an implementation:

- (void)touchesEnded:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event
{
    for ( UITouch *touch in touches )
    {
        [[self.wikitudeSDK captureDeviceManager] focusAtPointOfInterest:[touch locationInView:self.view]];
        [[self.wikitudeSDK captureDeviceManager] exposeAtPointOfInterest:[touch locationInView:self.view]];
    }
}

Documentation

Wikitude SDK iOS Native API