diff --git a/.claude-context/00-overview.md b/.claude-context/00-overview.md new file mode 100644 index 0000000..734d988 --- /dev/null +++ b/.claude-context/00-overview.md @@ -0,0 +1,45 @@ +# Newbury Exhibit — Overview + +Fan-made shared multi-viewer AR experience for a physical LEGO® Hidden Side™ town +display (tribute project — not affiliated with the LEGO Group). Multiple phones +point at printed "Newbury Crests" (ArUco markers) and see the same server-driven +ghosts anchored to real-world positions, each from their own viewpoint. + +## Shape of the thing + +- **Delivery:** web, no app install. Visitors open a URL and press Start. +- **Tracking:** printed fiducials + a joint multi-marker solve. No SLAM, no + cloud AR service — self-hosted end to end. +- **Authority:** the server owns which ghosts exist and where; clients own only + their own camera pose. That's what keeps multiple phones consistent. +- **Motion:** deterministic functions of (spawn record, wall-clock time), so + phones agree without streaming positions. + +## Current state (v3) + +v3 is a **tracking-core transplant** into v2's body: the playlist engine, +residents/tracks, character editor, admin suite, error overlay, password-gated +final mode and deployment all carry over unchanged. What changed is how the +camera pose is recovered — see `01-architecture.md`. + +Deployed in place of v2: same host port, container name and `exhibit-live` +volume, so live state carries over and rollback is one command. + +- Repo: `newbury-exhibit-v3` (v2 retained as the rollback path) +- Deploy: `cd ~/newbury-exhibit-v3 && bash deploy.sh` +- Rollback: `cd ~/newbury-exhibit && docker compose up -d --build` +- Page index, API list and HUD guide: `docs/PAGES.md` + +## Conventions + +- World units cm; origin at the front-left table corner; +X right, +Z back, + +Y up. Marker print sizes stay in mm (`sizeMM`), converted once at the solver + boundary. +- `data/*.json` are committed seeds; `data/live/` (a Docker volume) is runtime + state. +- Dev mode shows a tracking HUD and an on-screen error overlay; final mode + password-gates admin. + +## Session Log + +- 2026-09-23 — AR Tracking Overhaul: Worker Offload, Camera Model, and Coplanar Pose Ambiguity — moved OpenCV off the main thread, fixed the focal/FOV model for portrait streams, deduped marker ids, gated the mirrored coplanar pose, and built a two-page A3 test rig with a foldable marker tower.