ROS 2 - ZED Stereo Node
The easiest way to start a ZED ROS 2 node for a stereo camera is by using the command line:
where <camera model> must be replaced with one in the list zed, zedm, zed2, zed2i, zedx, zedxm, zedxnano, and virtual.
Published Topics
Not all the topics are advertised by default. The version v5.1.0 of the ROS 2 Wrapper introduces new parameters to enable/disable the publishing of each topic. Please refer to the “Configuration parameters” section for more details.
The ZED node publishes data to the following topics:
-
Status
~/status/health: the general status of the node (custom message).~/status/heartbeat: heartbeat signal to monitor if the node is alive from other nodes (custom message).~/status/svo: the status of the SVO playback (custom message). Only advertised when an SVO file is used as input.
-
Image streams
The image topic names are created using the following naming convention:
~/<sensor_type>/<color_model>/<rect_type>/image
Starting from version 5.1.0 of the ROS 2 Wrapper the new convention replaces the previous formats such as ~/<sensor_type>/image_<rect_type>_<color_model> and ~/<sensor_type>_<rect_type>/image_<rect_type>_<color_model> (e.g., ~/left/image_rect_color, ~/rgb_raw/image_raw_gray). Please update your launch files and scripts to use the new topic names.
-
RGB channel
~/rgb/color/rect/image: Color rectified image.~/rgb/color/rect/camera_info: Color camera calibration data.~/rgb/gray/rect/image: Grayscale rectified image.~/rgb/gray/rect/camera_info: Grayscale camera calibration data.~/rgb/color/raw/image: Color unrectified image.~/rgb/color/raw/camera_info: Color raw calibration data.~/rgb/gray/raw/image: Grayscale unrectified image.~/rgb/gray/raw/camera_info: Grayscale raw calibration data.
-
Left channel
~/left/color/rect/image: Left sensor RGB rectified image.~/left/color/rect/camera_info: Left sensor RGB camera calibration data.~/left/gray/rect/image: Left sensor Grayscale rectified image.~/left/gray/rect/camera_info: Left sensor Grayscale camera calibration data.~/left/color/raw/image: Left sensor RGB unrectified image.~/left/color/raw/camera_info: Left sensor RGB raw calibration data.~/left/gray/raw/image: Left sensor Grayscale unrectified image.~/left/gray/raw/camera_info: Left sensor Grayscale raw calibration data.
-
Right channel
~/right/color/rect/image: Right sensor RGB rectified image.~/right/color/rect/camera_info: Right sensor RGB camera calibration data.~/right/gray/rect/image: Right sensor Grayscale rectified image.~/right/gray/rect/camera_info: Right sensor Grayscale camera calibration data.~/right/color/raw/image: Right sensor RGB unrectified image.~/right/color/raw/camera_info: Right sensor RGB raw calibration data.~/right/gray/raw/image: Right sensor Grayscale unrectified image.~/right/gray/raw/camera_info: Right sensor Grayscale raw calibration data.
Since v5.5.0 of the ROS 2 Wrapper the distortion_model and the distortion coefficients published in the camera_info topics are read from the ZED SDK (>= 5.4) instead of a hard-coded per-model table that the lens does not always follow: a fisheye ZED X One now reports equidistant instead of rational_polynomial. Rectified parameters are reported as plumb_bob with zero coefficients.
The rgb and left channels of stereo cameras are identical. We use both names to differentiate the usage: while left and right are used for stereo processing, rgb is associated with the synchronized depth map.
-
Stereo pair
~/stereo/color/rect/image: side-by-side left/right rectified stereo pair. Calibration data are available in the topics:~/left/color/rect/camera_infoand~/right/color/rect/camera_info.~/stereo/color/raw/image: side-by-side left/right unrectified stereo pair. Calibration data are available in the topics:~/left/color/raw/camera_infoand~/right/color/raw/camera_info.
-
Depth and point cloud
~/depth/camera_info: Depth camera calibration data.~/depth/depth_registered: Depth map image registered on left image.~/image/depth_image: colorized depth image, for visualization only (published only whendepth.publish_depth_imageistrue). Since v5.6.0 of the ROS 2 Wrapper.~/depth/depth_info: minimum and maximum depth information (custom message).~/point_cloud/cloud_registered: Registered color point cloud.~/confidence/confidence_map: Confidence image (floating point values).~/disparity/map: disparity map, of typestereo_msgs/msg/DisparityImage, to be used for depth processing.~/disparity/image: normalized disparity map, of typesensor_msgs/msg/Image, for visualization purposes. This is the topic to subscribe to in RViz 2.
The topic ~/disparity/disparity_image is obsolete since v5.4.0 of the ROS 2 Wrapper and is replaced by the two topics above. To visualize the disparity map, run ros2 run image_view disparity_view --ros-args -r image:=/zed/zed_node/disparity/map.
-
Region of Interest
~/roi_mask/image: the Region of Interest mask applied to the ZED SDK processing. See the Region of Interest page.
-
Sensors data
~/left_cam_imu_transform: Transform from the left camera sensor to the IMU sensor.~/imu/data: Accelerometer, gyroscope, and orientation data in Earth frame.~/imu/data_raw: Accelerometer and gyroscope data in Earth frame.~/imu/mag: Raw magnetometer data (only ZED 2 and ZED 2i).~/atm_press: atmospheric pressure (only ZED 2 and ZED 2i).~/temperature/imu: temperature measured by the IMU sensor.~/temperature/left: temperature measured near the left CMOS sensor (only ZED 2 and ZED 2i).~/temperature/right: temperature measured near the right CMOS sensor (only ZED 2 and ZED 2i).
-
Positional tracking
~/pose: Absolute 3D position and orientation relative to the Map frame (Sensor Fusion algorithm + SLAM).~/pose/status: the status of the positional tracking module (custom message).~/pose/motion_prior_links: the links held by the motion prior between keyframes, as avisualization_msgs/Markerfor RViz 2 (published only whenpos_tracking.motion_prior.enabledistrue) [ZED SDK >= 5.6]. See Motion prior.~/pose_with_covariance: Camera pose referred to Map frame with covariance.~/odom: Absolute 3D position and orientation relative to the Odometry frame (visual-inertial odometry on cameras equipped with an IMU, pure visual odometry on the original ZED).~/odom/status: the status of the odometry from the positional tracking module (custom message).~/path_map: Sequence of camera poses in Map frame.~/path_odom: Sequence of camera odometry poses in Map frame.~/pose/landmarks: the 3D landmarks used by the positional tracking algorithm, published as asensor_msgs/msg/PointCloud2message.
-
Geo Tracking
~/pose/filtered: the GNSS fused pose of the robot~/pose/filtered/status: the status of the GNSS fused pose (custom message).~/geo_pose: the Latitude/Longitude pose of the robot~/geo_pose/status: the status of the Latitude/Longitude pose (custom message).~/pose/fused_fix: the GNSS fused fix of the robot, published as asensor_msgs/msg/NavSatFixmessage.~/pose/origin_fix: the Latitude/Longitude of the origin of themapframe, published as asensor_msgs/msg/NavSatFixmessage.
-
3D Mapping
~/mapping/fused_cloud: Fused point cloud created when theenable_mappingservice is called.
-
Object Detection
~/obj_det/objects: detected objects (custom message).
-
Body Tracking
~/body_trk/skeletons: detected body skeletons (custom message).
-
Plane Detection
~/plane: Detected plane (custom message).~/plane_marker: Detected plane object to be displayed on RViz 2.
Each topic has a common prefix created by the launch file as ~ = /<namespace>/<node_name>/, where <namespace> is replaced with the value of the parameter camera_name and <node_name> is the name of the node, e.g. zed_node.
Image Transport
The ROS 2 wrapper supports the stack image_transport introduced with ROS 2 Crystal Clemmys.
Starting from version 5.3 of the ROS 2 Wrapper, image messages are published through rclcpp::TypeAdapter for more efficient handling:
- The base
rawtopic is handled by aTypeAdapterpublisher. Intra-process subscribers (e.g., other nodes running in the same component container) receive aStampedSlMatobject (a wrapper around the nativesl::Mat) directly, without any serialization overhead. Inter-process subscribers transparently receive a standardsensor_msgs/msg/Imagemessage thanks to the automaticTypeAdapterconversion. - The transport-specific variants are handled by an
image_transportpublisher. Itsrawtransport is disabled to avoid publishing duplicate messages, since therawstream is already provided by theTypeAdapterpublisher described above.
To prevent silent data corruption caused by incompatible plugin/encoding combinations (e.g., applying JPEG compression to floating-point depth data), the advertised image transports are filtered by topic type:
- Visual image topics (color and grayscale images) advertise only:
compressed: JPEG or PNG compressed imagetheora: Ogg Theora compressed imagezstd: lossless Zstandard-compressed image (available starting with ROS 2 Jazzy Jalisco)
- Measurement topics (e.g., depth) advertise only:
compressedDepth: depth image compressed with a lossless algorithmzstd: lossless Zstandard-compressed image (available starting with ROS 2 Jazzy Jalisco)
For proper association between images and their corresponding camera information, the ZED ROS 2 Wrapper also publishes camera_info topics for all compressed image streams:
~/rgb/color/rect/image/camera_info~/rgb/gray/rect/image/camera_info~/rgb/color/raw/image/camera_info~/rgb/gray/raw/image/camera_info
When the isaac_ros_nitros package is installed and NITROS is not disabled via the debug.disable_nitros parameter, NITROS publishers take priority and neither the TypeAdapter nor the image_transport publishers are created. Please refer to the dedicated section about NVIDIA® Isaac ROS Nitros for more details.
NVIDIA® Isaac ROS Nitros
The ZED ROS 2 Wrapper supports NITROS with NVIDIA® Isaac™ ROS 3.2. Isaac™ ROS 5 removed the NITROS packages: with Isaac™ ROS 5, the ZED node publishes standard ROS 2 messages and IPC is enabled automatically. See the ZED Isaac™ ROS Integration Overview.
The ZED ROS 2 Wrapper supports the NVIDIA® Isaac™ ROS Nitros package for zero-copy transport of ROS messages using NVIDIA® GPUDirect® RDMA.
NVIDIA® Isaac ROS Nitros integration is enabled and used only if the required packages are manually installed. They are not added as a dependency because this is an optional feature.
Starting from version 5.3 of the ROS 2 Wrapper, Intra-Process Communication (IPC) is handled automatically:
- If NITROS is not installed on the host machine, IPC is always enabled.
- If NITROS is installed, IPC is disabled and NITROS takes priority.
If you want to use IPC on a machine where NITROS is installed, set the debug.disable_nitros parameter to true to disable NITROS; IPC will then be enabled automatically. (This parameter has no effect when NITROS is not installed, since IPC is already active.)
IPC is also controlled by the enable_ipc launch argument of zed_camera.launch.py (default true). When NITROS is installed and debug.disable_nitros is false, IPC and NITROS conflict: with the default ipc_nitros_conflict_policy:=disable_ipc the launch file logs a warning and forces enable_ipc:=false for that launch. To use NITROS, you can also set enable_ipc:=false explicitly, as required by the Isaac ROS 3 integration. Set enable_ipc:=false as well when no component shares the container with the ZED node and you do not need intra-process delivery.
For more information about the installation and usage of the NVIDIA® Isaac™ ROS packages, please refer to the dedicated section of the documentation: ZED Isaac™ ROS Integration Overview.
Point Cloud Transport
The ROS 2 wrapper supports the stack pointcloud_transport introduced with ROS 2 Humble Hawksbill.
The point cloud transport is enabled and used only if the required packages are manually installed, they are not added as a dependency because this is an optional feature:
Point cloud topics are published using the point_cloud_transport::Publisher object, which provides both standard raw and compressed point cloud streams for efficient data transmission.
CUDA zero-copy transport
Starting with v5.6.0, on ROS 2 Lyrical and newer, the ZED ROS 2 Wrapper supports the rosidl::Buffer message fields and shares the data retrieved on the GPU without copies. In ROS 2 Lyrical, the uint8[] data field of messages such as sensor_msgs/msg/Image and sensor_msgs/msg/PointCloud2 is a rosidl::Buffer, whose memory can live on the GPU: the cuda buffer backend shares this GPU memory between a publisher and its subscribers.
The general.buffer_backend parameter selects how the data are published:
cuda(default): the images, the depth map, the confidence map, the colorized depth image, and the point cloud stay in GPU memory. The subscribers that accept thecudabackend and run on the same host, with the same GPU and the same Linux user, receive the GPU memory of the ZED node without copies. All the other subscribers, such as RViz2,ros2 bag, Python nodes, and nodes on other hosts, automatically receive standard CPU data, with no change on their side.cpu: the node always publishes standard CPU data, as in the previous versions.
The disparity map is always published from CPU memory. An invalid value is replaced by cuda, with a warning. On ROS 2 Humble and Jazzy, the parameter is ignored.
The CUDA zero-copy transport requires the cuda_buffer package when the wrapper is built, the cuda_buffer_backend plugin when the node runs, and the rmw_fastrtps_cpp middleware (Fast DDS), the default of ROS 2 Lyrical, or the rmw_zenoh_cpp middleware (Zenoh) v0.10.5 or newer. When a requirement is missing, the node publishes standard CPU data. At startup, the node logs the transport in use in the line that starts with * Buffer transport:, and the reason when it falls back to CPU data.
With the cuda backend, the node still publishes standard CPU data, for all the subscribers of a topic, in these cases:
- An rclcpp Intra-Process Communication (IPC) subscriber is connected to the topic: IPC delivers the messages without the buffer backend negotiation. To receive CUDA buffers in a node loaded in the ZED container, disable IPC for that node.
- The topic uses the
TRANSIENT_LOCALdurability, not supported by thecudabackend. - A compressed
point_cloud_transportplugin is subscribed to the point cloud: the uncompressed point cloud is then published with CPU data too.
The compressed image_transport topics always carry CPU data, and do not change how the uncompressed image topics are published. The topics published with NITROS are not affected.
The CUDA zero-copy transport guide of the Isaac™ ROS 5 integration explains how the transport works and how to set it up. To receive the CUDA buffers in your own C++ nodes, follow the image and the point cloud tutorials.
QoS profiles
All the topics are configured by default to use the following ROS 2 QoS profile:
- Reliability: RELIABLE
- History (Depth): KEEP_LAST (10)
- Durability: VOLATILE
- Lifespan: Infinite
- Deadline: Infinite
- Liveliness: AUTOMATIC
- Liveliness lease duration: Infinite
Read the official ROS 2 documentation about the QoS and the related settings for details.
The QoS settings can be modified by changing the relative parameters in the YAML files, as described in this official ROS 2 design document.
When creating a subscriber, be sure to use a compatible QoS profile according to the following tables:
Compatibility of QoS durability profiles:
Compatibility of QoS reliability profiles:
In order for a connection to be made, all of the policies that affect compatibility must be compatible. For instance, if a publisher-subscriber pair has compatible reliability QoS profiles, but incompatible durability QoS profiles, the connection will not be made.
For a detailed list of all the compatibility settings, please refer to the official ROS 2 documentation.
Configuration parameters
Specify your launch parameters in the common_stereo.yaml, zed.yaml, zedm.yaml, zed2.yaml, zed2i.yaml, zedx.yaml, zedxm.yaml, zedxnano.yaml, and virtual.yaml files available in the folder zed_wrapper/config.
General parameters
Namespace: general
common_stereo.yaml
* Dynamic parameter
timestamp_reference: 'IMAGE_CENTER_OF_EXPOSURE' requires an input that carries a per-frame exposure, that is a ZED X or a ZED X Mini, live, from an SVO or from a stream. On the USB models the node warns once and falls back to IMAGE. It is not applied to the sensors data, to the SVO /clock topic, nor in simulation.
Since v5.6.0 of the ROS 2 Wrapper, when the camera is disconnected while the node is running, the node waits general.camera_timeout_sec x general.camera_max_reconnect seconds (25 by default) for it to come back. If it does, the node resumes publishing; otherwise, the node closes the camera and stops as described in When the node stops. Previous versions either waited forever while the ZED SDK was reopening the camera, or were killed as soon as the ZED SDK reported the camera as not detected.
The same time is given to the ZED SDK to reopen a USB camera (InitParameters::open_timeout_sec), so a camera plugged back at any time during the wait resumes; as a consequence, each attempt to open the camera at start-up can also last up to that time.
While the camera is disconnected, the node diagnostic reports Camera disconnected: waiting for it to come back (N / 25 sec), and the Disconnections entry counts the disconnections of the session with the time of the last reconnection.
zed.yaml, zedm.yaml, zed2.yaml, zed2i.yaml, zedx.yaml, zedxm.yaml, zedxnano.yaml, and virtual.yaml
Valid grab_resolution values per camera model:
When the node stops
Since v5.6.0 of the ROS 2 Wrapper, a node that fails for good (the camera cannot be opened at start-up or does not come back after a disconnection or a reboot, invalid configuration, critical camera error) closes the camera and stops cleanly. The general.exit_on_failure parameter decides what happens next:
true: the whole process stops.zed_camera.launch.pysets this value when it creates the container, so the launch then ends andros2 launchreturns. The process exits with code 0, so a supervisor must restart it on any exit (e.g. systemdRestart=always, notRestart=on-failure).false(default): only this node stops, and the other nodes of the same container keep running, for example the other cameras started withzed_multi_camera.launch.py.zed_camera.launch.pysets this value when the node is loaded in an existing container (container_namelaunch argument). The node diagnostic reportsNode stoppedwith the reason; unload the node withros2 component unloadbefore loading it again.
Previous versions stopped the whole container when a node could not open its camera, usually with a crash, which also stopped the cameras of the other nodes in it.
SVO input parameters
Namespace: svo
common_stereo.yaml
* Dynamic parameter
SVO encryption requires OpenSSL (libcrypto) at runtime. The value of svo.encryption_key is never written to the log, and the same value must be set as svo.decryption_key to play the recording back: if the key is lost the recorded data is unrecoverable.
Streaming input parameters
Namespace: stream
common_stereo.yaml
Simulation input parameters
Namespace: simulation
common_stereo.yaml
Since v5.6.0 of the ROS 2 Wrapper [ZED SDK >= 5.6 on the simulator and on the node side], the video parameters (video.*, including their dynamic changes) are sent to the simulated camera, and the simulator applies the ones it supports. A setting the simulator does not support is reported once at the INFO level and not applied. With older ZED SDK versions the video parameters are ignored in simulation. See Using the ZED with ROS 2 in Isaac™ Sim to set up the simulated camera.
Streaming server parameters
Namespace: stream_server
common_stereo.yaml
Video parameters
Namespace: video
common_stereo.yaml
* Dynamic parameter
zed.yaml, zed2.yaml, and zed2i.yaml
* Dynamic parameter
zedx.yaml, zedxm.yaml, zedxnano.yaml, and virtual.yaml
* Dynamic parameter
The node accepts exposure_time and the auto_exposure_time_range_* values from 28 to 66,000 µs, but the camera applies only the exposure range of the video mode: from 39 µs (21 µs in SVGA) to one frame period, up to 65,000 µs at 15 fps. With ZED SDK 5.6, a value outside this range is not applied, and the node logs no warning.
Region of Interest parameters
Namespace: region_of_interest
common_stereo.yaml
Depth parameters
Namespace: depth
common_stereo.yaml
To disable depth calculation set depth_mode to NONE. All the other parameters relative to depth will be ignored and only the video streams and sensors data will be published.
* Dynamic parameter
zed.yaml, zedm.yaml, zed2.yaml, zed2i.yaml, zedx.yaml, zedxm.yaml, zedxnano.yaml, and virtual.yaml
* Dynamic parameter
Positional tracking parameters (Odometry and Localization)
Namespace: pos_tracking
common_stereo.yaml
* Dynamic parameter
Global Localization (GNSS Fusion)
Namespace: gnss_fusion
common_stereo.yaml
Mapping parameters
Namespace: mapping
common_stereo.yaml
* Dynamic parameter
Sensors parameters
Namespace: sensors
common_stereo.yaml
* Dynamic parameter
Since v5.6.0 of the ROS 2 Wrapper, when the input does not provide the IMU data at the sensor rate, such as an SVO recorded with the legacy SVO v1 format, the node logs a single warning and does not publish the sensors topics. Set sensors_image_sync to true to publish the IMU data at the camera frame rate with such an input: the sensors messages are then published together with the video and depth messages, so only while a node subscribes to a video or depth topic.
Since v5.6.0 of the ROS 2 Wrapper, the IMU sampling rate and ranges actually used by the camera are logged at start-up. With a ZED X driver older than 1.5.0, or with another camera model, the IMU keeps its default configuration and the ZED SDK logs a warning.
Starting from v5.5.0 of the ROS 2 Wrapper the sensors stream is read independently of grab(), so the IMU publishing delay no longer depends on general.grab_frame_rate nor on general.grab_compute_capping_fps. Measured on a ZED X on an AGX Orin, the median publish delay dropped from 411 ms to 10.5 ms and the output rate went from 92.6 Hz to the requested 100.0 Hz.
sensors.sensors_pub_rate is now decimated against the measured sample interval instead of the rate the ZED SDK advertises, so it is honored on cameras whose IMU does not run at the advertised rate (with ZED SDK 5.5 or earlier, a ZED X One GS advertises 400 Hz but delivers 200 Hz), and cameras that report correctly produce exactly the requested rate.
Two consequences of the reduced CPU usage of the sensors thread: a new subscriber to a sensors topic can wait up to 250 ms for its first message, and a subscriber whose QoS is incompatible with the publisher no longer triggers publishing (it could never receive the data anyway).
Object detection parameters
Namespace: object_detection
common_stereo.yaml
object_detection.yaml
* Dynamic parameter
custom_object_detection.yaml
FOR EACH CLASS CREATE THE FOLLOWING PARAMETERS
* Dynamic parameter
Body Tracking parameters
Namespace: body_tracking
common_stereo.yaml
* Dynamic parameter
Starting from v5.5.0 of the ROS 2 Wrapper the default body_tracking.body_format is BODY_34 instead of BODY_38, and body_tracking.enable_body_fitting defaults to true. Only BODY_18 and BODY_34 have a GEN_2 network, so the previous default silently fell back to the older GEN_1. Skeletons published on ~/body_trk/skeletons now carry 34 keypoints instead of 38: set body_format back to BODY_38 to keep the previous topology, at the cost of running GEN_1.
Advanced parameters
Namespace: advanced
These are advanced threading parameters. Do not modify them unless you are confident of what you are doing. The SCHED_FIFO and SCHED_RR scheduling policies require root privileges, the CAP_SYS_NICE capability, or an RTPRIO limit (ulimit -r) at least equal to the requested priority.
With GMSL2 cameras, ZED SDK >= 5.6 and ZED X driver >= 1.5.0 run the capture and sensors threads of the camera at SCHED_RR priority 5. The ZED SDK installer grants this priority to the members of the zed group, from their next login. A node started by a systemd service that does not run as root needs LimitRTPRIO=5 in the [Service] section, and a Docker container needs --ulimit rtprio=5 (or --cap-add=SYS_NICE). Otherwise, these threads run at normal priority and the ZED SDK logs how to allow it. Giving the node threads a higher real-time priority than 5 can delay the camera capture. Reference: sched(7).
common_stereo.yaml
Debug parameters
Namespace: debug
common_stereo.yaml
Dynamic parameters
The ZED node lets you reconfigure many parameters dynamically during the execution of the node. All the dynamic parameters are indicated with a * in the list above and with the tag [DYNAMIC] in the comments of the YAML files.
You can set the parameters using the CLI command ros2 param set, e.g.:
If the parameter is set successfully, you will get a confirmation message:
In the case you tried to set a parameter that’s not dynamically reconfigurable, or you specified an invalid value, you will get this type of error:
A video setting accepted by the node parameter can still be refused by the camera, when the camera model or the input (SVO, stream, simulation) does not support it, or when the camera rejects the value. Since v5.6.0 of the ROS 2 Wrapper [ZED SDK >= 5.6], the node logs a single warning naming the setting and the reason, and does not retry it until the video parameters change again. Older ZED SDK versions reported such settings as applied. To stop the node from setting video.exposure_compensation or video.ae_antibanding on a camera that refuses it, set the parameter to -1: the camera keeps its own value. The default configuration of the Virtual Stereo Camera (virtual.yaml) already does so for both parameters.
You can also use the Configuration -> Dynamic Reconfigure plugin of the rqt tool to dynamically set parameters by using a graphic interface.
Transform frames
The ZED ROS 2 wrapper broadcasts multiple coordinate frames that each provides information about the camera’s position and orientation. If needed, the reference frames can be changed in the launch file.
<camera_name>_camera_linkis the current position and orientation of the ZED base center. It corresponds to the bottom central fixing hole.<camera_name>_camera_centeris the current position and orientation of ZED middle baseline, determined by visual odometry and the tracking module.<camera_name>_right_camera_frameis the position and orientation of the ZED’s right camera.<camera_name>_right_camera_frame_opticalis the position and orientation of the ZED’s right camera optical frame.<camera_name>_left_camera_frameis the position and orientation of the ZED’s left camera.<camera_name>_left_camera_frame_opticalis the position and orientation of the ZED’s left camera optical frame.<camera_name>_imu_linkis the origin of the inertial data frame (not available with ZED).<camera_name>_mag_linkis the origin of the magnetometer frame (ZED2/ZED2i only).<camera_name>_baro_linkis the origin of the barometer frame (ZED2/ZED2i only).<camera_name>_temp_left_linkis the origin of the left temperature frame (ZED2/ZED2i only).<camera_name>_temp_right_linkis the origin of the right temperature frame (ZED2/ZED2i only).
For RViz 2 compatibility, the root frame map_frame is called map.
The TF tree generated by the zed_wrapper reflects the standard described in REP105.
The odometry frame is updated using only the “visual inertial odometry” information (loop closure is not applied).
The map frame is updated using the Positional Tracking algorithm provided by the StereoLabs SDK, fusing the inertial information from the IMU sensor, and applying loop closure information.
Static transforms and positional tracking
The node publishes the frames of the sensors, from <camera_name>_camera_center down. The transform from the base frame <camera_name>_camera_link to <camera_name>_camera_center comes from the ZED URDF, published by the robot_state_publisher node that zed_camera.launch.py starts with publish_urdf:=true (default). The positional tracking needs it to refer the camera pose to the base frame.
Since v5.6.0 of the ROS 2 Wrapper, when no node publishes this transform, for example with publish_urdf:=false or when the component is loaded in your own application without the ZED URDF, the node waits for it for 10 seconds when it starts the positional tracking, then logs a warning and starts the positional tracking without it:
- the pose and the odometry describe
<camera_name>_camera_centerinstead of<camera_name>_camera_link. The initial pose (pos_tracking.initial_base_pose) is applied to<camera_name>_left_camera_frame. - the
~/odommessages carry<camera_name>_camera_centeraschild_frame_id. - the
odom-><camera_name>_camera_linktransform is not published, so the camera frames are not connected toodomandmap.
As soon as the transform is available, the node logs it, the pose and the odometry move to <camera_name>_camera_link with no jump of the camera position, and the odom -> <camera_name>_camera_link transform is published. To get the full TF tree without the ZED URDF, publish the static transform from <camera_name>_camera_link to <camera_name>_camera_center yourself.
The same applies when the positional tracking is started for another module, such as depth.depth_stabilization.
When the Geo Tracking module is enabled the ZED Node TF Tree reflects the following diagram:
Services
The ZED node provides the following services:
~/reset_odometry(std_srvs/srv/Trigger): Resets the odometry values eliminating the drift due to the Visual Odometry algorithm. The new odometry value is set to the latest camera pose received from the tracking algorithm. Only available if positional tracking is enabled.~/reset_pos_tracking(std_srvs/srv/Trigger): Restarts the Tracking algorithm setting the initial pose to the value available in the param server or to the latest pose set with the serviceset_pose. Only available if positional tracking is enabled.~/set_pose(zed_msgs/srv/SetPose): Restarts the Tracking algorithm setting the initial pose of the camera to the value passed as vector parameter -> [X, Y, Z, R, P, Y]. Only available if positional tracking is enabled.~/save_area_memory(zed_msgs/srv/SaveAreaMemory): Saves the Area Memory (.areafile) of the current session so that it can be reloaded later with thepos_tracking.area_file_pathparameter. The file path is passed in the request; if it is empty the value ofpos_tracking.area_file_pathis used. Only available if positional tracking is enabled.~/enable_depth(std_srvs/srv/SetBool): enable/disable the depth processing at runtime. Not available ifdepth.depth_modeisNONE.~/enable_obj_det(std_srvs/srv/SetBool): enable/disable object detection.~/enable_body_trk(std_srvs/srv/SetBool): enable/disable body tracking.~/enable_mapping(std_srvs/srv/SetBool): enable/disable spatial mapping.~/enable_streaming(std_srvs/srv/SetBool): enable/disable a local streaming server.~/start_svo_rec(zed_msgs/srv/StartSvoRec): Start recording an SVO file. If no filename is provided the defaultzed.svo2is used. A filename without a path is saved in the working directory of the node process.~/stop_svo_rec(std_srvs/srv/Trigger): Stop an active SVO recording.~/pause_svo_rec(std_srvs/srv/SetBool): Pause (data: true) and resume (data: false) an active SVO recording without closing the file. It returnssuccess: falsewhen no recording is active, and the diagnostic reportsSVO Recording: PAUSEDwhile paused.~/toggle_svo_pause(std_srvs/srv/Trigger): set/reset SVO playing pause. Only available ifsvo.svo_realtimeis false and if an SVO has been chosen as input source.~/set_svo_frame(zed_msgs/srv/SetSvoFrame): Set the SVO playback frame to the specified value. Only available if an SVO has been chosen as input source.~/set_roi(zed_msgs/srv/SetROI): Set the Region of Interest to the described polygon.~/reset_roi(std_srvs/srv/Trigger): Reset the Region of Interest to the full image frame.~/toLL(robot_localization/srv/ToLL): converts frommapcoordinate frame to Latitude/Longitude. Only available if GNSS fusion is enabled.~/fromLL(robot_localization/srv/FromLL): converts from Latitude/Longitude tomapcoordinate frame. Only available if GNSS fusion is enabled.~/reboot_camera(std_srvs/srv/Trigger): Reboots the camera without restarting the node: the node closes the camera, reboots it, reopens it and resumes publishing. The call returns when the camera is back, after 5 to 15 seconds, or fails if the camera does not come back withingeneral.camera_timeout_secxgeneral.camera_max_reconnectseconds, and the node then stops as after a disconnection (see When the node stops). Available for the GMSL cameras, the ZED 2 and the ZED 2i with a live input, and not while GNSS fusion is enabled.
When positional tracking is disabled (pos_tracking.pos_tracking_enabled: false) the positional tracking and the spatial mapping services are not advertised at all.
Since v5.6.0 of the ROS 2 Wrapper, ~/reboot_camera reboots the camera from a running node. While it runs no data is published and the other services of the node wait. After the reboot the node starts again the modules that were enabled: the positional tracking restarts from the last valid pose, so odom and map stay continuous (with pos_tracking.floor_alignment, the floor is not searched again because that pose is already aligned to it), and object detection, body tracking, spatial mapping (with an empty map), the streaming server and the Region of Interest are enabled again. An active SVO recording is stopped. The diagnostic reports Camera rebooting while it runs, then the Reboots entry gives the number of reboots with the time and result of the last one. Rebooting a GMSL camera restarts the GMSL capture of the device: the other GMSL cameras can stop for a few seconds, and their nodes wait for them as for a disconnection.
Services can be called using the rqt graphical tool by enabling the plugin Plugins -> Services -> Service caller.
It is possible to call a service also by using the CLI command ros2 service call.
For example, to start Object Detection:
and the service server will reply:
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 common_stereo.yaml configuration 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.
Node Diagnostic
The ZED ROS 2 node publishes useful diagnostic information aggregated into the /diagnostics topic using the diagnostic_updater package.
Diagnostic information can be analyzed and parsed by using ROS 2 tools, like for example the Runtime Monitor plugin of rqt.
Available information:
- Uptime
- Camera disconnections: count and time of the last reconnection (since v5.6.0 of the ROS 2 Wrapper)
- Grab frequency and processing time
- Frame drop rate
- Input mode
- Video and Depth publishing rate and processing time
- Depth Mode
- Point Cloud publishing rate and processing time
- GNSS Fusion status
- Odometry and Localization status
- Pose confidence: the
[0,100]quality metric of the positional tracking. It requires ZED SDK >= 5.4 andPOSITIONAL_TRACKING_MODE::GEN_3, and is reported asN/Aotherwise - TF broadcasting rate
- Object Detection status and publishing rate
- Body Tracking status and publishing rate
- IMU TF broadcasting rate
- Sensor data publishing rate
- Camera Internal temperatures
- Scene Illuminance (ZED X family)
- Camera health status: image quality, lighting, depth reliability, motion sensors reliability and, with ZED SDK >= 5.5 and
zed_msgsv5.5, duplicated images - SVO playback status
- SVO recording status, including the
PAUSEDstate - Streaming server status
The diagnostic goes to WARN and names the issues while any camera health check is raised. It reports DISABLED when general.enable_image_validity_check is off.


