ZED ROS 2 Wrapper

https://github.com/stereolabs/zed-ros2-wrapper
Admin
The ZED ROS 2 Wrapper provides ROS 2 packages that enable the use of Stereolabs ZED cameras,...
Tokens:78,362
Snippets:455
Trust Score:8.3
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Build and install zed-ros2-wrapper package with colcon

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Full setup and build workflow for the zed-ros2-wrapper package in a colcon workspace. Use this in a bash terminal after cloning the repository; the steps install dependencies, build with symlink-install and Release type, and optionally source the installation in every new bash. The --symlink-install flag links files instead of copying so modifications to Python scripts or configs are reflected without a rebuild.

```bash
mkdir -p ~/ros2_ws/src/ # create your workspace if it does not exist
cd ~/ros2_ws/src/ #use your current ros2 workspace folder
git clone https://github.com/stereolabs/zed-ros2-wrapper.git
cd ..
sudo apt update
rosdep update
rosdep install --from-paths src --ignore-src -r -y # install dependencies
colcon build --symlink-install --cmake-args=-DCMAKE_BUILD_TYPE=Release --parallel-workers $(nproc) # build the workspace
echo source $(pwd)/install/local_setup.bash >> ~/.bashrc # automatically source the installation in every new bash (optional)
source ~/.bashrc

```

--------------------------------

### [SERVICE] /zed/zed_node/start_svo_rec

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/endpoints.md

Starts SVO recording with configurable parameters.

```APIDOC
## [SERVICE] /zed/zed_node/start_svo_rec

### Description
Starts SVO recording with specified bitrate, compression mode, target framerate, and transcode option.

### Method
SERVICE CALL

### Endpoint
`/zed/zed_node/start_svo_rec`

### Service Type
`zed_msgs/srv/StartSvoRec`

### Request
- `bitrate` (int) - Bitrate for recording (e.g., 12500).
- `compression_mode` (int) - Compression mode (e.g., 1).
- `target_framerate` (int) - Desired framerate (e.g., 30).
- `input_transcode` (bool) - Whether to transcode input.
- `svo_filename` (string) - Filename for the SVO file.

### Request Example
```json
{
  "bitrate": 12500,
  "compression_mode": 1,
  "target_framerate": 30,
  "input_transcode": true,
  "svo_filename": "rec.svo2"
}
```

### Response
- `success` (bool) - Indicates success.
- `message` (string) - Error message if unsuccessful.

### Response Example
```json
{
  "success": true,
  "message": ""
}
```

```

--------------------------------

### startSvoRecording() signature

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_component.md

Starts SVO recording. Returns false with errMsg filled when no camera is open or recording cannot start; compression/bitrate come from the service request and svo.* parameters.

```cpp
bool startSvoRecording(std::string & errMsg);
```

--------------------------------

### startStreamingServer() signature

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_component.md

Starts the network streaming server. Returns true when started with parameters from stream_server.*.

```cpp
bool startStreamingServer();
```

--------------------------------

### start3dMapping() signature

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_component.md

Starts spatial mapping. Returns true when started, using sl::SpatialMappingParameters from mapping.resolution and mapping.max_mapping_range.

```cpp
bool start3dMapping();
```

--------------------------------

### Cost traversability usage example

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/cost_traversability.md

Shows how to use the cost traversability API: include the header, initialize cost with initCostTraversibily, set robot and traversability parameters, compute cost with computeCost, and visualize with normalization. The comments indicate example values for a bigger robot and prioritizing flat paths.

```cpp
#include <zed_components/cost_traversability.hpp>

using namespace stereolabs::cost_traversability;

sl::Terrain elevation, cost;
initCostTraversibily(cost, 0.05f, 10.0f, 0.2f);

RobotParameters robot;
robot.radius = 0.3f;       // bigger robot
robot.slope_max = 15.0f;   // degrees

TraversabilityParameters trav;
trav.slope_weight = 0.5f;  // prioritize flat paths

computeCost(elevation, cost, 0.05f, robot, trav);

sl::Mat view;
normalization(cost, TRAVERSABILITY_COST, view);  // visualize combined cost
```

--------------------------------

### Launch rviz2 for simulation visualization

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Starts a preconfigured rviz2 instance for visualizing all available simulation information. The launch file includes zed_camera.launch.py and forwards sim_mode, sim_address, sim_port, and use_sim_time.

```bash
ros2 launch zed_display_rviz2 display_zed_cam.launch.py camera_model:=zedx \
  sim_mode:=true use_sim_time:=true
```

--------------------------------

### Install Ultralytics YOLO tools

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Installs the Ultralytics YOLO tools, needed to generate and export ONNX models for custom object detection. If already installed, update it first with `pip install -U ultralytics`.

```bash
python -m pip install ultralytics
```

--------------------------------

### startCamera() method

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_one_component.md

Starts the camera. Returns true on success; false when the input (live camera, SVO, stream, or simulation server) cannot be opened. configureZedInput() selects the input type and openZedCamera() retries with a 500 ms sleep, honoring general.camera_timeout_sec for live input and SIM_CONN_TIMEOUT_SEC for simulation. Declared in zed_camera_one_component.hpp:83.

```cpp
bool startCamera();
```

--------------------------------

### Launch node for each simulated camera with sim_port

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Commands to start a node per camera. Each camera requires a distinct even sim_port and unique camera_name. The commands must be executed separately, one per terminal or as separate processes.

