Skip to navigation

Camera Controls

Open in ClaudeOpen in ChatGPT

Several camera settings can be tuned using ZED Explorer or the API.

ZED Explorer

Selecting a Resolution

On stereo cameras, the left and right video frames are synchronized and streamed as a single uncompressed video frame in a side-by-side format.

Video ModeOutput Resolution (side by side)Frame Rate (fps)Field of View
HD2K4416x124215Wide
HD10803840x108030, 15Wide
HD7202560x72060, 30, 15Extra Wide
VGA1344x376100, 60, 30, 15Extra Wide

You can change video resolution and frame rate in ZED Explorer or use the API. To choose the frame rate that minimizes latency, see Frame Rate and Latency.

Selecting an Output View

The ZED outputs images in different formats. Using retrieveImage() with a value of the sl::VIEW enum, you can select the image and its pixel format: BGRA (4 channels, 32 bits per pixel, the default), BGR (3 channels, 24 bits per pixel), grayscale (1 channel, 8 bits per pixel) or NV12 (YUV 4:2:0 semi-planar):

ImageBGRA (32 bits)BGR (24 bits)Grayscale (8 bits)NV12
Left rectifiedLEFT, LEFT_BGRALEFT_BGRLEFT_GRAYLEFT_NV12
Right rectifiedRIGHT, RIGHT_BGRARIGHT_BGRRIGHT_GRAYRIGHT_NV12
Left unrectifiedLEFT_UNRECTIFIED, LEFT_UNRECTIFIED_BGRALEFT_UNRECTIFIED_BGRLEFT_UNRECTIFIED_GRAYLEFT_NV12_UNRECTIFIED
Right unrectifiedRIGHT_UNRECTIFIED, RIGHT_UNRECTIFIED_BGRARIGHT_UNRECTIFIED_BGRRIGHT_UNRECTIFIED_GRAYRIGHT_NV12_UNRECTIFIED
Left and right rectified, side by sideSIDE_BY_SIDE, SIDE_BY_SIDE_BGRASIDE_BY_SIDE_BGRSIDE_BY_SIDE_GRAY-
Left and right unrectified, side by sideSIDE_BY_SIDE_UNRECTIFIED_BGRASIDE_BY_SIDE_UNRECTIFIED_BGRSIDE_BY_SIDE_UNRECTIFIED_GRAY-
Depth map renderingDEPTH, DEPTH_BGRADEPTH_BGRDEPTH_GRAY-
Depth confidence map renderingCONFIDENCE, CONFIDENCE_BGRACONFIDENCE_BGRCONFIDENCE_GRAY-
Normals map renderingNORMALS, NORMALS_BGRANORMALS_BGRNORMALS_GRAY-
Depth map rendering, aligned on the right sensorDEPTH_RIGHT, DEPTH_RIGHT_BGRADEPTH_RIGHT_BGRDEPTH_RIGHT_GRAY-
Normals map rendering, aligned on the right sensorNORMALS_RIGHT, NORMALS_RIGHT_BGRANORMALS_RIGHT_BGRNORMALS_RIGHT_GRAY-

The two names in the BGRA column are aliases: LEFT_BGRA returns the same image as LEFT. The side by side images have twice the width of a single image.

The depth, confidence and normals views are renderings intended for display only and require depth computation to be enabled. To access the underlying measurement values, use retrieveMeasure() with the sl::MEASURE enum instead. Monocular cameras (ZED X One) do not provide depth-related views.

The NV12 views are available only on NVIDIA® Jetson™ platforms with GMSL2 cameras. The unrectified NV12 views return the native resolution image as a zero-copy GPU buffer, without resizing. The rectified NV12 views support resizing to even dimensions, in both CPU and GPU memory. For direct access to the capture buffers, see the raw NV12 buffer access guides for the ZED X and the ZED X One.

For more information on how to select these views using the API, see Image Capture.

Adjusting Camera Settings

The ZED camera features an ISP (Image Signal Processor) module that performs various image processing algorithms on raw images captured by the CMOS image sensors. Several parameters of the ISP can be adjusted directly from the ZED Explorer application or through the ZED SDK with the sl::VIDEO_SETTINGS:

ZED Explorer camera parameters
VIDEO_SETTINGSDescriptionValues
BRIGHTNESSControls image brightness.[0 - 8]
CONTRASTControls image contrast.[0 - 8]
HUEControls image color.[0 - 11]
SATURATIONControls image color intensity.[0 - 8]
SHARPNESSControls image sharpness.[0 - 8]
GAMMAControls gamma correction.[1 - 9]
GAINControls digital amplification of the signal from the camera sensors.[0 - 100]
EXPOSUREControls shutter speed. Setting a long exposure time leads to an increase in motion blur. See Exposure Control.[0 - 100] (% of the longest exposure of the video mode)
AEC_AGCControls if gain and exposure are in automatic mode or not.[0 - 1]
AEC_AGC_ROIControls the region of interest for automatic exposure/gain computation.sl::Rect
WHITEBALANCE_TEMPERATUREControls camera white balance.[2800 - 6500]
WHITEBALANCE_AUTOControls camera white balance automatic mode.[0 - 1]
LED_STATUSControls the status of the camera front LED. Set to 0 to disable the light, 1 to enable the light.[0 - 1]

