Using the API

Overview

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
err = zed.open(init_params);
if (err != SUCCESS)
    exit(-1);
# Create a ZED camera object
zed = sl.Camera()

# Set configuration parameters
init_params = sl.InitParameters()
init_params.camera_resolution = sl.RESOLUTION.RESOLUTION_HD1080
init_params.camera_fps = 30

# Open the camera
err = zed.open(init_params)
if err != sl.ERROR_CODE.SUCCESS:
    exit(-1)

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

Video 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() == SUCCESS) {
  // A new image is available if grab() returns SUCCESS
  zed.retrieveImage(image,VIEW_LEFT); // Retrieve the left image
}
image = sl.Mat()
runtime_parameters = sl.RuntimeParameters()
if zed.grab(runtime_parameters) == sl.ERROR_CODE.SUCCESS:
  # A new image is available if grab() returns SUCCESS
  zed.retrieve_image(image, sl.VIEW.VIEW_LEFT) # Retrieve the left image

Adjusting Camera Settings

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(CAMERA_SETTINGS_EXPOSURE, 50, false);
// Set white balance to 4600K
zed.setCameraSettings(CAMERA_SETTINGS_WHITE_BALANCE, 4600, false);
// Reset to auto exposure
zed.setCameraSettings(CAMERA_SETTINGS_EXPOSURE, -1, true);
# Set exposure to 50% of camera framerate
zed.set_camera_settings(sl.CAMERA_SETTINGS.CAMERA_SETTINGS_EXPOSURE, 50, False)
# Set white balance to 4600K
zed.set_camera_settings(sl.CAMERA_SETTINGS.CAMERA_SETTINGS_WHITE_BALANCE, 4600, False)
# Reset to auto exposure
zed.set_camera_settings(sl.CAMERA_SETTINGS.CAMERA_SETTINGS_EXPOSURE, -1, True)

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

Camera Calibration

Camera parameters such as focal length, field of view or stereo calibration can be retrieved for each eye and resolution:

  • Focal length: fx, fy.
  • Principal points: cx, cy.
  • Lens distortion: k1, k2.
  • Horizontal and vertical field of view.
  • Stereo calibration: rotation and translation between left and right eye.

Those values are available in CalibrationParameters. They can be accessed using getCameraInformation().

CalibrationParameters calibration_params = zed.getCameraInformation()->calibration_parameters;
// Focal length of the left eye in pixels
float focal_left_x = calibration_params.left_cam.fx;
// Horizontal field of view of the left eye in degrees
float h_fov = calibration_params.left_cam.h_fov;
calibration_params = zed.get_camera_information().calibration_parameters
# Focal length of the left eye in pixels
focal_left_x = calibration_params.left_cam.fx
# Horizontal field of view of the left eye in degrees
h_fov = calibration_params.left_cam.h_fov

Note that calibration parameters can be re-estimated by the camera self-calibration technology over the lifetime of the device. Updated parameters will be available in CalibrationParameters. It is also possible to recalibrate the camera manually using the ZED Calibration tool.

Saving a Video

To record SVO files, you need to enable the Recording module with enableRecording(). Specify an output file name (eg: output.svo) and SVO_COMPRESSION_MODE, then save each grabbed frame using record(). SVO lets you record video and associated metadata (timestamp, IMU data if available).

// Enable recording with the filename specified in argument
String path_output(argv[1]);
err = zed.enableRecording(path_output, SVO_COMPRESSION_MODE_LOSSLESS);

while (!exit_app) {
    if (zed.grab() == SUCCESS) {
        // Each new frame is added to the SVO file
        zed.record();
    }
}
// Disable recording
zed.disableRecording();
# Enable recording with the filename specified in argument
path_output = sys.argv[0]
err = zed.enable_recording(path_output, sl.SVO_COMPRESSION_MODE.SVO_COMPRESSION_MODE_LOSSLESS)

while !exit_app :
    if zed.grab() == sl.ERROR_CODE.SUCCESS :
        # Each new frame is added to the SVO file
        zed.record()

# Disable recording
zed.disable_recording()

Learn more about Compression Modes.

Code Example

For code examples, check out the Camera Control and SVO Recording samples to learn how to control the camera and record, playback and export videos and depth with the ZED.