rerun-loader-mjcf

A Rerun external data loader for MJCF (MuJoCo XML) files.

https://github.com/user-attachments/assets/a9f95ed6-1441-4ce0-bef8-c3fb1e720d56

Simulating fourier_n1 and boston_dynamics_spot from mujoco_menagerie:

uv run rerun-loader-mjcf --simulate mujoco_menagerie/fourier_n1/scene.xml
uv run rerun-loader-mjcf --simulate mujoco_menagerie/boston_dynamics_spot/scene.xml

https://github.com/user-attachments/assets/36aab5aa-134f-49a3-92d4-efb6b61e9354

Loading all robots from mujoco_menagerie

Installation

pip install rerun-loader-mjcf

Usage

CLI

rerun-loader-mjcf robot.xml

To run a real-time simulation loop:

rerun-loader-mjcf robot.xml --simulate

Or run directly without installing:

uvx rerun-loader-mjcf robot.xml

Python API

import mujoco
import rerun as rr
import rerun_loader_mjcf

model = mujoco.MjModel.from_xml_path("robot.xml")
data = mujoco.MjData(model)

rr.init("mjcf_viewer", spawn=True)
logger = rerun_loader_mjcf.MJCFLogger(model)

rr.set_time("frame", sequence=0)
logger.log_model()

data.qpos[0] += 0.5
mujoco.mj_forward(model, data)

rr.set_time("frame", sequence=1)
logger.log_data(data)

Options

logger = rerun_loader_mjcf.MJCFLogger(
    model,
    entity_path_prefix="robot",  # Prefix for all entity paths
    opacity=0.5,                 # Transparency (0.0 to 1.0)
    log_collision=True,          # Log collision geometries (default: False)
)

When log_collision=True, collision geometries are logged to a separate entity path ({prefix}/collision_geometries/) which can be toggled in the Rerun viewer.

To log collision geometries but hide them by default:

import rerun.blueprint as rrb

logger = rerun_loader_mjcf.MJCFLogger(model, log_collision=True)
rr.set_time("sim_time", duration=0.0)
logger.log_model()

blueprint = rrb.Spatial3DView(
    overrides={logger.paths.collision_root: rrb.EntityBehavior(visible=False)}
)
rr.send_blueprint(blueprint)

Dynamic Body Colors

You can change body colors during simulation (e.g., for highlighting):

# Set a body to red
logger.set_body_color(body_id=5, rgba=[1.0, 0.0, 0.0, 1.0])

# Reset to original color
logger.reset_body_color(body_id=5)

# Reset with custom opacity
logger.reset_body_color(body_id=5, opacity=0.5)

Recording Simulations

For efficient batch recording of simulations, use MJCFRecorder:

import mujoco
import rerun as rr
import rerun_loader_mjcf

model = mujoco.MjModel.from_xml_path("robot.xml")
data = mujoco.MjData(model)

rr.init("simulation", spawn=True)

logger = rerun_loader_mjcf.MJCFLogger(model)
rr.set_time("sim_time", duration=0.0)
logger.log_model()

# With simulation time (default: uses duration=data.time)
with rerun_loader_mjcf.MJCFRecorder(logger) as recorder:
    while data.time < 5.0:
        mujoco.mj_step(model, data)
        recorder.record(data)

# With explicit sequence index
with rerun_loader_mjcf.MJCFRecorder(logger, timeline_name="frame") as recorder:
    for i in range(1000):
        mujoco.mj_step(model, data)
        recorder.record(data, sequence=i)

# With explicit timestamp
with rerun_loader_mjcf.MJCFRecorder(logger, timeline_name="sim_time") as recorder:
    while data.time < 5.0:
        mujoco.mj_step(model, data)
        recorder.record(data, timestamp=data.time)

Lint

uv run pre-commit run -a

Credits

Inspired by rerun-loader-python-example-urdf.

What's Next

• Integrate mujoco-rs to implement a native Rust loader similar to loader_urdf.rs