For more information on how to adjust camera settings using the API, see Camera Controls.

Camera controls adjust parameters of left and right image sensors in sync. It is not possible to adjust sensor parameters individually.

The ISP processes the images before they are sent to the host, so camera control settings are baked into the pixels that a recording writes to an SVO file. They are the only settings that cannot be changed when the file is played back: setCameraSettings() returns INVALID_FUNCTION_CALL in Playback mode. Everything else, including depth, is computed live at playback and can be freely reconfigured.

Manual/Auto Mode

When camera White Balance, Exposure and Gain are in AUTO mode, they are automatically adjusted depending on the luminance in the scene.

In AUTO mode, Exposure level will be increased first, then Gain in order to reduce noise. When Exposure is at its maximum level, motion blur is increased. If you need to reduce blur, switch to MANUAL mode and increase Gain before Exposure.

It is also recommended to increase the Gamma setting in low-light environments, as it can provide a considerable light boost while reducing saturated areas.

Exposure Control

Three settings control the exposure. The USB cameras support only the first one.

VIDEO_SETTINGSUnitCamerasUse
EXPOSURE% [0 - 100] of the exposure range of the video modeAllManual exposure on any camera
EXPOSURE_TIMEµsZED X and ZED X One familiesManual exposure as an absolute time. Reading it returns the exposure of the current frame, also in automatic mode
AUTO_EXPOSURE_TIME_RANGEµs (minimum and maximum)ZED X and ZED X One familiesLimits of the automatic exposure

On the ZED, ZED 2, ZED 2i and ZED Mini, isCameraSettingSupported() returns false for EXPOSURE_TIME and AUTO_EXPOSURE_TIME_RANGE, and the exposure time in µs cannot be read.

Setting EXPOSURE or EXPOSURE_TIME switches the exposure to manual. Set AEC_AGC to 1, or EXPOSURE to -1, to return to the automatic exposure and gain.

Exposure Ranges

The longest exposure is one frame period, with a limit set by the sensor at 15 fps. The ZED X, ZED X Mini, ZED X Nano, ZED X One GS and ZED X One S share the same 2.3 MP global shutter sensor, and the same ranges:

CameraVideo modesShortest (µs)Longest at 15 fps (µs)30 fps60 fps120 fps
ZED X, ZED X Mini, ZED X Nano, ZED X One GS, ZED X One SHD1200, HD10803965,00033,33316,666-
ZED X, ZED X Mini, ZED X Nano, ZED X One GS, ZED X One SSVGA2165,00033,33316,6668,333
ZED X One 4KHD4K, HD1200, HD10801639,00033,33316,666-
ZED X One 4K, HDR modeQHDPLUS, HD12001,02466,66633,33316,666-

On the ZED X One 4K, HD4K and QHDPLUS run at 15 fps only, and QHDPLUS is available only in HDR mode.

EXPOSURE maps linearly onto this range: 0 gives the shortest exposure and 100 the longest. At 30 fps on a ZED X, EXPOSURE = 50 gives about 16,700 µs.

To get the range of the current video mode on any camera of the ZED X and ZED X One families, call getCameraSettingsRange() with EXPOSURE_TIME in C++. In Python and C#, read AUTO_EXPOSURE_TIME_RANGE right after the camera opens: it then holds the full range of the video mode.

On the USB cameras, EXPOSURE is a percentage of a longest exposure that depends on the video mode, and this exposure cannot be longer than a frame. In some video modes, the highest values all give the same exposure: in HD720 at 30 fps, for example, every value above about 76 gives the longest exposure the sensor accepts.

With ZED SDK 5.6, setCameraSettings() returns SUCCESS for an EXPOSURE_TIME outside the range of the video mode, but the camera does not apply it: a value above the longest exposure leaves the previous exposure in use. AUTO_EXPOSURE_TIME_RANGE also accepts bounds outside the range and reports them as set. Keep the values within the range, and read EXPOSURE_TIME back with getCameraSettings() to check the exposure in use.

Frame Rate and Maximum Exposure

A frame cannot be exposed longer than its frame period, so the frame rate set with InitParameters::camera_fps limits the longest exposure: 33.3 ms at 30 fps, 16.7 ms at 60 fps. The frame rate can only be changed by opening the camera again, and the range of AUTO_EXPOSURE_TIME_RANGE then follows the new video mode.

  • Low light: to expose longer than the frame period allows, lower the frame rate (at 15 fps, up to 65 ms on the ZED X family and the ZED X One GS and S, 39 ms on the ZED X One 4K and 66.7 ms in its HDR mode), or raise the gain, which adds noise.
  • Motion blur: in automatic mode, the exposure goes up to the maximum of the range before the gain increases. To limit motion blur, lower the maximum of AUTO_EXPOSURE_TIME_RANGE: the automatic control then raises the gain instead.

