# 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.