Using the Video API

The ZED API provides low-level access to the camera hardware and video features, facilitating camera control and high-quality video recording and streaming.

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

Camera settings such as exposure, white balance and others can be manually set at runtime using setCameraSettings().

// Set exposure in manual mode at 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, -1);

To see the list of available video modes and settings, read Camera Controls.

Identifying the Camera Model

The camera model is reported as an sl::MODEL value. Depending on what you have at hand, there are three ways to get it:

• From an opened camera or an SVO file, with getCameraInformation().
• From a connected camera, without opening it, with getDeviceList().
• From the serial number only, for example the one printed on the camera label or in the name of a calibration file (SNxxxxxxx.conf).

From an opened camera or an SVO file

Once the camera is opened, getCameraInformation() returns its model and serial number. This also works when playing back an SVO file: the values are the ones of the camera that recorded it.

Camera zed;
InitParameters init_params;
if (zed.open(init_params) != ERROR_CODE::SUCCESS)
    exit(-1);
CameraInformation info = zed.getCameraInformation();
std::cout << "Model: " << info.camera_model << " - S/N: " << info.serial_number << std::endl;

When using a monocular camera through the CameraOne class, getCameraInformation() provides the same camera_model and serial_number fields.

From a connected camera, without opening it

The static getDeviceList() method lists the connected cameras with their model and serial number, without opening them. Use it to choose which camera to open with InitParameters.input.setFromSerialNumber(), as described in Multi-Camera.

std::vector<DeviceProperties> devices = Camera::getDeviceList();
for (const auto& dev : devices)
    std::cout << "ID: " << dev.id << " - Model: " << dev.camera_model << " - S/N: " << dev.serial_number << std::endl;

From the serial number only

The serial number of a ZED camera encodes its model: the model is the serial number divided by 10,000,000 (integer division), and the result is the value of the sl::MODEL enum. For example, the serial number 31234567 belongs to a ZED 2i (31234567 / 10000000 = 3 = MODEL::ZED2i), and 301234567 to a ZED X One GS (30 = MODEL::ZED_XONE_GS).

The sl::MODEL values are the same in all the APIs. Model IDs that are not in the table do not correspond to a known camera model, so the following functions check the result against the list of known models.

// Returns MODEL::LAST if the serial number does not match a known camera model
MODEL getModelFromSerialNumber(unsigned int serial_number) {
    const MODEL known_models[] = {
        MODEL::ZED, MODEL::ZED_M, MODEL::ZED2, MODEL::ZED2i,
        MODEL::ZED_X, MODEL::ZED_XM, MODEL::ZED_X_NANO, MODEL::VIRTUAL_ZED_X,
        MODEL::ZED_XONE_GS, MODEL::ZED_XONE_UHD, MODEL::ZED_XONE_CORE};
    const int model_id = static_cast<int>(serial_number / 10000000);
    if (serial_number != 0) {
        for (MODEL model : known_models)
            if (static_cast<int>(model) == model_id)
                return model;
    }
    return MODEL::LAST;
}
std::cout << getModelFromSerialNumber(31234567) << std::endl; // ZED 2i

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
}

Video Recording

The ZED SDK uses StereoLabs’ SVO format to store videos along with additional metadata such as timestamps and sensor data. An SVO file only holds the raw unrectified images and the sensor data: depth, rectification and all other processing are performed live by the ZED SDK when the file is played back. See What an SVO File Contains for details.

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 then call grab(): each grabbed frame is added to the SVO file. SVO lets you record video and associated metadata (timestamp, IMU data and more if available).

// Create and open a ZED camera object
Camera zed;
InitParameters init_parameters;
ERROR_CODE err = zed.open(init_parameters);
if (err != ERROR_CODE::SUCCESS)
    exit(-1);
// Enable recording with the filename specified in argument
String output_path(argv[1]);
RecordingParameters recordingParameters;
recordingParameters.compression_mode = SVO_COMPRESSION_MODE::H264;
recordingParameters.video_filename = output_path;
err = zed.enableRecording(recordingParameters);
while (!exit_app) {
    // Each new frame is added to the SVO file
    zed.grab();
}
// Disable recording
zed.disableRecording();

Video Playback

To play SVO files, simply add the file path as an argument in setFromSVOFile(). When loading SVO files, the ZED API will behave as if a ZED was connected and a live feed was available. Every module of the ZED API will be available: depth, tracking, spatial mapping and more, regardless of what was enabled during the recording session. When an SVO file is read entirely, END_OF_SVOFILE_REACHED error code is returned.

// Create a ZED camera object
Camera zed;
// Set SVO path for playback
String input_path(argv[1]);
InitParameters init_parameters;
init_parameters.input.setFromSVOFile(input_path);
// Open the ZED
ERROR_CODE err = zed.open(init_parameters);
sl::Mat svo_image;
while (!exit_app) {
    ERROR_CODE grab_status = zed.grab();
    if (grab_status == ERROR_CODE::SUCCESS) {
        // Read side by side frames stored in the SVO
        zed.retrieveImage(svo_image, VIEW::SIDE_BY_SIDE);
        // Get frame count      
        int svo_position = zed.getSVOPosition();
    }
    else if (grab_status == ERROR_CODE::END_OF_SVOFILE_REACHED) {
        std::cout << "SVO end has been reached. Looping back to first frame" << std::endl;
        zed.setSVOPosition(0);
    }
}

Local Streaming

To learn how to stream stereo video on the local network using the ZED SDK, read Local Streaming section.

Code Examples

Get started with stereo video capture, recording and streaming using the following code samples on GitHub:

• Camera Control
• SVO Recording, SVO Playback and SVO Export
• Camera Streaming