{"case":  [{"id": "c03", "nodes": ["battery_pouch", "battery_jst_plug"], "show": ["foot", "base", "battery_pouch"],
            "frame": ["battery_pouch"], "beta": 0.8, "rmul": 1.7, "label": "150 mAh LiPo", "text": "The battery lies flat underneath.", "dur": 5.7}],
 "board": [{"id": "b01", "nodes": ["U1"], "side": "top", "label": "U1  ATtiny1616", "text": "The microcontroller echoes the pulse.", "dur": 7.3}]}

# The 3D walkthrough

The part-by-part walkthrough is the centre of the film: the enclosure built up from the bottom, then the board's major parts on the top and the underside, each one highlighted and labelled while the narration says what it does. `assets/walkthrough-director.js` drives the Adom 3D viewer through it; you write the steps.

## Steps file

`walkthrough/steps.json`, one list per segment (see `docs/example-walkthrough-steps.json`, from the Ghost Hand rev 2 film):

```json
{"case":  [{"id": "c03", "nodes": ["battery_pouch", "battery_jst_plug"], "show": ["foot", "base", "battery_pouch"],
            "frame": ["battery_pouch"], "beta": 0.8, "rmul": 1.7, "label": "150 mAh LiPo", "text": "The battery lies flat underneath.", "dur": 5.7}],
 "board": [{"id": "b01", "nodes": ["U1"], "side": "top", "label": "U1  ATtiny1616", "text": "The microcontroller echoes the pulse.", "dur": 7.3}]}
```

- `nodes`: the GLB node names to highlight (a board exported from KiCad names its parts by reference: U1, J2, D4).
- `show` (enclosure): everything visible at this step, so the model builds up part by part.
- `side`: `top` or `bottom` for board parts; the underside turns the bottom light on and views the board so its text reads the right way up.
- `label`: the on-screen name. `text`: the narration line. `dur`: that line's length in seconds (narrate first with adom-tts, then measure).
- `frame`, `beta`, `rmul`: optional framing (what to centre on, the camera's tilt, how far back).

## Recording a take

1. Open the project's 3D viewer page in a pup window on the recording machine, sized to about 90 percent over a full-screen Hydrogen.
2. Inject the director (`pup_evaluate`), set up the segment, start a desktop recording, call `GHW.run(steps, root)`, wait for `GHW.running` to go false, stop the recording.
3. Read `GHW.log` and `GHW.wall0`: each step's start time, to line the narration up in the cut.

## What we learned making the first ones

- Merge the board first (`GHW.mergeBoard()`): a KiCad board model can be 20,000 small meshes and drop the viewer to 3 frames a second; merged per part it runs at 60.
- Keep the highlight light: an outline glow plus a tint. A heavy glow froze the page.
- Set the camera's target before its angle and distance, or the viewer recomputes them and the shot drifts.
- Evaluations that wait more than about 20 s time out: start long jobs, then poll.
- Look at a frame from the middle of every step before using the take. Toasts, a part hidden behind another, and upside-down text all show up there.
- The walkthrough plays at real speed (1.0x). Do not speed 3D up.