Tutorial: Installation from Docker images

Table of Contents

• Introduction
• Prerequisites: Install Docker Engine
  • On Ubuntu host
  • On MacOS host
• Pull existing docker image
  • Pull Ubuntu 22.04 image
  • Pull Ubuntu 20.04 image
  • Pull Ubuntu 18.04 image
• Build docker image from Dockerfile
  • Build Ubuntu 24.04 image
  • Build Ubuntu 22.04 image
  • Build Ubuntu 20.04 image
  • Build Ubuntu 18.04 image
• Start ViSP container
  • On Ubuntu host
  • On MacOS host
• How to use ViSP container
• Next tutorial

Introduction

Even with the detailed and tested Installation from source code tutorials, sometimes it is tough for people to get a system up and running with ViSP. That's why in this tutorial we explain how to get ready to use Docker images that contains ViSP source code with already build tests, examples and tutorials that you may just run to discover ViSP capabilities.

Our Docker images available on Docker Hub are around 1 GB in size (compressed size) and contain minimal things to discover and start to play with ViSP.

Prerequisites: Install Docker Engine

On Ubuntu host

As mentioned here, to install Docker Engine on Ubuntu host using the repository, follow the instructions:

• Update the apt package index and install packages to allow apt to use a repository over HTTPS:

  $ sudo apt-get update
  
  $ sudo apt-get install \
      apt-transport-https \
      ca-certificates \
      curl \
      gnupg-agent \
      software-properties-common
  

• Add Docker’s official GPG key:

  $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
  

• Use the following command to set up the stable repository

  $ sudo add-apt-repository \
      "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
      $(lsb_release -cs) \
      stable"
  

• Update the apt package index, and install the latest version of Docker Engine and containerd

  $ sudo apt-get update
  $ sudo apt-get install docker-ce docker-ce-cli containerd.io
  

On MacOS host

• To install Docker Engine on MacOS host, first go to the Docker Store and download Docker Desktop for Mac.
• Double-click Docker.dmg to open the installer, then drag Moby the whale to the Applications folder.
• Double-click Docker.app in the Applications folder to start Docker.
• You are prompted to authorize Docker.app with your system password after you launch it. Privileged access is needed to install networking components and links to the Docker apps.
• In order to run GUIs from the container, you will need to:
  • Install XQuartz 2.7.11 or later
  • After installing XQuartz, start it and open XQuartz -> Preferences from the menu bar. Go to the last tab, Security, and enable both "Allow connections from network clients" and "Authenticate connections" checkboxes and restart XQuartz.
    
  • Now your Mac will be listening on port 6000 for X11 connections. Record the IP Address of your Mac as you will need it in your containers.
  • Restart X11 server or reboot your Mac to take into account previous changes

Pull existing docker image

In Docker Hub, we provide several ready-to-use Docker images that can be used on an Ubuntu or macOS host with ViSP already built. Instead, there is also the possibility to build docker images from a Dockerfile following instruction given in Build docker image from Dockerfile section.

Pull Ubuntu 22.04 image

$ docker pull vispci/vispci:ubuntu-22.04

Pull Ubuntu 20.04 image

$ docker pull vispci/vispci:ubuntu-20.04

Pull Ubuntu 18.04 image

$ docker pull vispci/vispci:ubuntu-18.04

Build docker image from Dockerfile

We suppose here that you cloned ViSP from github in your workspace.

Change directory to access the Dockerfile and build the corresponding docker image

Build Ubuntu 24.04 image

$ cd $VISP_WS/visp/docker/ubuntu-24.04
$ docker build -t vispci/vispci:ubuntu-24.04 .

Build Ubuntu 22.04 image

$ cd $VISP_WS/visp/docker/ubuntu-22.04
$ docker build -t vispci/vispci:ubuntu-22.04 .

Build Ubuntu 20.04 image

$ cd $VISP_WS/visp/docker/ubuntu-20.04
$ docker build -t vispci/vispci:ubuntu-20.04 .

Build Ubuntu 18.04 image

$ cd $VISP_WS/visp/docker/ubuntu-18.04
$ docker build -t vispci/vispci:ubuntu-18.04 .

Start ViSP container

On Ubuntu host

• On your computer running Ubuntu, allow access to the X11 server

  $ xhost +local:docker
  non-network local connections being added to access control list
  

• Run your Docker container. The following command connects to the ubuntu-22.04 Docker container. It can be easily adapted to any other container name.

  $ docker run --rm -it --network=host --privileged \
            --env=DISPLAY \
            --env=QT_X11_NO_MITSHM=1 \
            --volume=/tmp/.X11-unix:/tmp/.X11-unix:rw \
            --volume=/dev:/dev \
            vispci/vispci:ubuntu-22.04
  vispci@6c8d67579659:~$ pwd
  /home/vispci
  

On MacOS host

• Get your MacOS computer IP address

  $ IP=$(/usr/sbin/ipconfig getifaddr en0)
  $ echo $IP
  $ 192.168.1.18
  

• Allow connections from MacOS to XQuartz

  $ xhost + "$IP"
  192.168.1.18 being added to access control list
  

• Run your Docker container. The following command connects to the ubuntu-22.04 Docker container. It can be easily adapted to any other container name.

  $ docker run --rm -it --network=host --privileged \
            --env=DISPLAY="${IP}:0" \
            --env=QT_X11_NO_MITSHM=1 \
            --volume=/tmp/.X11-unix:/tmp/.X11-unix:rw \
            --volume=/dev:/dev \
            vispci/vispci:ubuntu-22.04
  vispci@6c8d67579659:~$ pwd
  /home/vispci
  

How to use ViSP container

• We suppose here that you successfully Start ViSP container using one of the previous command:

  $ docker run ... -it vispci/vispci:ubuntu-<version>
  

• Within the container, ViSP workspace is installed in $HOME/visp-ws folder:

  vispci@6c8d67579659:~$ ls $HOME/visp-ws
  visp  visp-build  visp-images
  

  • In visp folder you will find a Github clone of the source code. To update its content with the last changes, run:

    cd $HOME/visp-ws/visp; git pull
    

  • In visp-build folder you will find ViSP libraries and all the build binaries corresponding to the tests, examples and tutorials. If you updated visp folder content, don't forget to refresh your build with:

    cd $HOME/visp-ws/visp-build; cmake ../visp; make -j$(nproc)
    

  • In visp-images folder you will find the dataset used by the tests and examples.
• You are now ready to run binaries that open GUI

  vispci@6c8d67579659:~$ cd $HOME/visp-ws/visp-build/tutorial/image
  vispci@6c8d67579659:~$ ./tutorial-viewer monkey.png
  A click to quit...
  

  
• If you are on an Ubuntu host, you are now ready to run binaries that require access to your camera.

  vispci@6c8d67579659:~$ cd $HOME/visp-ws/visp-build/tutorial/grabber
  vispci@6c8d67579659:~$ ./tutorial-grabber-v4l2
  Use device : 0
  Recording  : disabled
  Warning: cannot set input channel to 2
  Image size : 640 480
  

  or with this other tutorial

  vispci@6c8d67579659:~$  ./tutorial-grabber-opencv
  Use device : 0
  Recording  : disabled
  

Next tutorial

You are now ready to see the next Tutorial: How to create and build a project that uses ViSP and CMake on Unix or Windows that will show you how to use ViSP as a 3rd party to build your own project.