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).
A fully unconstrained 3D torso base (freejoint) so roll/yaw/lateral motion emerge from contacts.
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

Use --frame world for physically grounded playback in the web app. In world frame, the feet contact the ground plane at z=0 and torso height stays above the floor as expected.

If you export with --frame body, the torso is re-centered to body-local coordinates (torso.z ~= 0), which is useful for relative-linkage debugging but can look like the body is dropped onto the floor in overlay/playback.

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 torso now uses an unconstrained freejoint; side tilt is physically simulated, but the default PD crank gait can be less stable and may tumble during some runs.
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.

TODO

Tune contact/friction/damping to improve stability with unconstrained 3D freejoint dynamics.
Retune PD gait phase offsets and gains for forward progress under full 3D dynamics.
Add roll/pitch/yaw summary metrics to walker-eval for easier stability regression checks.
Add a short recommended viewer camera preset for inspecting side tilt behavior.

2.9 KiB Raw Blame History