> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.stereolabs.com/docs/integrations/ros-2/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.stereolabs.com/_mcp/server. # Getting Started with ROS 2 and ZED The [ZED ROS 2 wrapper](https://github.com/stereolabs/zed-ros2-wrapper) lets you use the ZED stereo and monocular cameras with the second version of [ROS](https://www.ros.org/), the **R**obot **O**perating **S**ystem, a set of software libraries and tools that help you build robot applications. It provides access to the following data: * Rectified/Unrectified images * Depth data * Colored 3D point cloud * Inertial information * Sensors information * Visual Inertial Odometry: Position and Orientation of the camera * Pose tracking: localization of the camera with loop closure * AI Detected objects * Human body skeleton tracking ![image](/_fern-img/cb560a8649bfc607fe0e4f387c0e3108305b6ee9e405fe98e9fc1fb1c78f3248.webp) ## The ROS 2 packages The ZED ROS 2 integration is split across several packages. The core ones live in the [zed-ros2-wrapper](https://github.com/stereolabs/zed-ros2-wrapper) repository, while interfaces, robot models, and examples are distributed in dedicated repositories so that they can also be installed on machines without an NVIDIA® GPU. ### Packages in the `zed-ros2-wrapper` repository | Package | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `zed_ros2` | A metapackage that depends on all the others, allowing you to install the full wrapper with a single dependency. | | `zed_wrapper` | The main package. It provides the [launch files](/docs/integrations/ros-2/zed-stereo-node), the YAML configuration files for every camera model, and automatically generates the camera URDF. It loads the `zed_components` in a single process. | | `zed_components` | The actual ROS 2 components. It contains the `ZedCamera` component, used by the [ZED Stereo Node](/docs/integrations/ros-2/zed-stereo-node), and the `ZedCameraOne` component, used by the [ZED Monocular Node](/docs/integrations/ros-2/zed-monocular-node). These components can be composed in a single process for zero-copy communication (see [Composition and IPC](/docs/integrations/ros-2/composition-and-ipc)). | | `zed_debug` | A package intended for **internal development only**, used to debug the components by loading them in a single C++ process. You can safely exclude it from your build with `--packages-skip zed_debug`. | ### Related packages These packages are required by the wrapper but maintained in their own repositories. They do **not** depend on CUDA or the ZED SDK, so they can be installed on any ROS 2 machine (for example a remote workstation receiving data over the network). | Package | Repository | Description | | ------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `zed_msgs` | [zed-ros2-interfaces](https://github.com/stereolabs/zed-ros2-interfaces) | All the custom topics and services used by the ZED nodes. See [The "zed\_msgs" Package](/docs/integrations/ros-2/zed-msgs) and the [Custom Message Types](/docs/integrations/ros-2/custom-msgs) reference. | | `zed_description` | [zed-ros2-description](https://github.com/stereolabs/zed-ros2-description) | The URDF/xacro models and 3D meshes of the ZED camera family, used to build the camera TF tree and to display the camera in RViz 2. See [The "zed\_description" Package](/docs/integrations/ros-2/zed-description). | | `zed_display_rviz2` | [zed-ros2-examples](https://github.com/stereolabs/zed-ros2-examples) | Pre-configured RViz 2 launch files and visualization tools, plus a set of tutorials and advanced examples. See [Data display with RViz2](/docs/integrations/ros-2/data-display-with-r-viz-2). | ## Installation ### Prerequisites * [Ubuntu 20.04 (Focal Fossa)](https://releases.ubuntu.com/focal/) \[**Not recommended. EOL reached**], [Ubuntu 22.04 (Jammy Jellyfish)](https://releases.ubuntu.com/jammy/), [Ubuntu 24.04 (Noble Numbat)](https://releases.ubuntu.com/noble/), or [Ubuntu 26.04 (Resolute Raccoon)](https://releases.ubuntu.com/26.04/) * [ZED SDK](https://www.stereolabs.com/developers/release/latest/) v5.5. To use older SDK versions, check the [wrapper releases](https://github.com/stereolabs/zed-ros2-wrapper/releases) * [CUDA](https://developer.nvidia.com/cuda-downloads) dependency * A supported ROS 2 distribution: * [Humble Hawksbill on Ubuntu 22.04](https://docs.ros.org/en/humble/Installation/Linux-Install-Debians.html) \[LTS, EOL May 2027] * [Jazzy Jalisco on Ubuntu 24.04](https://docs.ros.org/en/jazzy/Installation/Linux-Install-Debians.html) \[LTS, EOL May 2029] * [Lyrical Luth on Ubuntu 26.04](https://docs.ros.org/en/lyrical/Installation/Linux-Install-Debians.html) \[LTS] * [Foxy Fitzroy on Ubuntu 20.04](https://docs.ros.org/en/foxy/Installation/Linux-Install-Debians.html) \[**Backward compatibility only. EOL reached**] * [Rolling Ridley](https://docs.ros.org/en/rolling/Installation/Linux-Install-Debians.html) \[For developers] > **Note** > > All the current LTS distributions are officially supported: **Humble Hawksbill** (Ubuntu 22.04), **Jazzy Jalisco** (Ubuntu 24.04), and **Lyrical Luth** (Ubuntu 26.04). > > **Rolling Ridley** is supported for developers, but breaking changes introduced in Rolling cannot always be supported immediately. Non-LTS distributions, e.g. Iron and Kilted, are not officially tested, but they can work. > **Note** > > The ZED ROS 2 Wrapper has limited compatibility with [ROS 2 Foxy](https://docs.ros.org/en/foxy/index.html) on Ubuntu 20.04, which is supported for backward compatibility only. Modules requiring ROS 2 Humble (or newer) features are disabled in Foxy (e.g. benchmarking and point cloud compression), and there are limitations when newer packages are not available for it. > **Note** > > We recommend setting up your environment according to the recommended [DDS and Network configurations](/docs/integrations/ros-2/dds-and-network-tuning) to obtain the maximum performance. ### Build the package The **zed-ros2-wrapper** uses [colcon](http://design.ros2.org/articles/build_tool.html) to build packages. > **Note** > > If you haven’t set up your colcon workspace yet, please follow this [tutorial](https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Colcon-Tutorial.html). To install the **zed-ros2-wrapper** packages, open a bash terminal, clone the repository from GitHub, and build: ```bash # Create your ROS 2 Workspace if you do not have one mkdir -p ~/ros2_ws/src/ # Move to the `src` folder of the ROS 2 Workspace cd ~/ros2_ws/src/ git clone https://github.com/stereolabs/zed-ros2-wrapper.git cd .. sudo apt update # Install the required dependencies rosdep install --from-paths src --ignore-src -r -y # Build the wrapper colcon build --symlink-install --cmake-args=-DCMAKE_BUILD_TYPE=Release # Setup the environment variables echo source $(pwd)/install/local_setup.bash >> ~/.bashrc source ~/.bashrc ``` > **Note** > > The option `--symlink-install` is useful while developing your robotics system. It allows using symbolic links instead of copying files to the ROS 2 folders during the installation, where possible. Each package in ROS 2 must be installed and all the files used by the nodes must be copied into the installation folders. Using symbolic links allows you to modify them in your workspace, reflecting the modification during the next executions without needing to issue a new `colcon build` command to overwrite the files in the `install` folders. This is true only for the files that don't need to be compiled (Python launch scripts, YAML configurations, etc). > **Note** > > If you are using a different console interface like `zsh`, you have to change the `source` command as follows: `echo source $(pwd)/install/local_setup.zsh >> ~/.zshrc` and `source ~/.zshrc`. ## Starting the ZED node To start the ZED node, open a terminal and use the CLI command `ros2 launch`: ```bash ros2 launch zed_wrapper zed_camera.launch.py camera_model:= ``` The `zed_camera.launch.py` is a ROS 2 Python launch script that automatically starts the ZED node using "[manual composition](https://docs.ros.org/en/humble/Concepts/Intermediate/About-Composition.html)", loading the parameters from the right "YAML files" associated with the specific camera model, and creating the static TF tree from the "URDF file" that is automatically generated from a [xacro](https://index.ros.org/p/xacro/) configuration file. > **Note** > > You can set your own configurations by modifying the parameters in the files `common_stereo.yaml`, `common_mono.yaml`, `zed.yaml`, `zedm.yaml`, `zed2.yaml`, `zed2i.yaml`, `zedx.yaml`, `zedxm.yaml`, `zedxnano.yaml`, `virtual.yaml`, `zedxonegs.yaml`, `zedxone4k.yaml`, and `zedxonecore.yaml` available in the folder [`zed_wrapper/config`](https://github.com/stereolabs/zed-ros2-wrapper/tree/master/zed_wrapper/config). For a full description of each parameter, follow the [complete guide](/docs/integrations/ros-2/zed-stereo-node/#configuration-parameters). ## Displaying ZED data ### Using RViz 2 RViz 2 is a useful visualization tool in ROS 2. With RViz 2, you can visualize the left and right images acquired by the ZED cameras, the depth image, and the 3D colored point cloud, plus other useful information. Launch the ZED wrapper along with RViz 2 by using the following command (installing the packages included in the [zed-ros2-examples](https://github.com/stereolabs/zed-ros2-examples) repository is required): ```bash ros2 launch zed_display_rviz2 display_zed_cam.launch.py camera_model:= ``` > **Note** > > If you haven't yet configured your own RViz 2 interface, you can find a detailed tutorial [here](/docs/integrations/ros-2/data-display-with-r-viz-2/). > **Warning** > > Using RViz 2 on NVIDIA® Jetson™ devices is not recommended for heavy tasks such as processing point clouds and full-resolution images; doing so may slow down the system and affect the reliability of the ZED nodes. ### Displaying Images The ZED node publishes both original (raw) and stereo-rectified (aligned) left and right images. In RViz 2, select a topic and use the `image` preview mode. Here is a list of the main available image topics (more image topics are [available](/docs/integrations/ros-2/zed-stereo-node/#published-topics)): * **rgb/color/rect/image**: Color rectified image (left image by default) * **rgb/color/raw/image**: Color unrectified image (left image by default) * **right/color/rect/image**: Color rectified right image * **right/color/raw/image**: Color unrectified right image * **left/color/rect/image**: Color rectified left image * **left/color/raw/image**: Color unrectified left image * **confidence/confidence\_map**: Confidence map ![image](/_fern-img/033fe252baacbcdd7671a431ec213a2245af1b7a7a578c7b56e3d2118d7999ba.webp) > **Note** > > For a step-by-step tutorial on configuring an RViz 2 session to display only the video data you need, see [Using Video Capture with ROS 2](/docs/integrations/ros-2/video-capture). ### Displaying Depth The depth map can be displayed in RViz 2 by subscribing to the following topic: * **depth/depth\_registered**: 32-bit depth values in meters. RViz 2 normalizes the depth map to 8 bits and displays it as a grayscale depth image. > **Note** > > An OpenNI compatibility mode is available by modifying the `config/common_stereo.yaml` file. Set `depth.openni_depth_mode` to `true` to get depth in millimeters with 16-bit precision, then restart the ZED node. > **Note** > > To learn how to fine-tune the depth and point cloud configuration and set up a dedicated RViz 2 session, see the [Using Depth Perception with ROS 2](/docs/integrations/ros-2/depth-sensing) tutorial. ![image](/_fern-img/36757a3beae94114acba50986642810870f63805e14642d28ff97bc264d8ef20.webp) ### Displaying the Point cloud A 3D colored point cloud can be displayed in RViz 2 by subscribing to the **point\_cloud/cloud\_registered** topic. To display it, add a `PointCloud2` display in RViz 2 and set its topic to `point_cloud/cloud_registered`. ![image](/_fern-img/e35eb0f4e31f4027de5fa3a96c633493aeb995ff12d7c21a2d26986555f39f42.webp) ### Displaying Position and Path The ZED position and orientation in space over time are published to the following topics: * **odom**: Odometry pose referred to the odometry frame * **pose**: Camera pose referred to the Map frame (the complete data fusion algorithm is applied) * **pose\_with\_covariance**: Camera pose referred to the Map frame with covariance * **path\_odom**: The sequence of camera odometry poses in the Map frame * **path\_map**: The sequence of camera poses in the Map frame For a detailed explanation of the reference frames, the TF tree, and how to configure the positional tracking module, see the [Using Positional Tracking with ROS 2](/docs/integrations/ros-2/positional-tracking) tutorial. If you want to fuse GNSS data to improve outdoor localization, refer to the [Using Geo Tracking with ROS 2](/docs/integrations/ros-2/geo-tracking) tutorial. ## Launching with a recorded SVO video With the ZED SDK, you can record and play back stereo video by using StereoLabs' SVO file format. To record a sequence, open the **ZED Explorer** app (`/usr/local/zed/tools`) and click on the **REC** button. To launch the ROS 2 wrapper with an SVO file, set the related parameter while starting the node. For example, to start the ZED node using the SVO as input source: ```bash ros2 launch zed_wrapper zed_camera.launch.py camera_model:= svo_path:= ``` with RViz 2: ```bash ros2 launch zed_display_rviz2 display_zed_cam.launch.py camera_model:= svo_path:= ``` > **Note** > > The ZED ROS 2 Wrapper supports the SVO v2 format, available since ZED SDK v4.1. > **Note** > > You can also record and replay data directly as ROS 2 bag files. For a complete walkthrough of recording, replaying, and synchronizing camera data, see the [Record and Replay Camera Data with ROS 2](/docs/integrations/ros-2/record-and-replay-data) guide. ## Dynamic reconfigure You can dynamically change many configuration parameters during the execution of the ZED node. All the parameters that can be dynamically changed while the node is running are marked as `[DYNAMIC]` in the YAML configuration files. For a full description of each parameter please read the [complete guide](/docs/integrations/ros-2/zed-stereo-node#configuration-parameters). To discover which parameters the node exposes, list them first: ```bash # List all parameters of the ZED node ros2 param list /zed/zed_node ``` You can set the parameters by 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 ``` If you try to set a parameter that's not dynamically reconfigurable, or if you provided 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 a GUI to set dynamic parameter values: ```bash rqt ``` select `Plugins` -> `Configuration` -> `Dynamic Reconfigure` ![image](/_fern-img/d7e88433d9ed66227eab256452c9740eb36c9a4994a4706c505eab82fbfbbe1b.webp) ## Node Diagnostics 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. These diagnostics report the health and the real-time performance of the node, including the camera grabbing frequency, the processing time of each enabled module (depth, positional tracking, object detection, etc.), the publishing rate of the main topics, and the camera temperature when available. Monitoring this information is the recommended way to verify that the node is running at the expected frequency and to detect performance bottlenecks on your hardware. Diagnostic information can be analyzed and parsed by using ROS 2 tools, like for example the **Runtime Monitor** plugin of **rqt**. ![image](/_fern-img/3d87f7ebe7584cabe2d0cc0da694ea50f5803314663409acbddfe852743482a3.webp) > **Note** > > If the node is not running at the expected frequency, refer to the [Stereo Node Frequency Tuning](/docs/integrations/ros-2/node-frequency-tuning) guide to learn how to balance the processing load across the modules. ## Going further The pages above cover the basics of installing and running the ZED ROS 2 Wrapper. The following guides and tutorials describe the individual nodes, the perception modules, and the advanced topics in detail. ### Nodes and camera setups * [ZED Stereo Node](/docs/integrations/ros-2/zed-stereo-node): the complete reference of the node for stereo cameras, including all the published topics and configuration parameters. * [ZED Monocular Node](/docs/integrations/ros-2/zed-monocular-node): the node dedicated to monocular cameras (ZED X One). * [Custom Stereo Rig](/docs/integrations/ros-2/custom-stereo-rig): how to build a custom stereo rig from a dual ZED X One setup. * [Multi-Camera setup](/docs/integrations/ros-2/multi-camera-setup): how to run several ZED cameras on the same system. ### Perception modules * [Using Video Capture with ROS 2](/docs/integrations/ros-2/video-capture): display and configure the camera image streams. * [Using Depth Perception with ROS 2](/docs/integrations/ros-2/depth-sensing): depth maps and 3D point clouds. * [Using Positional Tracking with ROS 2](/docs/integrations/ros-2/positional-tracking): localize the camera in space with loop closure. * [Using Geo Tracking with ROS 2](/docs/integrations/ros-2/geo-tracking): fuse GNSS data to improve outdoor localization. * [Using Plane Detection with ROS 2](/docs/integrations/ros-2/plane-detection): detect planes in the environment. * [Using Object Detection and Tracking with ROS 2](/docs/integrations/ros-2/object-detection-and-tracking): detect and track objects with the built-in models. * [Custom Object Detection and Tracking with ROS 2](/docs/integrations/ros-2/custom-object-detection-and-tracking): use your own YOLO-like model. * [Body Tracking with ROS 2](/docs/integrations/ros-2/body-tracking): track human body skeletons. * [Setting the Region of Interest in ROS 2](/docs/integrations/ros-2/region-of-interest): restrict SDK processing to a specific area of the image. ### Configuration, performance, and integration * [DDS and Network Tuning for ROS 2](/docs/integrations/ros-2/dds-and-network-tuning): required network settings to reliably exchange large data such as images and point clouds. * [Stereo Node Frequency Tuning](/docs/integrations/ros-2/node-frequency-tuning): balance the processing load across the enabled modules. * [ROS 2 Composition and ZED ROS 2 Wrapper](/docs/integrations/ros-2/composition-and-ipc): load the components in a single process for zero-copy (IPC) communication. * [Hardware Encoding Bridge for ROS 2](/docs/integrations/ros-2/hardware-encoding-bridge): stream compressed data across machines using the ZED SDK Local Streaming module. * [ZED Integration on a Robot](/docs/integrations/ros-2/robot-integration): add the ZED camera to the URDF of a robot. * [Record and Replay Camera Data with ROS 2](/docs/integrations/ros-2/record-and-replay-data): capture and replay SVO and ROS 2 bag files. * [Data display with RViz 2](/docs/integrations/ros-2/data-display-with-r-viz-2): pre-configured RViz 2 launch files and visualization tools. ### Interfaces and models * [The "zed\_msgs" Package](/docs/integrations/ros-2/zed-msgs): the custom topics and services used by the ZED nodes. * [Custom Message Types](/docs/integrations/ros-2/custom-msgs): the reference of the custom message definitions. * [The "zed\_description" Package](/docs/integrations/ros-2/zed-description): the URDF/xacro models and 3D meshes of the ZED camera family. ## Docs - [ROS 2 - ZED Stereo Node](https://docs.stereolabs.com/docs/integrations/ros-2/zed-stereo-node.md) - [ROS 2 - ZED Mono Node](https://docs.stereolabs.com/docs/integrations/ros-2/zed-monocular-node.md) - [ROS 2 - Custom Stereo Rig](https://docs.stereolabs.com/docs/integrations/ros-2/custom-stereo-rig.md) - [DDS and Network Tuning for ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/dds-and-network-tuning.md) - [Using Zenoh as ROS 2 Middleware](https://docs.stereolabs.com/docs/integrations/ros-2/using-zenoh-as-middleware.md) - [Stereo Node Frequency Tuning](https://docs.stereolabs.com/docs/integrations/ros-2/node-frequency-tuning.md) - [ZED Topic Benchmark Tool](https://docs.stereolabs.com/docs/integrations/ros-2/topic-benchmark-tool.md) - [The "zed_msgs" Package](https://docs.stereolabs.com/docs/integrations/ros-2/zed-msgs.md) - [The "zed_description" Package](https://docs.stereolabs.com/docs/integrations/ros-2/zed-description.md) - [Hardware Encoding Bridge for ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/hardware-encoding-bridge.md) - [ROS 2 - Data display with RViz2](https://docs.stereolabs.com/docs/integrations/ros-2/data-display-with-r-viz-2.md) - [Using Video Capture with ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/video-capture.md) - [Using Depth Perception with ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/depth-sensing.md) - [Using Positional Tracking with ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/positional-tracking.md) - [Using Geo Tracking with ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/geo-tracking.md) - [Using Plane Detection with ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/plane-detection.md) - [Using Object Detection and Tracking with ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/object-detection-and-tracking.md) - [Custom Object Detection and Tracking with ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/custom-object-detection-and-tracking.md) - [Body Tracking with ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/body-tracking.md) - [ZED ROS 2 Wrapper Custom Messages](https://docs.stereolabs.com/docs/integrations/ros-2/custom-msgs.md) - [Setting the Region of Interest in ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/region-of-interest.md) - [Record and Replay Camera Data with ROS 2](https://docs.stereolabs.com/docs/integrations/ros-2/record-and-replay-data.md) - [ROS 2 Composition and ZED ROS 2 Wrapper](https://docs.stereolabs.com/docs/integrations/ros-2/composition-and-ipc.md) - [Multi-camera setup](https://docs.stereolabs.com/docs/integrations/ros-2/multi-camera-setup.md) - [ZED Integration on a Robot](https://docs.stereolabs.com/docs/integrations/ros-2/robot-integration.md)