docs(daikoku): measured reference spec for PA entrance geometry

Real-world numbers gathered from OSM (Overpass), Esri aerial imagery, and
frame-sampled onboard video. Replaces estimation with measurement.

Key findings:
  * Loop radii MEASURED via Kasa circle fit on OSM ways: 27.5-204 m,
    mean 131 m (469 studs). Two cleanest fits (rms<1.5) are the true
    helixes at 147 m (525 studs) and 124 m (441 studs).
  * 6 of 8 curved ramps turn CLOCKWISE - matches the video captions
    'right, right and you will reach the PA'.
  * FIVE deck layers in the interchange (OSM layer 1-5). Current
    PA_LIFT=56 models only one; faithful build wants 3+ overhead.
  * Real PA footprint 181x174 m (parking) / 203x227 m (rest_area).
    Current APRON 210x200 m already matches well - the divergence is
    SHAPE (square vs rounded wedge), not extent.
  * Scale clarified: PA work uses M=3.571 studs/m, NOT the 4.3 in
    c1_georeference.json (different mapping, 366 m median error).

Video reference archived to NAS 004-video-reference/ (364 MB, 4 routes).

docs/daikoku-reference-spec.md

@@ -0,0 +1,160 @@
+# Daikoku Futo PA — Measured Reference Spec
+
+Source-of-truth numbers for building the Daikoku PA entrance/exit ramps and
+apron in `MapBuilder.luau`. Everything here is **measured**, not estimated:
+OSM geometry via Overpass (`/tmp/osm_daikoku.py`), Esri aerial imagery, and
+frame-sampled onboard video.
+
+Generated 2026-08-03.
+
+---
+
+## 1. Scale
+
+| Quantity | Value |
+|---|---|
+| Project scale | `M = 1/0.28` = **3.571 studs per metre** (`MapBuilder.luau:69`) |
+| Reciprocal | 1 stud = 0.28 m |
+| `Circuit.STUDS_TO_KM` | 0.28 / 1000 |
+
+> NOTE: `c1_georeference.json` records `scale_studs_per_meter: 4.3` for the C1
+> loop georeference. That is a **different** mapping (real-Tokyo lat/lon → C1
+> world) with a stated `median_error_m: 366`. Do **not** use 4.3 for PA
+> geometry. PA work uses 3.571.
+
+---
+
+## 2. The real PA footprint (OSM)
+
+Overpass, bbox 35.4545/139.6700 → 35.4705/139.6935. ENU metres about
+`35.46246657, 139.68149001` (user's Google Earth point).
+
+| OSM way | Type | Extent (m) | Perimeter | Name |
+|---|---|---|---|---|
+| `405966005` | `highway=rest_area` | **203 × 227** | 646 m | 大黒PA |
+| `59608205` | `amenity=parking` | **181 × 174** | 507 m | 大黒ふ頭パーキングエリア |
+| `88702527` | `amenity=parking` | 102 × 107 | 359 m | (satellite lot, W of main) |
+
+**Current build:** apron is `APRON_X = 210*M`, `APRON_Z = 200*M`
+(`MapBuilder.luau:991`) = 210 × 200 m. That sits between the parking polygon
+(181×174) and the rest_area polygon (203×227) — **already a good match.** The
+apron extent is not the problem.
+
+The *shape* is the divergence: the build is an axis-aligned square; the real
+lot is a rounded wedge bounded on the N/E by the loop ramp arc.
+
+---
+
+## 3. Loop ramp radii — MEASURED
+
+Kasa circle fit over each OSM ramp way with |cumulative turn| ≥ 120°.
+`rms` = fit residual (low = genuinely circular).
+
+| OSM way | Length | Turn | **Radius** | rms | Layer | Direction |
+|---|---|---|---|---|---|---|
+| `32355896` | 475 m | −272° | **70.9 m** | 14.4 | — | CW / right |
+| `32403901` | 601 m | −217° | **147.4 m** | **1.2** | 5 | CW / right |
+| `32592491` | 729 m | +208° | **197.4 m** | 12.7 | 2 | CCW / left |
+| `307397558` | 167 m | −178° | **27.5 m** | 9.0 | — | CW / right |
+| `779045459` | 371 m | +161° | **123.6 m** | **0.7** | 3 | CCW / left |
+| `32403902` | 656 m | −150° | **204.2 m** | 13.3 | 3 | CW / right |
+| `32592481` | 359 m | −146° | **120.4 m** | 12.0 | 1 | CW / right |
+| `32592487` | 488 m | −122° | **158.8 m** | 11.3 | 2 | CW / right |
+
+**Headline numbers**
+
+- Radius range **27.5 – 204 m**; mean **131 m** = **469 studs**
+- The two cleanest circular fits (rms < 1.5) are the true helixes:
+  - `32403901` — **147 m** (526 studs), 217° of turn, layer 5
+  - `779045459` — **124 m** (441 studs), 161° of turn, layer 3
+- **6 of 8 curve clockwise (right).** Matches the video captions exactly:
+  `右、右と覚えておくとPAに着きます` — "remember right, right".
+
+**Recommended build values**
+
+| Ramp | Radius (m) | Radius (studs) | Turn |
+|---|---|---|---|
+| Main entry helix | 147 | **525** | ~220° CW |
+| Secondary helix | 124 | **440** | ~160° CCW |
+| Tight connector | 71 | **255** | ~270° CW |
+
+Current `Circuit.PA_RADIUS = 260` studs = 72.8 m — which is almost exactly the
+tight connector (`32355896`, 70.9 m). The *main* helixes are roughly 2× that.
+
+---
+
+## 4. Deck layers — the vertical stack
+
+OSM `layer` tags on bridge ways in the interchange:
+
+| Layer | Bridge ways | Total length |
+|---|---|---|
+| 1 | 11 | 17,696 m |
+| 2 | 7 | 5,637 m |
+| 3 | 8 | 5,368 m |
+| 4 | 10 | 10,096 m |
+| 5 | 6 | 1,417 m |
+
+**Five distinct deck levels.** This is the single most important structural
+fact: Daikoku JCT is a five-level stack, and the PA sits at the bottom of it.
+
+Current `Circuit.PA_LIFT = 56` studs (15.7 m) of clearance over the apron —
+that is one level. A faithful build wants at least 3 visible levels overhead.
+
+Typical Japanese expressway deck-to-deck spacing is ~10–12 m; at 3.571 studs/m
+that is **36–43 studs per level**.
+
+---
+
+## 5. Video-derived detail
+
+Sources archived at
+`unraid-1:/mnt/user/data/yy-roblox-games/0-tokyo-wangan-racing/004-video-reference/`
+
+| Route | Video ID | Len | Light | Value |
+|---|---|---|---|---|
+| CMT TOKYO "How to go to?" | `91suWmNr62c` | 2m50 | night | narrated turn-by-turn |
+| Bay Bridge up (ベイブリッジ〜大黒PA) | `PK4BachUlYo` | 2m36 | night | full entry sequence |
+| Yokohane down (横羽線下り) | `zlmdaR0opgE` | 5m15 | **day** | best structural read |
+| Honmoku JCT (攻略車載#18) | `fNHucFnFQ1c` | 10m07 | **day** | approach + JCT |
+| Night walkaround | `7i0-KCwMDyc` | 10m40 | night | apron-level atmosphere |
+
+### Confirmed visual details
+
+1. **Red/orange chevron shoulder paint** on the outer kerb through every ramp
+   curve. Present in all five videos, day and night. Highest-value cheap
+   detail available.
+2. **White splayed / V-shaped piers** with trapezoidal box-girder deck
+   underside (clearest at `yokohane_down` t=218–242s).
+3. **Chain-link mesh fencing** along ramp edges — not solid barrier. Above a
+   low concrete jersey base.
+4. **Green route shields** `大黒線 K5`; blue circular regulatory signs;
+   `50` km/h limit discs on ramps.
+5. **`/P` + up-right arrow gantry** marks the parking entry (`91suWmNr62c`
+   t=104s).
+6. Apron at night: warm sodium pole lighting, **white stall lines clearly
+   visible**, painted directional arrows, low guardrail perimeter.
+7. Arrival reads as **descending into a canyon** — decks close in overhead.
+
+---
+
+## 6. Gaps / not yet measured
+
+- **Deck heights above ground.** OSM `layer` gives ordering, not elevation.
+  Needs either a DEM lookup or estimation from video pier counts.
+- **Third approach route.** Confirmed to exist (video states "3 ways"); two
+  are captured in full, the Honmoku run covers the approach only.
+- **Exit ramp geometry.** All captured footage is *entry*. Exits not yet
+  sampled.
+- **Stall grid angle.** Aerial shows a diagonal ~40–45° grid; exact bearing
+  not yet fitted.
+
+---
+
+## 7. Reproduce
+
+```bash
+python3 /tmp/osm_daikoku.py            # OSM geometry + circle fits
+python3 /tmp/route.py <videoid> <name> <step_s>   # video -> contact sheets
+python3 /tmp/sat.py                    # Esri aerial tiles
+```