ROS 2 - ZED Mono Node

The easiest way to start a ZED ROS 2 node for a monocular camera is by using the command line:

ros2 launch zed_wrapper zed_camera.launch.py camera_model:=<camera model>

where <camera model> must be replaced with one of zedxonegs, zedxone4k, or zedxonecore.

Published Topics

The ZED node publishes data to the following topics:

Status
- ~/status/heartbeat: heartbeat signal to monitor if the node is alive from other nodes (custom message).
- ~/status/svo: status of the SVO playback (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.

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.

Sensors data
- ~/imu/data
- ~/imu/data_raw
- ~/temperature
- ~/left_cam_imu_transform

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 raw topic is handled by a TypeAdapter publisher. Intra-process subscribers (e.g., other nodes running in the same component container) receive a StampedSlMat object — a wrapper around the native sl::Mat — directly, without any serialization overhead. Inter-process subscribers transparently receive a standard sensor_msgs/msg/Image message thanks to the automatic TypeAdapter conversion.
The transport-specific variants are handled by an image_transport publisher. Its raw transport is disabled to avoid publishing duplicate messages, since the raw stream is already provided by the TypeAdapter publisher described above.

To prevent silent data corruption caused by incompatible plugin/encoding combinations, the advertised image transports are filtered by topic type. Visual image topics (color and grayscale images) advertise only:

compressed: JPEG or PNG compressed image
theora: Ogg Theora compressed image
zstd: 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 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: it is disabled when NITROS is enabled and enabled when NITROS is disabled. You can use the debug.disable_nitros parameter to disable NITROS and force IPC to be enabled if needed.

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.

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:

Publisher	Subscriber	Connection	Result
Volatile	Volatile	Yes	Volatile
Volatile	Transient local	No	-
Transient local	Volatile	Yes	Volatile
Transient local	Transient local	Yes	Transient local

Compatibility of QoS reliability profiles:

Publisher	Subscriber	Connection	Result
Best effort	Best effort	Yes	Best effort
Best effort	Reliable	No	-
Reliable	Best effort	Yes	Best effort
Reliable	Reliable	Yes	Reliable

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_mono.yaml, zedxonegs.yaml, zedxone4k.yaml, and zedxonecore.yaml files available in the folder zed_wrapper/config.

General parameters

Namespace: general

common_mono.yaml

Parameter	Description	Value
serial_number	Select a ZED X One camera by its Serial Number	int
camera_id	Select a ZED X One camera by its ID (0 for first, 1 for second…)	int
bus_type	Bus searched when the camera is selected with `camera_id`. `AUTO` searches any bus, `USB` and `GMSL` restrict the search to that transport, `MIPI` targets a camera on a MIPI capture card (e.g. a ZED X One Core) and `HOLOSCAN` a camera reached over Camera-over-Ethernet through a Holoscan sensor bridge. The ZED SDK matches the bus type exactly, so a value other than `AUTO` hides the cameras reached over another bus. Ignored when the camera is selected with `serial_number`	string, ‘AUTO’, ‘USB’, ‘GMSL’, ‘MIPI’ [ZED SDK >= 5.5], ‘HOLOSCAN’ [ZED SDK >= 5.5]
pub_resolution	The resolution used for output. ‘NATIVE’ to use the same `general.grab_resolution` - `CUSTOM` to apply the `general.pub_downscale_factor` downscale factor to reduce bandwidth in transmission	string, ‘NATIVE’, ‘CUSTOM’
pub_downscale_factor	Rescale factor used to rescale image before publishing when ‘pub_resolution’ is ‘CUSTOM’	double
gpu_id	Select a GPU device for image processing	int
optional_opencv_calibration_file	Optional path where the ZED SDK can find a file containing the calibration information of the camera computed with OpenCV.	string
publish_status	Enable publishing of the node status topics	`true`, `false`
sdk_timestamp_clock	[ZED SDK >= 5.3] Clock source behind every SDK timestamp (images and sensors). `SYSTEM_CLOCK` is the wall clock and is affected by NTP/PTP, `MONOTONIC_CLOCK` is immune to clock steps but still frequency-slewed by NTP/PTP, `MONOTONIC_RAW_CLOCK` [ZED SDK >= 5.4] is immune to both steps and slewing. Process-wide: the first node in a composition wins	string, ‘SYSTEM_CLOCK’, ‘MONOTONIC_CLOCK’, ‘MONOTONIC_RAW_CLOCK’
max_system_clock_step_ms	[ZED SDK >= 5.3] Largest backward host clock adjustment (NTP/PTP step, manual date change) that the SDK applies to a single sample, in milliseconds. It therefore sets how fast the SDK catches up with a clock step: `4.0` is the ZED SDK default and suits slew-only setups, a negative value makes step corrections land instantly, as PTP deployments expect, and `0.0` freezes the offset captured on first use. It is applied only when `sdk_timestamp_clock` is `SYSTEM_CLOCK`, and it is always overridden by the `ZED_SDK_MAX_SYSTEM_CLOCK_STEP_MS` environment variable	double
timestamp_reference	[ZED SDK >= 5.5] Time reference used to stamp the published data. `IMAGE` is the start of the sensor readout; `IMAGE_CENTER_OF_EXPOSURE` is the middle of the frame exposure, half an exposure earlier, which aligns the frames with sensors that are timestamped at the instant they measure, such as a LiDAR or the joints of a robot	string, ‘IMAGE’, ‘IMAGE_CENTER_OF_EXPOSURE’
sdk_use_monotonic_clock	[DEPRECATED] Use `sdk_timestamp_clock` instead. Still read for backward compatibility: when `true` and `sdk_timestamp_clock` is left at `SYSTEM_CLOCK`, the SDK clock is set to `MONOTONIC_CLOCK`. The node logs a deprecation warning	`true`, `false`

timestamp_reference: 'IMAGE_CENTER_OF_EXPOSURE' requires an input that carries a per-frame exposure, that is a ZED X One GS or a ZED X One 4K, live, from an SVO or from a stream. On any other camera 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.

zedxonegs.yaml, zedxone4k.yaml, and zedxonecore.yaml

Parameter	Description	Value
camera_model	Type of StereoLabs camera	string, `zedxonegs`, `zedxone4k`, `zedxonecore`
camera_name	User name for the camera, can be different from camera model	string
grab_resolution	The native camera grab resolution. The valid values depend on the camera model, see the table below. An invalid value is rejected with a warning and replaced by ‘AUTO’	string
grab_frame_rate	ZED SDK internal grabbing rate	int, ‘15’,‘30’,‘60’,‘90’,‘100’,‘120’

Valid grab_resolution values per camera model:

Camera model	Valid values
`zedxonegs`, `zedxonecore`	’HD1200’, ‘HD1080’, ‘SVGA’, ‘AUTO’
`zedxone4k`	’HD4K’, ‘QHDPLUS’, ‘HD1200’, ‘HD1080’, ‘SVGA’, ‘AUTO’

Simulation input parameters

Namespace: simulation

common_mono.yaml

Parameter	Description	Value
sim_enabled	Enable simulation input	`true`, `false`
sim_address	Address of the simulation server	string
sim_port	Port of the simulation server	int

Simulation support for the ZED X One monocular cameras is available starting from v5.5.0 of the ROS 2 Wrapper. Launch the node with sim_mode:=true plus the optional sim_address, sim_port and use_sim_time arguments to publish images and IMU data from the simulated camera. With use_sim_time:=true the node waits for a valid /clock and stamps every topic with the simulation time.

Streaming input parameters

Namespace: stream

common_mono.yaml

Parameter	Description	Value
stream_address	Address of the local streaming server	string
stream_port	Port of the local streaming server (only even values are valid)	int

SVO input parameters

Namespace: svo

common_mono.yaml

Parameter	Description	Value
svo_path	Specify SVO filename	string, Note: relative file paths are not allowed
svo_encoding_preset	[ZED SDK >= 5.3] SVO encoder speed/quality preset used by the `start_svo_rec` service	string, ‘DEFAULT’, ‘ULTRAFAST’, ‘FAST’, ‘MEDIUM’, ‘SLOW’
encryption_key	[ZED SDK >= 5.3] Optional key/passphrase used to encrypt the SVO files created by the `start_svo_rec` service (AES-256-CTR). Accepted as a path to a 32-byte key file, a 64-character hex key, or a passphrase. Empty disables encryption	string
decryption_key	[ZED SDK >= 5.3] Optional decryption key/passphrase used when opening encrypted SVO files	string
use_svo_timestamps	Use the SVO timestamps to publish data. If false, data will be published at the system time	`true`, `false`
publish_svo_clock	When `use_svo_timestamps` is true allows you to publish the SVO clock to the `/clock` topic. This is useful for synchronous rosbag playback	`true`, `false`
svo_loop	Restart the SVO if the end of the file is reached	`true`, `false`
svo_realtime	if true SVO will be played trying to respect the original framerate eventually skipping frames, otherwise every frame will be processed	`true`, `false`
play_from_frame	Start playing the SVO from a specific frame ID	int

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 server parameters

Namespace: stream_server

common_mono.yaml

Parameter	Description	Value
stream_enabled	enable the streaming server when the camera is open	`true`, `false`
codec	Different encoding types for image streaming: ‘H264’, ‘H265’	string
port	Port used for streaming. Port must be an even number. Any odd number will be rejected.	int
bitrate	Streaming bitrate (in Kbits/s) used for streaming. See doc	int, [1000 - 60000]
gop_size	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 scenes. But latency will increase.	int, [max 256]
adaptative_bitrate	Bitrate will be adjusted depending on the number of packets dropped during streaming. If activated, the bitrate can vary between [bitrate/4, bitrate].	`true`, `false`
chunk_size	Stream buffers are divided into X number of chunks where each chunk is chunk_size bytes long. You can lower chunk_size value if network generates a lot of packet lost: this will generate more chunks for a single image, but each chunk sent will be lighter to avoid inside-chunk corruption. Increasing this value can decrease latency.	int, [1024 - 65000]
target_framerate	Framerate for the streaming output. This framerate must be below or equal to the camera framerate. Allowed framerates are 15, 30, 60 or 100 if possible. Any other values will be discarded and camera FPS will be taken.	int

Video parameters

Namespace: video

common_mono.yaml

Parameter	Description	Value
saturation^*	Image saturation	int, [0,8]
sharpness^*	Image sharpness	int, [0,8]
gamma^*	Image gamma	int, [0,8]
auto_whitebalance^*	Enable the auto white balance	`true`, `false`
whitebalance_temperature^*	White balance temperature	int [28,65]
auto_exposure^*	Enable or disable auto exposure control (false: manual, true: auto)	`true`, `false`
exposure_time^*	Defines the real exposure time in microseconds. Recommended to control manual exposure (instead of `video.exposure` setting)	int, [28,30000]
auto_exposure_time_range_min^*	Defines the minimum range of exposure auto control in micro seconds	int
auto_exposure_time_range_max^*	Defines the maximum range of exposure auto control in micro seconds	int
exposure_compensation^*	Defines the Exposure-target compensation made after auto exposure. Reduces the overall illumination target by factor of F-stops.	int, [0 - 100]
auto_analog_gain^*	Enable or disable auto analog gain control (false: manual, true: auto)	`true`, `false`
analog_gain^*	Defines the real analog gain (sensor) in mDB. Recommended to control manual sensor gain (instead of `video.gain` setting)	int, [1000-16000].
auto_analog_gain_range_min^*	Defines the minimum range of sensor gain in automatic control	int
auto_analog_gain_range_max^*	Defines the maximum range of sensor gain in automatic control	int
auto_digital_gain^*	Enable or disable auto digital gain control (false: manual, true: auto)	`true`, `false`
digital_gain^*	Defines the real digital gain (ISP) as a factor. Recommended to control manual ISP gain (instead of `video.gain` setting)	int, [1-256]
auto_digital_gain_range_min^*	Defines the minimum range of digital ISP gain in automatic control	int
auto_digital_gain_range_max^*	Defines the maximum range of digital ISP gain in automatic control	int
denoising^*	Defines the level of denoising applied on both left and right images	int, [0-100]
ae_antibanding^*	[ZED SDK >= 5.3] Auto-exposure anti-banding mode	int, 0=OFF, 1=AUTO, 2=50Hz, 3=60Hz
enable_24bit_output	Enable BGR 24-bit output for images (instead of 32-bit)	`true`, `false`
publish_rgb	Enable publishing of RGB image streams	`true`, `false`
publish_raw	Enable publishing of raw (unrectified) image streams	`true`, `false`
publish_gray	Enable publishing of grayscale image streams	`true`, `false`

^* Dynamic parameter

zedxone4k.yaml

Parameter	Description	Value
enable_hdr	When set to true, the camera will be set in HDR mode if the camera model and resolution allows it	`true`, `false`

Sensors parameters

Namespace: sensors

common_mono.yaml

Parameter	Description	Value
publish_imu_tf	Enable/disable the IMU TF broadcasting	`true`, `false`
sensors_pub_rate^*	Frequency of publishing of sensors data	double
publish_imu	Advertise the IMU topic that is published only if a node subscribes to it	`true`, `false`
publish_imu_raw	Advertise the raw IMU topic that is published only if a node subscribes to it	`true`, `false`
publish_cam_imu_transf	Advertise the CAMERA-IMU transformation topic that is published only if a node subscribes to it	`true`, `false`
publish_temp	Advertise the temperature topics that are published only if a node subscribes to them	`true`, `false`

^* Dynamic parameter

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. The node polls the sensors well above the hardware ODR, so no sample is lost.

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: a ZED X One GS advertises 400 Hz but delivers 200 Hz, and sensors_pub_rate: 100 used to produce a steady 50 Hz.

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).

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 running with sudo. Reference: sched(7).

