STEREOLABS

3.0 Migration Guide

Update from ZED SDK 2.0 to 3.0

Introduction

This major release follows Semantic Versioning more strictly than before. This means that each minor version is guaranteed to be API compatible and each patch version is guaranteed to be binary compatible. This major release therefore introduces some breaking changes.

The ZED SDK v3.0 continues to follow the architecture of previous versions. It is separated into different modules: Video, Depth, Positional Tracking, Spatial Mapping, and the new Object Detection module. Each module can be configured through dedicated parameters. The new API is clearer and more consistent, which facilitates its integration and development.

Since there are a lot of changes from ZED SDK v2.8, this tutorial will help you switch from 2.8 to 3.0.

ZED SDK Content Changes

  • All headers are now amalgamated into a single one: sl/Camera.hpp
  • The ZED SDK is now contained into a single sl_zed library (sl_zed64.dll or libsl_zed.so)

ZED SDK Code Changes

Overview

  • Adding support for the new ZED 2 camera.
  • Camera::grab() function is now blocking: each call waits for a new image. If the camera is connected (or the SVO file isn't finished) the call is guaranteed to compute everything on a new frame. ERROR_CODE_NOT_A_NEW_FRAME has been removed accordingly. If the camera is disconnected, the grab() function will time out and return ERROR_CODE::CAMERA_NOT_DETECTED. For SVO files, if the end of file is reached, it will return a new error code created specifically for this: ERROR_CODE::END_OF_SVOFILE_REACHED.
  • ENUMs have been refactored under the following convention: ENUM_NAME::VALUE instead of the current ENUM_NAME::ENUM_NAME_VALUE or sometimes ENUM_NAME_VALUE. For example, the 2K resolution is now set with RESOLUTION::HD2K instead of RESOLUTION::RESOLUTION_HD2K or RESOLUTION_HD2K.
  • All deprecated functions have been removed such as resetSelfCalibration(), getSelfCalibrationState(), setCameraFPS(), SticktoCPUCore(), isZEDConnected() (use getDeviceList().size() instead).
  • Every module parameter can now be retrieved directly from Camera, such as Camera::getInitParameters(), Camera::getPositionalTrackingParameters, etc.
  • Camera::retrieve* functions now take a Resolution instead of height and width integers.
  • CalibrationParameters::getCameraBaseline() has been added in the calibration parameters to access the distance between the left and right sensors (called the "baseline").
  • Adding Mat::save() function, replacing SaveAs functions
  • Added static function Camera::reboot() to perform a hardware reset of the camera. It simulates physically unplugging and replugging the camera. This feature is only available for ZED2.
  • ERROR_CODE_SENSOR_NOT_DETECTED has been replaced with ERROR_CODE::SENSORS_NOT_AVAILABLE since the ZED2 contains multiple sensors (IMU, barometer, etc.). Added ERROR_CODE::MOTION_SENSORS_REQUIRED
  • ERROR_CODE_CAMERA_ALREADY_IN_USE has been replaced by ERROR_CODE::CANNOT_START_CAMERA_STREAM to be more coherent with what actually happens; in most cases, it would the camera is being used by another process, but in a rare case, a firewall or antivirus software can prevent the camera from starting.

Modules

Video
  • Enum CAMERA_SETTINGS is renamed to VIDEO_SETTINGS to better reflect the module name.
  • Camera::setCameraSettings now takes the enum and a value. Default values are enabled through an alias VIDEO_SETTINGS_AUTO (=-1)
  • CAMERA_SETTINGS_WHITEBALANCE has been renamed in VIDEO_SETTINGS::WHITEBALANCE_TEMPERATURE since it controls the manually-adjustable color temperature of the camera.
  • CAMERA_SETTINGS_AUTO_WHITEBALANCE has been changed to VIDEO_SETTINGS::WHITEBALANCE_AUTO. It only controls whether the camera will use automatic or manual white balance. If the manual mode is set, then the color temperature can be controlled with VIDEO_SETTINGS::WHITEBALANCE_TEMPERATURE. Note that setting a value to VIDEO_SETTINGS::WHITEBALANCE_TEMPERATURE will automatically disable VIDEO_SETTINGS::WHITEBALANCE_AUTO.
  • Added VIDEO_SETTINGS::AEC_AGC to control if the Exposure/Gain are in automatic mode or not. This was previously mixed into the default value of Exposure or gain control and is now separated.
  • Added VIDEO_SETTINGS::SHARPNESS, a digital two-pass sharpening control that improves image quality.
  • Camera::getResolution has been moved to Camera::getCameraInformation().camera_resolution
  • Camera::getCameraFPS has been moved to Camera::getCameraInformation().camera_fps
  • MAT_TYPE format enums are slightly modified to fit the new convention: MAT_TYPE_32F_X and MAT_TYPE_8U_X are now respectively MAT_TYPE::F32_X and MAT_TYPE::U8_X.
  • Added InitParameters::image_enhancement for improved image quality. Available for ZED, ZED-M and ZED 2.
Recording
  • Adding RecordingParameters struct (input of enableRecording function)
  • RecordingState has been renamed into RecordingStatus for homogenization
  • Camera::record() function has been removed:
  • enableRecording() will automatically start recording, and disableRecording() will stop it. Camera::grab() now contains the previous per-frame record function internally.
  • Added getRecordingStatus() to get info about the RecordingStatus.
  • Removed isRecordingEnabled() function, which is now merged with getRecordingStatus.
  • SVO_COMPRESSION_MODE: AVCHD and HEVC have been renamed to H264 and H265.
  • Removed deprecated RAW and LOSSY modes for recording in the SDK. ZED Explorer can still record in LOSSY mode if H264/H265 is not supported (ex: when not using an NVIDIA graphics card).
  • Added pause recording function pauseRecording().
Streaming
  • STREAMING_CODEC: AVCHD and HEVC are renamed into H264 and H265
  • Adding StreamingParameters::chunk_size attribute.
Depth
  • DepthRange related functions like setDepthMaxRangeValue() are converted to parameters like depth_maximum_distance in the InitParameters. As a result, the maximum depth range is no longer a dynamic parameter.
  • DepthConfidence related parameters are moved into RuntimeParameters
  • DEPTH_MODE_MEDIUM has been removed. Use PERFOMANCE, QUALITY or ULTRA instead.
Positional Tracking
  • Positional Tracking module functions have been renamed to include "positional" :
    • Camera::enableTracking -> Camera::enablePositionalTracking
    • Camera::disableTracking -> Camera::disablePositionalTracking
    • Camera::resetTracking -> Camera::resetPositionalTracking
    • Camera::isTrackingEnabled -> Camera::isPositionalTrackingEnabled
    • TrackingParameters -> PositionalTrackingParameters
    • TRACKING_STATE -> POSITIONAL_TRACKING_STATE
  • PositionalTrackingParameters::enable_spatial_memory has been renamed to enable_area_memory to make the naming consistent with other references to this memory.
  • Rename Camera::saveCurrentArea() to Camera::saveAreaMap().
  • Rename AREA_EXPORT_STATE to AREA_EXPORTING_STATE.
Spatial Mapping
  • Removing all deprecated Mesh functions: requestMeshAsync(), getMeshRequestStatusAsync(), retrieveMeshAsync(), extractWholeMesh(). The overloaded SpatialMap functions, which include support for both Mesh and FusedPointCloud, should be used instead.
  • extractWholeSpatialMap is now smarter. If a previously retrieved map is given as an argument, it only retrieves the updated difference.
  • Removing Texture class as it is redundant with a simple sl::Mat
Object Detection
  • New module that detects and tracks objects in 2D and 3D, such as people. Available only for ZED 2.
  • Added enable/disableObjectDetection() and retrieveObjects() functions.
  • Added ObjectData class to hold information about each detected object, such as 2D and 3D bounding boxes, tracking information, dimensions, and its 2D mask.
  • New ERROR_CODE: MODULE_NOT_COMPATIBLE_WITH_CAMERA

Conclusion

Moving from ZED SDK 2.8 to 3.0 should be quick and easy, and brings many performance improvements along with its new features. For more information, take a look at our improved online documentation or contact our Support team. We’d be happy to help you make the switch to 3.0.