ROS - ZED Node

To start a ZED ROS node you can use the following commands in a shell console:

• ZED:

$ roslaunch zed_wrapper zed.launch

• ZED Mini:

$ roslaunch zed_wrapper zedm.launch

• ZED 2:

$ roslaunch zed_wrapper zed2.launch

• ZED 2i:

$ roslaunch zed_wrapper zed2i.launch

Published Topics

The ZED node publishes data to the following topics:

• Left camera

  • rgb/image_rect_color: Color rectified image (left RGB image by default)
  • rgb/image_rect_gray: Grayscale rectified image (left RGB image by default)
  • rgb_raw/image_raw_color: Color unrectified image (left RGB image by default)
  • rgb_raw/image_raw_gray: Grayscale unrectified image (left RGB image by default)
  • rgb/camera_info: Color camera calibration data
  • rgb_raw/camera_info: Color unrectified camera calibration data
  • left/image_rect_color: Left camera color rectified image
  • left/image_rect_gray: Left camera grayscale rectified image
  • left_raw/image_raw_color: Left camera color unrectified image
  • left_raw/image_raw_gray: Left camera grayscale unrectified image
  • left/camera_info: Left camera calibration data
  • left_raw/camera_info: Left unrectified camera calibration data

• Right camera

  • right/image_rect_color: Color rectified right image
  • right_raw/image_raw_color: Color unrectified right image
  • right/image_rect_gray: Grayscale rectified right image
  • right_raw/image_raw_gray: Grayscale unrectified right image
  • right/camera_info: Right camera calibration data
  • right_raw/camera_info: Right unrectified camera calibration data

• Stereo pair

  • stereo/image_rect_color: stereo rectified pair images side-by-side
  • stereo_raw/image_raw_color: stereo unrectified pair images side-by-side

  Note: to retrieve the camera parameters you can subscribe to the topics left/camera_info, right/camera_info, left_raw/camera_info and right_raw/camera_info

• Depth and point cloud

  • depth/depth_registered: Depth map image registered on left image (32-bit float in meters by default)
  • depth/camera_info: Depth camera calibration data
  • point_cloud/cloud_registered: Registered color point cloud
  • confidence/confidence_map: Confidence image (floating point values to be used in your own algorithms)
  • disparity/disparity_image: Disparity image

• Tracking

  • odom: Absolute 3D position and orientation relative to the Odometry frame (pure visual odometry for ZED, visual-inertial for ZED-M and ZED 2)
  • pose: Absolute 3D position and orientation relative to the Map frame (Sensor Fusion algorithm + SLAM + Loop closure)
  • pose_with_covariance: Camera pose referred to Map frame with covariance
  • path_odom: Sequence of camera odometry poses in Map frame
  • path_map: Sequence of camera poses in Map frame

• Mapping

  • mapping/fused_cloud: Fused color point cloud

  Note: published only if mapping is enabled, see mapping/mapping_enabled parameter

• Sensor Data

  • imu/data: Accelerometer, gyroscope, and orientation data in Earth frame [only ZED-M and ZED 2]
  • imu/data_raw: Accelerometer and gyroscope data in Earth frame [only ZED-M and ZED 2]
  • imu/mag: Calibrated magnetometer data [only ZED 2]
  • atm_press: Atmospheric pressure data [only ZED 2]
  • temperature/imu: Temperature of the IMU sensor [only ZED 2]
  • temperature/left: Temperature of the left camera sensor [only ZED 2]
  • temperature/right: Temperature of the right camera sensor [only ZED 2]
  • left_cam_imu_transform: Transform from left camera sensor to IMU sensor position

• Object Detection [only ZED 2]

  • objects: array of the detected/tracked objects for each camera frame [only ZED 2]
  • object_markers: array of markers of the detected/tracked objects to be rendered in Rviz [only ZED 2]

• Diagnostic

  • /diagnostics: ROS diagnostic message for ZED cameras

ZED parameters

You can specify the parameters to be used by the ZED node modifying the values in the files

• params/common.yaml: common paramters to all camera models
• params/zed.yaml: parameters for the ZED camera
• params/zedm.yaml: parameters for the ZED Mini camera
• params/zed2.yaml: parameters for the ZED 2 camera
• params/zed2i.yaml: parameters for the ZED 2i camera

