voxblox

Voxblox is a volumetric mapping library based mainly on Truncated Signed Distance Fields (TSDFs). It varies from other SDF libraries in the following ways:

• CPU-only, can be run single-threaded or multi-threaded for some integrators
• Support for multiple different layer types (containing different types of voxels)
• Serialization using protobufs
• Different ways of handling weighting during merging
• Different ways of inserting pose information about scans
• Tight ROS integration (in voxblox_ros package)
• Easily extensible with whatever integrators you want
• Features an implementation of building Euclidean Signed Distance Fields (ESDFs, EDTs) directly from TSDFs.

Table of Contents

• Paper and Video
• Credits
• Performance
• Installation
• Running Voxblox
• Voxblox Node
  • Published and Subscribed Topics
  • Services
  • Parameters
• Modifying Voxblox
  • Serialization

Paper and Video

A video showing sample output from voxblox can be seen here. A video of voxblox being used for online planning on-board a multicopter can be seen here.

If using voxblox for scientific publications, please cite the following paper:

Helen Oleynikova, Zachary Taylor, Marius Fehr, Juan Nieto, and Roland Siegwart, “Voxblox: Building 3D Signed Distance Fields for Planning”, arXiv preprint arXiv:1611.03631, 2016.

@article{oleynikova2016voxblox,
  title={Voxblox: Building 3D Signed Distance Fields for Planning},
  author={Oleynikova, Helen and Taylor, Zachary and Fehr, Marius and Nieto, Juan and Siegwart, Roland},
  journal={arXiv preprint arXiv:1611.03631},
  year={2016}
}

Credits

This library was written primarily by Helen Oleynikova and Marius Fehr, with significant contributions from Zachary Taylor, Alexander Millane, and others. The marching cubes meshing and ROS mesh generation were taken or heavily derived from open_chisel. We've retained the copyright headers for the relevant files.

Performance

The Voxblox code has prioritized readability and easy extension over performance. It was also designed to operate on systems that lack a GPU. One of the main drives to create Voxblox was to create a volumetric mapping library that fit the needs of planning for robots, because of this, and unlike many TSDF libraries all possible freespace is mapped in addition to areas close to surfaces. These design decisions limit performance, however high quality real-time mapping of large enviroments is still easily acheivable.

An example of the system integrating a TSDF, generating a mesh and publishing the result to RViz in real time is shown below. A table of the performance on the cow and lady dataset on a i7-4810MQ 2.80GHz CPU is also shown.

Rendered Mesh	Setup
	Integrator: Merged Voxel: 20 cm TSDF: 56 ms / scan Meshing: 2 ms / scan Total RAM: 49 MB
	Integrator: Fast Voxel: 20 cm TSDF: 20 ms / scan Meshing: 2 ms / scan Total RAM: 62 MB
	Integrator: Merged Voxel: 5 cm TSDF: 112 ms / scan Meshing: 10 ms / scan Total RAM: 144.2 MB
	Integrator: Fast Voxel: 5 cm TSDF: 23 ms / scan Meshing: 12 ms / scan Total RAM: 153.9 MB
	Integrator: Merged Voxel: 2 cm TSDF: 527 ms / scan Meshing: 66 ms / scan Total RAM: 609.2 MB
	Integrator: Fast Voxel: 2 cm TSDF: 63 ms / scan Meshing: 110 ms / scan Total RAM: 673.1 MB

Installation

To install voxblox, please install ROS Indigo or ROS Kinetic. These instructions are for Ubuntu, but Voxblox will also run on OS X but you're more or less on your own there.

Then install additional system dependencies (swap indigo for kinetic as necessary):

sudo apt-get install python-wstool python-catkin-tools ros-indigo-cmake-modules protobuf-compiler

Finally, add a few other dependencies. If you don't have a catkin workspace yet, set it up as follows:

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws
catkin init
catkin config --extend /opt/ros/indigo
catkin config --cmake-args -DCMAKE_BUILD_TYPE=Release
catkin config --merge-devel

If using SSH keys for github (recommended):

cd ~/catkin_ws/src/
wstool init
wstool set catkin_simple   --git [email protected]:catkin/catkin_simple.git
wstool set eigen_catkin    --git [email protected]:ethz-asl/eigen_catkin.git
wstool set eigen_checks    --git [email protected]:ethz-asl/eigen_checks.git
wstool set gflags_catkin   --git [email protected]:ethz-asl/gflags_catkin.git
wstool set glog_catkin     --git [email protected]:ethz-asl/glog_catkin.git
wstool set minkindr        --git [email protected]:ethz-asl/minkindr.git
wstool set minkindr_ros    --git [email protected]:ethz-asl/minkindr_ros.git
wstool set voxblox         --git [email protected]:ethz-asl/voxblox.git
wstool update

If not using SSH keys but using https instead:

cd ~/catkin_ws/src/
wstool init
wstool set catkin_simple   --git https://github.com/catkin/catkin_simple.git
wstool set eigen_catkin    --git https://github.com/ethz-asl/eigen_catkin.git
wstool set eigen_checks    --git https://github.com/ethz-asl/eigen_checks.git
wstool set gflags_catkin   --git https://github.com/ethz-asl/gflags_catkin.git
wstool set glog_catkin     --git https://github.com/ethz-asl/glog_catkin.git
wstool set minkindr        --git https://github.com/ethz-asl/minkindr.git
wstool set minkindr_ros    --git https://github.com/ethz-asl/minkindr_ros.git
wstool set voxblox         --git https://github.com/ethz-asl/voxblox.git
wstool update

