Concepts#
Camera 1#
Camera1 peripherals are used like any other peripheral in GroundSdk to monitor and change settings and to trigger specific actions.
Camera parameters and actions are accessible through settings organized by features:
Feature |
Description |
Peripheral Field |
Type |
---|---|---|---|
Camera Mode |
Switch between photo capture and video recording modes |
modeSetting |
CameraModeSetting |
Photo |
Configure photo mode, format and file format parameters |
photoSettings |
CameraPhotoSettings |
Monitor photo function state |
photoState |
CameraPhotoState |
|
Video Recording |
Configure recording mode, resolution and framerate parameters |
recordingSettings |
CameraRecordingSettings |
Auto start and stop recording |
autoRecordSetting |
BoolSetting |
|
Monitor recording function state |
recordingState |
CameraRecordingState |
|
Exposure |
Configure exposure mode, shutter speed, iso sensitivity and maximum iso sensitivity |
exposureSettings |
CameraExposureSettings |
Exposure lock |
exposureLock |
CameraExposureLock |
|
EV (Exposure Value) compensation |
exposureCompensationSetting |
CameraExposureCompensationSetting |
|
White balance |
Configure white balance mode and temperatures |
whiteBalanceSettings |
CameraWhiteBalanceSettings |
White balance lock |
whiteBalanceLock |
CameraWhiteBalanceLock |
|
HDR |
Configure High Dynamic Range |
hdrSetting |
BoolSetting |
Image styles |
Set image style and customize its parameters |
styleSettings |
CameraStyleSettings |
Zoom |
Zoom control |
zoom |
CameraZoom |
Alignment |
Configure camera alignment |
alignment |
CameraAlignment |
With Camera1 peripheral when the user changes the value of a the setting, this value is immediately sent to the drone, if the drone is connected.
Camera 2#
Camera2 introduces the new concept of sub-components and a new way to configure camera parameters.
Sub-components are provided by the camera peripheral. They are used to perform some specific actions and monitor some specific information. For instance, there is a sub-component to start and stop photo capture and another sub-component to monitor photo capture progress. The user can register a listener to get notified every time a sub-component changes.
The camera peripheral provides a single interface Camera2Config
that is used to monitor camera configuration.
The camera configuration groups all camera parameters.
This Camera2Config interface comes with a configuration editor Camera2Editor that is used to modify the configuration. With this configuration editor, the user can modify multiple camera parameters locally on application side before sending the new configuration to the drone. The configuration editor ensures the consistency of parameters between them before sending them to the drone. This mechanism reduces transactions between the application and the drone and simplifies management of parameters consistency by the application.
This is a major difference with Camera1 API. Unlike Camera1, when a configuration parameter is modified by the user,
the new configuration is not sent immediately. It is only sent when the user calls the method Camera2Editor.commit()
.
The following table shows camera2 features and the corresponding configuration parameters and sub-components:
Feature |
Description |
Configuration Parameter(s) |
Sub-components |
---|---|---|---|
Camera Mode |
Switch between photo capture and video recording modes |
mode |
|
Photo |
Configure photo capture |
photoMode, photoDynamicRange, photoResolution, photoFormat, photoFileFormat, photoBracketing, photoBurst, photoTimelapseInterval, photoGpslapseInterval, photoStreamingMode, photoDigitalSignature |
|
Start/stop photo capture and monitor photo capture state |
Camera2Components.photoCapture |
||
Monitor remaining time or distance before next capture |
Camera2Components.photoProgressIndicator |
||
Video Recording |
Configure video recording |
videoRecordingMode, videoRecordingDynamicRange, videoRecordingCodec, videoRecordingResolution, videoRecordingFramerate, videoRecordingBitrate, videoRecordingHyperlapse |
|
Audio recording |
audioRecordingMode |
||
Auto start and stop recording and monitor recording state |
autoRecordMode |
||
Start/stop recording |
Camera2Components.recording |
||
Streaming |
Configure video stream |
streamingMode, streamingCodec |
|
Exposure |
Configure exposure |
exposureMode, maximumIsoSensitivity, isoSensitivity, shutterSpeed, exposureCompensation, autoExposureMeteringMode |
|
Exposure lock |
Camera2Components.exposureLock |
||
Monitor effective exposure |
Camera2Components.exposureIndicator |
||
White balance |
Configure white balance balance |
whiteBalanceMode, whiteBalanceTemperature |
|
White balance lock |
Camera2Components.whiteBalanceLock |
||
Image styles |
Configure image style and its parameters |
imageStyle, imageContrast, imageSaturation, imageSharpness |
|
Zoom |
Configure zoom |
zoomMaxSpeed, zoomVelocityControlQualityMode |
|
Control zoom |
Camera2Components.zoom |
||
Alignment |
Configure camera alignment |
alignmentOffsetPitch, alignmentOffsetRoll, alignmentOffsetYaw |
|
Storage |
Configure media storage |
storagePolicy |
|
Metadata |
Define custom fields saved in media metadata |
Camera2Components.mediaMetadata |
Sub-components#
Components are accessed with the method getComponent()
.
A listener can be passed to this method to get notified every time the component changes.
// get reference to exposureLock component
var exposureLockRef = camera.getComponent(Camera2Components.exposureLock) { exposureLock in
// closure called at every component change
if let exposureLock = exposureLock {
print("ExposureLock mode: \(exposureLock.mode)")
} else {
print("ExposureLock unavailable")
}
}
Important: The peripheral listener is not notified when a sub-component changes. Therefore, listeners on the sub-components have to be registered to get notified of sub-components changes.
Configuration#
All camera parameters are accessible through Camera2config
protocol.
Supported parameters are listed in Camera2Config.supportedParams
.
Each parameter has an identifier Camera2ParamId
that is used to access its value and supported values.
The current camera configuration can be accessed as follows:
// current exposure compensation value
let value = camera.config[Camera2Params.exposureCompensation]?.value
// exposure compensation values supported by the drone
let overallSupportedValues = camera.config[Camera2Params.exposureCompensation]?.overallSupportedValues
// exposure compensation values available in the current configuration
let currentSupportedValues = camera.config[Camera2Params.exposureCompensation]?.currentSupportedValues
print("Exposure compensation \(value) \(overallSupportedValues) \(currentSupportedValues)")
The camera configuration can be modified with Camera2Editor
.
The camera configuration can be edited starting from an empty configuration:
let editor = camera.config.edit(fromScratch: true)
It can also be edited starting from current configuration:
let editor = camera.config.edit(fromScratch: false)
The value of a parameter can be changed as follows:
editor[Camera2Params.exposureCompensation]?.value = .ev1_00
Trying to set a parameter value at a value not contained in overallSupportedValues
will have no effect.
The configuration editor ensures the configuration consistency. It ensures that configuration parameters
are not conflicting between them.
So when setting a parameter value at a value not contained in currentSupportedValues
,
the configuration editor will unset other parameters conflicting with the new value.
The configuration can automatically complete missing parameters in a configuration with method autoComplete()
:
editor.autoComplete()
The configuration is sent to the drone when method commit()
is called:
editor.commit()
Note that only a complete configuration can be sent to the drone.
Below, a sample code to modify exposure compensation value:
// start camera configuration edition starting from current configuration;
// when starting from current configuration, the edited configuration is
// considered as `complete`
let editor = camera.config.edit(fromScratch: false)
guard let exposureCompensation = editor[Camera2Params.exposureCompensation] else {
print("exposureCompensation parameter not available")
return
}
// new exposure compensation value to apply
let newValue = Camera2EvCompensation.ev1_00
// verify that the camera supports the new value
if !exposureCompensation.overallSupportedValues.contains(newValue) {
print("exposureCompensation value not supported by the drone: \(newValue)")
}
// verify that the new value is available in the currently edited configuration
else if exposureCompensation.currentSupportedValues.contains(newValue) {
// the new value is available in the currently edited configuration,
// meaning that the new value does not conflict with other parameters
// apply new value, this will not change other parameters as there is no
// conficting parameter
exposureCompensation.value = newValue
// at this point, the edited configuration is `complete`, so no need to
// call `autoComplete` method
// send new configuration to drone
editor.commit()
} else {
// the new value is not available in the currently edited configuration,
// meaning that the new value conflicts with some other parameters
// apply new value, this will unset conflicting parameters,
// therefore the edited configuration will not be `complete` anymore
exposureCompensation.value = newValue
// complete configuration, by automatically setting missing parameters values
editor.autoComplete()
// send new configuration to drone
editor.commit()
}