GENERAL PARAMETERS

Parameters with prefix general

VIDEO PARAMETERS

Parameters with prefix video

DEPTH PARAMETERS

Parameters with prefix depth

POSITION PARAMETERS

Parameters with prefix pos_tracking

MAPPING PARAMETERS

Parameters with prefix mapping

SENSORS PARAMETERS (ONLY ZED-M, ZED 2, AND ZED 2I)

Parameters with prefix sensors

OBJECT DETECTION PARAMETERS (ONLY ZED 2 AND ZED 2I)

Parameters with prefix object_detection

Dynamic parameters

The ZED node lets you reconfigure these parameters dynamically:

To modify a dynamic parameter, you can use the GUI provided by the rqt stack:

$ rosrun rqt_reconfigure rqt_reconfigure

Transform frames

The ZED ROS wrapper broadcasts multiple coordinate frames that each provide information about the camera’s position and orientation. If needed, the reference frames can be changed in the launch file.

• base_frame is the current position and orientation of the reference base of the robot
• <camera_name>_camera_center is the current position and orientation of ZED, determined by visual odometry and the tracking module
• <camera_name>_right_camera is the position and orientation of the ZED’s right camera
• <camera_name>_right_camera_optical is the position and orientation of the ZED’s right camera optical frame
• <camera_name>_left_camera is the position and orientation of the ZED’s left camera
• <camera_name>_left_camera_optical is the position and orientation of the ZED’s left camera optical frame
• <camera_name>_imu_link is the origin of the inertial data frame (ZED-M and ZED2 only)
• <camera_name>_mag_link is the origin of the magnetometer frame (ZED2 only)
• <camera_name>_baro_link is the origin of the barometer frame (ZED2 only)
• <camera_name>_temp_left_link is the origin of the left temperature frame (ZED2 only)
• <camera_name>_temp_right_link is the origin of the right temperature frame (ZED2 only)

For RVIZ compatibilty, the root frame map_frame is called map. The TF tree generated by the zed_wrapper reflects the standard descripted in REP105. The odometry frame is updated using only the “visual odometry” information. The map frame is updated using the Tracking algorithm provided by the Stereolabs SDK, fusing the inertial information from the IMU sensor if using a ZED-M camera.

map_frame (`map`)
└─odometry_frame (`odom`)
   └─base_frame (`base_link`)
      └─camera_frame (`<camera_name>_camera_center`)
      |  └─left_camera_frame (`<camera_name>_left_camera_frame`)
      |  |     └─left_camera_optical_frame (`<camera_name>_left_camera_optical_frame`)
      |  |     └─left_temperature:frame (`<camera_name>_temp_left_link`)
      |  └─right_camera_frame (`<camera_name>_right_camera_frame`) (*only ZED 2 and ZED2i*)
      |        └─right_camera_optical_frame (`<camera_name>_right_camera_optical_frame`)
      |        └─left_temperature:frame (`<camera_name>_temp_left_link`)
      └─imu_frame (`<camera_name>_imu_link`) (*only ZED-M and ZED 2 and ZED2i*)
      └─magnetometer_frame (`<camera_name>_mag_link`) (*only ZED 2 and ZED2i*)
      └─barometer_frame (`<camera_name>_baro_link`) (*only ZED 2 and ZED2i*)

ZED-M

The ZED-M provides the same information as the ZED, plus the inertial data from the IMU sensor. The IMU data are used internally to generate the pose in the Map frame with the Tracking sensor fusion algorithm.

Note: The initial pose in Odometry frame can be set to the first pose received by the Tracking module by setting the parameter init_odom_with_first_valid_pose to true.

ZED 2 / ZED 2i

The ZED 2 and ZED 2i provide the same information as the ZED and the ZED-M, plus the data from a new set of sensors. The ZED 2 and ZED 2i provide magnetometer data to get better and absolute information about the YAW angle, atmospheric pressure information to be used to estimate the height of the camera respect to a reference point and temperature information to check the camera health in a complex robotic system.

Services

The ZED node provides the following services:

