Voxblox Documentation

Voxblox is a volumetric mapping library primarily based on Truncated Signed Distance Fields (TSDFs). It is designed for incremental 3D mapping and can be used for generating Euclidean Signed Distance Fields (ESDFs/EDTs) directly from TSDFs.

Key features include:

• CPU-only execution: Supports both single-threaded and multi-threaded operation for certain integrators.
• Extensible Layer Types: Supports multiple different layer types containing different voxel types.
• Serialization: Uses protobufs for data serialization.
• Flexible Integration: Offers different methods for handling weighting during merging and inserting scan pose information.
• ROS Integration: Tight integration via the voxblox_ros package.
• Extensibility: Easily extensible with custom integrators.
• ESDF Generation: Built-in implementation for building ESDFs from TSDFs.

When comparing Voxblox to Octomap for integration tasks:

1. Integration Speed: Voxblox's Fast integrator is significantly faster than Octomap, particularly as the Max ray length or Voxel size increases. While Octomap's integration time scales poorly with ray length (e.g., 3748 ms/scan for 0.1m voxels at 50m range), Voxblox maintains much lower latency (e.g., 100 ms/scan for the same parameters).
2. Memory Usage: Voxblox typically uses 2 to 3 times more RAM than Octomap.
3. Integration Method: Octomap ray casts all points from the origin without approximation. Voxblox's Merged integrator uses a similar approach, but the Fast integrator uses approximation techniques to achieve higher performance.

The Voxblox documentation is generated using a pipeline of Exhale, Doxygen, Sphinx, and Breathe.

Key files in the docs/ directory:

• conf.py: A Python script that controls Sphinx execution, loads Breathe/Exhale extensions, and configures the project.
• Doxyfile: Contains configuration options for Doxygen.
• index.rst: The homepage of the generated site (in .rst format). It defines the Sphinx TOC Tree used in the sidebar.
• logo.gif: The project logo image.
• Makefile: Used to build the website via Sphinx.
• requirements.txt: Used by ReadTheDocs to install the Exhale extension.
• pages/: A folder containing additional wiki pages in .rst or .md format.

Voxblox generates Euclidean Signed Distance Fields (ESDF) by propagating values from a Truncated Signed Distance Field (TSDF). The process is incremental and relies on two wavefront algorithms to update distance values efficiently:

1. TSDF to ESDF Propagation: TSDF values (which represent the distance to the nearest surface within a truncated range) are used as the starting point for calculating the ESDF (which represents the true distance to the nearest surface).
2. Raise Wavefront: This mechanism handles the propagation of increasing distance values.
3. Lower Wavefront: This mechanism handles the propagation of decreasing distance values.

For a detailed mathematical description of the algorithm, refer to the original paper: 'Voxblox: Incremental 3D Euclidean Signed Distance Fields for On-Board MAV Planning' (IROS 2017).

The legacy voxblox_node has been replaced by two specialized servers:

• Use tsdf_server if you only require a Truncated Signed Distance Function (TSDF).
• Use esdf_server if you require both a TSDF and an Euclidean Signed Distance Field (ESDF).

These servers handle the integration of pointclouds and provide services for mesh generation, map saving/loading, and map publishing.

To add new content to the documentation, simply add a .rst or .md file to the docs/pages folder. The documentation generator will automatically detect and include these files in the build.

Note: The markdown parser used in this setup does not support tables.

If you are not using SSH keys, clone the repository via HTTPS and use wstool to initialize and update the dependencies using the voxblox_https.rosinstall file.

cd ~/catkin_ws/src/
git clone https://github.com/ethz-asl/voxblox.git
wstool init . ./voxblox/voxblox_https.rosinstall
wstool update

Depending on your specific goal, you may need a specialized version or companion package of Voxblox:

• For skeletonization, sparse topology, or planning applications: Use the mav_voxblox_planning repository.
• For creating ground truth maps from meshes or Gazebo environments: Use the voxblox_ground_truth package.

To compile the online documentation on your local machine, you must install the necessary system dependencies and Python packages, then use make to generate the HTML files.

Dependencies

System packages:

sudo apt-get install python-pip doxygen python-pyaudio

Python packages:

pip install sphinx exhale breath sphinx_rtd_theme recommonmark --user

Compilation

Navigate to the documentation directory and run make html:

cd ~/catkin_ws/src/voxblox/voxblox/docs
make html

This generates a docs/_build folder. The homepage is located at docs/_build/html/index.html. Note that Sphinx may produce many warnings during this process; these can typically be ignored.

If you are using SSH keys for GitHub (recommended), clone the repository and use wstool to initialize and update the dependencies using the voxblox_ssh.rosinstall file.

cd ~/catkin_ws/src/
git clone git@github.com:ethz-asl/voxblox.git
wstool init . ./voxblox/voxblox_ssh.rosinstall
wstool update