```bash
ros2 launch zed_wrapper zed_camera.launch.py camera_model:=zedx camera_name:=zed_front \
  sim_mode:=true use_sim_time:=true sim_port:=30000
```

```bash
ros2 launch zed_wrapper zed_camera.launch.py camera_model:=zedx camera_name:=zed_rear \
  sim_mode:=true use_sim_time:=true sim_port:=30002
```

--------------------------------

### Launch ZED node with gdbserver prefix

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/zed_debug/README.md

Starts the ZED camera node with a gdbserver prefix on localhost:3000, enabling remote debugging from VSCode.

```bash
ros2 launch zed_debug zed_camera_debug.launch.py camera_model:=<your_camera_model> cmd_prefix:='gdbserver localhost:3000'
```

--------------------------------

### Launch ZED node with ros2 launch

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Starts the ZED node using manual composition and loads the YAML parameters for the specified camera model. Replace <camera_model> with one of 'zed', 'zedm', 'zed2', 'zed2i', 'zedx', 'zedxm', 'zedxnano', 'zedxhdrmini', 'zedxhdr', 'zedxhdrmax', 'virtual', 'zedxonegs', 'zedxone4k', or 'zedxonehdr'. A Robot State Publisher node is also started to publish the camera static links and joints from the URDF model.

```bash
ros2 launch zed_wrapper zed_camera.launch.py camera_model:=<camera_model>
```

--------------------------------

### Manual composition of ZedCamera node

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_component.md

Manual composition example showing how to instantiate stereolabs::ZedCamera as a ROS 2 node with intra-process communication enabled for a zero-copy path. The class is normally loaded as a component by the launch file, not instantiated directly.

```cpp
#include <rclcpp/rclcpp.hpp>
#include <zed_components/zed_camera_component.hpp>

int main(int argc, char ** argv)
{
  rclcpp::init(argc, argv);
  rclcpp::NodeOptions options;
  options.use_intra_process_comms(true);  // zero-copy path
  auto node = std::make_shared<stereolabs::ZedCamera>(options);
  rclcpp::spin(node);
  rclcpp::shutdown();
  return 0;
}
```

--------------------------------

### Install point_cloud_transport packages

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Installs the point_cloud_transport packages. This is required to use the Point Cloud Transport feature; without them it will be disabled automatically. Use this on Debian/Ubuntu-based ROS 2 environments.

```bash
sudo apt install ros-$ROS_DISTRO-point-cloud-transport ros-$ROS_DISTRO-point-cloud-transport-plugins
```

--------------------------------

### Run Docker container for USB3 cameras

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/docker/README.md

Starts the ZED ROS 2 wrapper container with NVIDIA runtime, privileged mode, host network, IPC, and PID namespaces, plus volume mounts for X11, devices, shared memory, AI models, and calibration settings. Replace <docker_image_tag> with your image tag.

```bash
docker run --runtime nvidia -it --privileged --network=host --ipc=host --pid=host \
  -e NVIDIA_DRIVER_CAPABILITIES=all -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix/:/tmp/.X11-unix \
  -v /dev:/dev \
  -v /dev/shm:/dev/shm \
  -v /usr/local/zed/resources/:/usr/local/zed/resources/ \
  -v /usr/local/zed/settings/:/usr/local/zed/settings/ \
  <docker_image_tag>
```

--------------------------------

### Run Docker container for GMSL cameras

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/docker/README.md

Starts the ZED ROS 2 wrapper container for GMSL2 cameras (ZED X, ZED X One) with additional volume mounts for /tmp, NVIDIA camera settings, and the ZED X daemon service. Replace <docker_image_tag> with your image tag.

```bash
docker run --runtime nvidia -it --privileged --network=host --ipc=host --pid=host \
  -e NVIDIA_DRIVER_CAPABILITIES=all -e DISPLAY=$DISPLAY \
  -v /tmp:/tmp \
  -v /dev:/dev \
  -v /var/nvidia/nvcam/settings/:/var/nvidia/nvcam/settings/ \
  -v /etc/systemd/system/zed_x_daemon.service:/etc/systemd/system/zed_x_daemon.service \
  -v /usr/local/zed/resources/:/usr/local/zed/resources/ \
  -v /usr/local/zed/settings/:/usr/local/zed/settings/ \
  <docker_image_tag>
```

--------------------------------

### Build Jetson image with DOCKER_DEFAULT_PLATFORM

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/docker/README.md

Forces arm64 platform on x86_64 host. Example builds ROS 2 Lyrical on JetPack 7.1.0.

```bash
# ROS 2 Lyrical on JetPack 7.1 (L4T r38.4, Ubuntu 24.04)
DOCKER_DEFAULT_PLATFORM=linux/arm64 \
  ./build_jetson.sh --ros-distro lyrical --os jp7.1.0
```

--------------------------------

### Call set_pose service from C++ client

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/endpoints.md

C++ client example that calls the /zed/zed_node/set_pose service and checks the response. It creates a client for zed_msgs/srv/SetPose, sends a request with pos and orient fields, and logs an error if the service returns success == false.

