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.

Streaming a Video

To stream the video content of a ZED camera, you need to enable the streaming module with enableStreaming(). Once called, standard calls to grab() to grab a frame will also send that frame over the network.

Use StreamingParameters to specify settings like bitrate, port, etc. Then pass those parameters when you call enableStreaming().


// Set the streaming parameters
sl::StreamingParameters stream_params;
stream_params.codec = sl::STREAMING_CODEC_AVCHD; // can be AVCHD or HEVC
stream_params.bitrate = 8000;
stream_params.port = 30000; // port used for sending the stream
// Enable streaming with the streaming parameters
err = zed.enableStreaming(stream_params);

while (!exit_app) {
    zed.grab();
}
// Disable streaming
zed.disableStreaming();

# Set the streaming parameters
stream = sl.StreamingParameters()
stream.codec = sl.STREAMING_CODEC.STREAMING_CODEC_AVCHD # can be AVCHD or HEVC
stream.bitrate = 8000
stream.port = 30000 # port used for sending the stream
# Enable streaming with the streaming parameters
status = zed.enable_streaming(stream)

while !exit_app :
    zed.grab()

# Disable streaming
zed.disable_streaming()

Learn more about Streaming Modes.

Using a Stream as SDK Input

Video content streamed from a ZED camera is accessible remotely and can be used as standard input for the ZED API. Therefore, every ZED API module will work as if the camera was directly connected to the device. To use a remote stream as input, specify the IP address and the port of the sender in initParameters. Then call open() to open the camera from the stream and grab() to grab a new frame and do the processing you want.


// Set the input from stream
InitParameters initParameters;
initParameters.input.setFromStream("127.0.0.1", 30000); // Specify the IP and port of the sender 
// Open the camera
ERROR_CODE zed_error = zed.open(initParameters);

while (!exit_app) {
    if (zed.grab() == SUCCESS) {
        // Any processing
    }
}
// Close the camera
zed.close();

# Set the input from stream
init = sl.InitParameters()
init.set_from_stream("127.0.0.1", 30000) # Specify the IP and port of the sender 
# Open the camera
status = zed.open(init)

while !exit_app:
    if zed.grab() == sl.ERROR_CODE.SUCCESS):
        # Any processing

# Close the camera
zed.close()

Code Example

Check out the Camera Control, SVO Recording and Camera Streaming samples on our GitHub.