common_mono.yaml

Parameter	Description	Value
change_thread_priority	Master switch for the other `advanced` parameters: the thread scheduling policy and the priorities below are applied only when this is `true`	`true`, `false`
thread_sched_policy	Thread scheduling policy	string, ‘SCHED_OTHER’, ‘SCHED_BATCH’, ‘SCHED_FIFO’, ‘SCHED_RR’
thread_grab_priority	Priority of the grab thread (only with ‘SCHED_FIFO’ and ‘SCHED_RR’)	int, [1 (LOW) - 99 (HIGH)]
thread_sensor_priority	Priority of the sensors thread (only with ‘SCHED_FIFO’ and ‘SCHED_RR’)	int, [1 (LOW) - 99 (HIGH)]

Debug parameters

Namespace: debug

common_mono.yaml

Parameter	Description	Value
sdk_verbose	Set the verbose level of the ZED SDK	int, `0` -> disable
sdk_verbose_log_file	Path to the file where the ZED SDK will log its messages. If empty, no file will be created. The log level can be set using the `sdk_verbose` parameter.	string
use_pub_timestamps	Use the current ROS time for the message timestamp instead of the camera timestamp. This is useful to test data communication latency.	`true`, `false`
debug_common	Enable general debug log outputs	`true`, `false`
debug_dyn_params	Enable dynamic parameters update debug log outputs	`true`, `false`
debug_video_depth	Enable video debug log outputs	`true`, `false`
debug_camera_controls	Enable camera controls debug log outputs	`true`, `false`
debug_sensors	Enable sensors debug log outputs	`true`, `false`
debug_sim	Enable simulation mode debug log outputs	`true`, `false`
debug_tf	Enable TF broadcasting debug log outputs	`true`, `false`
debug_streaming	Enable streaming debug log outputs	`true`, `false`
debug_advanced	Enable advanced debug log outputs	`true`, `false`
debug_nitros	Enable Nitros debug log outputs	`true`, `false`
disable_nitros	If available, disable NITROS usage for debugging and testing purposes	`true`, `false`