• reset_tracking: Restarts the Tracking module setting the initial pose to the value available in the param server.
• reset_odometry: Resets the odometry values eliminating the drift due to the Visual Odometry algorithm, setting the new odometry value to the latest camera pose received from the tracking module.
• set_pose: Sets the current pose of the camera to the value passed as single parameters -> X, Y, Z [m], R, P, Y [rad].
• save_area_memory: Triggers the saving of the current area memory used for relocation, if area memory is enabled.
• set_led_status: Sets the status of the blue led -> True: LED ON, False: LED OFF.
• toggle_led: Toggles the status of the blue led, returning the new status.
• start_svo_recording: Starts recording an SVO file. If no filename is provided the default zed.svo is used. If no path is provided with the filename the default recording folder is ~/.ros/.
• stop_svo_recording: Stops an active SVO recording.
• start_remote_stream: Starts streaming over network to allow processing of ZED data on a remote machine. See Remote streaming.
• stop_remote_stream: Stops streaming over network.
• start_3d_mapping: Starts the Spatial Mapping processing. See Spatial Mapping.
• stop_3d_mapping: Stops the Spatial Mapping processing (works even with automatic start from configuration file).
• save_3d_map: Triggers the saving of the current 3D fused point cloud if the mapping module is enabled.
• start_object_detection: Starts the Object Detection processing. See Object Detection Note: returns error if not using a ZED 2 camera.
• stop_object_detection: Stops the Object Detection processing (works even with automatic start from configuration file).

Note: Currently the H26x SVO compression uses the resolution and the real FPS to calculate the bitrate. This feature can lead to some issues of quality when FPS is low. On Nvidia Jetson TX1 and Jetson TX2, the FPS is quite low at the beginning of the grab loop, therefore it could be better to wait for some grab calls before calling start_svo_recording so that the camera FPS is stabilized at the requested value (15fps or more).

Remote streaming

With SDK v2.8 has been introduced the capability to acquire ZED data and to stream it on a remote machine over network. This features is useful when the ZED is connected to a machine with limited CUDA capabilities while a high definition analysis is required. Starting the streaming without activating any other feature (i.e. depth processing, positional tracking, point cloud publishing, …) requires only the power for H264 or H265 compression.

To start streaming the service start_remote_stream must be called with the following parameters:

• codec (def. 0): Defines the codec used for streaming (0: AVCHD [H264], 1: HEVC [H265]) Note: If HEVC (H265) is used, make sure the recieving host is compatible with HEVC decoding (basically a pascal NVIDIA card). If not, prefer to use AVCHD (H264) since every compatible NVIDIA card supports AVCHD decoding
• port (def. 30000): Defines the PORT the data will be streamed on. Note: port must be an even number. Any odd number will be rejected uint16 port=30000
• bitrate (def. 2000): Defines the streaming BITRATE in Kbits/s
• gop_size (def. -1): Defines the GOP SIZE in frame unit. Note: if value is set to -1, the gop size will match 2 seconds, depending on camera fps. The gop size determines the maximum distance between IDR/I-frames. Very high GOP size will result in slightly more efficient compression, especially on static scene. But it can result in more latency if IDR/I-frame packet are lost during streaming. Maximum allowed value is 256 (frames)
• adaptative_bitrate (def. False): Enable/Disable adaptive bitrate. Note: Bitrate will be adjusted regarding the number of packet loss during streaming. If activated, bitrate can vary between [bitrate/4, bitrate]. Currently, the adaptive bitrate only works when “sending” device is a NVIDIA jetson (X1,X2,Xavier,Nano)

RECEIVE A REMOTE STREAM

To acquire the streaming on a remote machine start a ZED node with the following command:

$ roslaunch zed_wrapper zed.launch stream:=<sender_IP>:<port>

For example:

$ roslaunch zed_wrapper zed.launch stream:=192.168.1.127:30000

Note: the stream contains only visual information. Using a ZED-M camera the inertial topic will not be available if not subscribed using ROS standard methods.

Spatial Mapping

The ZED node provides a basilar mapping module publishing a 3D map of the environment as 3D color point cloud (mapping/fused_cloud).

Spatial Mapping is disabled by default as it’s an heavy consuming process, it can be enabled setting to true the parameter mapping/mapping_enabled in the file params/common.yaml.

