OctoMap Python Bindings (cmeel)

1.10.0 · active · verified Wed Apr 15

cmeel-octomap provides efficient Python bindings for the OctoMap library, a probabilistic 3D mapping framework based on octrees. It enables users to build, query, and manage 3D occupancy maps in Python. The current version is 1.10.0, with updates typically aligned with upstream OctoMap releases or cmeel improvements.

Warnings

gotcha OctoMap uses a specific coordinate system convention (e.g., Z-up). Mismatches with other libraries or sensor data (e.g., ROS, custom camera setups) are a common source of bugs. Always verify your coordinate transformations.
Fix: Explicitly transform your points to the OctoMap coordinate system before insertion, or ensure your data source aligns with it. Consult OctoMap C++ documentation for exact conventions.
gotcha OctoMaps, especially at fine resolutions and for large environments, can consume significant amounts of RAM. Monitor memory usage to avoid out-of-memory errors in your applications.
Fix: Optimize your map resolution based on actual application needs. Consider using smaller sub-maps or streaming data if memory becomes a constraint. Use `tree.prune()` to reduce memory if applicable.
gotcha As a wrapper around a C++ library, some errors might originate from the underlying OctoMap C++ code. These can sometimes manifest as cryptic Python exceptions or segfaults without clear Python tracebacks.
Fix: Ensure all inputs to OctoMap functions are valid (e.g., non-NaN points, valid resolutions). For complex issues, isolating the problematic input or operation and consulting OctoMap's C++ documentation might be necessary.
gotcha There are multiple Python wrappers for OctoMap (e.g., `octomap-python`, `coctomap`). Ensure you are importing from the `octomap` module provided by `cmeel-octomap` to avoid conflicts or unexpected behavior if you have other wrappers installed.
Fix: Always use `from octomap import ...` after installing `cmeel-octomap`. If issues arise, check `pip freeze` for other OctoMap-related packages and consider using a dedicated virtual environment.

Install

pip install cmeel-octomap Install stable version

Imports

OcTree
wrong:
```
from cmeel_octomap import OcTree
```
correct:
```
from octomap import OcTree
```
The top-level module provided by cmeel-octomap is 'octomap', not 'cmeel_octomap'.
Point3D
```
from octomap import Point3D
```

Quickstart

This quickstart demonstrates how to create an OctoMap, insert occupied and free points, and query their occupancy status. It highlights basic map manipulation and information retrieval.

from octomap import OcTree, Point3D

# Create an OcTree with a resolution of 0.1 meters
tree = OcTree(0.1)

# Insert some occupied points
tree.insert_point(Point3D(0.0, 0.0, 0.0), occupied=True)
tree.insert_point(Point3D(0.1, 0.0, 0.0), occupied=True)
tree.insert_point(Point3D(0.5, 0.5, 0.5), occupied=True)

# Insert a free point (clears any occupied status at this node)
tree.insert_point(Point3D(0.0, 0.1, 0.0), occupied=False)

# Query occupancy of points
is_occupied_000 = tree.is_node_occupied(Point3D(0.0, 0.0, 0.0))
is_occupied_055 = tree.is_node_occupied(Point3D(0.5, 0.5, 0.5))
is_occupied_001 = tree.is_node_occupied(Point3D(0.0, 0.0, 1.0))

print(f"Point (0,0,0) is occupied: {is_occupied_000}")
print(f"Point (0.5,0.5,0.5) is occupied: {is_occupied_055}")
print(f"Point (0,0,1) is occupied: {is_occupied_001} (outside inserted points)")

# Get the total number of occupied nodes
print(f"Total occupied nodes: {tree.num_occupied_nodes}")

# You can also save and load the map (uncomment to run)
# tree.write_binary("my_octomap.bt")
# loaded_tree = OcTree("my_octomap.bt")
# print(f"Loaded tree has {loaded_tree.num_occupied_nodes} occupied nodes.")

view raw JSON →