Metadata-Version: 2.4
Name: pyoctomap
Version: 0.1.11
Summary: Python binding of the OctoMap library with bundled shared libraries.
Author-email: Spinkoo <lespinkoo@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Spinkoo (PyOctoMap)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://spinkoo.github.io/pyoctomap/
Project-URL: Repository, https://github.com/Spinkoo/pyoctomap
Project-URL: Documentation, https://github.com/Spinkoo/pyoctomap/tree/main/docs
Project-URL: Bug Tracker, https://github.com/Spinkoo/pyoctomap/issues
Keywords: octomap,occupancy,mapping,robotics,3d
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.16.0
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.0.0; extra == "visualization"
Requires-Dist: open3d>=0.13.0; extra == "visualization"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# PyOctoMap

<div align="center">
<img src="https://github.com/Spinkoo/pyoctomap/blob/main/images/octomap_core.png?raw=true" alt="OctoMap Core" width="900">
</div>

A comprehensive Python wrapper for the OctoMap C++ library, providing efficient 3D occupancy mapping capabilities for robotics and computer vision applications. This modernized binding offers enhanced performance, bundled shared libraries for easy deployment, and seamless integration with the Python scientific ecosystem.

## Features

- **3D Occupancy Mapping**: Efficient octree-based 3D occupancy mapping
- **Probabilistic Updates**: Stochastic occupancy updates with uncertainty handling
- **Path Planning**: Ray casting and collision detection
- **File Operations**: Save/load octree data in binary format
- **Cross-Platform**: Linux native support with Windows compatibility via WSL

## Installation

### Quick Install (Recommended)

Install from PyPI (pre-built manylinux wheel when available):

```bash
pip install pyoctomap
```

