Reconstruct OctoMap

SUMMARY

Reconstruct OctoMap converts a point cloud into a probabilistic 3D occupancy map composed of occupied and free cubic cells.

This Skill is useful in industrial, mobile, and humanoid robotics pipelines for mapping, collision avoidance, and motion planning. For example, it can represent obstacles around a robot workcell, build a navigable map from depth-sensor data, or provide free-space information for a humanoid robot moving through a scene.

Use this Skill when you need a compact voxel representation that distinguishes observed surfaces from ray-cast free space.

The Skill

from telekinesis import vitreous

occupied_cells, free_cells = vitreous.reconstruct_octomap(
    point_cloud=point_cloud,
    resolution=0.01,
    sensor_origin=[0.0, 0.0, 0.0],
)

API Reference

Performance Note

Current Data Limits: The system currently supports up to 1 million points per request (approximately 16MB of data). We're actively optimizing data transfer performance as part of our beta program, with improvements rolling out regularly to enhance processing speed.

Example

Input Point Cloud

The point cloud used as the observed surface data for reconstruction.

Reconstructed OctoMap

The reconstructed occupancy map. Occupied cells represent observed surfaces, while free cells represent space traversed by rays from the sensor origin.
Parameters: resolution = 0.01

The Code

from telekinesis import vitreous
from datatypes import io
import pathlib

# Optional for logging
from loguru import logger

DATA_DIR = pathlib.Path("path/to/telekinesis-data")

# Load point cloud
filepath = str(DATA_DIR / "point_clouds" / "beer_can_corrupted_normals.ply")
point_cloud = io.load_point_cloud(filepath=filepath)
logger.success(f"Loaded point cloud with {len(point_cloud.positions)} points")

# Execute operation
occupied_cells, free_cells = vitreous.reconstruct_octomap(
    point_cloud=point_cloud,
    resolution=0.01,
    sensor_origin=[0.0, 0.0, 0.0],
)
logger.success(
    f"Reconstructed OctoMap with {len(occupied_cells.centers)} occupied "
    f"and {len(free_cells.centers)} free cells"
)

The Explanation of the Code

The script imports vitreous for the OctoMap operation, io for loading point-cloud data, pathlib for file paths, and loguru for optional logging.

from telekinesis import vitreous
from datatypes import io
import pathlib

# Optional for logging
from loguru import logger

Next, it loads a point cloud from a .ply file and logs the number of input points.

DATA_DIR = pathlib.Path("path/to/telekinesis-data")

filepath = str(DATA_DIR / "point_clouds" / "beer_can_corrupted_normals.ply")
point_cloud = io.load_point_cloud(filepath=filepath)
logger.success(f"Loaded point cloud with {len(point_cloud.positions)} points")

The reconstruct_octomap Skill discretizes the scene into cells with an edge length of 0.01 point-cloud units. It marks cells containing observed endpoints as occupied and uses the supplied sensor origin for ray casting to identify free cells along each observation ray. The result is returned as two Boxes3D objects, so their centers and half_sizes can be visualized or passed to downstream spatial-processing steps.

occupied_cells, free_cells = vitreous.reconstruct_octomap(
    point_cloud=point_cloud,
    resolution=0.01,
    sensor_origin=[0.0, 0.0, 0.0],
)
logger.success(
    f"Reconstructed OctoMap with {len(occupied_cells.centers)} occupied "
    f"and {len(free_cells.centers)} free cells"
)

Running the Example

Runnable examples are available in the Telekinesis examples repository. Follow the README in that repository to set up the environment. Once set up, run this example with:

cd telekinesis-examples
python examples/vitreous_examples.py --example reconstruct_octomap

How to Tune the Parameters

resolution (required, defualt: 0.01):

• Sets the edge length of every OctoMap cell in the same units as the point cloud
• Decrease it to preserve finer detail, at the cost of more cells, memory, and computation
• Increase it to produce a coarser, smaller, and faster map
• Choose a value that is no smaller than the useful spatial precision of the sensor data

For example, resolution=0.01 creates cells with an edge length of 0.01 units: 10 mm when the point cloud uses meters, or 0.01 mm when it uses millimeters.

sensor_origin (required, default: [0, 0, 0]):

• Specifies the 3D sensor position used for ray casting
• Accepts a three-element list, NumPy array, or Vector3D
• Must use the same coordinate frame and units as the point cloud
• Set it to the actual depth camera or lidar origin to obtain meaningful free-space cells
• Omit it only when sensor-origin information is unavailable or free-space carving is not required

TIP

Best practice: Start with a resolution close to the smallest obstacle or surface feature the robot must detect. Use the calibrated sensor origin in the point-cloud coordinate frame; an incorrect origin can cause free space to be inferred along the wrong rays.

Where to Use the Skill in a Pipeline

OctoMap reconstruction is commonly used for:

• 3D environment mapping
• Obstacle and collision checking
• Free-space estimation
• Robot navigation and motion planning

A typical mapping pipeline looks as follows:

from telekinesis import vitreous

# 1. Load or acquire a point cloud
point_cloud = vitreous.load_point_cloud(...)

# 2. Remove noise and reduce point density
filtered_cloud = vitreous.filter_point_cloud_using_statistical_outlier_removal(...)
downsampled_cloud = vitreous.filter_point_cloud_using_voxel_downsampling(...)

# 3. Reconstruct occupied and free space
occupied_cells, free_cells = vitreous.reconstruct_octomap(
    point_cloud=downsampled_cloud,
    resolution=0.01,
    sensor_origin=[0.0, 0.0, 0.0],
)

# 4. Use occupied cells for collision checking and free cells for planning

Related skills to build such a pipeline:

• filter_point_cloud_using_statistical_outlier_removal: remove isolated sensor noise before mapping
• filter_point_cloud_using_voxel_downsampling: reduce input density and processing time

When Not to Use the Skill

Do not use reconstruct OctoMap when:

• You need a smooth surface for rendering or inspection (use mesh reconstruction instead)
• You need exact surface geometry (voxelization quantizes geometry according to resolution)
• The point cloud and sensor origin use different coordinate frames (transform them into a common frame first)