update

README.md

@@ -78,6 +78,65 @@ a procedural blue "Sad" wisp.
 
 ---
 
+## Forgiving scanning (`js/detect-tuned.js`)
+
+Raw js-aruco can feel finicky — slow to acquire, quick to drop on blur, jittery once locked.
+`detect-tuned.js` wraps it with three tolerances, used by `ar-head.html`:
+
+1. **Looser detector params** — smaller min marker size, looser polygon fit, adjustable light
+   threshold. Three presets: `strict` / `forgiving` (default) / `greedy`. Switch live from the
+   "scan:" dropdown in `ar-head.html`.
+2. **Multi-scale pass** — also detects on a half-res copy, catching distant / motion-blurred
+   markers that fail at full res (corners scaled back up).
+3. **Coast + smooth tracker** — `MarkerTracker` keeps the last good pose for ~280 ms through a
+   dropout (no more snapping off when a hand passes or the image blurs), and smooths corners with
+   an adaptive 1€ filter: heavy smoothing when you hold still (kills jitter), light when you move
+   fast (stays responsive).
+
+Tuning knobs: `DETECT_PRESETS` (params per preset), `MarkerTracker({ coastMs, smooth })`.
+Verified that the looser presets don't introduce false negatives — all presets still cleanly
+detect a known marker, including small + blurred.
+
+> The jitter meter (`jitter.html`) deliberately does **not** smooth — it reports raw pose truth so
+> the numbers are honest. `ar-head.html` smooths because there the goal is a stable-feeling ghost.
+
+## 3D LEGO-head ghost: `ar-head.html`
+
+The real-3D successor to the flat-sprite PoC. Camera → ArUco → **full 6-DoF pose** → a Three.js
+ghost shaped like a classic minifig head (cylinder body, domed top, the stud) in a translucent
+Hidden Side gradient with a fresnel rim-glow. Because it's driven by the marker's solved
+rotation+translation, the head holds its orientation in world space — **walk around the crest and
+it turns**, showing its sides. Eyes on the front (+Z) face; simple original ghost eyes, no
+reproduced LEGO face print. Tap the swatches to switch lure colour (Blue/Red/Yellow).
+
+Geometry lives in `js/lego-head-ghost.js` (`buildLegoHeadGhost(THREE, colorKey)`), built from
+primitives so there's no model file to load. Set `MARKER_SIZE_MM` in `js/ar-head.js` to match your
+marker.
+
+> Pose convention: POS-IT gives the marker pose in a camera frame (X right, Y up, Z toward viewer);
+> we flip Y/Z into Three.js's (Y up, looking down −Z). Verified: anchor lands in front of camera at
+> unit scale.
+
+## Pose jitter meter: `jitter.html`
+
+Measures how *stable* the solved camera pose is per marker while you hold still — the number
+that predicts whether occlusion will look clean. "Jitter" = standard deviation of the marker's
+solved position (mm) and orientation (deg) over a ~1s rolling window.
+
+**Workflow for the en-masse test:**
+1. Open `jitter.html` on the phone (HTTPS).
+2. Label the run in the text box (e.g. `1 marker, 30cm, room light`).
+3. Hold steady on a crest, **Record** ~10s, **Stop**.
+4. Repeat for: closer / further, sharper angle, 1 marker vs several crests in frame, bright vs dim.
+5. **Export → Download JSON** and send the file back.
+
+The HUD shows live pos-jitter (green <0.5 mm, amber, red >1.5 mm), angle jitter, distance, and
+view angle. `distMeanMm`, `markersPerFrame`, and per-marker `posJitMedMm` in the export are the
+key numbers — they'll tell us how much multi-marker fusion is worth before we build occlusion.
+
+> Set `MARKER_SIZE_MM` at the top of `public/js/jitter.js` to the outer black-square size of the
+> marker you actually test with (default 96 mm = 6 cells × 16 mm). Distance readings depend on it.
+
 ## Run
 
 ```bash
@@ -97,7 +156,11 @@ Env: `PORT` (default 34034), `TICK_HZ` (default 20).
 - [x] God-view desktop viewer
 - [x] Scene + anchor + spawn data model (mm, corner origin)
 - [x] ArUco 4×4 marker system + LEGO build maps ("Newbury Crests")
-- [x] AR PoC: camera + detection + ghost locked to marker
+- [x] AR PoC: camera + detection + ghost locked to marker (flat sprite)
+- [x] 3D LEGO-head ghost holding world orientation (`ar-head.html`)
+- [x] Pose jitter meter (`jitter.html`) with session logging + JSON export
+- [ ] Multi-marker pose fusion (one combined camera pose from all visible crests)
+- [ ] Occluder geometry: ghosts vanish behind premapped buildings (depth-only boxes)
 - [ ] Phone AR client: render anchored ghosts through the camera using marker pose
 - [ ] Calibration page: scan each crest, record its measured world position
 - [ ] Per-ghost colour/sprite wiring from the enriched roster