Running Voxblox

The easiest way to test out voxblox is to try it out on a dataset. We have launch files for our own dataset, the Euroc Vicon Room datasets, and the KITTI raw datasets processed through kitti_to_rosbag.

For each of these datasets, there's a launch file associated under voxblox_ros/launch.

The easiest way to start is to download the cow and lady dataset, edit the path to the bagfile in cow_and_lady_dataset.launch, and then simply: roslaunch voxblox_ros cow_and_lady_dataset.launch

If you open rviz, you should be able to see the the mesh visualized on the /voxblox_node/mesh MarkerArray topic, in the world static frame, as shown below. The mesh only updates once per second (this is a setting in the launch file).

The rest of the commonly-used settings are parameters in the launch file.

Voxblox Node

Published and Subscribed Topics

The voxblox_node publishes and subscribes to the following topics:

• Published topics:

  • mesh of type visualization_msgs::MarkerArray. A visualization topic showing the mesh produced from the tsdf in a form that can be seen in RViz. Set update_mesh_every_n_sec to control its update rate.
  • surface_pointcloud of type pcl::PointCloud<pcl::PointXYZRGB>. A colored pointcloud of the voxels that are close to a surface.
  • tsdf_pointcloud of type pcl::PointCloud<pcl::PointXYZI>. A pointcloud showing all allocated voxels.
  • mesh_pointcloud of type pcl::PointCloud<pcl::PointXYZRGB>. Only appears if output_mesh_as_pointcloud is true, outputs a pointcloud containing the verticies of the generated mesh.
  • mesh_pcl of type pcl_msgs::PolygonMesh. Only appears if output_mesh_as_pcl_mesh is true, outputs any mesh generated by the generate_mesh service.
  • tsdf_slice of type pcl::PointCloud<pcl::PointXYZI>. Outputs a 2D horizontal slice of the TSDF colored by the stored distance value.
  • esdf_pointcloud of type pcl::PointCloud<pcl::PointXYZI>. A pointcloud showing the values of all allocated ESDF voxels. Only appears if generate_esdf is true.
  • esdf_slice of type pcl::PointCloud<pcl::PointXYZI>. Outputs a 2D horizontal slice of the ESDF colored by the stored distance value. Only appears if generate_esdf is true.
  • occupied_nodes of type visualization_msgs::MarkerArray. Visualizes the location of the allocated voxels in the TSDF.

• Subscribed topics:

  • transform of type geometry_msgs::TransformStamped. Only appears if use_tf_transforms is false. The transformation from the world frame to the current sensor frame.
  • pointcloud of type sensor_msgs::PointCloud2. The input pointcloud to be integrated.

Services

The voxblox_node has the following services:

• generate_mesh This service has an empty request and response. Calling this service will generate a new mesh. The mesh will be saved as a ply file unless mesh_filename is set to "". The mesh will also be output on the mesh_pointcloud topic if output_mesh_as_pointcloud is true and on the mesh_pcl topic if output_mesh_as_pcl_mesh is true.
• generate_esdf This service has an empty request and response. It can be used to trigger an esdf map update.
• save_map This service has a voxblox_msgs::FilePath::Request and voxblox_msgs::FilePath::Response. The service call saves the tsdf layer to a .vxblx file.
• load_map This service has a voxblox_msgs::FilePath::Request and voxblox_msgs::FilePath::Response. The service call loads the tsdf layer from a .vxblx file.

Parameters

A summary of the user setable voxblox_node parameters:

Modifying Voxblox

Here's some hints on how to extend voxblox to fit your needs...

Serialization

Serialization is currently implemented for:

• TSDF layers
• ESDF layers
• Occupancy layers
• ...

The following serialization tools are implemented:

• Store a layer to file
• Load layer from file
• Store a subset of the blocks of a layer to file
• Load blocks from file and add to a layer

How to add your own voxel/layer type

• Add your own voxel type and implement the getVoxelType(), e.g. fancy_voxel.h :

namespace voxblox {

// Used for serialization only.
namespace voxel_types {
 const std::string kYOUR_FANCY_VOXEL = "fancy_voxel"
}  // namespace voxel_types

template <>
inline std::string getVoxelType<YOUR_FANCY_VOXEL>() {
 return voxel_types::kYOUR_FANCY_VOXEL;
}

}  // namespace voxblox

• Implement the block (de)serialization functions for your voxel type, e.g. fancy_block_serialization.cc

namespace voxblox {

template <>
void Block<YOUR_FANCY_VOXEL>::DeserializeVoxelData(const BlockProto& proto,
                                            YOUR_FANCY_VOXEL* voxels) {
// Your serialization code.
}

template <>
void Block<YOUR_FANCY_VOXEL>::SerializeVoxelData(const YOUR_FANCY_VOXEL* voxels,
                                          BlockProto* proto) const {
// Your serialization code.
}

}  // namespace voxblox

• Create your own fancy_integrator.h, fancy_mesh_integrator.h, ...

Have a look at the example package:

TODO(mfehr, helenol): add example package with a new voxel type