```cpp
#include <zed_msgs/srv/set_pose.hpp>
#include <rclcpp/rclcpp.hpp>

auto client = node->create_client<zed_msgs::srv::SetPose>("/zed/zed_node/set_pose");
auto req = std::make_shared<zed_msgs::srv::SetPose::Request>();
req->pos = {0.0f, 0.0f, 0.5f};
req->orient = {0.0f, 0.0f, 0.0f};
auto fut = client->async_send_request(req);
if (fut.get()->success == false) {
  RCLCPP_ERROR(node->get_logger(), "set_pose rejected: %s",
               fut.get()->message.c_str());
}
```

--------------------------------

### CMake error on Jetson JP6: Specify CUDA_TOOLKIT_ROOT_DIR

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Example of a CMake error that can occur when building the ZED ROS 2 Wrapper for the first time on an NVIDIA Jetson with JP6. The error asks to specify CUDA_TOOLKIT_ROOT_DIR; fix it by installing the missing nvidia-jetpack packages with 'sudo apt install nvidia-jetpack nvidia-jetpack-dev'.

```bash
CMake Error at /usr/share/cmake-3.22/Modules/FindCUDA.cmake:859 (message):
  Specify CUDA_TOOLKIT_ROOT_DIR
Call Stack (most recent call first):
 /usr/local/zed/zed-config.cmake:72 (find_package)
 CMakeLists.txt:81 (find_package)

```

--------------------------------

### GNSSReplay usage example

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/gnss_replay.md

Typical consumer flow for GNSSReplay: open a ZED camera in SVO mode, create a GNSSReplay instance, initialize it, then repeatedly call grab() with the current camera timestamp. Check the return code against sl::FUSION_ERROR_CODE::SUCCESS; treat any other value as 'no new fix'.

```cpp
#include <sl/Camera.hpp>
#include <zed_components/gnss_replay.hpp>

std::shared_ptr<sl::Camera> zed = std::make_shared<sl::Camera>();
sl::InitParameters init;  // svo_input_filename = "recording.svo"
if (zed->open(init) != sl::ERROR_CODE::SUCCESS) { /* handle */ }

sl_tools::GNSSReplay replay(zed);
if (!replay.initialize()) {
  // SVO contains no 'GNSS_json' custom data
}

sl::GNSSData gnss;
sl::Timestamp cam_ts = zed->getTimestamp(sl::TIME_REFERENCE::IMAGE);
sl::FUSION_ERROR_CODE rc = replay.grab(gnss, cam_ts.getNanoseconds());
if (rc == sl::FUSION_ERROR_CODE::SUCCESS) {
  // feed gnss into a fusion callback / publish on ~/pose/fused_fix
}
```

--------------------------------

### Object detection and body tracking signatures

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_component.md

Signatures for object detection and body tracking start/stop methods. Return true when the module started, using models from object_detection.detection_model and body_tracking.model. Unsupported on ZED X One and first-generation ZED.

```cpp
bool startObjDetect();
void stopObjDetect();
bool startBodyTracking();
void stopBodyTracking();
```

--------------------------------

### Cost Traversability Usage

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/cost_traversability.md

Example usage of the cost traversability API functions: initCostTraversibily, computeCost, and normalization.

```APIDOC
## Usage Example

### Description
Example usage of the cost traversability API functions: initCostTraversibily, computeCost, and normalization.

### Code
```cpp
#include <zed_components/cost_traversability.hpp>

using namespace stereolabs::cost_traversability;

sl::Terrain elevation, cost;
initCostTraversibily(cost, 0.05f, 10.0f, 0.2f);

RobotParameters robot;
robot.radius = 0.3f;       // bigger robot
robot.slope_max = 15.0f;   // degrees

TraversabilityParameters trav;
trav.slope_weight = 0.5f;  // prioritize flat paths

computeCost(elevation, cost, 0.05f, robot, trav);

sl::Mat view;
normalization(cost, TRAVERSABILITY_COST, view);  // visualize combined cost
```
```

--------------------------------

### setSdkReplayMode / getSdkReplayMode

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/sl_tools.md

Sets or gets the process-wide replay mode flag.

```APIDOC
## setSdkReplayMode / getSdkReplayMode

### Description
Sets or gets the process-wide replay mode flag. Both components call `setSdkReplayMode(mSvoMode || mSimMode)` right before opening the camera. Multi-camera compositions with conflicting modes are not supported.

### Signatures
```cpp
void setSdkReplayMode(bool isReplay);
bool getSdkReplayMode();
```

### Parameters (setSdkReplayMode)
- **isReplay** (bool) - Required - `true` for SVO playback or simulation input, `false` for a live camera

### Return (getSdkReplayMode)
- **bool** - The current replay mode flag.
```

--------------------------------

### setSdkLiveTimeOffsetNs / getSdkLiveTimeOffsetNs

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/sl_tools.md

Sets or gets the process-wide offset in nanoseconds added to live SDK timestamps.

```APIDOC
## setSdkLiveTimeOffsetNs / getSdkLiveTimeOffsetNs

### Description
Sets or gets the process-wide offset in nanoseconds added to live SDK timestamps. Set once after a successful `Camera::open()` for a monotonic `TIMESTAMP_CLOCK` (SDK >= 5.3). No effect in replay mode. Default: `0`.

### Signatures
```cpp
void setSdkLiveTimeOffsetNs(int64_t offset_ns);
int64_t getSdkLiveTimeOffsetNs();
```

### Parameters (setSdkLiveTimeOffsetNs)
- **offset_ns** (int64_t) - Required - Nanoseconds added to live SDK timestamps (`ros_now_ns - sl::getCurrentTimeStamp_ns`); `0` disables the shim

### Return (getSdkLiveTimeOffsetNs)
- **int64_t** - The current offset in nanoseconds.
```

