OctoMap

An Efficient Probabilistic 3D Mapping Framework Based on Octrees

The OctoMap library implements a 3D occupancy grid mapping approach, providing data structures and mapping algorithms in C++. The map implementation is based on an octree and is designed to meet the following requirements:

Full 3D model. The map is able to model arbitrary environments without prior assumptions about it. The representation models occupied areas as well as free space. If no information is available about an area (commonly denoted as unknown areas), this information is encoded as well. While the distinction between free and occupied space is essential for safe robot navigation, information about unknown areas is important, e.g., for autonomous exploration of an environment.
Updatable. It is possible to add new information or sensor readings at any time. Modeling and updating is done in a probabilistic fashion. This accounts for sensor noise or measurements which result from dynamic changes in the environment, e.g., because of dynamic objects. Furthermore, multiple robots are able to contribute to the same map and a previously recorded map is extendable when new areas are explored.
Flexible. The extent of the map does not have to be known in advance. Instead, the map is dynamically expanded as needed. The map is multi-resolution so that, for instance, a high-level planner is able to use a coarse map, while a local planner may operate using a fine resolution. This also allows for efficient visualizations which scale from coarse overviews to detailed close-up views.
Compact. The map is stored efficiently, both in memory and on disk. It is possible to generate compressed files for later usage or convenient exchange between robots even under bandwidth constraints.

Detailed information can be found in the OctoMap paper (pdf).

The OctoMap library is available as a self-contained source distribution for Linux (recommended), Mac OS and Windows. It is actively maintained by Kai M. Wurm and Armin Hornung. Feel free to contact us with questions and issues. To report bugs or request features, best use our tracker at https://sourceforge.net/apps/trac/octomap. We would like to thank Stefan Oßwald, Jörg Müller, and all other contributors.

You may also want to have a look at the Sourceforge project page for further details about this project.

Example Projects

License

OctoMap is released under the New BSD License.

The viewer octovis is released under the GNU-GPL License (version 2).

Using Octomap?

Please let us know if you are using OctoMap, as we are curious to find out how it enables other people's work or research. Additionally, please cite our paper if you use OctoMap in your research:

K. M. Wurm, A. Hornung, M. Bennewitz, C. Stachniss, and W. Burgard, "OctoMap: A Probabilistic, Flexible, and Compact 3D Map Representation for Robotic Systems" in Proc. of the ICRA 2010 Workshop on Best Practice in 3D Perception and Modeling for Mobile Manipulation, 2010. Software available at http://octomap.sf.net/.

BibTeX:

@inproceedings{octomap,
  author = {K. M. Wurm and A. Hornung and 
  M. Bennewitz and C. Stachniss and W. Burgard},
  title = {{OctoMap}: A Probabilistic, Flexible, and Compact {3D} Map 
  Representation for Robotic Systems},
  booktitle = {Proc. of the ICRA 2010 Workshop on Best Practice in 
  3D Perception and Modeling for Mobile Manipulation},
  year = 2010,
  month = may,
  address = {Anchorage, AK, USA},
  url = {http://octomap.sf.net/},
  note = {Software available at \url{http://octomap.sf.net/}}
}

Installation

Download

Download a the latest released distribution package, or check out the latest development version from our svn repository with:

svn co https://octomap.svn.sourceforge.net/svnroot/octomap/trunk octomap

Older releases are available from the Sourceforge download page or at the SVN URL https://octomap.svn.sourceforge.net/svnroot/octomap/tags/.

If you want to use OctoMap in the Robot Operating System (ROS), see the documentation on the ROS wiki and the octomap_mapping stack for map building. Pre-compiled packages for most platforms are already available and directly integrated.

Compilation

To build the OctoMap libraries, you need a current version of GCC (tested with 4.3 - 4.6 under Ubuntu 9.04 - 12.04, 32 and 64 Bit) and cmake. The 3D viewer application requires Qt4 and OpenGL, and is based on libQGLViewer. You can either install libQGLViewer as a system-wide package (libqglviewer-qt4-dev in Ubuntu), or use the version we provide in the "external" directory. If the CMake compilation can't find an installed qglviewer, it will automatically compile our supplied version and link against it. For building the GUI, you need to make sure that qmake for Qt4 is used (qmake -v). If yours is set to Qt3 in Ubuntu, you can change it to qmake-qt4 by running sudo update-alternatives --config qmake after installing the dependencies below.

All dependencies for the library and viewer on Ubuntu can be met by running:

sudo apt-get install build-essential cmake doxygen libqt4-dev \
	libqt4-opengl-dev libqglviewer-qt4-dev

Build the complete project by changing into the "build" directory and running cmake:

cmake ..

Type make to compile afterwards. This will create all CMake files cleanly in the "build" folder (Out-of-source build). Executables will end up in "bin", libraries in "lib". You can also build the library and viewer separately, just have a look at the enclosed README.txt for details.

A debug configuration can be created by running:

cmake -DCMAKE_BUILD_TYPE=Debug ..

in "build" or a different directory (e.g. "build-debug").

Getting started

Jump right in and have a look at the example src/octomap/simple.cpp or start the 3D viewer bin/octovis. You will find an example scan to load at src/examples/scan.dat.bz2 (please bunzip2 it first). The Maps section below contains some finished real-world maps to look at.

Documentation

A thorough auto-generated doxygen documentation of the API for the latest release is available at http://octomap.sourceforge.net/doxygen/. Depending on your version, this may be outdated. To generate the documentation corresponding to you local version of OctoMap, type make docs in the build directory (requires doxygen). Just open doc/html/index.html with a web browser to read it.

Maps

Take a look at some of our example maps below. You can find these and more datasets in our dataset repository as finished OctoMap files and sources in the form of 3D laser scans.

Freiburg campus (outdoor)

Freiburg building 079 (corridor)

New College (Epoch C)

Importing Data

Laser Scan Data

Plain-text laser scan data can be imported from the following file format:

NODE x y z roll pitch yaw
x y z
x y z
[...]
NODE x y z roll pitch yaw
x y z
[...]

The keyword NODE is followed by the 6D pose of the laser origin of the 3D scan (roll, pitch, and yaw angles are around the axes x, y, z respectively). After a NODE-line, the laser endpoints of the scan originating at that scan node are listed as 3D points, in the coordinate frame of the scan node. The next NODE keyword specifies the start of a new 3D scan. Lines starting with '#' or empty lines are ignored.

Our tool "log2graph" converts these plain-text log files into a binary scan graph file, which can be directly opened and converted in the viewer "octovis", or converted to an octree map from the command line with "graph2tree".

3D model files

You can directly create an OctoMap file from a variety of 3D file formats (3DS, VRML, OBJ ...) by first voxelizing them with binvox. For convenience, we provide the binvox Linux binary in src/extern/binvox.

After converting your 3D data to a binvox file, you can create an Octree map from it by running our tool "binvox2bt".

Acknowledgments

OctoMap was developed at University of Freiburg in the DFG-funded SFB/TR8 Spatial Cognition within the projects A3-[MultiBot] and A8-[HumanoidSpace].

Logo Uni Freiburg Logo SFBTR8 Logo DFG