Camera Controls | StereoLabs

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

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.

ZED, ZED 2/2i, ZED Mini

ZED X, ZED X Mini, ZED X Nano

ZED X One GS

ZED X One 4K

Video Mode	Output Resolution (side by side)	Frame Rate (fps)	Field of View
`HD2K`	4416x1242	15	Wide
`HD1080`	3840x1080	30, 15	Wide
`HD720`	2560x720	60, 30, 15	Extra Wide
`VGA`	1344x376	100, 60, 30, 15	Extra 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):

Image	BGRA (32 bits)	BGR (24 bits)	Grayscale (8 bits)	NV12
Left rectified	`LEFT`, `LEFT_BGRA`	`LEFT_BGR`	`LEFT_GRAY`	`LEFT_NV12`
Right rectified	`RIGHT`, `RIGHT_BGRA`	`RIGHT_BGR`	`RIGHT_GRAY`	`RIGHT_NV12`
Left unrectified	`LEFT_UNRECTIFIED`, `LEFT_UNRECTIFIED_BGRA`	`LEFT_UNRECTIFIED_BGR`	`LEFT_UNRECTIFIED_GRAY`	`LEFT_NV12_UNRECTIFIED`
Right unrectified	`RIGHT_UNRECTIFIED`, `RIGHT_UNRECTIFIED_BGRA`	`RIGHT_UNRECTIFIED_BGR`	`RIGHT_UNRECTIFIED_GRAY`	`RIGHT_NV12_UNRECTIFIED`
Left and right rectified, side by side	`SIDE_BY_SIDE`, `SIDE_BY_SIDE_BGRA`	`SIDE_BY_SIDE_BGR`	`SIDE_BY_SIDE_GRAY`	-
Left and right unrectified, side by side	`SIDE_BY_SIDE_UNRECTIFIED_BGRA`	`SIDE_BY_SIDE_UNRECTIFIED_BGR`	`SIDE_BY_SIDE_UNRECTIFIED_GRAY`	-
Depth map rendering	`DEPTH`, `DEPTH_BGRA`	`DEPTH_BGR`	`DEPTH_GRAY`	-
Depth confidence map rendering	`CONFIDENCE`, `CONFIDENCE_BGRA`	`CONFIDENCE_BGR`	`CONFIDENCE_GRAY`	-
Normals map rendering	`NORMALS`, `NORMALS_BGRA`	`NORMALS_BGR`	`NORMALS_GRAY`	-
Depth map rendering, aligned on the right sensor	`DEPTH_RIGHT`, `DEPTH_RIGHT_BGRA`	`DEPTH_RIGHT_BGR`	`DEPTH_RIGHT_GRAY`	-
Normals map rendering, aligned on the right sensor	`NORMALS_RIGHT`, `NORMALS_RIGHT_BGRA`	`NORMALS_RIGHT_BGR`	`NORMALS_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, ZED 2/2i, ZED Mini

ZED X, ZED X Mini, ZED X Nano, ZED X One

VIDEO_SETTINGS	Description	Values
BRIGHTNESS	Controls image brightness.	[0 - 8]
CONTRAST	Controls image contrast.	[0 - 8]
HUE	Controls image color.	[0 - 11]
SATURATION	Controls image color intensity.	[0 - 8]
SHARPNESS	Controls image sharpness.	[0 - 8]
GAMMA	Controls gamma correction.	[1 - 9]
GAIN	Controls digital amplification of the signal from the camera sensors.	[0 - 100]
EXPOSURE	Controls shutter speed. Setting a long exposure time leads to an increase in motion blur.	[0 - 100] (% of camera frame rate)
AEC_AGC	Controls if gain and exposure are in automatic mode or not.	[0 - 1]
AEC_AGC_ROI	Controls the region of interest for automatic exposure/gain computation.	sl::Rect
WHITEBALANCE_TEMPERATURE	Controls camera white balance.	[2800 - 6500]
WHITEBALANCE_AUTO	Controls camera white balance automatic mode.	[0 - 1]
LED_STATUS	Controls 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() has no effect 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.

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 camera framerate
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.

Code Example

Check out the Camera Control sample on GitHub.