> **🚀 ROS Integration**: ROS/ROS2 integration is currently being developed on the [`ros` branch](https://github.com/Spinkoo/pyoctomap/tree/ros), featuring ROS2 message support and real-time point cloud processing.

### Building from Source

> **📋 Prerequisites**: See [Build System Documentation](https://github.com/Spinkoo/pyoctomap/blob/main/docs/build_system.md) for detailed system dependencies and troubleshooting guide.

If you need to build from source or create custom wheels, we provide a Docker-based build system:

**Linux / WSL (Windows Subsystem for Linux):**
```bash
# Clone the repository with submodules
git clone --recursive https://github.com/Spinkoo/pyoctomap.git
cd pyoctomap

chmod +x build.sh
./build.sh
```

```bash
# Build wheels for all supported Python versions
./build-wheel.sh

# Or build manually with Docker
docker build -f docker/Dockerfile.wheel -t pyoctomap-wheel .
```

The Docker build creates manylinux-compatible wheels for Python 3.8-3.14, properly bundling all required C++ libraries.

> **📋 Google Colab Users**: See [Build System Documentation](https://github.com/Spinkoo/pyoctomap/blob/main/docs/build_system.md) for detailed Colab installation instructions.

## Quick Start

### Basic Usage

```python
import pyoctomap
import numpy as np

# Create an octree with 0.1m resolution
tree = pyoctomap.OcTree(0.1)

# Add occupied points
tree.updateNode([1.0, 2.0, 3.0], True)
tree.updateNode([1.1, 2.1, 3.1], True)

# Add free space
tree.updateNode([0.5, 0.5, 0.5], False)

# Check occupancy
node = tree.search([1.0, 2.0, 3.0])
if node and tree.isNodeOccupied(node):
    print("Point is occupied!")

# Save to file
tree.write("my_map.bt")
```

### Tree Families Overview

PyOctoMap provides multiple octree variants from a single package:

- `OcTree` – standard probabilistic occupancy tree (most users start here)
- `ColorOcTree` – occupancy + RGB color per voxel
- `CountingOcTree` – integer hit counters per voxel
- `OcTreeStamped` – occupancy with per-node timestamps for temporal mapping

See the **[API Reference](https://github.com/Spinkoo/pyoctomap/blob/main/docs/api_reference.md)** for a detailed comparison
table and full method documentation.

### Color Occupancy Mapping (ColorOcTree)

```python
import pyoctomap
import numpy as np

tree = pyoctomap.ColorOcTree(0.1)
coord = [1.0, 1.0, 1.0]

tree.updateNode(coord, True)
tree.setNodeColor(coord, 255, 0, 0)  # R, G, B (0-255)
```

### Dynamic Mapping and Point Cloud Insertion


### Batch Operations (Summary)

For large point clouds, use the unified `insertPointCloud` method:

- `OcTree.insertPointCloud(points, origin, max_range=-1.0, lazy_eval=False, discretize=False)`
- `ColorOcTree.insertPointCloud(points, sensor_origin=None, ..., colors=colors)` — also sets per-point colors
- `OcTreeStamped.insertPointCloud(points, sensor_origin=None, ..., timestamps=ts)` — also sets per-node timestamps

See the [Performance Guide](https://github.com/Spinkoo/pyoctomap/blob/main/docs/performance_guide.md) for practical batch sizing and resolution
recommendations.

## Examples

See runnable demos in the [examples directory](https://github.com/Spinkoo/pyoctomap/blob/main/examples/):
- [examples/basic_test.py](https://github.com/Spinkoo/pyoctomap/blob/main/examples/basic_test.py) — smoke test for core API
- [examples/demo_occupancy_grid.py](https://github.com/Spinkoo/pyoctomap/blob/main/examples/demo_occupancy_grid.py) — build and visualize a 2D occupancy grid
- [examples/demo_octomap_open3d.py](https://github.com/Spinkoo/pyoctomap/blob/main/examples/demo_octomap_open3d.py) — visualize octomap data with Open3D
- [examples/sequential_occupancy_grid_demo.py](https://github.com/Spinkoo/pyoctomap/blob/main/examples/sequential_occupancy_grid_demo.py) — comprehensive sequential occupancy grid with Open3D visualization
- [examples/test_sequential_occupancy_grid.py](https://github.com/Spinkoo/pyoctomap/blob/main/examples/test_sequential_occupancy_grid.py) — comprehensive test suite for all occupancy grid methods

### Demo Visualizations

**3D OctoMap Scene Visualization:**
<div align="center">
<img src="https://github.com/Spinkoo/pyoctomap/blob/main/images/octomap_demo_scene.png?raw=true" alt="OctoMap Demo Scene" width="700">
</div>

**Occupancy Grid Visualization:**
<div align="center">
<img src="https://github.com/Spinkoo/pyoctomap/blob/main/images/occupancy_grid.png?raw=true" alt="Occupancy Grid" width="700">
</div>

## Advanced Usage

### Room Mapping with Ray Casting

```python
import pyoctomap
import numpy as np

# Create octree
tree = pyoctomap.OcTree(0.05)  # 5cm resolution
sensor_origin = np.array([2.0, 2.0, 1.5])

# Add walls with ray casting
wall_points = []
for x in np.arange(0, 4.0, 0.05):
    for y in np.arange(0, 4.0, 0.05):
        wall_points.append([x, y, 0])  # Floor
        wall_points.append([x, y, 3.0])  # Ceiling

# Use batch insertion for better performance
wall_points = np.array(wall_points)
tree.insertPointCloud(wall_points, sensor_origin, lazy_eval=True)
tree.updateInnerOccupancy()

print(f"Tree size: {tree.size()} nodes")
```

### Path Planning

```python
import pyoctomap
import numpy as np

# Create an octree for path planning
tree = pyoctomap.OcTree(0.1)  # 10cm resolution

# Add some obstacles to the map
obstacles = [
    [1.0, 1.0, 0.5],  # Wall at (1,1)
    [1.5, 1.5, 0.5],  # Another obstacle
    [2.0, 1.0, 0.5],  # Wall at (2,1)
]

for obstacle in obstacles:
    tree.updateNode(obstacle, True)

def is_path_clear(start, end, tree):
    """Efficient ray casting for path planning using OctoMap's built-in castRay"""
    start = np.array(start, dtype=np.float64)
    end = np.array(end, dtype=np.float64)
    
    # Calculate direction vector
    direction = end - start
    ray_length = np.linalg.norm(direction)
    
    if ray_length == 0:
        return True, None
    
    # Normalize direction
    direction = direction / ray_length
    
    # Use OctoMap's efficient castRay method
    end_point = np.zeros(3, dtype=np.float64)
    hit = tree.castRay(start, direction, end_point, 
                      ignoreUnknownCells=True, 
                      maxRange=ray_length)
    
    if hit:
        # Ray hit an obstacle - path is blocked
        return False, end_point
    else:
        # No obstacle found - path is clear
        return True, None

# Check if path is clear
start = [0.5, 2.0, 0.5]
end = [2.0, 2.0, 0.5]
clear, obstacle = is_path_clear(start, end, tree)
if clear:
    print("✅ Path is clear!")
else:
    print(f"❌ Path blocked at: {obstacle}")

# Advanced path planning with multiple waypoints
def plan_path(waypoints, tree):
    """Plan a path through multiple waypoints using ray casting"""
    path_clear = True
    obstacles = []
    
    for i in range(len(waypoints) - 1):
        start = waypoints[i]
        end = waypoints[i + 1]
        clear, obstacle = is_path_clear(start, end, tree)
        
        if not clear:
            path_clear = False
            obstacles.append((i, i+1, obstacle))
    
    return path_clear, obstacles

# Example: Plan path through multiple waypoints
waypoints = [
    [0.0, 0.0, 0.5],
    [1.0, 1.0, 0.5], 
    [2.0, 2.0, 0.5],
    [3.0, 3.0, 0.5]
]

path_clear, obstacles = plan_path(waypoints, tree)
if path_clear:
    print("✅ Complete path is clear!")
else:
    print(f"❌ Path blocked at segments: {obstacles}")
```

### Dynamic Environment Mapping & Iterators

For more complete examples on:

- dynamic environment mapping,
- iterator usage (`begin_tree`, `begin_leafs`, `begin_leafs_bbx`),

refer to the [API Reference](https://github.com/Spinkoo/pyoctomap/blob/main/docs/api_reference.md) and example scripts in the [examples directory](https://github.com/Spinkoo/pyoctomap/blob/main/examples/).

## Requirements

- Python 3.8+
- NumPy
- Cython (for building from source)

**Optional for visualization:**
- matplotlib (for 2D plotting)
- open3d (for 3D visualization)

## Documentation

- **[Complete API Reference](https://github.com/Spinkoo/pyoctomap/blob/main/docs/api_reference.md)** - Detailed API documentation
- **[Build System](https://github.com/Spinkoo/pyoctomap/blob/main/docs/build_system.md)** - Prerequisites, build process, and troubleshooting
- **[File Format Guide](https://github.com/Spinkoo/pyoctomap/blob/main/docs/file_format.md)** - Supported file formats
- **[Performance Guide](https://github.com/Spinkoo/pyoctomap/blob/main/docs/performance_guide.md)** - Optimization tips and benchmarks
- **[Troubleshooting](https://github.com/Spinkoo/pyoctomap/blob/main/docs/troubleshooting.md)** - Common issues and solutions
- **[Wheel Technology](https://github.com/Spinkoo/pyoctomap/blob/main/docs/wheel_technology.md)** - Library bundling details

## License

MIT License - see [LICENSE](https://github.com/Spinkoo/pyoctomap/blob/main/LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## Acknowledgments

- **Previous work**: [`wkentaro/octomap-python`](https://github.com/wkentaro/octomap-python) - This project builds upon and modernizes the original Python bindings
- **Core library**: [OctoMap](https://OctoMap.github.io) - An efficient probabilistic 3D mapping framework based on octrees
- **Build system**: Built with Cython for seamless Python-C++ integration and performance
- **Visualization**: [Open3D](https://www.open3d.org/) - Used for 3D visualization capabilities in demonstration scripts
- **Research support**: Development of this enhanced Python wrapper was supported by the French National Research Agency (ANR) under the France 2030 program, specifically the IRT Nanoelec project (ANR-10-AIRT-05), advancing robotics and 3D mapping research capabilities.
