{"id":6569,"library":"cmeel-octomap","title":"OctoMap Python Bindings (cmeel)","description":"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.","status":"active","version":"1.10.0","language":"en","source_language":"en","source_url":"https://github.com/cmake-wheel/cmeel-octomap.git","tags":["3d mapping","robotics","octree","point cloud","c++ binding"],"install":[{"cmd":"pip install cmeel-octomap","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The top-level module provided by cmeel-octomap is 'octomap', not 'cmeel_octomap'.","wrong":"from cmeel_octomap import OcTree","symbol":"OcTree","correct":"from octomap import OcTree"},{"symbol":"Point3D","correct":"from octomap import Point3D"}],"quickstart":{"code":"from octomap import OcTree, Point3D\n\n# Create an OcTree with a resolution of 0.1 meters\ntree = OcTree(0.1)\n\n# Insert some occupied points\ntree.insert_point(Point3D(0.0, 0.0, 0.0), occupied=True)\ntree.insert_point(Point3D(0.1, 0.0, 0.0), occupied=True)\ntree.insert_point(Point3D(0.5, 0.5, 0.5), occupied=True)\n\n# Insert a free point (clears any occupied status at this node)\ntree.insert_point(Point3D(0.0, 0.1, 0.0), occupied=False)\n\n# Query occupancy of points\nis_occupied_000 = tree.is_node_occupied(Point3D(0.0, 0.0, 0.0))\nis_occupied_055 = tree.is_node_occupied(Point3D(0.5, 0.5, 0.5))\nis_occupied_001 = tree.is_node_occupied(Point3D(0.0, 0.0, 1.0))\n\nprint(f\"Point (0,0,0) is occupied: {is_occupied_000}\")\nprint(f\"Point (0.5,0.5,0.5) is occupied: {is_occupied_055}\")\nprint(f\"Point (0,0,1) is occupied: {is_occupied_001} (outside inserted points)\")\n\n# Get the total number of occupied nodes\nprint(f\"Total occupied nodes: {tree.num_occupied_nodes}\")\n\n# You can also save and load the map (uncomment to run)\n# tree.write_binary(\"my_octomap.bt\")\n# loaded_tree = OcTree(\"my_octomap.bt\")\n# print(f\"Loaded tree has {loaded_tree.num_occupied_nodes} occupied nodes.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}