102 lines
3.6 KiB
Markdown
102 lines
3.6 KiB
Markdown
# Walker Linkage Web Simulator
|
|
|
|
2D + 3D browser simulator of the walker linkage from [`linkage.svg`](linkage.svg), implemented with HTML Canvas for the top pane and Three.js for the lower pane.
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- One-side linkage solve from fixed bar lengths and crank angle.
|
|
- Duplicated opposite side with 180° phase offset.
|
|
- Color mapping aligned with the drawing:
|
|
- pivots = yellow
|
|
- crank = green
|
|
- links = black
|
|
- body = red
|
|
- Play/pause, reset, speed slider, angle scrubber.
|
|
- Live length controls in centimeters (cm):
|
|
- body (`AB`) with `A`/`B` preserved as body endpoints
|
|
- crank (`OC`)
|
|
- leg (`CG`) with automatic coupling to `CF`
|
|
- tendon (`BE`) with automatic coupling to `AD`
|
|
- defaults normalized to a `45 cm` leg baseline while preserving original mechanism ratios
|
|
- mirrored automatically to far side (180° phase side)
|
|
- Presets tab for built-in MuJoCo playback traces (10cm/20cm/30cm).
|
|
- Foot trajectory traces for both sides.
|
|
- Optional linkage annotation overlay (joint and link labels).
|
|
- Optional real-time 3D viewport with orbit camera and camera reset.
|
|
- Optional microphone-reactive camera motion (volume + frequency bands).
|
|
- Audio debug views (switchable waterfall/spectrogram) for beat tuning.
|
|
- Diagnostics panel with closure error and fallback counters.
|
|
|
|
## File layout
|
|
|
|
- [`index.html`](index.html): 2D + 3D viewport shell and control panel
|
|
- [`styles.css`](styles.css): Stacked view layout and styling
|
|
- [`src/main.js`](src/main.js): bootstrap, animation loop, integration
|
|
- [`src/math.js`](src/math.js): vector math and circle intersection
|
|
- [`src/geometry.js`](src/geometry.js): normalized points and derived lengths
|
|
- [`src/kinematics.js`](src/kinematics.js): mechanism solve for near/far sides
|
|
- [`src/renderer.js`](src/renderer.js): Canvas rendering pipeline
|
|
- [`src/renderer3d.js`](src/renderer3d.js): Three.js scene, camera, and 3D linkage rendering
|
|
- [`src/trace.js`](src/trace.js): trajectory buffers
|
|
- [`src/ui.js`](src/ui.js): controls + diagnostics text
|
|
|
|
## Run
|
|
|
|
Any static server is enough.
|
|
|
|
No build step is required. Three.js is loaded via ESM URL imports.
|
|
|
|
Recommended (compressed static serving for large MuJoCo JSON presets):
|
|
|
|
```bash
|
|
caddy run
|
|
```
|
|
|
|
This uses the repo `Caddyfile` (`zstd` + `gzip`) on `http://localhost:8676`.
|
|
|
|
If you do not have Caddy installed, a basic uncompressed fallback is:
|
|
|
|
```bash
|
|
python3 -m http.server 8676
|
|
```
|
|
|
|
Then open:
|
|
|
|
`http://localhost:8676/`
|
|
|
|
## MuJoCo rigid-body track
|
|
|
|
A Python + MuJoCo scaffold is available in `sim/mujoco` for rigid-body walking experiments.
|
|
|
|
Quick start:
|
|
|
|
```bash
|
|
cd sim/mujoco
|
|
uv sync
|
|
uv run walker-run --seconds 10
|
|
```
|
|
|
|
Use `uv run walker-run --viewer --seconds 30` for interactive visualization.
|
|
See `sim/mujoco/README.md` for details.
|
|
|
|
The MuJoCo torso base is now a full 3D freejoint (unconstrained), so side tilt and lateral motion are physically simulated.
|
|
|
|
To compare physics in the browser app with true MuJoCo playback in the 3D pane, export JSON via
|
|
`uv run walker-export-web --frame world --seconds 15 --out ../../artifacts/mujoco_trace.json`
|
|
from `sim/mujoco`, then load it in the "MuJoCo Import" panel.
|
|
|
|
Notes:
|
|
|
|
- Default export format is `v2` (`walkersim-mujoco-playback-v2`) with time-indexed 3D frames.
|
|
- `overlay2d` is embedded in the same payload, so the 2D pane still shows foot traces.
|
|
- For legacy 2D-only payloads, use `--format v1`.
|
|
|
|
## Model notes
|
|
|
|
- v1 is pure kinematic visualization.
|
|
- No collision/ground dynamics and no body translation.
|
|
- Side B is driven by `theta + pi`.
|
|
- Lower branch of each circle-circle intersection is selected to maintain leg-down posture.
|