PyPI Installation

The library is available on PyPI and can be installed using pip. It is recommended to install the library inside a virtual environment.

pip install coverage_control

The package depends on the following packages

pip install torch torchvision torch-geometric

Note: PyTorch and PyTorch Geometric have CPU and CUDA-specific versions. The command installs the default version (latest CUDA).

We need the following optional packages for visualization and video generation:

gnuplot or gnuplot-nox (for visualizing environment)
ffmpeg (for generating videos)

On Ubuntu, these can be installed using the following command:

sudo apt install gnuplot-nox ffmpeg

Docker Installation

Docker images are available for the library with different configurations and versions.

Prerequisites (Optional)

We will organize files in a workspace directory: ${CoverageControl_ws} (e.g., ~/CoverageControl_ws). The workspace directory is mounted to the docker container.

Add the following lines to your ${HOME}/.bashrc file for convenience.

export CoverageControl_ws=${HOME}/CoverageControl_ws # Change to your workspace directory

Note: Close and reopen the terminal for the changes to take effect.

Clone the repository:

mkdir -p ${CoverageControl_ws}/src
git clone https://github.com/KumarRobotics/CoverageControl.git \
          ${CoverageControl_ws}/src/CoverageControl

Docker Container

Container can be created using the script in setup_utils/create_container.sh.

cd ${CoverageControl_ws}/src/CoverageControl/setup_utils/docker

bash create_container.sh --with-cuda -d ${CoverageControl_ws} # See flags below

This will land you in a shell inside the container in the directory /workspace. If the workspace directory was specified, it will be mounted to the container at the same location.

One can exit the container by typing exit or pressing Ctrl+D.

The container can be started again using the following command:

docker start -i coverage-control-$USER # Replace with the name of the container

Flags:

-d <dir> : The workspace directory
-n <name>: Name of the container (default: coverage-control-$USER)
--with-cuda : With CUDA support
--with-ros : With ROS support

The base image is ghcr.io/kumarrobotics/coveragecontrol with different tags for different versions and configurations.

Tags Suffix	Flags
`python2.2.2-cuda12.2.2-ros2humble`	`--with-ros --with-cuda`
`python2.2.2-cuda12.2.2`	`--with-cuda`
`python2.2.2-ros2humble`	`--with-ros`
`python2.2.2`	None

The library is already built and installed in the container. However, if you want to build it again, you can do so following the Installation from Source instructions (except for the prerequisites).

Installation From Source

Prerequisites

The following packages are required to build the library:

sudo apt install libboost-all-dev libgmp-dev libmpfr-dev libeigen3-dev gnuplot-nox ffmpeg

Note: gnuplot-nox and ffmpeg are optional (but recommended) and only required for generating environment visualizations.

Additional dependencies (generally already installed):

sudo apt install build-essential cmake git wget python3 python3-pip python3-venv python3-dev

CUDA Support

(Optional but recommended for GPU acceleration)

The package also supports GPU acceleration using CUDA. To enable this feature, the following additional packages are required:

cmake (version 3.24 or higher)
cuda (version 11.8 or higher, 12.1 recommended)

Note: On Ubuntu, latest cmake version can be installed from the official Kitware APT Repository.

Automated Installation

pip install .

Testing the installation (from the root of the repository):

Download the file pytest_data.tar.gz from the repository's release page and extract it to python/tests/. This will create a directory python/tests/data.

Then run the following commands:

pip install pytest

pytest

Building the Core C++ Library

Note: This is only necessary if you want to use the C++ library directly.

We will organize files in a workspace directory: ${CoverageControl_ws} (e.g., ~/CoverageControl_ws).

Add the following lines to your ~/.bashrc file.

export CoverageControl_ws=~/CoverageControl_ws # Change to your workspace directory
export PATH=${CoverageControl_ws}/install/bin:$PATH
export LD_LIBRARY_PATH=${CoverageControl_ws}/install/lib:$LD_LIBRARY_PATH

Clone the repository:

mkdir -p ${CoverageControl_ws}/src
git clone https://github.com/KumarRobotics/CoverageControl.git \
          ${CoverageControl_ws}/src/CoverageControl

The primary setup script is setup.sh located in the root of the repository.

cd ${CoverageControl_ws}/src/CoverageControl

bash setup.sh --with-deps -d ${CoverageControl_ws}

Testing the installation:

coverage_algorithm

There are multiple options for building the library.

Option	Description
`-d <dir>`	The workspace directory
`--with-cuda`	Build with CUDA support

Warning: Ubuntu 22.04 (Jammy) has CGAL 5.4 (libcgal-dev) in the official repositories, which has bugs and is not compatible with the library. The package requires CGAL 5.6, which is automatically installed from the official CGAL repository through CMake.

Table of Contents