Getting Started with ROS 2 and ZED

The ZED ROS 2 wrapper lets you use the ZED stereo cameras with the second version of ROS. It provides access to the following data:

  • Left and right rectified/unrectified images.
  • Depth data.
  • Colored 3D point cloud.
  • IMU data.
  • Visual odometry: Position and orientation of the camera
  • Pose tracking: Position and orientation of the camera fixed and fused with IMU data.
  • Detected objects.
  • Human body skeleton.

Installation #

Prerequisites #

Build the package #

The zed_ros2_wrapper is a colcon package.

Note: If you haven’t set up your colcon workspace yet, please follow this tutorial.

To install the zed_ros2_wrapper, open a bash terminal, clone the package from GitHub, and build it:

$ cd ~/ros2_ws/src/ #use your current ros 2 workspace folder
$ git clone --recursive https://github.com/stereolabs/zed-ros2-wrapper.git
$ cd ..
$ rosdep install --from-paths src --ignore-src -r -y
$ colcon build --symlink-install --cmake-args=-DCMAKE_BUILD_TYPE=Release
$ echo source $(pwd)/install/local_setup.bash >> ~/.bashrc
$ source ~/.bashrc

Note: The zed-ros2-wrapper repository contains the repository zed-ros2-interfaces as a sub-module. zed-ros2-interfaces contains the definitions of the custom topics and services, and the meshes for the 3D visualization of the camera models on rviz 2. It is very important to use the command --recursive while cloning the repository to retrieve also the latest version of the sub-module repository.

Note: The option --symlink-install is very important. It allows using symlinks instead of copying files to the ROS 2 folders during the installation, where possible. Each package in ROS 2 must be installed and all the files used by the nodes must be copied into the installation folders. Using symlinks allows you to modify them in your workspace, reflecting the modification during the next executions without the needing to issue a new colcon build command. This is true only for all the files that don’t need to be compiled (Python launch scripts, YAML configurations, etc).

Note: If you are using a different console interface like zsh, you have to change the source command as follows: echo source $(pwd)/install/local_setup.zsh >> ~/.zshrc and source ~/.zshrc.

Starting the ZED node #

To start the ZED node, open a terminal and use the CLI command ros2 launch:

ZED:

$ ros2 launch zed_wrapper zed.launch.py

ZED Mini:

$ ros2 launch zed_wrapper zedm.launch.py

ZED 2:

$ ros2 launch zed_wrapper zed2.launch.py

ZED 2i:

$ ros2 launch zed_wrapper zed2i.launch.py

ZED X:

$ ros2 launch zed_wrapper zedx.launch.py

ZED X Mini:

$ ros2 launch zed_wrapper zedxm.launch.py

The zed.launch.py, zedm.launch.py, zed2.launch.py, zed2i.launch.py, zedx.launch.py, and zedxm.launch.py are Python scripts that automatically start the ZED node using “manual composition”, loading the parameters from the correct “YAML files”, and creating the camera model from the “URDF file” that is automatically created from a xacro configuration file.

Note: You can set your own configurations by modifying the parameters in the files common.yaml, zed.yaml, zedm.yaml, zed2.yaml, zed2i.yaml, zedx.yaml, and zedxm.yaml available in the folder zed_wrapper/config. For full descriptions of each available parameter, follow the complete guide.

Displaying ZED data #

Using rviz 2 #

rviz 2 is a useful visualization tool in ROS 2. Using rviz 2, you can visualize the left and right images acquired by the ZED cameras, the depth image and the 3D colored point cloud, plus other useful information.

Launch the ZED wrapper along with rviz 2 by using the following command (installing the zed-ros2-examples repository is required):

$ ros2 launch zed_display_rviz display_zed.launch.py

If you are using a ZED Mini camera:

$ roslaunch zed_display_rviz display_zedm.launch.py

If you are using a ZED 2 camera:

$ roslaunch zed_display_rviz display_zed2.launch.py

If you are using a ZED 2i camera:

