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()
}