--------------------------------

### Call ZED services with ros2 service call

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/endpoints.md

Shows how to call four ZED ROS 2 services from the command line: reset odometry, set pose, start SVO recording, and set a ROI polygon. Each call uses the service type and a JSON-like argument string; note the backslash line continuation and the quoted arguments.

```bash
# Reset odometry (Trigger)
ros2 service call /zed/zed_node/reset_odometry std_srvs/srv/Trigger {}

# Set a new base pose (zed_msgs/srv/SetPose)
ros2 service call /zed/zed_node/set_pose zed_msgs/srv/SetPose \
  "{pos: [1.0, 2.0, 0.0], orient: [0.0, 0.0, 1.57]}"

# Start SVO recording (zed_msgs/srv/StartSvoRec)
ros2 service call /zed/zed_node/start_svo_rec zed_msgs/srv/StartSvoRec \
  "{bitrate: 12500, compression_mode: 1, target_framerate: 30, input_transcode: true, svo_filename: 'rec.svo2'}"

# Set a ROI polygon (zed_msgs/srv/SetROI)
ros2 service call /zed/zed_node/set_roi zed_msgs/srv/SetROI \
  "{roi: '[[0.5,0.25],[0.75,0.5],[0.5,0.75],[0.25,0.5]]'}"
```

--------------------------------

### Export custom YOLO model to ONNX

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Exports a custom-trained YOLO model to ONNX format. Change the weight file path to your own model. Img size 512 and dynamic=False are example settings.

```bash
yolo export model=yolov8l_custom_model.pt format=onnx simplify=True dynamic=False imgsz=512
```

--------------------------------

### ZedCameraOne protected lifecycle method signatures

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_one_component.md

Exact protected lifecycle method signatures from the ZedCameraOne header. These methods are called during component initialization and shutdown, covering node setup, camera opening, TF, publishers, and streaming/SVO helpers.

```cpp
void initNode();
void deInitNode();
void initParameters();
void initServices();
void initTFCoordFrameNames();
void initPublishers();
void initSubscribers();
void initVideoPublishers();
void initSensorPublishers();
void initializeTimestamp();
void initializeDiagnosticStatistics();
void initThreadsAndTimers();

bool startCamera();
void closeCamera();
void createZedObject();
void logSdkVersion();
void setupTf2();
void configureZedInput();
void setZedInitParams();
bool openZedCamera();
void processCameraInformation();
void setupCameraInfoMessages();

bool startStreamingServer();
void stopStreamingServer();
bool startSvoRecording(std::string & errMsg);
void stopSvoRecording();
```

--------------------------------

### Clean previous build artifacts

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/zed_debug/README.md

Cleans the previous build artifacts (install, build, logs) from the ROS2 workspace root before rebuilding with debug symbols.

```bash
rm -rf install
rm -rf build
rm -rf logs
```

--------------------------------

### Export YOLO model to ONNX (yolo11n.pt)

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Exports a YOLO model (yolo11n.pt) to ONNX format. Use this to generate a custom inference engine for the custom object detection feature. Img size 640 and dynamic=False are example settings.

```bash
yolo export model=yolo11n.pt format=onnx simplify=True dynamic=False imgsz=640
```

--------------------------------

### setSdkReplayMode and getSdkReplayMode declarations

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/sl_tools.md

Process-wide functions to enable or query replay mode for SVO playback or simulation input. Both components call setSdkReplayMode(mSvoMode || mSimMode) before opening the camera; conflicting modes in multi-camera setups are not supported.

```cpp
// sl_tools.hpp:137
void setSdkReplayMode(bool isReplay);
bool getSdkReplayMode();
```

--------------------------------

### Fast binary Jetson build under QEMU

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/docker/README.md

Use a distribution whose target Ubuntu matches the base for a fast APT build. Measured ~15 minutes for Humble on JP6.2.2.

```bash
DOCKER_DEFAULT_PLATFORM=linux/arm64 ./build_jetson.sh --ros-distro jazzy --os jp7.1.0
```

--------------------------------

### List All Launch Arguments

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/launch_files.md

Displays all available launch arguments for the zed_camera.launch.py file.

```bash
ros2 launch zed_wrapper zed_camera.launch.py -s
```

--------------------------------

### List launch parameters with -s option

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Lists all available launch parameters for the ZED camera launch file and the RViz display launch file. Useful for inspecting the configuration options before running the nodes.

```bash
ros2 launch zed_wrapper zed_camera.launch.py -s
ros2 launch zed_display_rviz2 display_zed_cam.launch.py -s
```

--------------------------------

### Update Ultralytics package

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Updates an existing Ultralytics installation to the latest version. Recommended after installing the package, before exporting an ONNX model.

```bash
pip install -U ultralytics
```

--------------------------------

### Register QEMU binfmt handlers

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/docker/README.md

Run once per host to enable arm64 container execution on x86_64. Repeat after a reboot.

```bash
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
```

--------------------------------

### Launch zed_camera_debug.launch.py with gdbserver

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/launch_files.md

Launches the zed_debug package's zed_camera_debug.launch.py with camera_model set to zedx and a gdbserver command prefix. The cmd_prefix argument is used to prefix the node executable, enabling debugging with gdbserver.

