VDB Mapping ROS2 Package

DISCLAIMER: This library is still under development. Be warned that some interfaces will be changed and/or extended in the future.

The VDB Mapping ROS2 Package is a ROS2 wrapper around VDB Mapping

Getting Started

Requirements

This library requires OpenVDB as it is build around it. This library was initially developed using Version 5.0 and should work with all versions above.
Either use the apt package which will be automatically installed via rosdep or compile the package from source using the provided build instructions

Build instructions

Since the required VDB Mapping library is a plain C++ package, you cannot use catkin_make directly. Instead you have to use colcon build to build the workspace.

# source global ros
source /opt/ros/<your_ros_version>/setup.bash

# create a catkin workspace
mkdir -p ~/colcon_ws/src && cd ~/colcon_ws/src

# clone packages
git clone https://github.com/fzi-forschungszentrum-informatik/vdb_mapping
git clone https://github.com/fzi-forschungszentrum-informatik/vdb_mapping_ros2

# install dependencies
sudo apt update
rosdep update
rosdep install --from-paths src --ignore-src -y

# build the workspace.  
colcon build

# source the workspace
source install/setup.bash

Remote Mapping

The remote mapping module is at the moment mainly designed to provide an external access to the map, without saving and loading it in a different node. In our case we use it to visualize the map data on a remote base station which is then used to control the robots from far away and give the user an overview of the area the robot operates in. Basically it is a full additional mapping node which can access the data chunks generated by the main mapping on the robot. These can the be integrated into the remote mapping instance to generate the same or a similar map depending on the chosen parameter settings. Diving deeper into the remote mapping functionality you might stumble over the term of updates, overwrites and sections. These are different mechanics to update a remote mapping instance. The first two are just a byproduct of the normal mapping process. Therefore there is no additional computation needed to generate the data for a remote mapping instance. However all three mechanics use OpenVDB grids which are compressed and serialized as a bitstream before sending them out over the network.

Updates

Updates are grids generated during the raycasting process and are also used for the internal map update. Here all sensor data is previously accumulated into an update grid which specifies whether the occupancy probability in the map should be updated as occupied or free. This two step process helps to prevent discretization issues due to the larger resolution of the grid compared to the raw sensor data. It is also possible to accumulate multiple sensor sources and measurements into one update grid (see accumulation parameters). The update grid can then be applied to the local or remote instance to generate the same map on both sides.

Overwrites

Overwrite grids are similar to the update grid but only contain the voxel that have changed their occupancy state in the last iteration. Therefore they are more lightweight in terms of necessary bandwith. This can be useful in cases where the network is rather limited but has the downside, that the probabilistic framework is lost on the remote side.

Sections

In contrast to updates and overwrites, sections are not bound to the sensor data rate but are generated with a defined rate and create additional processing load. Here the binary occupancy state of a section around a specified frame is copied out of the map and transformed into an update grid that can be applied to a remote instance. Although this created additional overhead it is still highly useful in certain scenarios. In our case we had to handle transmission delay and package loss where both the update and overwrites would result in incomplete maps since grids were lost. Sections on the other hand contain the complete chunk of the map while still being small with respect to the bandwidth.

ROS API

ROS Parameters

VDB Mapping is highly configurable using ROS parameters. Below is a complete list of all available parameters. Internally we store them in a yaml configuration file. An example can be found here.

Basic Parameters

Listed below are the general parameters to configure the basic behavior of vdb_mapping

Parameter Name	Type	Default	Information
map_frame	string	' '	Coordinate frame of the map
robot_frame	string	' '	Coordinate frame of the robot
max_range	double	15.0	Global maximum raycasting range (can also be set for each sensor source individually)
resolution	double	0.07	Map resolution
prob_hit	double	0.7	Probability update if a beam hits a voxel
prob_miss	double	0.4	Probability update if a beam misses a voxel
prob_thres_min	double	0.12	Lower occupancy threshold of a voxel
prob_thres_max	double	0.97	Upper occupancy threshold of a voxel
map_save_dir	string	' '	Storage location for saved maps
accumulate_updates	boolean	false	Specifies whether the data of multiple sensor measurement should be accumulated before integrating it into the map.
accumulation_period	double	1	Specifies how long updates should be accumulated before integration
visualization_rate	double	1	Specifies in which rate the visualization is published
publish_pointcloud	boolean	true	Specifies whether the map should be published as pointcloud
publish_vis_marker	boolean	true	Specifies whether the map should be published as visual marker
apply_raw_sensor_data	boolean	true	Specify whether raw sensor data (e.g. Pointclouds) should be integrated into the map. This flag becomes relevant when the user wants to use a pure remote instance. If set to true all sensor sources will be periodically integrated into the map.
sources	string[]	[]	List of sensor sources
remote_sources	string[]	[]	List of remote sources

Sensor Sources