Up to v5.4 the sdk_use_monotonic_clock parameter was declared in the debug namespace of common_mono.yaml, while the node reads it from the general namespace, so it was silently ignored. It is now declared in the right namespace, and it is superseded by general.sdk_timestamp_clock.

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.:

ros2 param set /zed/zed_node video.exposure_time 5000

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

Set parameter successful

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:

ros2 param set /zed/zed_node video.exposure_time 0
Setting parameter failed: Parameter {video.exposure_time} doesn't comply with integer range.

and the ZED node will report a warning message explaining the error type:

1538556595.265117561: [zed.zed_node] [WARN]  The param 'video.exposure_time' requires an INTEGER value in the valid range

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_link is the current position and orientation of the ZED base center. It corresponds to the bottom central fixing hole.
<camera_name>_camera_center is the current position and orientation of ZED middle baseline, determined by visual odometry and the tracking module.
<camera_name>_camera_frame is the position and orientation of the ZED’s CMOS sensor.
<camera_name>_camera_frame_optical is the position and orientation of the ZED’s camera optical frame.
<camera_name>_imu_link is the origin of the inertial data frame (not available with ZED).

Frames

Services

The ZED node provides the following services:

~/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 default zed.svo is used. If no path is provided with the filename the default recording folder is ~/.ros/
~/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 returns success: false when no recording is active, and the diagnostic reports SVO Recording: PAUSED while paused.
~/toggle_svo_pause (std_srvs/srv/Trigger): set/reset SVO playing pause. Note: Only available if svo.svo_realtime is 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. Note: Only available if an SVO has been chosen as input source.

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 the local streaming server:

ros2 service call /zed/zed_node/enable_streaming std_srvs/srv/SetBool "{data: True}"

and the service server will reply:

requester: making request: std_srvs.srv.SetBool_Request(data=True)
response:
std_srvs.srv.SetBool_Response(success=True, message='Streaming Server started')

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 image processing in the common_mono.yaml configuration file. The default value (-1) will select the GPU with the highest number of CUDA cores. When using multiple cameras, 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
Grab frequency and processing time
Frame drop rate
Input mode
Image publishing rate and processing time
IMU TF broadcasting rate
IMU data publishing rate
Camera internal temperature
Scene Illuminance
SVO playback status
SVO recording status, including the PAUSED state
Streaming server status