> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.stereolabs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.stereolabs.com/_mcp/server. # 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: ```bash ros2 launch zed_wrapper zed_camera.launch.py camera_model:= ``` where `` must be replaced with one in the list `zed`, `zedm`, `zed2`, `zed2i`, `zedx`, `zedxm`, `zedxnano`, and `virtual`. ## Published Topics > **Note** > > 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](#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](/docs/integrations/ros-2/custom-msgs/#node-health-status)). * `~/status/heartbeat`: heartbeat signal to monitor if the node is alive from other nodes ([custom message](/docs/integrations/ros-2/custom-msgs/#node-heartbeat)). * `~/status/svo`: the status of the SVO playback ([custom message](/docs/integrations/ros-2/custom-msgs/#svo-status)). Only advertised when an SVO file is used as input. * **Image streams** The image topic names are created using the following naming convention: `~////image` > **Note** > > Starting from version 5.1.0 of the ROS 2 Wrapper the new convention replaces the previous formats such as `~//image__` and `~/_/image__` (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. > **Note** > > 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. > **Note** > > 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_info` and `~/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_info` and `~/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. * `~/depth/depth_info`: minimum and maximum depth information ([custom message](/docs/integrations/ros-2/custom-msgs/#depth-information)). * `~/point_cloud/cloud_registered`: Registered color point cloud. * `~/confidence/confidence_map`: Confidence image (floating point values). * `~/disparity/map`: disparity map, of type `stereo_msgs/msg/DisparityImage`, to be used for depth processing. * `~/disparity/image`: normalized disparity map, of type `sensor_msgs/msg/Image`, for visualization purposes. This is the topic to subscribe to in RViz 2. > **Note** > > 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](/docs/integrations/ros-2/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](/docs/integrations/ros-2/custom-msgs/#positional-tracking-status)). * `~/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](/docs/integrations/ros-2/custom-msgs/#positional-tracking-status)). * `~/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 a `sensor_msgs/msg/PointCloud2` message. * **Geo Tracking** * `~/pose/filtered`: the GNSS fused pose of the robot * `~/pose/filtered/status`: the status of the GNSS fused pose ([custom message](/docs/integrations/ros-2/custom-msgs/#gnss-fusion-status)). * `~/geo_pose`: the Latitude/Longitude pose of the robot * `~/geo_pose/status`: the status of the Latitude/Longitude pose ([custom message](/docs/integrations/ros-2/custom-msgs/#gnss-fusion-status)). * `~/pose/fused_fix`: the GNSS fused fix of the robot, published as a `sensor_msgs/msg/NavSatFix` message. * `~/pose/origin_fix`: the Latitude/Longitude of the origin of the `map` frame, published as a `sensor_msgs/msg/NavSatFix` message. * **3D Mapping** * `~/mapping/fused_cloud`: Fused point cloud created when the `enable_mapping` service is called. * **Object Detection** * `~/obj_det/objects`: detected objects ([custom message](/docs/integrations/ros-2/custom-msgs/#object-detection-and-body-tracking-results)). * **Body Tracking** * `~/body_trk/skeletons`: detected body skeletons ([custom message](/docs/integrations/ros-2/custom-msgs/#object-detection-and-body-tracking-results)). * **Plane Detection** * `~/plane`: Detected plane ([custom message](/docs/integrations/ros-2/custom-msgs/#plane-detection-result)). * `~/plane_marker`: Detected plane object to be displayed on RViz 2. > **Note** > > Each topic has a common prefix created by the launch file as `~` = `///`, where `` is replaced with the value of the parameter `camera_name` and `` is the name of the node, e.g. `zed_node`. ### Image Transport The ROS 2 wrapper supports the stack [image\_transport](https://docs.ros.org/en/humble/p/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 (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 image * `theora`: Ogg Theora compressed image * `zstd`: 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 algorithm * `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` > **Note** > > 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](#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: * 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 integration](/docs/integrations/isaac-ros/). 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](/docs/integrations/isaac-ros/). ### Point Cloud Transport The ROS 2 wrapper supports the stack [pointcloud\_transport](https://docs.ros.org/en/humble/p/point_cloud_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: ```bash sudo apt install ros-${ROS_DISTRO}-point-cloud-transport \ ros-${ROS_DISTRO}-point-cloud-transport-plugins \ ros-${ROS_DISTRO}-zlib-point-cloud-transport \ ros-${ROS_DISTRO}-zstd-point-cloud-transport \ ros-${ROS_DISTRO}-draco-point-cloud-transport ``` 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. ### QoS profiles All the topics are configured by default to use the following ROS 2 [QoS profile](http://design.ros2.org/articles/qos.html): * **Reliability**: RELIABLE * **History** (Depth): KEEP\_LAST (10) * **Durability**: VOLATILE * **Lifespan**: Infinite * **Deadline**: Infinite * **Liveliness**: AUTOMATIC * **Liveliness lease duration**: Infinite > **Note** > > Read the official [ROS 2 documentation](https://docs.ros.org/en/humble/Concepts/Intermediate/About-Quality-of-Service-Settings.html) 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](https://design.ros2.org/articles/qos_configurability.html). 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. > **Note** > > For a detailed list of all the compatibility settings, please refer to the [official ROS 2 documentation](https://docs.ros.org/en/humble/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-compatibilities). ## 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](https://github.com/stereolabs/zed-ros2-wrapper/tree/master/zed_wrapper/config). ### General parameters Namespace: `general` **common\_stereo.yaml** | Parameter | Description | Value | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | camera\_timeout\_sec | Camera timeout (sec) if communication fails | int | | camera\_max\_reconnect | Reconnection attempts after timeout, before shutting down | int | | camera\_flip | Flip the camera data if it is mounted upside down | `true`, `false` | | self\_calib | Enable the self-calibration process at camera opening. See the [API documentation](https://www.stereolabs.com/docs/api/structsl_1_1InitParameters.html#affeaa06cfc1d849e311e484ceb8edcc5) | `true`, `false` | | serial\_number | Select a ZED camera by its Serial Number | int | | camera\_id | Select a ZED camera by its ID (0 for first, 1 for second...) | int | | virtual\_serial\_numbers | Serial numbers of the two ZED X One cameras composing a [Virtual Stereo Camera](/docs/integrations/ros-2/custom-stereo-rig), `[left_sn,right_sn]`. Set by the `serial_numbers` launch argument | int array | | virtual\_camera\_ids | IDs of the two ZED X One cameras composing a [Virtual Stereo Camera](/docs/integrations/ros-2/custom-stereo-rig), `[left_id,right_id]`. Set by the `camera_ids` launch argument | int array | | pub\_resolution | The resolution used for image and depth map publishing. '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 | | grab\_compute\_capping\_fps | Upper limit applied to the grab frequency to cap the computation load. Set to 0 to disable (process data at the grab rate) | double | | pub\_frame\_rate\* | Set the video/depth publish rate | double | | enable\_image\_validity\_check | Sets the image validity check. If set to 1, the SDK will check if the frames are valid before processing | int | | gpu\_id | Select a GPU device for depth computation | int | | optional\_opencv\_calibration\_file | Optional path where the ZED SDK can find a file containing the calibration information of the camera computed by OpenCV. | string | | async\_image\_retrieval | If set to true, the camera images are retrieved at a framerate different from the `grab()` application framerate. This is useful for recording an SVO or sending the camera stream at a different rate than the application | `true`, `false` | | 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` | \* *Dynamic parameter* > **Note** > > `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. **zed.yaml**, **zedm.yaml**, **zed2.yaml**, **zed2i.yaml**, **zedx.yaml**, **zedxm.yaml**, **zedxnano.yaml**, and **virtual.yaml** | Parameter | Description | Value | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | camera\_model | Type of StereoLabs camera | string, `zed`, `zedm`, `zed2`, `zed2i`, `zedx`, `zedxm`, `zedxnano`, `virtual` | | 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','100','120' | Valid `grab_resolution` values per camera model: | Camera model | Valid values | | -------------------------------------- | ---------------------------------------- | | `zed`, `zedm`, `zed2`, `zed2i` | 'HD2K', 'HD1080', 'HD720', 'VGA', 'AUTO' | | `zedx`, `zedxm`, `zedxnano`, `virtual` | 'HD1200', 'HD1080', 'SVGA', 'AUTO' | ### SVO input parameters Namespace: `svo` **common\_stereo.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 respecting the `pub_frame_rate` setting | `true`, `false` | | play\_from\_frame | Start playing the SVO from a specific frame ID | int | | replay\_rate | Replay rate for the SVO when not used in realtime mode | double, \[0.10-5.0] | > **Warning** > > 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** | 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 | ### Simulation input parameters Namespace: `simulation` **common\_stereo.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 | ### Streaming server parameters Namespace: `stream_server` **common\_stereo.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](https://www.stereolabs.com/docs/api/structsl_1_1StreamingParameters.html#a873ba9440e3e9786eb1476a3bfa536d0) | 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 the number of packet 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 generates more chunk 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\_stereo.yaml** | Parameter | Description | Value | | --------------------------- | ------------------------------------------------------- | --------------- | | saturation\* | Image saturation | int, \[0,8] | | sharpness\* | Image sharpness | int, \[0,8] | | gamma\* | Image gamma | int, \[0,8] | | auto\_exposure\_gain\* | Enable the auto exposure and auto gain | `true`, `false` | | exposure\* | Exposure value if `auto-exposure` is false | int \[0,100] | | gain\* | Gain value if `auto-exposure` is false | int \[0,100] | | auto\_whitebalance\* | Enable the auto white balance | `true`, `false` | | whitebalance\_temperature\* | White balance temperature | int \[28,65] | | 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\_left\_right | Enable publishing of Left and Right 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` | | publish\_stereo | Enable publishing of stereo pair image streams | `true`, `false` | \* *Dynamic parameter* **zed.yaml**, **zed2.yaml**, and **zed2i.yaml** | Parameter | Description | Value | | ------------ | ---------------- | ------------ | | brightness\* | Image brightness | int, \[0,8] | | contrast\* | Image contrast | int, \[0,8] | | hue\* | Image hue | int, \[0,11] | \* *Dynamic parameter* **zedx.yaml**, **zedxm.yaml**, **zedxnano.yaml**, and **virtual.yaml** | Parameter | Description | Value | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | 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] | | 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 | | 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, used to remove the flicker produced by artificial lighting | int, 0=OFF, 1=AUTO, 2=50Hz, 3=60Hz | \* *Dynamic parameter* ### Region of Interest parameters Namespace: `region_of_interest` **common\_stereo.yaml** | Parameter | Description | Value | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | automatic\_roi | Enable the automatic ROI generation to automatically detect part of the robot in the FoV and remove them from the processing. Note: if enabled the value of `manual_polygon` is ignored | `true`, `false` | | depth\_far\_threshold\_meters | Filtering how far object in the ROI should be considered, this is useful for a vehicle for instance | double | | image\_height\_ratio\_cutoff | By default consider only the lower half of the image, can be useful to filter out the sky | double | | manual\_polygon | A polygon defining the ROI where the ZED SDK perform the processing ignoring the rest. Coordinates must be normalized to '1.0' to be resolution independent. | string | | apply\_to\_depth | Apply ROI to depth processing | `true`, `false` | | apply\_to\_positional\_tracking | Apply ROI to positional tracking processing | `true`, `false` | | apply\_to\_object\_detection | Apply ROI to object detection processing | `true`, `false` | | apply\_to\_body\_tracking | Apply ROI to body tracking processing | `true`, `false` | | apply\_to\_spatial\_mapping | Apply ROI to spatial mapping processing | `true`, `false` | | publish\_roi\_mask | Publish the ROI mask image | `true`, `false` | ### Depth parameters Namespace: `depth` **common\_stereo.yaml** | Parameter | Description | Value | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | depth\_mode | Select depth map quality. If 'NONE' all the modules that require depth extraction are disabled (Positional Tracking, Object Detection, Mapping, ...) | string, 'NONE', 'NEURAL\_LIGHT', 'NEURAL', 'NEURAL\_PLUS' | | depth\_precision | \[ZED SDK >= 5.5] Precision of the neural depth inference. `INT8` is faster and uses less GPU memory than `FP16`, for a small accuracy cost, and requires `depth_mode: 'NEURAL'`. Always safe to set: the ZED SDK falls back to `FP16` when the depth mode or the GPU does not support `INT8` | string, 'FP16', 'INT8' | | allow\_depth\_cuda\_graph | \[ZED SDK >= 5.5] Let the ZED SDK record the depth computation once and replay it at every grab, lowering the CPU cost of launching it. This matters most on NVIDIA® Jetson™. The depth output is unchanged. It applies to the `NEURAL` depth mode family only, and the SDK reverts to the regular computation if the recording fails | `true`, `false` | | depth\_stabilization | Enable depth stabilization. Stabilizing the depth requires an additional computation load as it enables tracking. A negative value takes the SDK default, `0` disables it | int, \[0,100] | | openni\_depth\_mode | Enable/disable the depth OpenNI format (16 bit, millimeters) | `true`, `false` | | point\_cloud\_freq\* | frequency of the pointcloud publishing (equal or less to `grab_frame_rate` value) | double | | point\_cloud\_res | The resolution used for point cloud publishing - 'COMPACT'-Standard resolution. Optimizes processing and bandwidth, 'REDUCED'-Half resolution. Low processing and bandwidth requirements | string, 'COMPACT', 'REDUCED' | | depth\_confidence\* | Depth confidence threshold (lower values = more filtering) | int \[0,100] | | depth\_texture\_conf\* | Depth texture confidence threshold (lower values = more filtering) | int \[0,100] | | remove\_saturated\_areas\* | If true color saturated areas are not included in the depth map | `true`, `false` | | publish\_depth\_map | Enable publishing of depth map stream | `true`, `false` | | publish\_depth\_info | Enable publishing of depth info stream | `true`, `false` | | publish\_point\_cloud | Enable publishing of point cloud stream | `true`, `false` | | voxel\_point\_cloud\* | \[ZED SDK >= 5.3] When true, publish a voxel-decimated point cloud instead of the full resolution one | `true`, `false` | | voxel\_size\_mm\* | \[ZED SDK >= 5.3] Voxel grid cell size in millimeters. `-1` uses the 100 mm default. Clamped to \[5, max depth range] | double | | voxel\_resolution\_mode\* | \[ZED SDK >= 5.3] Voxelization mode | string, 'FIXED', 'STEREO\_UNCERTAINTY', 'LINEAR' | | voxel\_resolution\_scale\* | \[ZED SDK >= 5.3] Scale factor for depth-adaptive voxel growth | double, \[0.01, 3.0] | | publish\_depth\_confidence | Enable publishing of depth confidence map stream | `true`, `false` | | publish\_disparity | Enable publishing of disparity image stream | `true`, `false` | > **Note** > > 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** | Parameter | Description | Value | | ---------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | min\_depth | Minimum depth value (from the camera) that will be computed | double | | max\_depth | Maximum range allowed for depth. Values beyond this limit will be reported as TOO\_FAR | double, the maximum allowed value depends on the camera model (see the comment in its YAML file) | \* *Dynamic parameter* ### Positional tracking parameters (Odometry and Localization) Namespace: `pos_tracking` **common\_stereo.yaml** | Parameter | Description | Value | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | pos\_tracking\_enabled | Enable positional tracking when the node starts | `true`, `false` | | pos\_tracking\_mode | `AUTO` uses the SDK default. Use `GEN_1` for the legacy behavior, `GEN_3` for the latest algorithms | string, 'AUTO', 'GEN\_1', 'GEN\_3' | | compute\_preference | \[ZED SDK >= 5.5] How much GPU the positional tracking may use. `PREFER_GPU` makes the tracking faster and shortens `grab()`, `PREFER_CPU` keeps the GPU free for your own workloads. `GEN_3` runs on the CPU by default; `GEN_1` computes depth and so uses the GPU whatever the setting | string, 'AUTO', 'PREFER\_CPU', 'PREFER\_GPU' | | imu\_fusion | Enable IMU fusion. When set to false, only the optical odometry will be used. | `true`, `false` | | publish\_tf | Enable publishing of transform `odom` -> `_camera_link` and all the other transforms | `true`, `false` | | publish\_map\_tf | Enable publishing of transform `map` -> `odom`. Only valid if `publish_tf` is true | `true`, `false` | | map\_frame | Frame\_id of the pose message | string | | odometry\_frame | Frame\_id of the odom message | string | | area\_memory | Enable Loop Closing algorithm | `true`, `false` | | area\_file\_path | Path to the area memory file used for relocalization and loop closure in a previously explored environment | string | | enable\_localization\_only | If true, the camera only localizes in the loaded area memory without updating the map with new information | `true`, `false` | | save\_area\_memory\_on\_closing | Save the area memory before closing the camera if `area_file_path` is not empty (can also be triggered anytime with the `save_area_memory` service) | `true`, `false` | | reset\_odom\_with\_loop\_closure | Enable the automatic reset of the odometry when a loop closure event is detected. | `true`, `false` | | publish\_3d\_landmarks | Enable publishing of the 3D landmarks used by the positional tracking algorithm | `true`, `false` | | publish\_lm\_skip\_frame | Publish the landmarks every X frames to reduce bandwidth. Set to 0 to publish all landmarks | int | | depth\_min\_range | Set this value for removing fixed zones of the robot in the FoV of the camera from the visual odometry evaluation | double | | set\_as\_static | If 'true' the camera will be static and not move in the environment | `true`, `false` | | set\_gravity\_as\_origin | If 'true' align the positional tracking world to imu gravity measurement. Keep the yaw from the user initial pose. | `true`, `false` | | floor\_alignment | Indicates if the floor must be used as origin for height measures | `true`, `false` | | initial\_base\_pose | Initial reference pose. Useful if the `base_link` does not start from the origin | array | | path\_pub\_rate | Frequency (Hz) of publishing of the path messages | double | | path\_max\_count | Maximum number of poses kept in the pose arrays (-1 for infinite) | int | | two\_d\_mode | Enable if robot moves on a planar surface. Forces Z to `fixed_z_value`, roll and pitch to zero | `true`, `false` | | fixed\_z\_value | Fixed value assigned to Z coordinate if `two_d_mode` is true | double | | transform\_time\_offset | The value added to the timestamp of `map->odom` and `odom->base_link` transform being generated | double | | reset\_pose\_with\_svo\_loop | Reset the camera pose the `initial_base_pose` when the SVO loop is enabled and the SVO playback reaches the end of the file | `true`, `false` | | publish\_odom\_pose | Enable publishing of odometry and pose messages | `true`, `false` | | publish\_pose\_cov | Enable publishing of `pose_with_covariance` message | `true`, `false` | | publish\_cam\_path | Enable publishing of `path_odom` message | `true`, `false` | ### Global Localization (GNSS Fusion) Namespace: `gnss_fusion` **common\_stereo.yaml** | Parameter | Description | Value | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | | gnss\_fusion\_enabled | Enable the fusion of 'sensor\_msgs/NavSatFix' message information into pose data | `true`, `false` | | gnss\_fix\_topic | Name of the GNSS topic of type NavSatFix to subscribe \[Default: "/fix"] | string | | gnss\_zero\_altitude | Set to `true` to ignore GNSS altitude information | `true`, `false` | | h\_covariance\_mul | Multiplier factor to be applied to horizontal covariance of the received fix (plane X/Y) | double | | v\_covariance\_mul | Multiplier factor to be applied to vertical covariance of the received fix (Z axis) | double | | publish\_utm\_tf | Publish `utm` -> `map` TF | `true`, `false` | | broadcast\_utm\_transform\_as\_parent\_frame | If 'true' publish `utm` -> `map` TF, otherwise `map` -> `utm` | `true`, `false` | | enable\_reinitialization | Determines whether reinitialization should be performed between GNSS and VIO fusion when a significant disparity is detected between GNSS data and the current fusion data. It becomes particularly crucial during prolonged GNSS signal loss scenarios. | `true`, `false` | | enable\_rolling\_calibration | If this parameter is set to true, the fusion algorithm will use a rough VIO / GNSS calibration at first and then refine it. This allows you to quickly get a fused position | `true`, `false` | | enable\_translation\_uncertainty\_target | When this parameter is enabled (set to true), the calibration process between GNSS and VIO accounts for the uncertainty in the determined translation, thereby facilitating the calibration termination. The maximum allowable uncertainty is controlled by the 'target\_translation\_uncertainty' parameter | `true`, `false` | | gnss\_vio\_reinit\_threshold | Determines the threshold for GNSS/VIO reinitialization. If the fused position deviates out of the region defined by the product of the GNSS covariance and the gnss\_vio\_reinit\_threshold, a reinitialization will be triggered | double | | target\_translation\_uncertainty | Defines the target translation uncertainty at which the calibration process between GNSS and VIO concludes. By default, the threshold is set at 10 centimeters. | double | | target\_yaw\_uncertainty | Defines the target yaw uncertainty at which the calibration process between GNSS and VIO concludes. The unit of this parameter is in radian. By default, the threshold is set at 0.1 radians | double | ### Mapping parameters Namespace: `mapping` **common\_stereo.yaml** | Parameter | Description | Value | | --------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------- | | mapping\_enabled | Enable/disable the mapping module | `true`, `false` | | resolution | Resolution of the fused point cloud \[0.01, 0.2] | double, default=`0.05` | | max\_mapping\_range | Maximum depth range while mapping in meters (-1 for automatic calculation) \[2.0, 20.0] | double | | fused\_pointcloud\_freq | Publishing frequency (Hz) of the 3D map as fused point cloud | double | | clicked\_point\_topic | Topic published by RViz when a point of the cloud is clicked. Used for plane detection | string, default `"/clicked_point"` | | pd\_max\_distance\_threshold | Plane detection: controls the spread of plane by checking the position difference | double | | pd\_normal\_similarity\_threshold | Plane detection: controls the spread of plane by checking the angle difference | double | | publish\_det\_plane | Enable publishing of the detected planes | `true`, `false` | ### Sensors parameters Namespace: `sensors` **common\_stereo.yaml** | Parameter | Description | Value | | ------------------------- | ---------------------------------------------------------------------- | --------------- | | publish\_imu\_tf | Enable publishing of transform `imu_link` -> `left_camera_frame`. | `true`, `false` | | sensors\_image\_sync | Synchronize Sensors messages with latest published video/depth message | `true`, `false` | | sensors\_pub\_rate | Frequency of publishing of sensors data. MAX: 400. - MIN: grab rate | double | | publish\_imu | Enable publishing of IMU data | `true`, `false` | | publish\_imu\_raw | Enable publishing of raw IMU data | `true`, `false` | | publish\_cam\_imu\_transf | Enable publishing of transform between camera and IMU frames | `true`, `false` | | publish\_mag | Enable publishing of Magnetometer data | `true`, `false` | | publish\_baro | Enable publishing of Barometer data | `true`, `false` | | publish\_temp | Enable publishing of Temperature data | `true`, `false` | > **Note** > > 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 (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** | Parameter | Description | Value | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | od\_enabled | Automatically enables Object Detection when the node starts | `true`, `false` | | enable\_tracking | Whether the object detection system includes object tracking capabilities across a sequence of images | `true`, `false` | | detection\_model | Detection model. The three `CUSTOM_*` models run a user-provided ONNX file inside the ZED SDK and are configured in `custom_object_detection.yaml`; `CUSTOM_BOX_OBJECTS_AUTODETECT` picks YOLO-like or RF-DETR-like from the model outputs | string, 'MULTI\_CLASS\_BOX\_FAST', 'MULTI\_CLASS\_BOX\_MEDIUM', 'MULTI\_CLASS\_BOX\_ACCURATE', 'PERSON\_HEAD\_BOX\_FAST', 'PERSON\_HEAD\_BOX\_ACCURATE', 'CUSTOM\_YOLOLIKE\_BOX\_OBJECTS', 'CUSTOM\_RFDETRLIKE\_BOX\_OBJECTS' \[ZED SDK >= 5.5], 'CUSTOM\_BOX\_OBJECTS\_AUTODETECT' \[ZED SDK >= 5.5] | | allow\_reduced\_precision\_inference | Allow inference to run at a lower precision to improve runtime and memory usage | `true`, `false` | | max\_range | Defines an upper depth range for detections \[m]. The value cannot be greater than `depth.max_depth` | double | | prediction\_timeout | During this time \[sec], the object will have OK state even if it is not detected. Set this parameter to 0 to disable SDK predictions | double | | filtering\_mode | Defines the filtering mode that should be applied to raw detections | string, 'NONE', 'NMS3D', 'NMS3D\_PER\_CLASS' | **object\_detection.yaml** | Parameter | Description | Value | | ---------------------------------------------- | ----------------------------------------------------------------- | --------------- | | class.people.enabled\* | Enable detection of people | `true`, `false` | | class.people.confidence\_threshold\* | Minimum value of the detection confidence of people | double, \[0,99] | | class.vehicle.enabled\* | Enable detection of vehicles | `true`, `false` | | class.vehicle.confidence\_threshold\* | Minimum value of the detection confidence of vehicles | double, \[0,99] | | class.bag.enabled\* | Enable detection of bags | `true`, `false` | | class.bag.confidence\_threshold\* | Minimum value of the detection confidence of bags | double, \[0,99] | | class.animal.enabled\* | Enable detection of animals | `true`, `false` | | class.animal.confidence\_threshold\* | Minimum value of the detection confidence of animals | double, \[0,99] | | class.electronics.enabled\* | Enable detection of electronics | `true`, `false` | | class.electronics.confidence\_threshold\* | Minimum value of the detection confidence of electronics | double, \[0,99] | | class.fruit\_vegetable.enabled\* | Enable detection of fruit and vegetables | `true`, `false` | | class.fruit\_vegetable.confidence\_threshold\* | Minimum value of the detection confidence of fruit and vegetables | double, \[0,99] | | class.sport.enabled\* | Enable detection of sports | `true`, `false` | | class.sport.confidence\_threshold\* | Minimum value of the detection confidence of sports | double, \[0,99] | \* *Dynamic parameter* **custom\_object\_detection.yaml** | Parameter | Description | Value | | ------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------ | | object\_detection.custom\_onnx\_file | Path to the YOLO-like ONNX file for custom object detection directly performed by the ZED SDK | string | | object\_detection.custom\_onnx\_input\_size | Resolution used with the YOLO-like ONNX file. For example, 512 means an input tensor '1x3x512x512' | int | | object\_detection.custom\_class\_count | Number of classes in the custom ONNX file. For example, 80 for YOLOv8 trained on COCO dataset | int | ***FOR EACH CLASS CREATE THE FOLLOWING PARAMETERS*** | Parameter | Description | Value | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | object\_detection.class\_XXX.label | Label of the custom class. The label must be unique and not used by other classes | string | | object\_detection.class\_XXX.model\_class\_id | Class ID of the object in the custom ONNX file (it is not required that this value matches the value in the 'class\_XXX' identifier) | int | | object\_detection.class\_XXX.enabled\* | Enable/disable the detection of this class | `true`, `false` | | object\_detection.class\_XXX.confidence\_threshold\* | Minimum value of the detection confidence of an object \[0,99] | double | | object\_detection.class\_XXX.is\_grounded\* | Provide hypothesis about the object movements (degrees of freedom or DoF) to improve the object tracking | `true`, `false` | | object\_detection.class\_XXX.is\_static\* | Provide hypothesis about the object staticity to improve the object tracking | `true`, `false` | | object\_detection.class\_XXX.tracking\_timeout\* | Maximum tracking time threshold (in seconds) before dropping the tracked object when unseen for this amount of time | double | | object\_detection.class\_XXX.tracking\_max\_dist\* | Maximum tracking distance threshold (in meters) before dropping the tracked object when unseen for this amount of meters. Only valid for static object | double | | object\_detection.class\_XXX.max\_box\_width\_normalized\* | Maximum allowed width normalized to the image size | double | | object\_detection.class\_XXX.min\_box\_width\_normalized\* | Minimum allowed width normalized to the image size | double | | object\_detection.class\_XXX.max\_box\_height\_normalized\* | Maximum allowed height normalized to the image size | double | | object\_detection.class\_XXX.min\_box\_height\_normalized\* | Minimum allowed height normalized to the image size | double | | object\_detection.class\_XXX.max\_box\_width\_meters\* | Maximum allowed 3D width | double | | object\_detection.class\_XXX.min\_box\_width\_meters\* | Minimum allowed 3D width | double | | object\_detection.class\_XXX.max\_box\_height\_meters\* | Maximum allowed 3D height | double | | object\_detection.class\_XXX.min\_box\_height\_meters\* | Minimum allowed 3D height | double | | object\_detection.class\_XXX.object\_acceleration\_preset\* | Object acceleration preset | string, 'DEFAULT', 'LOW', 'MEDIUM', 'HIGH' | | object\_detection.class\_XXX.max\_allowed\_acceleration\* | If set with a different value from the default \[100000], this value takes precedence over the selected preset, allowing for a custom maximum acceleration. Unit is m/s^2 | double | | object\_detection.class\_XXX.velocity\_smoothing\_factor | Controls the smoothing of the velocity estimation | double, \[0.0, 1.0], default `0.5` | | object\_detection.class\_XXX.min\_velocity\_threshold | Threshold to force an object's velocity to zero | double, default `0.2` m/s | | object\_detection.class\_XXX.prediction\_timeout\_s | Duration to keep predicting a track's position after occlusion | double, default `0.5` s | | object\_detection.class\_XXX.min\_confirmation\_time\_s | Minimum confirmation time required to validate a track | double, default `0.05` s | \* *Dynamic parameter* ### Body Tracking parameters Namespace: `body_tracking` **common\_stereo.yaml** | Parameter | Description | Value | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | | bt\_enabled | True to enable Body Tracking | `true`, `false` | | model | Detection model | string, 'HUMAN\_BODY\_FAST', 'HUMAN\_BODY\_MEDIUM', 'HUMAN\_BODY\_ACCURATE' | | body\_format | Skeleton format. Default: `BODY_34`. Only `BODY_18` and `BODY_34` have a `GEN_2` network; `BODY_34` requires `enable_body_fitting` to be true, and the ZED SDK forces it on otherwise | string, 'BODY\_18','BODY\_34','BODY\_38' | | model\_gen | \[ZED SDK >= 5.5] Body tracking network generation. `GEN_2` (default) is bottom-up: more robust in crowded scenes and to unusual body orientations, detects people further from the camera, and is up to 18% faster and 14% more accurate than `GEN_1`. Overridden by the `ZED_SDK_BODY_TRACKING_MODEL_GENERATION` environment variable when set | string, 'GEN\_1', 'GEN\_2' | | allow\_reduced\_precision\_inference | Allow inference to run at a lower precision to improve runtime and memory usage. It has no effect on `GEN_2`, which always runs in FP16 | `true`, `false` | | max\_range | Defines an upper depth range for detections \[m] | double | | body\_kp\_selection | Defines the body selection output by the ZED SDK when `retrieveBodies` is called | string, 'FULL', 'UPPER\_BODY' | | enable\_body\_fitting | Defines if the body fitting will be applied. Default: `true` | `true`, `false` | | enable\_tracking | Defines if the body tracking will track bodies across the image flow | `true`, `false` | | prediction\_timeout\_s | During this time \[sec], the skeleton will have OK state even if it is not detected. Set this parameter to 0 to disable SDK predictions | double | | confidence\_threshold\* | Minimum value of the detection confidence of skeleton key points | double, \[0,99] | | minimum\_keypoints\_threshold\* | Minimum number of skeleton key points to be detected for a valid skeleton | int | \* *Dynamic parameter* > **Note** > > 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` > **Note** > > 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)](https://man7.org/linux/man-pages/man7/sched.7.html). **common\_stereo.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)] | | thread\_pointcloud\_priority | Priority of the point cloud thread (only with 'SCHED\_FIFO' and 'SCHED\_RR') | int, \[1 (LOW) - 99 (HIGH)] | ### Debug parameters Namespace: `debug` **common\_stereo.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\_grab | Enable grab function/thread debug log outputs | `true`, `false` | | debug\_sim | Enable simulation debug log outputs | `true`, `false` | | debug\_video\_depth | Enable video/depth debug log outputs | `true`, `false` | | debug\_camera\_controls | Enable camera controls debug log outputs | `true`, `false` | | debug\_point\_cloud | Enable point cloud debug log outputs | `true`, `false` | | debug\_tf | Enable TF broadcasting debug log outputs | `true`, `false` | | debug\_positional\_tracking | Enable positional tracking debug log outputs | `true`, `false` | | debug\_gnss | Enable GNSS fusion debug log outputs | `true`, `false` | | debug\_sensors | Enable sensors debug log outputs | `true`, `false` | | debug\_mapping | Enable mapping debug log outputs | `true`, `false` | | debug\_terrain\_mapping | Enable terrain mapping debug log outputs | `true`, `false` | | debug\_object\_detection | Enable object detection debug log outputs | `true`, `false` | | debug\_body\_tracking | Enable body tracking debug log outputs | `true`, `false` | | debug\_roi | Enable region of interest 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` | ## 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](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.html) command `ros2 param set`, e.g.: ```bash ros2 param set /zed/zed_node depth.depth_confidence 80 ``` If the parameter is set successfully, you will get a confirmation message: ```bash 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: ```bash ros2 param set /zed/zed_node depth.depth_confidence 150 Setting parameter failed: Parameter {depth.depth_confidence} doesn't comply with integer range. ``` You can also use the `Configuration` -> `Dynamic Reconfigure` plugin of the `rqt` tool to dynamically set parameters by using a graphic interface. ![image](/_fern-img/d7e88433d9ed66227eab256452c9740eb36c9a4994a4706c505eab82fbfbbe1b.webp) ## 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_link` is the current position and orientation of the ZED base center. It corresponds to the bottom central fixing hole. * `_camera_center` is the current position and orientation of ZED middle baseline, determined by visual odometry and the tracking module. * `_right_camera_frame` is the position and orientation of the ZED's right camera. * `_right_camera_frame_optical` is the position and orientation of the ZED's right camera optical frame. * `_left_camera_frame` is the position and orientation of the ZED's left camera. * `_left_camera_frame_optical` is the position and orientation of the ZED's left camera optical frame. * `_imu_link` is the origin of the inertial data frame (*not available with ZED*). * `_mag_link` is the origin of the magnetometer frame (*ZED2/ZED2i only*). * `_baro_link` is the origin of the barometer frame (*ZED2/ZED2i only*). * `_temp_left_link` is the origin of the left temperature frame (*ZED2/ZED2i only*). * `_temp_right_link` is 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](http://www.ros.org/reps/rep-0105.html). 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. ```text map_frame (`map`) └─odometry_frame (`odom`) └─camera_link (`_camera_link`) └─camera_frame (`_camera_center`) └─left_camera_frame (`_left_camera_frame`) | └─left_camera_frame_optical (`_left_camera_frame_optical`) | └─imu_frame (`_imu_link`) └─right_camera_frame (`_right_camera_frame`) └─right_camera_frame_optical (`_right_camera_frame_optical`) ``` When the Geo Tracking module is enabled the ZED Node TF Tree reflects the following diagram: ![image](/_fern-img/19139997fd813e2f0c880f9f5758fd0b8029f0403abf883c18055ca6ae0f3e22.webp) ## 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. **Note**: 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 service `set_pose`. **Note**: 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]. **Note**: Only available if positional tracking is enabled. * `~/save_area_memory` (`zed_msgs/srv/SaveAreaMemory`): Saves the Area Memory (`.area` file) of the current session so that it can be reloaded later with the `pos_tracking.area_file_path` parameter. The file path is passed in the request; if it is empty the value of `pos_tracking.area_file_path` is used. **Note**: Only available if positional tracking is enabled. * `~/enable_depth` (`std_srvs/srv/SetBool`): enable/disable the depth processing at runtime. **Note**: Not available if `depth.depth_mode` is `NONE`. * `~/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 default `zed.svo2` is 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 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. * `~/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 from `map` coordinate frame to Latitude/Longitude **Note**: Only available if GNSS fusion is enabled * `~/fromLL` (`robot_localization/srv/FromLL`): converts from Latitude/Longitude to `map` coordinate frame **Note**: Only available if GNSS fusion is enabled > **Note** > > When positional tracking is disabled (`pos_tracking.pos_tracking_enabled: false`) the positional tracking and the spatial mapping services are not advertised at all. 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**: ```bash ros2 service call /zed/zed_node/enable_obj_det std_srvs/srv/SetBool "{data: true}" ``` and the service server will reply: ```bash waiting for service to become available... requester: making request: std_srvs.srv.SetBool_Request(data=True) response: std_srvs.srv.SetBool_Response(success=True, message='Object Detection 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 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](https://index.ros.org/p/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 * 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 and `POSITIONAL_TRACKING_MODE::GEN_3`, and is reported as `N/A` otherwise * 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_msgs` v5.5, duplicated images * SVO playback status * SVO recording status, including the `PAUSED` state * Streaming server status > **Note** > > 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. ![image](/_fern-img/3d87f7ebe7584cabe2d0cc0da694ea50f5803314663409acbddfe852743482a3.webp)