Docker support

README.md

@@ -2,7 +2,7 @@
 
 TSDF++ is a novel multi-object TSDF formulation that can encode multiple object surfaces at each voxel. In a multiple dynamic object tracking and reconstruction scenario, a TSDF++ map representation allows maintaining accurate reconstruction of surfaces even while they become temporarily occluded by other objects moving in their proximity. At the same time, the representation allows maintaining a single volume for the entire scene and all the objects therein, thus solving the fundamental challenge of scalability with respect to the number of objects in the scene and removing the need for an explicit occlusion handling strategy.
 
-## Citing 
+## Citing
 
 When using **TSDF++** in your research, please cite the following publication:
 
@@ -22,11 +22,11 @@ Margarita Grinvald, Federico Tombari, Roland Siegwart, and Juan Nieto, **TSDF++:
 The installation has been tested on Ubuntu 16.04 and Ubutnu 20.04.
 
 ### Requirements
-- ROS 
+- ROS
 - C++14 for [PCL 1.10](https://github.com/PointCloudLibrary/pcl)
 
 ### Install dependencies
-Install ROS following the instructions at the [ROS installation page](http://wiki.ros.org/ROS/Installation). The full install (`ros-kinetic-desktop-full`, `ros-melodic-desktop-full`) are recommended. 
+Install ROS following the instructions at the [ROS installation page](http://wiki.ros.org/ROS/Installation). The full install (`ros-kinetic-desktop-full`, `ros-melodic-desktop-full`) are recommended.
 
 Make sure to source your ROS _setup.bash_ script by following the instructions on the ROS installation page.
 
@@ -42,7 +42,7 @@ If you don't have a [catkin](http://wiki.ros.org/catkin) workspace yet, create a
 ```bash
 mkdir -p $CATKIN_WS/src && cd $CATKIN_WS
 catkin init
-catkin config --extend /opt/ros/$ROS_VERSION --merge-devel 
+catkin config --extend /opt/ros/$ROS_VERSION --merge-devel
 catkin config --cmake-args -DCMAKE_CXX_STANDARD=14 -DCMAKE_BUILD_TYPE=Release
 wstool init src
 ```
@@ -69,16 +69,21 @@ catkin build tsdf_plusplus_ros rgbd_segmentation mask_rcnn_ros cloud_segmentatio
 source ../devel/setup.bash # (bash shell: ../devel/setup.bash,  zsh shell: ../devel/setup.zsh)
 ```
 
+# Installation using Docker
+
+See [Docker README.md](docker/README.md) for details.
+
 
 ## Troubleshooting
 ### Compilation freeze
-By default `catkin build` on a computer with `N` CPU cores will run `N` `make` jobs simultaneously. If compilation seems to hang forever, it might be running low on RAM. Try limiting the number of maximum parallel build jobs through the `-jN` flag to a value way lower than your CPU count, i.e.
+By default `catkin build` on a computer with `N` CPU cores will run `N` `make` jobs simultaneously. If compilation seems to hang forever, it might be running low on RAM. Try limiting the number of maximum parallel build jobs through the `-jN` flag to a value way lower than your CPU count.
+For instance, you can use half the cores in your computer. This will provide the OS and other processes the other half.
 ```bash
-catkin build tsdf_plusplus_ros rgbd_segmentation mask_rcnn_ros cloud_segmentation -j4
+catkin build tsdf_plusplus_ros rgbd_segmentation mask_rcnn_ros cloud_segmentation -j$(($(nproc) /  2))
 ```
 If it still freezes at compilation time, you can go as far as limiting the maximum number of parallel build jobs and max load to `1` through the `-lN` flag:
 ```bash
-catkin build tsdf_plusplus_ros rgbd_segmentation mask_rcnn_ros cloud_segmentation -j1 -l1
+catkin build tsdf_plusplus_ros rgbd_segmentation mask_rcnn_ros cloud_segmentation -j$(($(nproc) / 2)) -l1
 ```
 
 ## License

docker/README.md

@@ -0,0 +1,68 @@
+# Building image and running container
+
+To build the docker image run:
+```bash
+./bin/build-ros-image.sh
+```
+
+To run the docker image use:
+```bash
+./bin/run-ros-image.sh
+```
+
+# Getting environment up and running
+
+## Set up local development environment
+
+To get the a local development environment up and running quickly using docker run:
+```bash
+./bin/build-ros-image.sh
+./bin/set-me-up.sh
+```
+
+You can skip running `./bin/build-ros-image.sh` if the image is already built.
+
+The `./bin/set-me-up.sh` script will do the following:
+- Run a docker container
+- Copy the built workspace to the destination folder of choice
+- Stop the container
+
+Note that if you want to change the remote to SSH (or your fork) you'll need to edit the `origin` in the cloned repos.
+
+For instance, in the `tsdf-plusplus` project use something like:
+```bash
+git remote set-url origin [email protected]:ethz-asl/tsdf-plusplus.git
+```
+
+You can confirm you have the right origin URL by running:
+```bash
+git remote show origin
+```
+
+## Use computer workspace on docker
+
+If you have your workspace locally and want to use the docker machine to build
+and/or run nodes, you can use the script `./bin/docker-develop.sh`.
+You can get such workspace locally following the previous section.
+
+This script will discard the workspace from the remote repository and instead
+use the worksapce you have locally on your computer, which will be mounted
+onto the docker machine.
+
+This means that the docker will use the sources on your machine as well
+as build binaries onto your machine. This way you can use docker as a
+build tool and code locally on your computer while keeping the binaries.
+
+For example, you can use the following command:
+```bash
+./bin/docker-develop.sh /home/<YOUR_USERNAME>/catkin_ws
+```
+
+Once you are in the docker machine you can, for instance, build
+from sources doing
+```bash
+catkin build -j$(($(nproc) / 2)) -l1 tsdf_plusplus_ros rgbd_segmentation mask_rcnn_ros cloud_segmentation
+```
+
+By doing so, the docker machine will build the sources on your computer and
+keep the binaries on your computer as well.

docker/bin/build-ros-image.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+docker build --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) -t tsdf-plusplus-ros-base:v0.1 dockerfiles/base
+docker build -t tsdf-plusplus-ros-workspace:v0.1 dockerfiles/workspace
+docker build -t tsdf-plusplus-ros-catkin-build:v0.1 dockerfiles/catkin-build

docker/bin/docker-develop.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+workspace_folder=$1
+if [ -z "$1" ]
+  then
+    echo "Absolute path of the workspace folder not found"
+    exit 1
+fi
+mode=$2
+if [ -z "$2" ]
+  then
+    mode="it"
+fi
+docker container run --rm -$mode \
+  --user $(id -u) \
+  --mount type=bind,source="${workspace_folder}",target=/home/ros/catkin_ws \
+  --name tsdf-plusplus-dev \
+  --workdir /home/ros/catkin_ws \
+  tsdf-plusplus-ros-base:v0.1 \
+  bash

docker/bin/run-ros-image.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+mode=$1
+if [ -z "$1" ]
+  then
+    mode="it"
+fi
+docker container run --rm -$mode \
+  --user $(id -u) \
+  --name tsdf-plusplus \
+  --workdir /home/ros/catkin_ws \
+  tsdf-plusplus-ros-catkin-build:v0.1 \
+  bash

docker/bin/set-me-up.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+./bin/run-ros-image.sh dt
+sleep 5
+container_id=$(docker ps -aqf "name=tsdf-plusplus" | tr -d '\n')
+echo "Docker container $container_id"
+echo "Write absolute path of the folder on your computer, you want the entire '/home/ros/catkin_ws' folder on the docker machine to be copied into:"
+read destination_folder
+docker cp $container_id:/home/ros/catkin_ws $destination_folder
+docker stop -t 1 $container_id

docker/dockerfiles/base/Dockerfile

@@ -0,0 +1,31 @@
+FROM ros:melodic-ros-core
+ENV DEBIAN_FRONTEND=noninteractive
+
+ARG USER_ID
+ARG GROUP_ID
+
+# Install dependencies
+RUN apt update -y
+RUN apt upgrade -y
+RUN apt install -y build-essential tree vim \
+    git sudo python-pip ros-melodic-catkin \
+    autoconf libtool python-catkin-tools \
+    ros-melodic-eigen-conversions \
+    ros-melodic-pcl-ros ros-melodic-image-transport \
+    ros-melodic-codec-image-transport ros-melodic-pcl-msgs \
+    ros-melodic-pcl-conversions ros-melodic-cv-bridge \
+    ros-melodic-tf-conversions ros-melodic-rviz && \
+    rm -rf /var/lib/apt/lists/* && \
+    apt clean && \
+    apt autoclean
+RUN pip install -U osrf-pycommon wstool setuptools
+
+
+# Create 'ros' user with sudo powers
+ARG USERNAME=ros
+RUN groupadd --gid $GROUP_ID $USERNAME
+RUN useradd -s /bin/bash --uid $USER_ID --gid $GROUP_ID -m $USERNAME
+RUN echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME
+RUN chmod 0440 /etc/sudoers.d/$USERNAME
+RUN echo "source /usr/share/bash-completion/completions/git" >> /home/$USERNAME/.bashrc
+RUN echo "if [ -f /opt/ros/${ROS_DISTRO}/setup.bash ]; then source /opt/ros/${ROS_DISTRO}/setup.bash; fi" >> /home/$USERNAME/.bashrc

docker/dockerfiles/catkin-build/Dockerfile

@@ -0,0 +1,15 @@
+FROM tsdf-plusplus-ros-workspace:v0.1
+
+ARG USERNAME=ros
+USER $USERNAME
+WORKDIR /home/$USERNAME
+ARG ROS_VERSION=melodic
+ARG CATKIN_WS=/home/ros/catkin_ws
+RUN bash -c 'source /opt/ros/melodic/setup.bash && \
+    cd $CATKIN_WS/src && \
+    git clone https://github.com/ethz-asl/tsdf-plusplus.git && \
+    wstool merge -t . tsdf-plusplus/tsdf_plusplus_https.rosinstall && \
+    wstool update'
+RUN bash -c 'source /opt/ros/melodic/setup.bash && \
+    cd $CATKIN_WS && \
+    catkin build -j$(($(nproc) / 2)) -l1 tsdf_plusplus_ros rgbd_segmentation mask_rcnn_ros cloud_segmentation'

docker/dockerfiles/workspace/Dockerfile

@@ -0,0 +1,15 @@
+FROM tsdf-plusplus-ros-base:v0.1
+
+# Create workspace
+ARG USERNAME=ros
+USER $USERNAME
+WORKDIR /home/$USERNAME
+ARG ROS_VERSION=melodic
+ARG CATKIN_WS=/home/ros/catkin_ws
+RUN bash -c 'source /opt/ros/melodic/setup.bash && \
+    mkdir -p $CATKIN_WS/src && \
+    cd $CATKIN_WS && \
+    catkin init && \
+    catkin config --extend /opt/ros/melodic --merge-devel && \
+    catkin config --cmake-args -DCMAKE_CXX_STANDARD=14 -DCMAKE_BUILD_TYPE=Release && \
+    wstool init src'