```bash
ros2 launch zed_debug zed_camera_debug.launch.py camera_model:=zedx cmd_prefix:='gdbserver localhost:3000'
```

--------------------------------

### Build with custom ZED SDK using --sdk-url

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/docker/README.md

Use these commands to build the Docker image against a custom or unreleased ZED SDK. For desktop, --cuda must be a full version (X.Y.Z) to pick an nvcr.io/nvidia/cuda tag; for Jetson, --os must be a full L4T version (l4t-rX.Y.Z) to pick an nvcr.io/nvidia/l4t-jetpack tag. When --sdk-url is set, the base image is a plain NVIDIA image and --sdk is ignored.

```bash
./build_desktop.sh --ros-distro humble --os ubuntu-22.04 --cuda 12.6.3 \
                   --sdk-url https://download.stereolabs.com/.../ZED_SDK_....run
```

```bash
./build_desktop.sh --ros-distro humble --os ubuntu-22.04 --cuda 12.6.3 \
                   --sdk-url ~/Downloads/ZED_SDK_Ubuntu22_cuda12.6_v5.0.run
```

```bash
./build_jetson.sh --ros-distro humble --os l4t-r36.4.0 \
                  --sdk-url https://download.stereolabs.com/.../ZED_SDK_....run
```

--------------------------------

### GNSSReplay initialize() method

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/gnss_replay.md

Declaration of the initialize() method. Returns false when the opened SVO has no custom-data key containing "GNSS_json" (scanned via _zed->getSVODataKeys()); otherwise loads all records with _zed->retrieveSVOData("GNSS_json", data) and parses them into _gnss_data. Supports native and legacy record formats.

```cpp
bool initialize();
```

--------------------------------

### startPosTracking() signature

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_component.md

Enables positional tracking. Returns true on success; guarded by mPtMutex when called through startPosTrackingLocked(). Supports depth-less GEN_3 tracking with SDK >= 5.2.

```cpp
bool startPosTracking();
```

--------------------------------

### setSdkLiveTimeOffsetNs and getSdkLiveTimeOffsetNs declarations

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/sl_tools.md

Process-wide functions to set and get the nanosecond offset added to live SDK timestamps. Set once after a successful Camera::open() for a monotonic TIMESTAMP_CLOCK; default is 0 and no effect in replay mode.

```cpp
// sl_tools.hpp:123
void setSdkLiveTimeOffsetNs(int64_t offset_ns);
int64_t getSdkLiveTimeOffsetNs();
```

--------------------------------

### Launch ZedCameraOne with zed_camera.launch.py

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_one_component.md

Launches the ZedCameraOne component as a monocular camera model. Used when camera_model is zedxonegs, zedxone4k, zedxonehdr, or zedxonecore. Manual composition is identical to ZedCamera with the ZedCameraOne class.

```bash
ros2 launch zed_wrapper zed_camera.launch.py camera_model:=zedxone4k
```

--------------------------------

### Launch Multi-Camera with Streaming Input

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/launch_files.md

Launches a camera with a custom name and streaming input from a simulation. Sets sim_mode, use_sim_time, and sim_port.

```bash
ros2 launch zed_wrapper zed_camera.launch.py camera_model:=zedx camera_name:=zed_front sim_mode:=true use_sim_time:=true sim_port:=30000
```

--------------------------------

### ZedCamera(const rclcpp::NodeOptions & options)

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_component.md

Documentation for the ZedCamera constructor, which initializes the ROS 2 component node for ZED cameras.

```APIDOC
## Constructor: `ZedCamera(const rclcpp::NodeOptions & options)`

### Description
Creates a `ZedCamera` ROS 2 component node for the ZED stereo camera family. The constructor validates the node and global contexts, checks the compiled ZED SDK version against `[4.2, 5.5]`, sets the SDK environment variable `ZED_SDK_DISABLE_PROGRESS_BAR_LOG=1`, and schedules a 50 ms one-shot wall timer that invokes `initNode()`. All work happens asynchronously; the constructor returns immediately.

### Method
Constructor

### Signature
```cpp
ZED_COMPONENTS_PUBLIC
explicit ZedCamera(const rclcpp::NodeOptions & options);
```

### Parameters
- `options` (const rclcpp::NodeOptions &) - Required - ROS 2 node options; `use_intra_process_comms()` is read to decide the IPC publishing path.

### Behavior
- Reads `options.use_intra_process_comms()`.
- Validates that the node and global contexts are valid (calls `exit(EXIT_FAILURE)` otherwise).
- Checks the compiled ZED SDK version against `[4.2, 5.5]` (exits with failure on mismatch).
- Sets the SDK environment variable `ZED_SDK_DISABLE_PROGRESS_BAR_LOG=1`.
- Schedules a 50 ms one-shot wall timer that invokes `initNode()`.
- All work happens asynchronously; the constructor returns immediately.

### Throws
No exceptions escape — the body is wrapped in `try { ... } catch (const std::exception & e)` and `catch (...)` which log via `RCLCPP_ERROR_STREAM`.

### Source
- Header: `zed_components/src/zed_camera/include/zed_camera_component.hpp:46`
- Implementation: `zed_components/src/zed_camera/src/zed_camera_component_main.cpp:68`
```

--------------------------------

### SVO and streaming helper methods

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_one_component.md

SVO recording and streaming helper methods. They follow the same contract as ZedCamera::startSvoRecording and ZedCamera::startStreamingServer.

