rblox

Cross-platform GPU-accelerated TSDF reconstruction library. Rust + wgpu compute shaders with Python bindings.

Runs on NVIDIA (Vulkan), AMD (Vulkan), Apple Silicon (Metal), and Windows (DX12).

Python API

import rblox
import numpy as np

# Setup
mapper = rblox.Mapper(voxel_size_m=0.05)
sensor = rblox.Sensor.from_camera(fx=500, fy=500, cx=320, cy=240, width=640, height=480)

# Per frame — depth and color as numpy arrays, pose as 4x4 camera-to-world matrix
mapper.add_depth_frame(depth, pose, sensor)      # HxW float32, meters
mapper.add_color_frame(color, pose, sensor)       # HxWx3 uint8, RGB

# Mesh extraction
mapper.update_color_mesh()
mesh = mapper.get_color_mesh()
vertices = mesh.vertices()    # Nx3 float32
normals = mesh.normals()      # Nx3 float32
colors = mesh.colors()        # Nx4 uint8 RGBA
triangles = mesh.triangles()  # Mx3 uint32

# Render depth from the TSDF via sphere tracing
depth_map = rblox.render_depth_image(mapper, pose, sensor, height=480, width=640)

# Maintenance
mapper.decay()
mapper.clear()
mapper.tsdf_layer_view().num_blocks()

Coordinate system

• Camera frame: X right, Y up, Z forward
• World frame: agnostic (defined by your poses)
• Depth images: standard row-major (row 0 = top of image)

Install

Requires Rust and Python 3.9+.

uv add rblox --git https://github.com/Project-NEURIA/rblox --subdirectory crates/rblox-python

Development

To build from source for local development:

pip install maturin
cd crates/rblox-python
maturin develop

Architecture

crates/
├── rblox-core/       Pure Rust types (voxels, camera, transforms, marching cubes tables)
├── rblox-gpu/        wgpu compute shaders + dispatch code
│   └── shaders/      WGSL shaders (TSDF, color, sphere trace, decay)
├── rblox-mapper/     High-level Mapper combining layers + integrators
└── rblox-python/     PyO3 bindings (numpy interop, no PyTorch dependency)

How it works

• Sparse voxel grid: blocks (8x8x8 voxels) stored in a pre-allocated GPU buffer pool. CPU-side HashMap maps 3D block indices to buffer slots.
• TSDF integration: GPU compute shader projects each voxel to the depth image and updates a weighted average of signed distances.
• Color integration: same projection, weighted average of RGB values. Uses depth for occlusion testing.
• Sphere tracing: GPU compute shader marches rays through the TSDF using an uploaded open-addressing hash table for voxel lookups.
• Mesh extraction: CPU marching cubes with rayon parallelism. Reads TSDF blocks back from GPU, processes each block independently.
• Decay: GPU compute shader multiplies voxel weights by a decay factor. Fully decayed blocks are deallocated on CPU.

Parameters

Param	Default	Description
voxel_size_m	(required)	Voxel side length in meters
truncation_distance_vox	4.0	TSDF truncation band in voxels
max_integration_distance_m	7.0	Ignore depth beyond this
max_weight	5.0	Max accumulated voxel weight
decay_factor	0.95	Weight multiplier per decay call
sphere_trace_max_steps	100	Max ray marching iterations
sphere_trace_max_ray_length_m	15.0	Max ray distance

Pass as a dict: rblox.Mapper(voxel_size_m=0.05, params={"max_weight": 10.0})

Tests

# Rust
cargo test -p rblox-core -p rblox-mapper

# Python
python python/tests/test_mapper.py