Software IntegrationDocker

Create and use Docker images for ZED and ROS 2

Open in ClaudeOpen in ChatGPT

We recommend using the Docker image built using this guide as the base image for your custom setup.

Using the ZED ROS 2 Wrapper repository resources

The docker folder of the ZED ROS 2 Wrapper GitHub repository contains a list of Dockerfile files to build Docker images ready to start the nodes of the ZED ROS 2 Wrapper:

  • Dockerfile.desktop-humble: development desktop image for ROS 2 Humble, running on the specified Ubuntu and CUDA versions
  • Dockerfile.l4t-humble: Jetson™ image for ROS 2 Humble, running on the given L4T version

The ZED Wrapper code is copied from the source files of the working branch and compiled inside the Docker image.

In the entrypoint files, we set the value of the ROS_DOMAIN_ID environment variable to 0, which is the default value in ROS 2.

If your setup requires a different value, you can change it in the ros_entrypoint_jetson.sh and ros_entrypoint.sh files before building your image, so it is set automatically when starting your Docker image, or you can use the CLI command export ROS_DOMAIN_ID=<new_value> at the start of each interactive session.

You can get more details concerning the ROS_DOMAIN_ID usage on the official ROS 2 documentation.

Cross compilation

You can easily compile the image for Jetson™ from your usual desktop PC. To do so, just run the following line before launching the build command:

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

Build the Docker images

We provide scripts to build your image with the right configuration.

  • Checkout the branch, tag or commit id of the ROS 2 wrapper that you want to use.
$git checkout <build_branch>

e.g. use the latest code from the master branch:

$git checkout master
  • Build the image for Jetson:
$./jetson_build_dockerfile_from_sdk_and_l4T_version.sh <l4T version> <ZED SDK version>
  • Build the image for Desktop:
$./desktop_build_dockerfile_from_sdk_ubuntu_and_cuda_version.sh <Ubuntu version> <CUDA version> <ZED SDK version>

Examples:

$# Jetson™ with JP6.0 and ZED SDK v4.2.3
$./jetson_build_dockerfile_from_sdk_and_l4T_version.sh l4t-r36.3.0 zedsdk-4.2.3
$# Desktop on Ubuntu 22.04, CUDA 12.6.3 and ZED SDK v4.2.3
$./desktop_build_dockerfile_from_sdk_ubuntu_and_cuda_version.sh ubuntu-22.04 cuda-12.6.3 zedsdk-4.2.3

Some configurations will not work. For example, if a specific ZED SDK does not exist for a given Ubuntu/CUDA/L4T version, or if the given ROS 2 wrapper is not compatible with the selected Ubuntu version.

Run the Docker image

NVIDIA runtime

NVIDIA drivers must be accessible from the Docker image to run the ZED SDK code on the GPU. You’ll need:

  • The nvidia container runtime installed, following this guide
  • A specific docker runtime environment with --gpus all or -e NVIDIA_DRIVER_CAPABILITIES=all
  • Docker privileged mode with --privileged

Network

Set up the network configuration to enable communication between the Docker image, other Docker images, and the host:

  • --network=host: Remove network isolation between the container and the Docker host
  • --ipc=host: Use the host system’s Inter-Process Communication namespace
  • --pid=host: Use the host system’s namespace for process ID

Display context to use CUDA based applications

Use the same host DISPLAY environment variable in every Docker image to enable CUDA-based applications with -e DISPLAY=$DISPLAY.

The shared volume /tmp/.X11-unix/:/tmp/.X11-unix is also required.

Shared Volumes

A few volumes should also be shared with the host.

  • /tmp/.X11-unix/:/tmp/.X11-unix is required to enable X11 server communication for CUDA-based applications
  • /usr/local/zed/settings:/usr/local/zed/settings if you plan to use the robot in an Internet-negated area, and you previously downloaded the camera calibration files by following this guide.
  • /usr/local/zed/resources:/usr/local/zed/resources: if you plan to use the AI module of the ZED SDK (Object Detection, Skeleton Tracking, NEURAL depth), we suggest bind-mounting a folder to avoid downloading and optimizing the AI models each time the Docker image is restarted. The first time you use the AI model inside the Docker image, it will be downloaded and optimized in the local bind-mounted folder, and stored there for subsequent runs.
    • If you plan to use different SDK versions in different Docker images, it’s preferable to use a different volume on the host for each of them: /<specific_folder_name>/:/usr/local/zed/resources
  • /dev:/dev to share the video and other required devices
  • /dev/shm:/dev/shm to use ROS 2 with shared memory
  • For GMSL2 cameras (ZED X, ZED X One) you’ll also need
    • /tmp:/tmp
    • /var/nvidia/nvcam/settings/:/var/nvidia/nvcam/settings/
    • /etc/systemd/system/zed_x_daemon.service:/etc/systemd/system/zed_x_daemon.service

Start the Docker container

First, allow the container to access EGL display resources (required only once):

$sudo xhost +si:localuser:root

Then you can start an interactive session:

USB3 cameras

$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>

GMSL cameras

$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>