```cpp
bool startSvoRecording(std::string & errMsg);
void stopSvoRecording();
bool startStreamingServer();
void stopStreamingServer();
```

--------------------------------

### Launch Stereo Camera with Default Container

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/launch_files.md

Launches a stereo camera (e.g., zed2i) using the default container. This is the basic usage for a single camera.

```bash
ros2 launch zed_wrapper zed_camera.launch.py camera_model:=zed2i
```

--------------------------------

### Launch ZED node in simulation mode for stereo camera

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Launches a standalone ZED ROS 2 node with simulated ZED data as input. Requires sim_mode and camera_model options, and use_sim_time is recommended for synchronized ROS graph time. Simulated stereo models include zedx, zedxm, zedxnano, zedm, zed2i, and virtual; this feature is incompatible with first-generation ZED cameras.

```bash
ros2 launch zed_wrapper zed_camera.launch.py camera_model:=zedx sim_mode:=true use_sim_time:=true
```

--------------------------------

### Visualize disparity map with image_view

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/CHANGELOG.rst

Use this command to visualize the new ~/disparity/map topic. It replaces the obsolete ~/disparity/disparity_image topic.

```bash
ros2 run image_view disparity_view --ros-args -r image:=/zed/zed_node/disparity/disparity_image
```

--------------------------------

### openZedCamera() method

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_one_component.md

Waits for the camera to be open, reports the real model/SN/firmware and general.camera_name, and captures the SDK monotonic-clock offset via sl_tools::setSdkLiveTimeOffsetNs(...). Declared in zed_camera_one_component.hpp:86.

```cpp
bool openZedCamera();
```

--------------------------------

### Allow container to access EGL display resources

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/docker/README.md

Run this command once on the host to allow the container to access EGL display resources. Required for CUDA-based applications.

```bash
sudo xhost +si:localuser:root
```

--------------------------------

### Checkout wrapper branch or tag

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/docker/README.md

Checkout the tag or commit of the wrapper you want to build before running the build scripts.

```bash
git checkout <branch_or_tag>
```

--------------------------------

### Pre-Pull-Request Checklist Commands

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/CONTRIBUTING.md

Run these commands in order from the root of your ROS 2 workspace before submitting a pull request. They format the code, build the packages, run automatic tests, and analyze reported errors. Repeat steps 1 through 4 until all formatting errors are resolved.

```bash
$ ament_uncrustify --reformat src
```

```bash
$ colcon build --symlink-install --cmake-args=-DCMAKE_BUILD_TYPE=Release
```

```bash
$ colcon test
```

```bash
$ colcon test-result --verbose
```

--------------------------------

### Verify arm64 emulation

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/docker/README.md

Optional check that prints 'aarch64' to confirm emulation works.

```bash
docker run --rm --platform linux/arm64 arm64v8/ubuntu:24.04 uname -m
```

--------------------------------

### getFullFilePath

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/sl_tools.md

Expands a leading '~' using $HOME (falls back to /tmp when unset), then returns the absolute path.

```APIDOC
## getFullFilePath

### Description
Expands a leading '~' using $HOME (falls back to /tmp when unset), then returns the absolute path.

### Function Signature
```cpp
std::string getFullFilePath(const std::string & file_name);
```

### Parameters
- **file_name** (const std::string&) - Required - The file path to expand.

### Returns
- **std::string** - The absolute file path.
```

--------------------------------

### ZedCameraOne constructor declaration

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_one_component.md

Constructor declaration for ZedCameraOne. It accepts ROS 2 node options; use_intra_process_comms() selects the IPC publishing path. The constructor performs two-phase initialization: validates ROS contexts, enforces ZED SDK version range [4.2, 5.5], sets ZED_SDK_DISABLE_PROGRESS_BAR_LOG=1, and schedules a 50 ms one-shot timer calling initNode().

```cpp
ZED_COMPONENTS_PUBLIC
explicit ZedCameraOne(const rclcpp::NodeOptions & options);
```

--------------------------------

### Launch ZED node with gdb prefix

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/zed_debug/README.md

Launches the ZED node under gdb directly from the command line. The gdb --args prefix can be modified to add other gdb options.

```bash
ros2 launch zed_debug zed_camera_debug.launch.py camera_model:=<your_camera_model> cmd_prefix:='gdb --args'
```

--------------------------------

### Launch ZED node in simulation mode for virtual stereo camera

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Launches the ZED node in simulation mode for two simulated ZED X One cameras paired as a virtual stereo camera. No serial number or camera ID is required because the simulator streams already paired stereo images. The camera_model is set to 'virtual'.

```bash
ros2 launch zed_wrapper zed_camera.launch.py camera_model:=virtual sim_mode:=true use_sim_time:=true
```

--------------------------------

### GNSSReplay Class

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/gnss_replay.md

Documentation for the GNSSReplay class, including constructor, destructor, and methods for initializing, grabbing GNSS data, and closing the replay.