Spatial Mapping can be enabled manually at any time using the start_3d_mapping service.

To reduce the computational power requirements use value higher than 0.1 m for resolution_m and decrease the value of fused_pointcloud_freq to reduce the frequency of the point cloud topic publishing.

It is possible to save the generated 3D map as a pointcloud in format OBJ, OBJ binary or PLY, by calling the service save_3d_map.

Object Detection

Using the ZED 2 or ZED 2i camera unlocks the Object Detection module that allows to detect and track Human skeletons and Objects.

Object detection is disabled by default as it’s an heavy consuming process, it can be automatically enabled when the node starts setting to true the parameter object_detection/od_enabled in the file params/zed2.yaml or params/zed2i.yaml.

If Object Detection is disabled it can be manually enabled at any time using the start_object_detection service. See Object Detection parameters for more info about the meaning of each parameter used with the service.

The list of the detected objects is published as a custom topic of type ObjectStamped, defined in the package zed_interfaces. For details about the topic fileds please read the Object Detection full documentation.

OBJECT TRACKING

Enabling Object Tracking allows to get information frame by frame about the status of each detected object. The same object is identified with the same ID in all the frames after its first detection and its position is estimated if an occlusion occurs.

Each detected object can get four different values about their Tracking Status:

• OFF - The tracking is not yet initialized, the object ID is not usable
• OK - The object is tracked
• SEARCHING - The object couldn’t be detected in the image and is potentially occluded, the trajectory is estimated
• TERMINATE - This is the last searching state of the track, the track will be deleted in the next retreiveObject

Diagnostic

The ZED node publishes diagnostic information that can be used by the robotics system using a diagnostic_aggregator node.

Using the Runtime monitor plugin of rqt it is possible to get all the diagnostic information and check that the node is working as expected: 

A brief explanation of each field:

• Component: name of the diagnostic component
• Message: summary of the status of the ZED node
• HardwareID: Model of the ZED camera and its serial number
• Capture: grabbing frequency (if video or depth data are subscribed) and the percentage respect to the camera frame rate
• Processing time: time in seconds spent to elaborate data and the time limit to achieve max frame rate
• Playing SVO: (visible only if playng an SVO file) current frame position in the SVO file over the total frame count
• Depth status: indicates if the depth processing is performed
• Point Cloud: point cloud publishing frequency (if there is at least a subscriber) and the percentage respect to the camera frame rate
• Floor Detection: if the floor detection is enabled, indicates if the floor has been detected and the camera position correctly initialized
• Tracking status: indicates the status of the positional tracking, if enabled
• Object data processing: if Object Detection is enabled indicates the time required to process the data relative to detected objects
• IMU: the publishing frequency of the IMU topics, if the camera is the ZED Mini and there is at least a subscriber
• Left CMOS Temp.: (only ZED 2) the temperature of the CMOS of the left camera sensor [-273.15°C if not valid]
• Right CMOS Temp.: (only ZED 2) the temperature of the CMOS of the right camera sensor [-273.15°C if not valid]
• SVO Recording: indicates if the SVO recording is active
• SVO Compression time: average time spent on frame compressing
• SVO Compression ratio: average frame compression ratio

Using multiple ZEDs

It is possible to use multiple ZED cameras with ROS. Simply launch the node with the zed_multi_cam.launch file:

$ roslaunch zed_wrapper zed_multi_cam.launch

Assigning a GPU to a camera

To improve performance, you can specify the gpu_id of the graphic card that will be used for the depth computation in the launch file. The default value (-1) will select the GPU with the highest number of CUDA cores. When using multiple ZEDs, you can assign each camera to a GPU to increase performance.

Limitations

PERFORMANCE

This wrapper lets you quickly prototype applications and interface the ZED with other sensors and packages available in ROS. However, the ROS layer introduces significant latency and a performance hit. If performance is a major concern for your application, please consider using the ZED SDK library.

MULTIPLE ZEDS

The ZED camera uses the maximum bandwidth provided by USB 3.0 to output video. When using multiple ZEDs, you may need to reduce camera framerate and resolution to avoid corrupted frames (green or purple frames). You can also use multiple GPUs to load-balance computations and improve performance.