MuJoCo Walker Scaffold
This folder adds a Python + MuJoCo rigid-body simulation track to the existing web-based kinematic simulator.
What is included
- A rigid-body 4-leg linkage model in MJCF (two legs per side, tandem links).
- One crank motor per side; each motor drives two legs through closed-chain constraints.
- A PD crank controller baseline (phase-driven near/far cranks).
- A CLI runner for quick simulation and optional viewer.
- A CSV trajectory exporter for replay/comparison workflows.
Setup with uv
From this directory:
uv sync
Run the baseline simulation (headless):
uv run walker-run --seconds 10
Evaluate gait quality numerically:
uv run walker-eval --seconds 10
Run with interactive MuJoCo viewer:
uv run walker-run --viewer --seconds 30
Render video without opening a GUI:
uv run walker-video --seconds 12 --out ../../artifacts/walker.mp4
Export a CSV trajectory:
uv run walker-export --seconds 15 --out ../../artifacts/walker_traj.csv
Export playback JSON for the browser viewer (true 3D playback + 2D overlay):
uv run walker-export-web --frame world --seconds 15 --out ../../artifacts/mujoco_trace.json
In the web app, use "MuJoCo Import" to load that JSON.
- Default format is
v2(walkersim-mujoco-playback-v2) and is used for true playback in the 3D pane. - To export the old 2D-only overlay schema, add
--format v1.
RL wrapper
Install RL dependencies:
uv sync --extra rl
Train PPO baseline:
uv run walker-train-ppo --steps 200000
Notes
- The model matches the codebase linkage layout (nearF/nearG/farF/farG) but still needs tuning for stronger forward gait.
- This scaffold is independent from the browser simulator and can be evolved without breaking the JS app.
- Next step is geometry alignment/tuning against the linkage dimensions in the main app.