diff --git a/README.md b/README.md index e4f84b5..f529f6e 100644 --- a/README.md +++ b/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,24 +42,16 @@ 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 ``` -Clone the `tsdf-plusplus` repository over HTTPS (no Github account required) and automatically fetch dependencies: +Clone the `tsdf-plusplus` repository (first tries over SSH and falls back to HTTPS): ```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 -``` - -Alternatively, clone over SSH (Github account required): -```bash -cd $CATKIN_WS/src -git clone git@github.com:ethz-asl/tsdf-plusplus.git -wstool merge -t . tsdf-plusplus/tsdf_plusplus_ssh.rosinstall +git clone git@github.com:ethz-asl/tsdf-plusplus.git | git clone https://github.com/ethz-asl/tsdf-plusplus.git +wstool merge -t . tsdf-plusplus/tsdf_plusplus_ssh.rosinstall | wstool merge -t . tsdf-plusplus/tsdf_plusplus_https.rosinstall wstool update ``` @@ -69,16 +61,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 diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000..6ad4a1b --- /dev/null +++ b/docker/README.md @@ -0,0 +1,18 @@ +# Introduction + +To build the docker image ( `tsdf-plusplus-ros-catkin-build` ) run: +```bash +./build-ros-image.sh +``` + +To run the docker image use: +```bash +./run-ros-image.sh +``` + +The workspace is located in `/home/ros/tsdf-plusplus_ws` and the `docker` user is `ros`. + +TODO: + - Allow mounted local workspaced in docker + - Automatically build the current (remote) branch + - Entrypoint with all nodes running \ No newline at end of file diff --git a/docker/base/Dockerfile b/docker/base/Dockerfile new file mode 100644 index 0000000..1ab25aa --- /dev/null +++ b/docker/base/Dockerfile @@ -0,0 +1,18 @@ +FROM ros:melodic-ros-core +ENV DEBIAN_FRONTEND=noninteractive + +# 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 \ No newline at end of file diff --git a/docker/build-ros-image.sh b/docker/build-ros-image.sh new file mode 100755 index 0000000..616552f --- /dev/null +++ b/docker/build-ros-image.sh @@ -0,0 +1,4 @@ +#!/bin/bash +docker build -t tsdf-plusplus-ros-base:v0.1 base +docker build -t tsdf-plusplus-ros-workspace:v0.1 workspace +docker build -t tsdf-plusplus-ros-catkin-build:v0.1 catkin-build \ No newline at end of file diff --git a/docker/catkin-build/Dockerfile b/docker/catkin-build/Dockerfile new file mode 100644 index 0000000..02343b0 --- /dev/null +++ b/docker/catkin-build/Dockerfile @@ -0,0 +1,9 @@ +FROM tsdf-plusplus-ros-workspace:v0.1 + +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 && \ + catkin build -j$(($(nproc) / 2)) -l1 tsdf_plusplus_ros rgbd_segmentation mask_rcnn_ros cloud_segmentation' \ No newline at end of file diff --git a/docker/run-ros-image.sh b/docker/run-ros-image.sh new file mode 100755 index 0000000..196bd42 --- /dev/null +++ b/docker/run-ros-image.sh @@ -0,0 +1,2 @@ +#!/bin/bash +docker run -it tsdf-plusplus-ros-catkin-build:v0.1 bash \ No newline at end of file diff --git a/docker/workspace/Dockerfile b/docker/workspace/Dockerfile new file mode 100644 index 0000000..a5c5aab --- /dev/null +++ b/docker/workspace/Dockerfile @@ -0,0 +1,29 @@ +FROM tsdf-plusplus-ros-base:v0.1 + +# Create 'ros' user with sudo powers +ARG USERNAME=ros +ARG USER_UID=1001 +ARG USER_GID=$USER_UID +RUN groupadd --gid $USER_GID $USERNAME \ + && useradd -s /bin/bash --uid $USER_UID --gid $USER_GID -m $USERNAME \ + && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME\ + && chmod 0440 /etc/sudoers.d/$USERNAME \ + && echo "source /usr/share/bash-completion/completions/git" >> /home/$USERNAME/.bashrc \ + && echo "if [ -f /opt/ros/${ROS_DISTRO}/setup.bash ]; then source /opt/ros/${ROS_DISTRO}/setup.bash; fi" >> /home/$USERNAME/.bashrc + +# Create workspace +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 && \ + 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'