mujoco_lidar 0.3.0

A LiDAR sensor designed for MuJoCo

MuJoCo-LiDAR: High-Performance LiDAR Simulation

High-performance LiDAR simulation for MuJoCo with CPU, Taichi, and JAX backends.

中文文档 | Installation | Usage Guide | Development | Contributing

Features

• Multi-Backend Support:
  • CPU: MuJoCo native mj_multiRay, no GPU required
  • Taichi: GPU parallel computing, supports Mesh and Hfield
  • JAX: GPU + MJX integration, batch simulation support
• High Performance: 1M+ rays/sec on GPU, real-time BVH construction
• Multiple LiDAR Models: Velodyne (HDL-64E, VLP-32C), Livox (mid360, avia), Ouster (OS-128), custom patterns
• ROS Integration: Ready-to-use ROS1/ROS2 examples

Quick Start

Installation

From PyPI:

# Basic (CPU only)
uv add mujoco-lidar

# With Taichi backend (GPU)
uv add "mujoco-lidar[taichi]"

# With JAX backend (GPU + batch)
uv add "mujoco-lidar[jax]"

From Source:

git clone https://github.com/TATP-233/MuJoCo-LiDAR.git
cd MuJoCo-LiDAR

uv sync --extra dev                        # CPU only
uv sync --extra dev --extra taichi         # with Taichi backend
uv sync --extra dev --extra taichi --extra jax  # all backends

See Installation Guide for details.

Basic Usage

import mujoco
from mujoco_lidar import MjLidarWrapper, scan_gen

# Load model
model = mujoco.MjModel.from_xml_path("scene.xml")
data = mujoco.MjData(model)

# Create LiDAR
lidar = MjLidarWrapper(
    model,
    site_name="lidar_site",
    backend="cpu",  # or "taichi", "jax"
    cutoff_dist=50.0
)

# Generate scan pattern
theta, phi = scan_gen.generate_HDL64()

# Trace rays
ranges = lidar.trace_rays(data, theta, phi)

See Usage Guide for more examples.

Performance

Backend	Rays/sec	Hardware	Batch Support
CPU	~9M	Native	No
Taichi	~62M	GPU	Yes
JAX	~231M	GPU	Yes

Run benchmarks: make benchmark

Documentation

• Installation Guide - Detailed installation instructions
• Usage Guide - Examples and tutorials
• API Reference - Complete API documentation
• Development Guide - Contributing and testing
• Project Structure - Codebase organization

Examples

• examples/example_native.py - CPU backend
• examples/example_taichi.py - Taichi backend
• examples/lidar_vis_ros2.py - ROS2 integration
• examples/unitree_go2_ros2.py - Unitree Go2 robot

Development

git clone https://github.com/TATP-233/MuJoCo-LiDAR.git
cd MuJoCo-LiDAR
uv sync --extra dev

make test      # Run tests
make lint      # Check code quality
make benchmark # Run performance tests

See CONTRIBUTING.md for contribution guidelines.

License

MIT License - see LICENSE for details.

Citation

If you use this project in your research, please cite:

@software{mujoco_lidar,
  title = {MuJoCo-LiDAR: High-Performance LiDAR Simulation},
  author = {Yufei Jia},
  year = {2024},
  url = {https://github.com/TATP-233/MuJoCo-LiDAR}
}