$ roslaunch zed_display_rviz display_zed2i.launch.py

If you are using a ZED X camera:

$ roslaunch zed_display_rviz display_zed2i.launch.py

If you are using a ZED X Mini camera:

$ roslaunch zed_display_rviz display_zed2i.launch.py

Note: If you haven’t yet configured your own rviz 2 interface, you can find a detailed tutorial here.

Displaying Images #

The ZED node publishes both original and stereo-rectified (aligned) left and right images. In rviz 2, select a topic and use the image preview mode.

Here is a list of the main available image topics (more image topics are available):

  • rgb/image_rect_color: Color rectified image (left image by default)
  • rgb/image_raw_color: Color unrectified image (left image by default)
  • right/image_rect_color: Color rectified right image
  • right/image_raw_color: Color unrectified right image
  • left/image_rect_color: Color rectified left image
  • left/image_raw_color: Color unrectified left image
  • confidence/confidence_image: Confidence map

Displaying Depth #

The depth map can be displayed in RVIZ subscribing to the following topic:

  • depth/depth_registered: 32-bit depth values in meters. RVIZ will normalize the depth map on 8-bit and display it as a grayscale depth image.

Note: An OpenNI compatibility mode is available by modifying the config/common.yamlfile. Setdepth.openni_depth_modetotrue` to get depth in millimeters with 16-bit precision, then restart the ZED node.

Displaying the Point cloud #

A 3D colored point cloud can be displayed in rviz 2 subscribing to the point_cloud/cloud_registered topic.

Add it in rviz 2 with point_cloud -> cloud -> PointCloud2.

Note: Displaying point clouds slows down rviz 2, so open a new instance if you want to display other topics.

Displaying Position and Path #

The ZED position and orientation in space over time are published on the following topics:

  • odom: Odometry pose referred to odometry frame (only visual odometry is applied for ZED, visual-inertial for ZED Mini)
  • pose: Camera pose referred to Map frame (complete data fusion algorithm is applied)
  • pose_with_covariance: Camera pose referred to Map frame with covariance (if spatial_memory is false in launch parameters)
  • path_odom: The sequence of camera odometry poses in Map frame
  • path_map: The sequence of camera poses in Map frame

Launching with a recorded SVO video #

With the ZED, you can record and play back stereo video using Stereolabs’ SVO file format. To record a sequence, open the ZED Explorer app (/usr/local/zed/tools) and click on the REC button.

To launch the ROS wrapper with an SVO file, set the relative parameter while starting the node. For example, to start the ZED 2 node using the SVO as input source:

$ ros2 launch zed_wrapper zed2i.launch.py svo_path:=<full_path_to_svo_file>

with rviz 2:

$ ros2 launch zed_display_rviz2 display_zed2i.launch.py svo_path:=<full_path_to_svo_file>

Important: Use only full paths to the SVO file. Relative paths are not allowed.

Dynamic reconfigure #

You can dynamically change many configuration parameters during the execution of the ZED node. All the parameters that can be dynamically changed while the node is running are marked as [DYNAMIC] in the YAML configuration files. For a full description of each parameter please read the complete guide.

You can set the parameters by using the CLI command ros2 param set, e.g.:

$ ros2 param set /zed2/zed_node depth.depth_confidence 80

if the parameter is successfully set you will get a confirmation message:

Set parameter successful

If you try to set a parameter that’s not dynamically reconfigurable, or if you provided an invalid value, you will get this error:

$ ros2 param set /zed2/zed_node depth.depth_confidence 150
Setting parameter failed: depth.depth_confidence must be a positive integer in the range [0,100]

You can also use a GUI to set dynamic parameters values:

$ rqt

then select Plugins -> Configuration -> Dynamic Reconfigure

Node Diagnostic #

The ZED ROS 2 node publishes useful diagnostic information aggregated into the /diagnostics topic. Diagnostic information can be analyzed and parsed by using ROS 2 tools, like for example the Runtime Monitor plugin of rqt