Programming Guidelines: How to move to ZED SDK 2.0

Introduction

The ZED SDK v2.0 has been completely redesigned and architectured into different modules: Video, Depth, Positional Tracking and Spatial Mapping. Each module can be configured through dedicated parameters. Support functions have also been introduced and memory management has been simplified. The new API is much easier to use and integrate.

Since there are a lot of changes compared to ZED SDK v1.2, this tutorial will help you switch easily from 1.2 to 2.0.

Overview

The philosophy of the ZED SDK is still the same (you still have a camera object to handle your ZED) and most of the functions of v1.2 are still available. However, most of them have either been renamed or their parameters modified.

New image containers (Mat) have been introduced to simplify data handling and memory management: you will find the new definitions in Core.hpp or Types.hpp. The ‘zed’ namespace has been removed and merged into single namespace ‘sl’. Samples have been refactored as well and each module has now its dedicated sample to demonstrates the usage of the new API.

ZED SDK Content Changes

The ZED SDK is still installed in Program Files/ZED SDK/ on Windows and /usr/local/zed/ on Linux. The content of each folder (include, lib and samples) has changed:

Note: To protect possible code you could have stored in the ZED SDK directory, the previous ‘ZED SDK’ directory will be preserved and renamed in ‘ZED SDK.old’ during installation of 2.0. Note however that it is not recommended to have your own code in this directory.

ZED SDK Code Changes

Overview

This means you can now check that a function has succeeded before using the Mat result.

Memory Management (Mat)

We have refactored sl::Mat to provide a simpler way to handle images both on CPU and GPU. Our goal is to allow any developer to switch easily between CPU and GPU functions during development.

Example:

sl::Mat gpuImage_;
sl::Mat cpuImage_;
sl::Mat cpuMeasure_;
gpuImage_.alloc(w,h,sl::MAT_FORMAT_4_UCHAR, sl::MEM_GPU); // Create a RGBA image on the GPU
cpuImage_.alloc(w,h,sl::MAT_FORMAT_4_UCHAR, sl::MEM_CPU); // Create a RGBA image on the CPU
cpuMeasure_.alloc(w,h,sl::MAT_FORMAT_1_FLOAT, sl::MEM_CPU); // Create a 32bits measure (depth) on the CPU

Camera

Camera Construction

Compared to 1.2, there is now only one single default constructor. It allows to declare a zed (sl::Camera) object and have the default constructor called.

Camera initialization

To initialize the ZED, you still need to call a function that opens the camera with the sl::InitParameters structure. This function has been renamed open(...) but behaves in a similar way to the previous init(...) function. A close() function is now available to close the camera. The camera can be reopened by calling open() again.

Example :

sl::InitParameters param;
param.system_units = sl::UNIT_METER;
ERROR_CODE res = zed.open(param); // check if initialization succeeded

About SVO and LIVE mode: The choice between SVO and Live mode was previously done in the constructor. They are now parameters of the InitParameters class:

Leaving the Initparameters empty will provide default parameters in live mode.

Initialization parameters

Members of InitParameters have been renamed according to the modules they are attached to.

v 1.2 v 2.0
verbose sdk_verbose
device sdk_gpu_id
v 1.2 v 2.0
disableSelfCalib camera_disable_self_calib
vflip camera_image_flip
- camera_buffer_count_linux (NEW)
- camera_resolution (NEW)
- camera_fps (NEW)
v 1.2 v 2.0
mode depth_mode
minimumDistance depth_minimum_distance
v 1.2 v 2.0
unit coordinate_units
coordinate coordinate_system

Camera Retrieve function

Retrieving an image or a measure through the ZED SDK has been simplified : normalizeMeasure() and getView() have been merged into retrieveImage function. retrieveImage now takes a VIEW parameter instead of a SIDE (in 1.2).

A single function can now get images or measures from CPU or GPU memory. You just need to specify the MEM_TYPE in the last parameter of the retrieve function.

In the following example, we retrieve a left image, a side by side image, a point cloud and a displayable depth image (8-bit, only for vizualisation) from both CPU and GPU memory.

With ZED SDK 1.2:

//Left image (CPU and GPU)
sl::Mat left_image_cpu_ = zed->retrieveimage(sl::zed::SIDE::LEFT); // left image on cpu
sl::Mat left_image_gpu_ = zed->retrieveimage_gpu(sl::zed::SIDE::LEFT); // left image on GPU

//Side by Side image (CPU and GPU)
sl::Mat sbs_image_cpu_ = zed->getView(sl::zed::VIEW_MODE::STEREO_SBS); // side by side image on CPU
sl::Mat sbs_image_gpu_ = zed->getView_gpu(sl::zed::VIEW_MODE::STEREO_SBS); // side by side image on GPU

//Point Cloud XYZRGBA
sl::Mat point_cloud_cpu_ = zed->retrieveMeasure(sl::zed::MEASURE::XYZRGBA); // get the point cloud in CPU
sl::Mat point_cloud_gpu_ = zed->retrieveMeasure_gpu(sl::zed::MEASURE::XYZRGBA); // get the point cloud in GPU

