CudaRobotics Docs

Python bindings

MPPI and Registration API

The `cudarobotics` package exposes a GPU MPPI planner, CUDA DLPack costmap input, and point-cloud registration algorithms through a small Python wrapper layer over the CUDA core.

GPU MPPI Planner

`MppiPlanner.compute()` returns `(v, vy, w, info)`. NumPy costmaps use the host path. CUDA DLPack producers such as PyTorch or CuPy tensors can pass a `uint8` 2D costmap without staging it through host memory. `distance_field_weight` enables an optional GPU clearance critic built from the same costmap. 

import numpy as np
import cudarobotics as cr

planner = cr.MppiPlanner(
    batch_size=2048,
    time_steps=56,
    model_dt=0.05,
    motion_model="diff_drive",
    path_angle_weight=0.25,
    curvature_speed_weight=0.0,
    curvature_speed_min=0.18,
    distance_field_weight=12.0,
    distance_field_cutoff=0.8,
)

costmap = np.zeros((200, 200), dtype=np.uint8)
path = np.array([[x, 5.0] for x in np.arange(1.0, 9.1, 0.1)], dtype=np.float32)
v, vy, w, info = planner.compute(
    (1.0, 5.0, 0.0),
    costmap,
    path,
    (9.0, 5.0, 0.0),
    resolution=0.05,
)
GPU MPPI demo
MPPI rollout behavior from the animated demo gallery.

CUDA DLPack Costmap

Only the costmap currently accepts a device DLPack producer. Path and footprint inputs remain host arrays.

import numpy as np
import torch
import cudarobotics as cr

planner = cr.MppiPlanner(batch_size=2048, time_steps=56, model_dt=0.05)
costmap = torch.zeros((200, 200), dtype=torch.uint8, device="cuda")
path = np.array([[1.0, 5.0], [5.0, 5.0]], dtype=np.float32)

v, vy, w, info = planner.compute(
    (1.0, 5.0, 0.0),
    costmap,
    path,
    (5.0, 5.0, 0.0),
    resolution=0.05,
)

Runnable example: mppi_dlpack_costmap.py. It uses CUDA PyTorch when available and falls back to CuPy.

MPPI Info Fields

`compute()` returns diagnostics for controller tuning and failure analysis.

Field Meaning
`best_cost` / `mean_cost` Lowest and mean sampled rollout cost in the final MPPI iteration.
`sampled_rollouts` / `valid_rollouts` Total samples and samples that avoided collision-cost hits.
`valid_rollout_ratio` Quick health signal for costmap geometry, sample count, and local path quality.
`all_colliding` / `retreating` Collision saturation and recovery back-out state.

Registration Classes

Rigid wrappers retain the tuple-returning `register()` API and add `register_result()` for a normalized, typed `RegistrationResult`. 

result = registration.RobustP2Plane().register_result(target, source)
rotation = result.rotation
translation = result.translation
info = result.info
Class Purpose Example
`FilterReg` GPU filtered-EM rigid point-cloud registration. `rotation, translation, info = reg.register(target, source)`
`RobustP2Plane` Robust Student's-t point-to-plane registration. `rotation, translation, info = reg.register(target, source)`
`RobustTreg` Robust Student's-t point-to-point registration. `rotation, translation, info = reg.register(target, source)`
`SinkhornReg` Unbalanced optimal-transport registration. `rotation, translation, info = reg.register(target, source)`
`Fgr` Fast Global Registration with FPFH and graduated non-convexity. `rotation, translation, info = reg.register(target, source)`
`Bcpd` GPU BCPD non-rigid point-set registration. `deformed, info = reg.register(target, source)`