Getting Started with Docker and ZED SDK

Introduction

Docker lets you run code in a container, a virtualized world where all of the code dependencies are in place. Within a container the code is isolated from the rest of the host machine.

For the ZED SDK, with its specific OS and NVIDIA CUDA requirements, Docker means you can use the SDK on an unsupported operating system and without installing its target CUDA version – saving time and keeping your system “clean” from version conflicts. The isolation from your host machine also means that what you build is much more portable since it can be docked to other devices the same way.

Examples of when this is useful:

  • You’re working on a Linux distribution like Debian or CentOS which is not supported by the SDK. Switching to Ubuntu may not be an option and would be time-consuming. Docker lets you run the ZED SDK inside its own Ubuntu environment on your non-Ubuntu device with little effort.
  • You’re testing different versions of the ZED SDK at the same time, perhaps to check how the latest version improves performance over the one you’re been building your app with. Docker lets you quickly switch between them without reinstalling the SDK, CUDA, and possibly the OS.
  • You need to build, test and deploy an app using the ZED SDK in an isolated environment to be sure they don’t depend on a factor of the host machine other than the stated dependencies. This is useful for CI/CD (Continuous Integration/Continuous Delivery). We do this at Stereolabs to build our ROS wrapper among other things.

All this comes with virtually no performance cost. The only cost you do pay is the initial setup and configuration that is explained in the following documentations. We also provide ready-to-go containers and Dockerfiles.

Setting Up Docker

  1. Install Docker on your local host machine.
  2. Install NVIDIA Docker support. Since the ZED SDK uses CUDA capabilities, the NVIDIA Docker support is required to use the ZED SDK with Docker.

Download ZED SDK Docker Images

Now that Docker and NVIDIA Docker are installed you’ll be able to use the ZED SDK with Docker.

Docker images (which become containers when run) are stored online on a registry. A registry is a stateless, highly scalable server-side application that stores and lets you distribute Docker images. By default, the registry uses the official free-to-use Docker registry, DockerHub.

When running docker pull stereolabs/zed:2.8-devel-cuda10.0-ubuntu18.04, Docker will check if there’s an image called zed pushed by a user named stereolabs on Dockerhub, and a version of it with the tag 2.8-devel-cuda10.0-ubuntu18.04.

You can browse the available ZED images we provide here.

Once you’ve found an image from the above link that fits your needs you can pull it with:

$docker pull stereolabs/zed:{tag_of_the_image}

For instance, to pull the Docker image of SDK 2.8 with CUDA 10.0 on Ubuntu 18.04 use:

$docker pull stereolabs/zed:2.8-devel-cuda10.0-ubuntu18.04

Run a ZED SDK Docker Image

Once pulled on the host machine, you can run the Docker image with:

$docker run -it --privileged --runtime nvidia stereolabs/zed:2.8-devel-cuda10.0-ubuntu18.04

The --privileged option grants permission to pass through all the devices to get the Docker container. There is some security risk, but we do this because specifying the exact device to grant permissions to is very complicated given the direct, low-level connection required for the ZED.

Verify the camera connection with the lsusb command:

$lsusb -d 2b03: -vvv

For more information on running docker images please check out the Docker Documentation.

Graphical Interface with Docker

While not technically required, OpenGL is useful for developing ZED applications as Docker doesn’t provide any display at all by default. We recommend using a container with OpenGL display support included (from nvidia/cudagl container).

In fact we already propose an image for the ZED SDK with OpenGL support. You can pull this image with:

$docker pull stereolabs/zed:2.8-devel-gl-cuda10.0-ubuntu18.04

Then, to run it, you’ll need to add the rights to connect to server X:

$xhost +si:localuser:root

Once you have rights to connect to the server X, you can actually run the image:

$docker run -it --privileged --runtime nvidia --rm -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix stereolabs/zed:2.8-devel-gl-cuda10.0-ubuntu18.04

Now you can run any OpenGL tool provided with the SDK:

$/usr/local/zed/tools/ZED_Explorer

Using ROS with Docker

For ROS users, you can pull a container with ROS Kinetic installed:

$docker pull stereolabs/zed:2.8-ros-cuda10.0-ubuntu18.04

and run it with:

$docker run -it --privileged --runtime=nvidia --rm stereolabs/zed:2.8-ros-cuda10.0-ubuntu18.04

To install the latest ROS wrapper for the ZED, simply run:

$cd src ; git clone https://github.com/stereolabs/zed-ros-wrapper.git
$cd .. ; catkin_make

In order to run the container with display, checkout the ROS documentation about using Docker with X server.