The following example reads the range of the current video mode, sets a manual exposure time of 5 ms and checks it, then returns to the automatic exposure, limited to 5 ms:

// Range of the current video mode (ZED X and ZED X One families)
int min_us = 0, max_us = 0;
zed.getCameraSettingsRange(VIDEO_SETTINGS::EXPOSURE_TIME, min_us, max_us);
// Manual exposure time of 5 ms, then read back the exposure in use
zed.setCameraSettings(VIDEO_SETTINGS::EXPOSURE_TIME, 5000);
int exposure_us = 0;
zed.getCameraSettings(VIDEO_SETTINGS::EXPOSURE_TIME, exposure_us);
// Automatic exposure, limited to 0.1 - 5 ms to reduce motion blur
zed.setCameraSettings(VIDEO_SETTINGS::AEC_AGC, 1);
zed.setCameraSettings(VIDEO_SETTINGS::AUTO_EXPOSURE_TIME_RANGE, 100, 5000);

Using the API

The ZED API provides low-level access to camera control and configuration. To use the ZED in your application, you will need to create and open a Camera object. The API can be used with two different video inputs: the ZED live video (Live mode) or video files recorded in SVO format with the ZED API (Playback mode).

Camera Configuration

To configure the camera, create a Camera object and specify your InitParameters. Initial parameters let you adjust camera resolution, FPS, depth sensing parameters and more. These parameters can only be set before opening the camera and cannot be changed while the camera is in use.

// Create a ZED camera object
Camera zed;
// Set configuration parameters
InitParameters init_params;
init_params.camera_resolution = RESOLUTION::HD1080;
init_params.camera_fps = 30;
// Open the camera
ERROR_CODE err = zed.open(init_params);
if (err != ERROR_CODE::SUCCESS)
exit(-1);

InitParameters contains a configuration by default. To see the list of parameters, read the API documentation.

Image Capture

To capture images from the ZED, specify your RuntimeParameters and call grab() to grab a new frame and retrieveImage() to retrieve the grabbed frame. retrieveImage() lets you select between different views such as left, right, unrectified and grayscale images.

sl::Mat image;
if (zed.grab() == ERROR_CODE::SUCCESS) {
// A new image is available if grab() returns SUCCESS
zed.retrieveImage(image, VIEW::LEFT); // Retrieve the left image
}

Adjusting Camera Controls

Camera settings such as exposure, white balance and more can be manually set at runtime using setCameraSettings(). To change camera resolution and frame rate, use InitParameters.

// Set exposure to 50% of the exposure range
zed.setCameraSettings(VIDEO_SETTINGS::EXPOSURE, 50);
// Set white balance to 4600K
zed.setCameraSettings(VIDEO_SETTINGS::WHITEBALANCE_TEMPERATURE, 4600);
// Reset to auto exposure
zed.setCameraSettings(VIDEO_SETTINGS::EXPOSURE, VIDEO_SETTINGS_VALUE_AUTO);

Camera settings can be retrieved using getCameraSettings(). To get the list of available settings, see the API documentation.

Since ZED SDK 5.6, setCameraSettings() returns SUCCESS only when the setting was applied. Otherwise it returns a specific error:

  • INVALID_FUNCTION_PARAMETERS: the camera does not support the setting (for example LED_STATUS on the GMSL cameras, which have no status LED, or on a camera whose firmware cannot switch it), or the AEC/AGC region is outside the image.
  • INVALID_FUNCTION_CALL: SVO playback.
  • CAMERA_NOT_INITIALIZED: the camera or stream is gone.
  • FAILURE: the camera refused the value.

On a stream input, SUCCESS means the request was sent to the streaming camera.

Color Correction Matrix

Since ZED SDK 5.6, VIDEO_SETTINGS::COLOR_CORRECTION_MATRIX applies your own color correction matrix on GMSL cameras such as the ZED X, ZED X Mini and ZED X One GS. The matrix converts the sensor RGB values of each pixel to linear sRGB, before gamma correction: each row gives one output channel (red, green, blue) as a weighted sum of the sensor red, green and blue values. Use it when your application needs a specific color rendering, typically to match several cameras to one another or to a reference, with a matrix computed from images of a color chart.

// Apply a color correction matrix computed for this camera
float coefficients[9] = {1.8f, -0.5f, -0.3f,
-0.2f, 1.6f, -0.4f,
0.0f, -0.6f, 1.6f};
zed.setCameraSettings(VIDEO_SETTINGS::COLOR_CORRECTION_MATRIX, sl::Matrix3f(coefficients));
// Go back to the color correction of the camera
zed.setCameraSettings(VIDEO_SETTINGS::COLOR_CORRECTION_MATRIX);

In Python, use set_camera_settings_color_matrix(). The matrix is applied to both sensors and stays in use until you restore the color correction of the camera; meanwhile, VIDEO_SETTINGS::SATURATION has no effect. It works on a live camera or a stream, where the sending camera applies it, but not during SVO playback.

Code Example

Check out the Camera Control sample on GitHub.