DHB-XR

SE(3)-invariant trajectory representation, adaptation, and decode tooling for robotics and VLA applications

DHB-XR turns pose trajectories into motion invariants that preserve the shape of a demonstration while removing dependence on the global frame. Use it to encode robot motions, retarget demonstrations to new start and goal poses, compare or retrieve motions in invariant space, and feed compact trajectory representations into VLA action pipelines.

The core NumPy path handles DHB-DR/DHB-QR encode and decode. Optional solver paths add FATROP-first boundary adaptation for single trajectories and fixed-horizon CusADi GPU decode for high-throughput deployments that can compile local CUDA libraries ahead of time.

Research Background

This library implements double-reflection (DHB-DR) and quaternion-relative (DHB-QR) invariant representations for rigid-body motion trajectories on SE(3), as described in the manuscript "Double-Reflection DHB Invariant Representation on SE(3)".

Author: Andy Park (andypark.purdue@gmail.com)

Features

DHB-DR (Double-Reflection): Euler-based invariants (4 values per component)
DHB-QR (Quaternion-Relative): Quaternion-based invariants (5 values per component), no gimbal lock
DHB-TI (Time-Invariant): Speed-independent representations via arc-length reparameterization
Trajectory generation: FATROP-first boundary adaptation with explicit fallback policy
CusADi GPU decode: Optional fixed-horizon decode libraries for 50, 80, 100, 150, and 200 samples
Tokenization: VQ-VAE / RVQ for DHB-Token (VLA action representation)
Motion database: Storage, similarity (L2, DTW), and retrieval
Imitation learning: Invariant matching, SE(3) geodesic, and hybrid losses
Robust encoding: Handles reversals, zero-motion segments, and frame alignment issues

Quick start

pip install dhb_xr
# or with extras: pip install "dhb_xr[fatrop,cusadi,tokenization,database]"

from dhb_xr import encode_dhb_dr, decode_dhb_dr
from dhb_xr.core.types import DHBMethod, EncodingMethod
import numpy as np

# Create sample trajectory data
n = 50
positions = np.cumsum(np.random.randn(n, 3) * 0.01, axis=0)
quaternions = np.tile(np.array([1.0, 0.0, 0.0, 0.0]), (n, 1))  # identity orientation

# Encode trajectory to invariants
result = encode_dhb_dr(
    positions, quaternions,
    method=EncodingMethod.POSITION,
    use_default_initial_frames=True,
    dhb_method=DHBMethod.DOUBLE_REFLECTION
)

# Decode back to poses
decoded = decode_dhb_dr(
    result["linear_motion_invariants"],
    result["angular_motion_invariants"],
    result["initial_pose"],
    method=EncodingMethod.POSITION,
    dhb_method=DHBMethod.DOUBLE_REFLECTION,
    drop_padded=True
)

print(f"Original shape: {positions.shape}")
print(f"Decoded shape: {decoded['positions'].shape}")

Examples

See Examples for a walkthrough of the example scripts and how to run them.

VLA Integration

DHB-XR integrates with Vision-Language-Action (VLA) benchmarks:

LIBERO: Load trajectories, encode to DHB invariants, run in simulation
RoboCASA: HDF5 dataset support with motion retrieval

See VLA Integration Guide for setup and usage.

API Reference

See the API reference for core encoding, decoding, optimization, database, tokenization, losses, and visualization modules.

License

MIT License.