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.
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.
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]];
}
}