OctoMap: probabilistic 3D mapping with octrees, and how to build it

The problem OctoMap solves: turning noisy range readings into a queryable 3D volume

A depth camera or laser scanner gives you points. Points are a poor data structure for planning. They are noisy, they do not tell you where free space ends and unknown space begins, and a moving sensor keeps producing them, so the cloud grows without bound. OctoMap's answer is to discretise space into a hierarchical voxel grid and store, per cell, a probability that the cell is occupied. The README describes the project as an efficient probabilistic 3D mapping framework based on octrees, and that is the whole design in one line.

The audience is robotics engineers. The README points to pre-compiled packages for ROS and to the ROS wiki pages for octomap and octovis, which is a strong hint about where most users come from. If you are writing a planner that needs to ask whether a point in space is occupied, free, or simply unobserved, this library answers that question directly. If you are building a mapping product in Python, the repository does not offer you a first-class path; the code is C++.

How the octree works: pruning, probabilities and what the tree actually stores

An octree subdivides a cubic volume into eight children, recursively. In OctoMap, a node is either a leaf holding an occupancy probability or an inner node whose children are all identical, in which case the children are collapsed into the parent. That collapsing is where the memory saving comes from: large empty regions, such as the air above a robot, cost one node instead of thousands of voxels.

Each measurement updates the log-odds of the affected leaves rather than overwriting them, which is what makes the map tolerant of a single bad reading. The repository is split into three top-level components: octomap, the library itself, octovis, which the README calls the visualisation libraries and tools, and dynamicEDT3D, a separate directory that ships alongside them. The README is explicit that octomap and octovis are two separate libraries in their own subfolders, each with its own README, and that they can be built separately or together. That split matters for licensing, discussed later.

The practical consequence of the tree structure is that resolution is a global parameter chosen at construction time. A finer resolution multiplies the node count, and the documentation does not present a magic setting that avoids this. You pick a voxel size to match your sensor and your planner, and you live with the memory.

Installing OctoMap and running a first build

The README gives two routes. The first is a plain CMake build from a checkout. To compile only the library, run CMake inside the octomap subdirectory:

cd octomap
mkdir build
cd build
cmake ..
make

To compile the complete package, including octovis, the README shows the same sequence run from the top level:

cd build
cmake ..
make

After either build, the README states that binaries and libs end up in the bin and lib directories of the top-level directory where you started the build. If those two directories are populated, the build worked; the README does not promise an install step beyond that.

The second route is vcpkg, which the README documents as an alternative way to build and install octomap:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install octomap

The README notes that the vcpkg port is kept up to date by Microsoft team members and community contributors, and that if the version is out of date you should open an issue or pull request on the vcpkg repository rather than here. That is a real caveat: the port's version and the tagged release can drift apart.

For ROS users, the README does not give build instructions at all. It redirects to the ROS wiki pages and states that pre-compiled packages are available. If you are on ROS, that is the intended path, and the CMake route is for people building outside the ROS ecosystem.

Where OctoMap is the wrong tool: no SLAM, no loop closure, no Python API

OctoMap is a mapping framework, not a localisation system. It consumes poses and range data and produces a map. Nothing in the README describes pose estimation, loop closure, or trajectory optimisation. If your robot's odometry drifts, the map drifts with it, and the library will faithfully record a doubled wall. People searching for a SLAM stack should understand that OctoMap occupies one layer of that stack, not the whole of it.

The build story is also a limitation. The README's build status badge points at travis-ci.org, a service that is no longer the default for new projects, which suggests the CI configuration has not been revisited recently even though the repository's last push was on 2026-09-26 and v1.10.1 was released on 2026-09-18. The README itself warns that there are further hints on compiling, especially under Windows, in the sub-READMEs, which is a polite way of saying the top-level instructions are not sufficient on that platform.

Finally, the licence is not uniform across the repository. The README states that octomap carries the New BSD License while octovis and related libraries are GPL. Anyone linking the visualisation code into a proprietary product is in different territory from someone linking only the core library. The README does not analyse this; it simply states the two licences, and the top-level repository entry for the licence is listed as unknown.

OctoMap against rtabmap and against a plain octree

The two comparisons people actually search for are OctoMap versus rtabmap and OctoMap versus a bare octree, and they are different questions.

Against rtabmap: rtabmap is a full appearance-based SLAM system that produces maps as one of its outputs. OctoMap is the map data structure and the update rules, with no front end. Choosing rtabmap means accepting its pipeline and its constraints; choosing OctoMap means you already have poses from somewhere else and want a volumetric representation you can query. The README does not mention rtabmap, so this distinction comes from what OctoMap's own documentation covers, which is mapping, visualisation and the dynamicEDT3D directory, not SLAM.

Against a plain octree: a textbook octree stores whatever you put in it. OctoMap stores log-odds occupancy and updates them probabilistically, and it distinguishes free from unknown space, which is the property planners rely on. A generic octree implementation gives you the spatial index but not the sensor model. If you are writing your own occupancy update rules on top of a generic octree, you are rebuilding the part of OctoMap that is actually specific to robotics.

Maintenance, releases and what upgrading costs

The repository is not archived, and the last push was on 2026-09-26. The release history shows v1.10.1 on 2026-09-18, v1.10.0 on 2024-03-19 and v1.9.6 on 2021-01-23. The gap between v1.10.0 and v1.10.1 is roughly two and a half years, so treat this as a library that ships when it needs to rather than on a cadence.

The README points to a changelog in octomap/CHANGELOG.txt, which is where you should look before moving a production system between tags. Nothing in the README describes a deprecation policy or an API stability guarantee, so the changelog is the only evidence available.

On licensing: the README splits octomap under the New BSD License and octovis and related libraries under GPL. That means the cost of using the core library and the cost of shipping the viewer are not the same question, and the answer depends on which subfolder you compile and link. This is a description of what the README states, not legal advice; if the GPL boundary affects your distribution model, get it reviewed by someone qualified.

Editorial conclusion

Adopt OctoMap if you need a compact, queryable occupancy volume from noisy range data and you are comfortable in C++ or ROS, where pre-compiled packages exist. Do not adopt it if you need a full SLAM system with loop closure, or if GPL code in octovis is a problem for your product. Before committing, verify the licence of the exact subfolder you link against, check whether the vcpkg port matches v1.10.1, and confirm the octomap/README.md build hints for your platform.

Frequently asked questions

Official sources

1. Issues
2. OctoMap/octomap on GitHub
3. Project website
4. README
5. Releases