```APIDOC
## GNSSReplay Class

### Description
Replays GNSS data recorded as custom SVO v2 data (`GNSS_json` key) alongside a ZED SVO file, feeding the GNSS fusion module during playback.

### Header
`zed_components/src/tools/include/gnss_replay.hpp`

### Namespace
`sl_tools`

### Dependencies
`nlohmann/json`, `sl/Fusion.hpp`

### Class Declaration
```cpp
class GNSSReplay
{
public:
  explicit GNSSReplay(const std::shared_ptr<sl::Camera> & zed);
  ~GNSSReplay();
  bool initialize();
  void close();
  sl::FUSION_ERROR_CODE grab(sl::GNSSData & current_data, uint64_t current_timestamp);
protected:
  sl::GNSSData getNextGNSSValue(uint64_t current_timestamp);
private:
  unsigned _current_gnss_idx = 0;
  unsigned long long _previous_ts = 0;
  unsigned long long _last_cam_ts = 0;
  nlohmann::json _gnss_data;
  std::shared_ptr<sl::Camera> _zed;
};
```

## Constructor

### Description
Stores the camera handle; does no I/O.

### Signature
```cpp
explicit GNSSReplay(const std::shared_ptr<sl::Camera> & zed);
```

### Parameters
- **zed** (const std::shared_ptr<sl::Camera> &) - Required - The opened camera handle (must be reading an SVO)

## Destructor

### Description
Calls `close()`.

### Signature
```cpp
~GNSSReplay();
```

## Methods

### initialize()

#### Description
Initializes the replay by loading GNSS data from the SVO file. Returns `false` if the SVO has no custom-data key containing `"GNSS_json"`; otherwise loads all records and parses them.

#### Signature
```cpp
bool initialize();
```

#### Return Value
- **bool** - `false` when the opened SVO has no custom-data key containing `"GNSS_json"`; otherwise `true` after loading and parsing all records.

#### Supported Record Formats
1. Native format: `{"coordinates": {"latitude", "longitude", "altitude"}, "ts", "latitude_std", "longitude_std", "altitude_std", "position_covariance": [9 floats]}`.
2. Legacy format, converted to format 1: `{"Eph", "EpochTimeStamp", "Epv", "Geopoint": {"Altitude", "Latitude", "Longitude"}, "Position", "Velocity"}`.

### grab()

#### Description
Retrieves the next GNSS sample based on the current camera timestamp. Returns `SUCCESS` when a new GNSS fix is emitted, or a non-SUCCESS code when no more data is available.

#### Signature
```cpp
sl::FUSION_ERROR_CODE grab(sl::GNSSData & current_data, uint64_t current_timestamp);
```

#### Parameters
- **current_data** (sl::GNSSData &) - Required - Output parameter that receives the next GNSS sample.
- **current_timestamp** (uint64_t) - Required - Current camera timestamp used to pick the next record.

#### Return Value
- **sl::FUSION_ERROR_CODE** - `sl::FUSION_ERROR_CODE::SUCCESS` when a new GNSS fix was emitted, `sl::FUSION_ERROR_CODE::FAILURE` (or a non-SUCCESS code) when no more data is available.

### close()

#### Description
Clears the parsed data and resets the internal indices.

#### Signature
```cpp
void close();
```

### getNextGNSSValue() (protected)

#### Description
Returns the parsed `sl::GNSSData` for the internal index, or an empty record (`coordinate_status = sl::GNSS_STATUS::UNKNOWN`) when out of range.

#### Signature
```cpp
sl::GNSSData getNextGNSSValue(uint64_t current_timestamp);
```

#### Parameters
- **current_timestamp** (uint64_t) - Required - Current camera timestamp used to select the next record.

#### Return Value
- **sl::GNSSData** - The parsed GNSS data for the current index, or an empty record when out of range.

## Usage Example

```cpp
#include <sl/Camera.hpp>
#include <zed_components/gnss_replay.hpp>

std::shared_ptr<sl::Camera> zed = std::make_shared<sl::Camera>();
sl::InitParameters init;  // svo_input_filename = "recording.svo"
if (zed->open(init) != sl::ERROR_CODE::SUCCESS) { /* handle */ }

sl_tools::GNSSReplay replay(zed);
if (!replay.initialize()) {
  // SVO contains no 'GNSS_json' custom data
}

sl::GNSSData gnss;
sl::Timestamp cam_ts = zed->getTimestamp(sl::TIME_REFERENCE::IMAGE);
sl::FUSION_ERROR_CODE rc = replay.grab(gnss, cam_ts.getNanoseconds());
if (rc == sl::FUSION_ERROR_CODE::SUCCESS) {
  // feed gnss into a fusion callback / publish on ~/pose/fused_fix
}
```

## Error Handling
Check the return code of `grab()` against `sl::FUSION_ERROR_CODE::SUCCESS`; treat any other value as "no new fix".
```

--------------------------------

### VSCode launch.json for C++ debugging

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/zed_debug/README.md

VSCode launch configuration for debugging the ZED ROS2 node. With "stopAtEntry": true, the node stops at the beginning of the main function, allowing breakpoints to be set before execution continues.

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "C++ Debugger",
            "request": "launch",
            "type": "cppdbg",
            "miDebuggerServerAddress": "localhost:3000",
            "cwd": "${workspaceFolder}",
            "program": "install/zed_debug/lib/zed_debug/zed_debug_proc",
            "stopAtEntry": true
        }
    ]
}
```

--------------------------------

### getSDKVersion

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/sl_tools.md

Fills major, minor, and sub_minor by reference from sl::getSDKVersion() and returns the version string.

```APIDOC
## getSDKVersion

### Description
Fills major, minor, and sub_minor by reference from sl::getSDKVersion() and returns the version string.