VDB Mapping is able to integrate an arbitrary amount of different sensor sources (given they are available as PointCloud2 msg). To add a new sensor source the user has to add it to the list of sources in the basic parameters. Below are listed the parameters that can be used to configure the individual sensor source. These have to be put into the corresponding namespace in the yaml file. For an example see this configuration file.

Parameter Name	Type	Default	Information
topic	string	' '	Topic name of the sensor msg
sensor_origin_frame	string	' '	Sensor frame of the measurement. This parameter is optional and in general the frame id of the msg is used. However in some cases like already frame aligned point clouds this info is no longer the origin of the sensor. For this purpose the user can specify here from which frame the raycasting should be performed.
max_range	double	0	Individual per sensor max raycasting range. This parameter is optional and per default the global max range is used.

Remote Sources

VDB Mapping provides a remote operation mode. Here the map data is shared between multiple instances to generate the same or similar maps (depending on the chosen parameter settings). For this remote sources can be specified over the parameter server.

Local side

Parameter Name	Type	Default	Information
publish_updates	boolean	false	Specifies whether updates are published
publish_overwrites	boolean	false	Specifies whether overwrites are published
publish_sections	boolean	false	Specifies whether sections are published
section_update/rate	double	1	Rate in which the section update is published
section_update/frame	string	robot_frame	Center of the update section
section_update/min_coord/{x,y,z}	double	-10	Min coordinate of the section bounding box centered around the section frame
section_update/max_coord/{x,y,z}	double	10	Max coordinate of the section bounding box centered around the section frame

Remote side

Below are listed the parameters that can be used to configure the individual remote source. These have to be put into the corresponding namespace in the yaml file. An example config file can be found here.

Parameter Name	Type	Default	Information
namespace	string	' '	Namespace of the remote mapping instance
apply_remote_updates	boolean	false	Specifies whether remote updates should be applied to the map
apply_remote_overwrites	boolean	false	Specifies whether remote overwrites should be applied to the map
apply_remote_sections	boolean	false	Specifies whether remote sections should be applied to the map

Advertised ROS Topics

Topic Name	Type	Information
~/vdb_map_visualization	visualization_msgs/Marker	Map visualization topic as voxel marker
~/vdb_map_pointcloud	sensor_msgs/PointCloud2	Map visualization topic as pointcloud
~/vdb_map_updates	vdb_mapping_msgs/UpdateGrid	Map updates topic
~/vdb_map_overwrites	vdb_mapping_msgs/UpdateGrid	Map overwrites topic
~/vdb_map_sections	vdb_mapping_msgs/UpdateGrid	Map sections topic

Subscribed ROS Topics

Topic Name	Type	Information
{Parameter:sensor_source}/{Parameter:topic}	sensor_msgs/PointCloud2	Pointcloud sensor message
{Parameter:remote_source}/vdb_map_updates	vdb_mapping_msgs/UpdateGrid	Map updates topic
{Parameter:remote_source}/vdb_map_overwrites	vdb_mapping_msgs/UpdateGrid	Map overwrites topic
{Parameter:remote_source}/vdb_map_sections	vdb_mapping_msgs/UpdateGrid	Map sections topic

ROS Services

Service Name	Type	Information
~/load_map	vdb_mapping_msgs/LoadMap	Loads the map specified in the msg
~/save_map	std_srvs/Trigger	Saves the current map in the destination specified in the map_save_dir parameter
~/reset_map	std_srvs/Trigger	Resets the current map
~/raytrace	vdb_mapping_msgs/Raytrace	Raytraces a point and returns coordinate where the ray first intersected the map
~/trigger_map_section_update	vdb_mapping_msgs/TriggerMapSectionUpdate	Triggers a map section update on a remote instance

Citation

Thanks that you read until here and please let us know if you run into any issues or have suggestions for improvements. If you use our work in your publications please feel free to cite our manuscript:

  @inproceedings{besselmann2021vdb,
  title={VDB-Mapping: a high resolution and real-time capable 3D mapping framework for versatile mobile robots},
  author={Besselmann, M Grosse and Puck, Lennart and Steffen, Lea and Roennau, Arne and Dillmann, R{\"u}diger},
  booktitle={2021 IEEE 17th International Conference on Automation Science and Engineering (CASE)},
  pages={448--454},
  year={2021},
  organization={IEEE}
  doi={10.1109/CASE49439.2021.9551430}}
}

or for the remote mapping case:

@incollection{besselmann2022remote,
  title={Remote VDB-Mapping: A Level-Based Data Reduction Framework for Distributed Mapping},
  author={Besselmann, Marvin Grosse and R{\"o}nnau, Arne and Dillmann, R{\"u}diger},
  booktitle={Robotics in Natural Settings: CLAWAR 2022},
  pages={448--459},
  year={2022},
  publisher={Springer}
  doi={10.1007/978-3-031-15226-9_42}
}