//Depth map image (only for display)
sl::Mat image_depth_cpu_ = zed->normalizeMeasure(sl::zed::MEASURE::DEPTH); // get the point cloud in CPU
sl::Mat image_depth_gpu_ = zed->normalizeMeasure_gpu(sl::zed::MEASURE::DEPTH); // get the point cloud in GPU

With ZED SDK 2.0:

sl::Mat left_image_cpu_,left_image_gpu_,sbs_image_cpu_,sbs_image_gpu_, point_cloud_cpu_, point_cloud_gpu_, image_depth_cpu_, image_depth_gpu_;
ERROR_CODE res;

// Left image (CPU and GPU)
res =  zed->retrieveImage(left_image_cpu_, sl::VIEW_LEFT, sl::MEM_CPU);
res =  zed->retrieveImage(left_image_gpu_, sl::VIEW_LEFT, sl::MEM_GPU);

// Side by Side image (CPU and GPU)
res =  zed->retrieveImage(sbs_image_cpu_, sl::VIEW_SIDE_BY_SIDE, sl::MEM_CPU);
res =  zed->retrieveImage(sbs_image_gpu_, sl::VIEW_SIDE_BY_SIDE, sl::MEM_GPU);

// Point Cloud XYZRGBA
res =  zed->retrieveMeasure(point_cloud_cpu_, sl::MEASURE_XYZRGBA, sl::MEM_CPU);
res =  zed->retrieveMeasure(point_cloud_gpu_, sl::MEASURE_XYZRGBA, sl::MEM_GPU);

// Depth map image (only for display)
res =  zed->retrieveImage(image_depth_cpu_, sl::VIEW_DEPTH, sl::MEM_CPU);
res =  zed->retrieveImage(image_depth_gpu_, sl::VIEW_DEPTH, sl::MEM_GPU);

Note: Mat memory can be allocated with the alloc() function before calling a retrieve function. But if memory is not allocated (Mat default constructor) or incorrectly allocated (wrong MAT_FORMAT, size or MEM_TYPE), then the API will reallocate correctly the Mat memory during the first call of the retrieve function. Since reallocation takes some time, you should expect the first function call to take longer than for the next calls.

Camera Information

Camera information (available through the CameraInformation structure) now regroups all the information relative to the ZED camera: calibration parameters, firmware version, serial number. As a result, three function of the ZED SDK 1.2 have been merged into a single one in 2.0.

With ZED SDK 1.2:

sl::StereoParameters* calibration_parameters = zed->getParameters();
int focale_x = calibration_parameters->left_cam.fx; // Focal length in pixels of left camera (after image alignment/rectification)
int baseline = calibration_parameters->baseline; // Distance between the left and right camera
int zed_fw_version = zed->getZEDFirmware();  // Current firmware version inside the ZED
int zed_serial_number = zed->getZEDSerial(); // ZED serial number

With ZED SDK 2.0:

sl::CameraInformation *infos = zed->getCameraInformation();
int focale_x = infos.calibration_parameters.left_cam.fx; // Focal length in pixels of left camera (after image alignment/rectification)
int baseline = infos.calibration_parameters.T.x; // Distance between left and right camera
int zed_fw_version = infos.firmware_version;  // Current firmware version inside the ZED
int zed_serial_number = infos.serial_number; // ZED serial number

Frame Rate

Camera Framerate can now be controlled using setCameraFPS() and getCameraFPS(). In ZED SDK 1.2, those functions were setFPS() and getCurrentFPS().

getCurrentFPS() returns the callback time of the ZED (time between two successful grab()). It is based on the camera timestamp. Since it takes computation time into account, getCurrentFPS() will return an fps lower than getCameraFPS().

Camera Settings

We have introduced in ZED SDK 2.0 the possibility to set the camera white balance at a specific color temperature. This is a new entry in the CAMERA_SETTINGS enum, called CAMERA_SETTINGS_WHITEBALANCE and CAMERA_SETTINGS_AUTO_WHITEBALANCE.

To access camera settings (contrast, hue, brightness, exposure…), get and set functions are now available: setCameraSettings() and getCameraSettings().

Example with ZED SDK 1.2:

zed->setCameraSettingsValue(sl::CAMERA_SETTINGS::CONTRAST, 5);
int current_hue = zed->getCameraSettingsValue(sl::CAMERA_SETTINGS::HUE, 5);

With ZED SDK 2.0:

zed->setCameraSettings(sl::CAMERA_SETTINGS::CAMERA_SETTINGS_CONTRAST, 5);
int current_hue = zed->getCameraSettings(sl::CAMERA_SETTINGS::CAMERA_SETTINGS_HUE, 5);

Depth Range

Depth range control functions have been renamed but have the same behavior as in 1.2.

1.2 2.0
setDepthClampValue(float) setDepthMaxRangeValue(float)
float getDepthClampValue() float getDepthMaxRangeValue()
float getClosestDepthValue() float getDepthMinRangeValue()

Conclusion

Moving from ZED SDK 1.2 to 2.0 should be quick and easy, bringing many performance improvements along with additional features. For more information, have a look at our new online documentation or contact our Support team. We’ll be happy to help you make the switch to 2.0.