### Function Signature
```cpp
std::string getSDKVersion(int & major, int & minor, int & sub_minor);
```

### Parameters
- **major** (int&) - Required - Output for major version.
- **minor** (int&) - Required - Output for minor version.
- **sub_minor** (int&) - Required - Output for sub-minor version.

### Returns
- **std::string** - The SDK version string.
```

--------------------------------

### Launch ZED node with valgrind prefix

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/zed_debug/README.md

Runs the ZED node under valgrind with full leak checking and origin tracking to detect memory leaks and other memory-related issues. The valgrind options can be modified as needed.

```bash
ros2 launch zed_debug zed_camera_debug.launch.py camera_model:=<your_camera_model> cmd_prefix:='valgrind --leak-check=full --track-origins=yes'
```

--------------------------------

### Launch with Inline Parameter Override

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/launch_files.md

Launches a camera with inline parameter overrides, which have the highest priority. Overrides debug.disable_nitros and depth.depth_mode.

```bash
ros2 launch zed_wrapper zed_camera.launch.py camera_model:=zedx \
  param_overrides:='debug.disable_nitros:=true;depth.depth_mode:=NEURAL'
```

--------------------------------

### Launch ZED node in simulation mode for monocular ZED X One camera

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/README.md

Launches the ZED node in simulation mode for ZED X One monocular cameras. The camera_model must match the simulated device; here it is set to 'zedxonegs'. Simulated monocular models include zedxonegs, zedxone4k, and zedxonehdr.

```bash
ros2 launch zed_wrapper zed_camera.launch.py camera_model:=zedxonegs sim_mode:=true use_sim_time:=true
```

--------------------------------

### Build ZED ROS2 wrapper with RelWithDebInfo symbols

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/zed_debug/README.md

Builds the ZED ROS2 wrapper with optimized code and debug symbols using the RelWithDebInfo build type, normally required by the ZED SDK.

```bash
colcon build --symlink-install --cmake-args=-DCMAKE_BUILD_TYPE=RelWithDebInfo --parallel-workers $(nproc)
```

--------------------------------

### initCostTraversibily

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/cost_traversability.md

Initializes a cost terrain with the given resolution, range, and height threshold.

```APIDOC
## initCostTraversibily

### Description
Initializes a cost terrain with the given resolution, range, and height threshold.

### Function Signature
```cpp
void initCostTraversibily(
  sl::Terrain & cost_terrain, float resolution, float range,
  float height_threshold);
```

### Parameters
- `cost_terrain` (sl::Terrain &) - Required - Terrain to initialize (in/out)
- `resolution` (float) - Required - Grid resolution in meters
- `range` (float) - Required - Grid extent in meters
- `height_threshold` (float) - Required - Height threshold (meters) used when populating the terrain

### Notes
The function name is spelled `initCostTraversibily` (sic) in the source.
```

--------------------------------

### GNSSReplay constructor

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/gnss_replay.md

Constructor declaration for GNSSReplay. Takes a shared pointer to an opened sl::Camera that must be reading an SVO file. Stores the camera handle without performing any I/O.

```cpp
explicit GNSSReplay(const std::shared_ptr<sl::Camera> & zed);
```

--------------------------------

### checkRoot

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/sl_tools.md

Returns true when running as root (needed for SCHED_FIFO/SCHED_RR).

```APIDOC
## checkRoot

### Description
Returns true when running as root (needed for SCHED_FIFO/SCHED_RR).

### Function Signature
```cpp
bool checkRoot();
```

### Returns
- **bool** - True if running as root.
```

--------------------------------

### [SERVICE] ~/enable_streaming

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/endpoints.md

Enables or disables streaming of the ZED camera.

```APIDOC
## [SERVICE] ~/enable_streaming

### Description
Enables or disables streaming of the ZED camera.

### Method
SERVICE CALL

### Endpoint
`~/enable_streaming` where `~` is the node namespace.

### Service Type
`std_srvs/srv/SetBool`

### Request
- `data` (bool) - Enable (true) or disable (false) streaming.

### Request Example
```json
{
  "data": true
}
```

### Response
- `success` (bool) - Indicates success.
- `message` (string) - Descriptive message.

```

--------------------------------

### qos2str (history policy)

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/sl_tools.md

Converts a QoS history policy to a human-readable string.

```APIDOC
## qos2str (history policy)

### Description
Converts a QoS history policy to a human-readable string.

### Function Signature
```cpp
std::string qos2str(rmw_qos_history_policy_t qos);
```

### Parameters
- **qos** (rmw_qos_history_policy_t) - Required - The QoS history policy.

### Returns
- **std::string** - Human-readable QoS policy name.
```

--------------------------------

### Build ZED ROS2 wrapper with Debug symbols

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/zed_debug/README.md

Builds the ZED ROS2 wrapper with debug symbols using the Debug build type.

```bash
colcon build --symlink-install --cmake-args=-DCMAKE_BUILD_TYPE=Debug --parallel-workers $(nproc)
```

--------------------------------

### Echo health status topic

Source: https://github.com/stereolabs/zed-ros2-wrapper/blob/master/_autodocs/api-reference/zed_camera_component.md

Command to monitor the node's health status topic. Useful for observing startup failures because initNode() calls exit(EXIT_FAILURE) when startCamera() fails, so consumers watch the log and this topic.

```bash
ros2 topic echo /zed/zed_node/status/health --qos-durability transient_local
```
Tokens:
Raw