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 ;

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

Once initial configuration is done, open the camera.

// Open the camera
err = zed.open(init_params);
if (err != SUCCESS)
    exit(-1);

Video Capture

To capture images from the ZED, 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
}

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);

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

Getting Camera Information

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;

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.

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.