Docker Images

The following instructions will get you a copy of OpenPTrack running using Docker.

If you have chosen to use the Manual Build & Installation, you do not need to use Docker.

Prerequisites

Please see Supported Hardware. You need at least 30 GB of space on each machine to run the Docker installation. If you have an existing OpenPTrack Installation and need a Docker installation, it is possible to set up a Docker installation and run it in parallel with your current installation.

Docker, nvidia-docker 2, and the appropriate Nvidia drivers are required to use Open_PTrack docker images and this page guides you through the installation process.

Installation

As we finalize OpenPTrack v2.2 (with support for the Kinectv2, RealSense, and Zed imagers), there are two versions available. For the most up to date code with support for all imagers, clone the 1804 branch of the open_ptrack_docker_config repository (named 1804 because it uses Ubuntu 18.04):

git clone -b 1804 https://github.com/OpenPTrack/open_ptrack_docker_config.git
cd open_ptrack_docker_config

If, for whatever reason, you wish to use the older OpenPTrack version, you can clone the master branch:

git clone https://github.com/OpenPTrack/open_ptrack_docker_config.git
cd open_ptrack_docker_config

We recommend using the newest version- moving forward, we will be dropping support for the old version.

If you have nvidia-docker 1.0 installed, you need to remove it and all existing GPU containers. Run the following to do this:

sudo docker volume ls -q -f driver=nvidia-docker | xargs -r -I{} -n1 docker ps -q -a -f volume={} | xargs -r docker rm -f`

sudo apt-get purge -y nvidia-docker

If you have not yet installed docker, nvidia-docker 2 and Nvidia drivers, we have a script to do so.

N.B Nvidia drivers can be tricky to setup as they are dependent on your graphics card, host OS, and the CUDA version. The old OpenPTrack v2.1 docker image uses CUDA 8.0, and the new v2.2 uses CUDA 10.0. The scripts below install the minimum driver requirement. However, newer drivers may also work. If you already have Nvidia drivers installed and don't want to change them, please consult Nvidia's compatibility matrix for your specific configuration. Otherwise, the following commands will install the necessary drivers for you.

If you are using the older OpenPTrack v2.1 (i.e. you cloned the master branch above), execute:

chmod +x setup_host
./setup_host

If you are using the new OpenPTrack v2.2, we now support both Ubuntu 16.04 and 18.04 host machines with the scripts setup_1604_host and setup_1804_host. Run the commands above using the script that matches your host OS.

After successfully executing the setup host script, reboot your system. After rebooting your system test nvidia-docker 2 by running

sudo docker run --runtime=nvidia --rm nvidia/cuda:8.0-devel nvidia-smi

You should see an output similar to this (the Driver version will be different depending on which script you used above):

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 384.130                Driver Version: 384.130                   |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  GeForce GTX 750 Ti  Off  | 00000000:01:00.0  On |                  N/A |
| 40%   31C    P8     1W /  38W |    188MiB /  1998MiB |      1%      Default |
+-------------------------------+----------------------+----------------------+
                                                                               
+-----------------------------------------------------------------------------+
| Processes:                                                       GPU Memory |
|  GPU       PID   Type   Process name                             Usage      |
|=============================================================================|
+-----------------------------------------------------------------------------+

Working with Docker

This section provides a brief introduction to working with a Docker installation of OpenPTrack. For more detailed information, check out the Docker documentation.

Inside the open_ptrack_docker_config directory, there are single_camera_tracking and multi_camera_tracking folders. You can navigate into the appropriate folder depending if you're running a single or multi camera system.

Containers

After installing the prerequisites,you can start a single_camera_tracking or multi_camera_tracking container depending on your need. The single_camera_tracking container allows you to test OpenPTrack using just a single camera while the multi_camera_tracking container is the way to go if you have more than one camera working together in a network.

When you start a container (instructions below), directories will be linked between your host machine and the docker container. This means launch files created during the calibration file will be saved to your host machine. Changes to the OpenPTrack source code are not saved to the host machine.

After running a container, they can be stopped and/or removed. It is generally fine to keep your OpenPTrack docker container running; it can be useful to stop containers that aren't in use if you are running several docker containers, and it is advised to remove old docker containers (i.e. after updating your OpenPTrack software, etc.)

single_camera_tracking

cd ~/open_ptrack_docker_config/single_camera_tracking
chmod +x run_single_camera
./run_single_camera

To remove the container run : ./run_single_camera -r

To stop the container run: ./run_single_camera -s

Once the single camera tracking container is running you can move on to intrinsic calibration; or jump directly into person tracking, pose annotation or object tracking if intrinsic calibration is not needed.

N.B If you plan on running more than one single camera container on a single machine, you should edit the container_name in run_single_camera to be unique.

multi_camera_tracking

cd ~/open_ptrack_docker_config/multi_camera_tracking

Edit ros_network.env inside multi_camera_tracking to match your system network configuration and then run:

chmod +x run_multi_camera
./run_multi_camera

To remove the container run : ./run_multi_camera -r

To stop the container run: ./run_multi_camera -s

N.B If you plan on running more than one multi camera container on a single machine, you should edit the container_name in run_multi_camera to be unique

In order to run the script from any directory please use the following:

sudo ln -s /home/$USER/open_ptrack_docker_config/single_camera_tracking/run_single_camera /usr/local/bin/run_single_camera
sudo ln -s /home/$USER/open_ptrack_docker_config/multi_camera_tracking/run_multi_camera /usr/local/bin/run_multi_camera

Once your multi_camera_tracking container is running, follow Time Synchronization on the wiki here and then continue with the rest of the configuration and calibration.

Deployment

To create a new terminal within a running container (for example, during calibration, multi camera tracking, or face recognition), open a new terminal and follow the same procedures for single_camera_tracking or multi_camera_tracking.

Images

Docker containers are instances of Docker images. Pre-built docker images for OpenPTrack are available from our Docker Hub. If you'd like to manually build images, please see below.

Updating Images

New images containing software updates and fixes will periodically be push to Docker Hub. To update an image, you can run the command:

docker pull <IMAGE_NAME>

Any existing containers will have to be removed and restarted for the new image to be used. (Note that removing the docker containers means any changes to source code will be removed, but any calibration files/etc will be safe). Docker containers can be individually removed (as described above), or to stop & remove all containers of a given image, run:

sudo docker rm $(sudo docker stop $(sudo docker ps -a -q --filter ancestor=<IMAGE_NAME> --format="{{.ID}}"))

Manually Building Docker Images (Optional)

This step is not required to run OpenPtrack as pre-built images are already available. If however you want to build the images yourself, the information is available here.