Chatt diorama: real-life accuracy research — registration findings, source-data gaps, upgrade paths

[TortoiseWolfe]

Goal: make the /chatt Chattanooga Mini diorama as accurate to real life as possible. This issue is the durable record of the registration research from the 2026-07-07/08 sessions (what was measured, what flip-flopped and why, what's genuinely unresolved) plus the source-data accuracy gaps and their upgrade paths. It exists so future work starts from evidence, not from re-derivation. Companion issues: #225 (visible symptom: buildings render over the Tennessee River), #226 (ground-game mode — benefits directly from a more accurate model).

1 · What rigorously registers (measured, not eyeballed)

The three data layers are NAIP aerial drape (ArcGIS exportImage), USGS terrain (OpenTopoData ned10m), and OSM vectors (Overpass: buildings/highways/water). Cross-registration measurements:

OSM ↔ drape — registers to ~5 m where tested. The Walnut Street Bridge (OSM way 164158074, an unambiguous linear feature in both sources) projected through the pipeline's ENU→UV mapping lands ON the aerial bridge: mean E-W offset −2.8 px (~5 m), median 0 px, 83% of samples within 10 px:

(magenta = OSM bridge line; yellow = OSM aquarium footprint — note it traces the real bridge)

OSM streets trace the aerial roads corridor-wide (north half / south half):

Box-corner projection is exact: the four bbox corners (swLat 35.0078, swLon −85.316, neLat 35.06, neLon −85.3) map to drape pixel corners (0,0)/(728,0)/(0,2377)/(728,2377) precisely.

ArcGIS honors the requested bbox (verified via f=json): returned extent ymin=35.0078, ymax=35.06 exactly — the #223 degree-aspect fix works; the ±616 m N-S over-scan that caused the original float is gone.

Buildings ↔ OSM is exact by construction (buildings.json ring centroids equal OSM→ENU centroids, delta 0.0 m — same projection code path).

2 · What was historically wrong, and what is still unverified

• Historically real: pre-fix(chatt): register the aerial drape N-S so buildings stop floating over the river #223, ArcGIS silently expanded the drape's latitude extent by ~616 m per end (metre-aspect pixels vs degree bbox), shifting every N-S feature — the original buildings-in-river cause. Fixed in 0ef7fb9.
• Still unverified: the terrain (elevation) layer has never been rigorously cross-registered against drape/OSM the way the bridge test did for OSM↔drape. Its low-elevation band visually traces the river in 2D overlays, but a quantitative registration bound (like the bridge's ~5 m) does not exist for terrain↔anything. This is the remaining registration unknown.
• Temporal desync is unexamined: NAIP is flown every 2–3 years; OSM is edited continuously. Buildings can exist in one source and not the other, and no capture-date check exists anywhere in the bake.

3 · Failed-hypothesis log (the methodology record)

Every one of these was confidently asserted during the sessions and then overturned. Recorded so nobody re-walks the loop:

#	Hypothesis	Why it seemed true	How it died
1	"Drape is 1016 m too short N-S"	pixel-count × mpp ≠ groundHm	Runtime stretches the image by UV across groundHm; pixel count is irrelevant
2	"Layers are aligned; floaters are just dark-water lighting"	tidy Miniature overhead + 2D footprint overlay	2D/overhead proofs flatten the 3D problem — the user rejected it, correctly
3	"Terrain water bleeds ~300 m south of the aerial waterline"	single-column brightness scan + one bad landmark lat/lon	The full-mask overlay showed terrain water tracing the river well; the "landmark" was a mis-eyeballed building
4	"OSM markers land 150–240 m south of the real buildings"	eyeballed zoomed crops (aquarium/courthouse/Republic Centre)	The bridge-line measurement (~5 m) proved OSM↔drape registration; the eyeballed buildings were misidentified
5	"Floaters are the clipped North Shore seen edge-on"	terrain profile shows a ~60 m land sliver at the box's north edge	True observation, but still a single-symptom explanation — doesn't address whole-model accuracy
6	"Streets drift off roads in the south half"	downscaled overview image	Zoomed inspection + measurement: streets sit on roads in the south too

Standing methodology rules (earned the hard way): a 2D overlay never proves 3D registration; brightness/green water classifiers conflate tree-shadow with water in this NAIP tile (a low-local-variance term fixes that); eyeballed landmark identification is not measurement; a nearest-feature metric in a dense city always finds something within the window (biased toward 0); verify against service-returned ground truth (ArcGIS f=json extents) and unambiguous shared features (bridges), not the code's own assumptions.

4 · Accuracy gaps vs real life (independent of registration)

Gap	Current state	Real-life error	Better source / fix
Geodesy constants	enu.ts M_PER_DEG_LAT = 110574 — the equator value	0.33% N-S scale compression ≈ 19 m over the 5.77 km corridor (true at 35°N ≈ 110 941); M_PER_DEG_LON ~0.11% off similarly	Latitude-correct series constants, or proper UTM 16N projection
Building heights	86% fallback (1298/1510 buildings have no OSM height/levels; ruleHistogram)	Most of downtown is a guessed-height box	Microsoft Global ML Building Footprints (height attribute), city LIDAR-derived heights, or per-zone stochastic heights tuned to Chattanooga stock
Terrain resolution	OpenTopoData ned10m sampled at ~30 m (49×195)	Riverbank position quantized to ~30 m; bank slope smeared	USGS 3DEP 1 m lidar DEM (covers Hamilton County) via the same National Map services
Aerial resolution	NAIP fetched at 2 m/px	3× resolution discarded (NAIP native ~0.6 m)	Fetch at native res; mind texture-size limits (tile the drape if needed)
Water	No water geometry in OSM extract for the main channel (verified: is_in on mid-river returns nothing)	River = dark pixels on a flat mesh	Aerial-waterline carve (WIP on fix/chatt-camera-buried-tour) or NHD (National Hydrography Dataset) polygons
Temporal consistency	No capture dates recorded	OSM-vs-NAIP building mismatches possible	Record NAIP acquisition date + OSM timestamp in the manifest; flag disagreements

5 · External references feeding this work

• Modelur article (colleague's pointer): https://modelur.com/openstreetmap-sketchup-plugins/ — production OSM→3D tools (Skp2osm, Cadmapper, PlaceMaker, ModelurOSM). All emphasize georeferenced terrain placement. Cadmapper offers free geolocated 3D city extracts ≤1 km² (buildings + topography + roads) — the cheapest independent reference dataset to validate our building/terrain placement against ("stolen answer key" style: check our pipeline where a trusted answer exists).
• Bilawal Sidhu, "The Internet's Hidden 3D Model" (May 2026, https://youtu.be/KWXuxfdZhwk) — 17-year arc of photo-based 3D reconstruction (SfM → MegaDepth → NeRF → 3DGS → VGGT/π³ → MegaDepth-X). Cleaned, timestamp-anchored transcript lives at ~/repos/TranScripts/Spatial/Spatial_Edited/ (locally symlinked as knowledge/spatial, gitignored). Transferable ideas: ground-truth-first validation (MegaDepth-X's "stolen answer key" = train/verify against known-good reconstructions); multi-source fusion (SRI's diffusion-guided splatting fuses ground + drone + satellite — ours is NAIP + 3DEP + OSM); the long-tail problem is exactly our 86%-fallback heights (well-mapped landmarks have data; everywhere else doesn't); and a future path where a 3D Gaussian Splat capture of downtown Chattanooga replaces extruded boxes entirely for photoreal fidelity.

6 · Upgrade path (to be extended by the accuracy code review)

Ranked by realism-impact per effort — an accuracy-focused review of scripts/bake/* + src/world/* follows as a comment on this issue:

1. Fix the geodesy constants (one-line, removes a systematic 0.33% scale error).
2. 1 m 3DEP terrain (same fetch pattern, different dataset — sharpens the riverbank that caused Chatt diorama: buildings render ON the river — layers are NOT aligned (verification methodology also broken) #225's symptom).
3. Building heights from a source with real coverage (kills the 86% fallback).
4. Native-resolution NAIP drape.
5. Cadmapper 1 km² cross-validation of downtown placement.
6. Record source dates; detect temporal mismatches.
7. (Research horizon) 3DGS capture for photoreal replacement of the extruded-box aesthetic.

WIP note: the symptom-fix work (aerial-waterline carve scripts/bake/carve-water.ts, lit Water.tsx, 49×195 terrain, OSM water in the Overpass query) sits uncommitted on fix/chatt-camera-buried-tour. Items 1–2 above may supersede parts of it; reconcile before merging.

🤖 Generated with Claude Code

---

7 · The business model (2026-07-08 — this is now the program's north star)

Freemium: a client enters any address in any city → the pipeline generates a super-accurate digital twin of that address's surroundings (this bake, made repeatable — see the parameterization ticket). Premium: if they like it, upsell to onsite LiDAR scanning for as-is/as-built construction documentation, surfaced as a dedicated high-resolution property page linked from a button on their parcel in the twin.

Downtown Chattanooga is the flagship demo — every fidelity improvement in this issue's upgrade path (§6) exists to make the flagship sell the concept: geodesy correctness, 1 m 3DEP lidar terrain, real building heights, native-res imagery, NHD water, temporal metadata, Cadmapper/modelur-tool cross-validation, and the Bilawal-derived practices (ground-truth-first validation, multi-source fusion, 3DGS photoreal horizon — transcript at knowledge/spatial).

Repeatability is a hard requirement, not a nice-to-have: everything Chattanooga-specific in the bake (box.ts corridor, HERO_WAY_IDS, HEIGHT_OVERRIDES, tour waypoints) is tech debt against the address-in → twin-out flow. Program tickets:

• Parameterize the bake: address → box → twin (geocode → derive box → bake → verify; per-site config) — the freemium engine.
• Repeatable footprint-verification report — every bake, every city: whole-box footprint-on-aerial overlays + registration statistics with hard thresholds ("check the footprints of all the buildings", systematically).
• LiDAR premium demo (mini-twin first) — the real client parcel at 2630 E Main St (Polycam scan in ada-stair-generator/data/polycam/, ~13.8k-vert mesh, meters/Y-up, +USGS 1 m terrain + parcel GIS) gets its OWN mini-twin via the parameterized pipeline (~3 km east of the flagship box), DAE→GLB conversion, and a "client house" button in the flagship → dedicated as-built page. Privacy-gated — real client address/as-built never ships publicly without consent.

Backlog: flagship box extension — after the mini-twin proves the flow, extend the box north (resolves #225's clipped North Shore) and east (physically includes the client parcel) in one re-bake (~3× E-W cost; re-verify with the footprint report).

[TortoiseWolfe]

Accuracy code review — findings + what was fixed (commit 1757d2f)

Reviewed scripts/bake/* + src/world/* + src/lib/manifest.ts with one question: how accurate to real life is this model, and what would most improve it? Ranked by realism impact. ✅ = fixed in 1757d2f on fix/chatt-camera-buried-tour; 📋 = documented upgrade path.

#	Finding	Impact	Status
1	Geodesy constants were equator/spherical values — M_PER_DEG_LAT=110574 (equator) vs ~110 941 true at 35°N → 0.33% N-S compression (~19 m/corridor); lon similarly ~0.11% off	Systematic scale error on every feature	✅ WGS-84 series at box latitude; drape 729×2378→730×2382; all layers re-baked
2	Buildings seated at centroid elevation — on a 55 m-relief corridor, downhill corners hung in the air (a real contributor to "floating buildings")	Eye-level realism, directly feeds the #225 symptom	✅ Seat at MIN terrain under footprint (ring verts + centroid)
3	No water awareness anywhere — Overpass never fetched water; the river was dark pixels on a flat mesh (black void at grazing angles)	The single most visible artifact	✅ Water in the Overpass query + pixel-res aerial-waterline carve (low-local-variance classifier — immune to the shadow==water trap) + self-lit Water.tsx plane
4	Terrain 25×60 (~98 m N-S cells) smeared the riverbank across a cell	Bank position quantized ~100 m	✅ 49×195 (~30 m); 📋 next step: USGS 3DEP 1 m lidar via elevation.nationalmap.gov/arcgis/rest/services/3DEPElevation/ImageServer/exportImage (same fetch pattern as the NAIP drape; needs float-TIFF decode)
5	HEIGHT_OVERRIDES 100% dead — 7/9 names match nothing in OSM ("First Horizon Bank Building" vs real "First Tennessee Bank Building", etc.). Good news: the marquee towers carry explicit OSM height tags, so rules 1-2 render them correctly anyway	Skyline was saved by OSM data, not by the code	✅ Names corrected to real OSM names (safety net now functional)
6	86% of buildings (1298/1510) use fallback heights — the mass of ordinary buildings is guessed via level-priors + area bonus	The long-tail problem (cf. Bilawal transcript): landmarks have data, everywhere else doesn't	📋 Microsoft Global ML Building Footprints (height attribute, ODbL-compatible) join by footprint overlap; or Chattanooga LIDAR-derived heights
7	NAIP fetched at 2 m/px vs ~0.6 m native	3× ground detail discarded	📋 mpp=1 → 1460×5791 (needs 8192 texture support — fine desktop, risky mobile); mpp=0.6 needs drape tiling
8	No temporal-consistency checks — NAIP vintage vs OSM currency never recorded/compared	Buildings can exist in one source, not the other	📋 Record NAIP acquisition date (ImageServer identify) + OSM out meta timestamps in the manifest; flag disagreements
9	North Shore clipped to a ~60 m sliver at the box's north edge (neLat 35.06) — its buildings (e.g. Riviera Villa Apartments) measure ON land, 5-7 m above water, but read as floating at the Walnut tour waypoint because their land is invisible edge-on	The remaining visible "floater"	📋 Design decision: extend neLat (~35.062-35.065) for real North Shore depth + re-bake, and/or reframe the tour waypoint
10	Vertex-mean centroid (not area centroid) used for seating/heroes; fine for regular footprints, meters off on concave ones	Minor	📋 Shoelace centroid if it ever matters
11	Plate-carrée rows vs metre-linear V mapping — checked: variation of m/deg over 0.052° is negligible (<0.05 m)	None	✔ verified non-issue

Verification: all 36 bake/world tests updated+green; full unit suite 3639/3639 green; re-baked (groundWm 1460, groundHm 5791.1, drape 730×2382); live render re-captured — river reads as water along the real waterline, bank is sharp, buildings stop at the shore in Miniature; the item-9 North Shore artifact remains (by design, pending the box decision).

Category	Found	Fixed	Remaining
Geodesy / registration	3	2	1 (1 m lidar terrain)
Source-data fidelity	4	1	3 (heights, NAIP res, temporal)
Rendering realism	3	3	0
Scene extent / framing	1	0	1 (North Shore box decision)

🤖 Generated with Claude Code

[TortoiseWolfe]

Program tickets filed (§7):

• Digital twin: parameterize the bake — address → box → twin (repeatable, any city) #232 — parameterize the bake: address → box → twin (the freemium engine)
• Digital twin: repeatable footprint-verification report — every building, every bake, hard thresholds #233 — repeatable footprint-verification report (every building, every bake, hard thresholds; honest successor to closed PR test(chatt): automated guard — no buildings float over the river #224)
• Digital twin: LiDAR premium demo — 2630 E Main mini-twin + client-house button + as-built page (privacy-gated) #234 — LiDAR premium demo: 2630 E Main mini-twin + client-house button + as-built page (privacy-gated; blocked by Digital twin: parameterize the bake — address → box → twin (repeatable, any city) #232)

Shipping PR: #231. Backlog (this issue): flagship box extension north+east (resolves #225's North Shore + physically includes the parcel).