Skip to main content

Wave 3b — LOD ladder vs camera envelope architectural decision

Status​

Accepted and implemented. The user selected Option A: extend the physical LOD ladder with deeper z6 and z7 levels. MZ implements that decision as an eight-rung physical residency ladder plus generated close-detail truth. The decision remains explicit so later waves do not reopen camera-floor or target-relaxation alternatives.

Wave 3a (the tractable implementation track) completed: telemetry was split by role and metric so the gap is visible, per-scenario gates were calibrated to the post-Wave-2 measured ladder, the scale-ruler probe was redesigned, and the docs were corrected. Wave 3a did not raise either SSE target, raise the camera floor, extend the ladder, or otherwise paper over the architectural gap. MZ then extended the physical ladder and tightened close scenarios back to the documented 6 px raster/detail SSE target.

The problem​

Wave 2 of the LOD/Data-Coherence Foundation work redesigned the resolver (protect-set, ancestor walk, strict sidecar binding, etc.). With Wave 2 in place, the explorer measured the canonical scenario suite against the two documented SSE targets:

  • TERRAIN_GEOMETRIC_ERROR_TARGET_PX = 1.5 (height-displacement error)
  • TERRAIN_RASTER_SAMPLE_ERROR_TARGET_PX = 6.0 (raster sidecar sample footprint)

The geometric target is satisfied across the entire supported camera envelope. The raster-sample target was not satisfied by the six-rung ladder: the deepest LOD was z=5, and at altitudes below approximately 226 km the projected raster-sample footprint of a z=5 tile exceeded 6 px on screen. MZ repairs that gap by adding z6/z7 and by adding a generated closeDetailNormal sidecar with closeDetailScale = 8; smaller windows alone were not accepted as close-detail truth.

The Wave 3a explorer's measurement of close-zoom oblique scenarios at 55 km clearance recorded primaryRasterSsePxMax ≈ 30 px (primary-only, role-and-metric split) — five times the documented target.

Options considered​

Option A — Extend the ladder (accepted)​

Add z=6 (and possibly z=7) to the generator's tilePyramid. Each additional level halves the raster-sample footprint per side, so:

  • z=5 at 55 km clearance → ~30 px raster SSE
  • z=6 at 55 km clearance → ~15 px raster SSE (still above target)
  • z=7 at 55 km clearance → ~7.5 px raster SSE (right at target)

To satisfy the 6 px target at the 60 km envelope minimum, the generator needs both additional physical zoom levels and a finer generated detail product.

Decision. Implement z6/z7 physical LOD products rather than raising the camera floor or relaxing the raster SSE target. Keep physical tile residency separate from strategic semantic zoom; z6/z7 are artifact/streaming levels, not a substitute for map-mode or content-visibility policy. MZ adds generated semanticDisplayPolicy for the latter.

Cost. Generator changes:

  • new mesh assets and sidecar sets per added level (~4× tile count per level)
  • storage: z=6 is roughly 4× z=5; z=7 is ~16× z=5
  • decode + upload cost during interactive sessions
  • artifact validation, schema versioning, manifest emission
  • closeDetailNormal increases raster sidecar count and must be considered in cache/readiness budgets.

Benefit. Honours the documented 6 px target across the entire supported camera envelope. No camera-cap behaviour change. No scenario calibration above the target.

Option B — Raise the camera floor (rejected)​

Move OrbitControls.minDistance from the current ~60 km value to ~226 km so the camera never reaches the band where the existing z=5 ladder fails the raster target.

Cost. UX impact:

  • the location-zoom camera band loses its existing reach
  • close-zoom oblique scenarios (mapv10_location_geography_*_oblique_z5, mapv10_location_political_topdown, mapv10_location_routes_oblique_z5) become impossible at their current camera positions
  • the scale-ruler location case (60 km clearance) requires either a different camera or removal
  • baseline scenario set gets rebuilt; downstream evidence (R-19, R-22, R-23, R-24, R-25 baselines) gets invalidated

Benefit. Honours the documented 6 px target without generator changes. No new artifacts. Existing ladder unchanged.

Option C — Accept the violation explicitly (rejected)​

Keep both targets at their current values, keep the camera envelope as-is, and document that the close-zoom camera band operates above the 6 px raster target by design. Wave 3a is the partial implementation of this option: the calibrated primaryRasterSsePx ≤ 20–30 px gates on close-zoom scenarios.

Cost. Documentation cost only; the visual quality is the existing visual quality. Future readers must check docs/wave-3b-lod-ladder-camera-decision.md to learn that the target is intentionally violated at this camera band.

Benefit. No generator work. No UX regression. No baseline invalidation. The visible material crawl at close zoom is the existing material crawl, which the canonical scenario suite has been running with since the ladder shipped.

Data captured before the decision​

The Wave 3a explorer collected:

  • post-Wave-2 measured primaryRasterSsePxMax at every existing scenario's final camera pose
  • altitude-vs-raster-SSE curve for z=5 (the deepest current LOD)
  • altitude below which z=5 fails the 6 px target (~226 km clearance for the continent-lod6 fixture's tile sizing)

What the explorer did NOT collect:

  • generator cost to add z=6 and z=7 (storage size, decode cost, upload bytes)
  • visual quality delta between the current 30 px raster SSE and a hypothetical 6 px raster SSE at the same camera pose (i.e. is the difference visually obvious in a real-browser screenshot, or is the 6 px target itself conservatively chosen?)
  • UX impact of moving the camera floor from 60 km to 226 km. This became less important once the user chose the deeper-ladder route.

Later implementation waves still need real generator/viewer cost evidence for z6/z7 before accepting the implementation: storage growth, decode/upload cost, streaming behaviour, scenario runtime, and fresh browser screenshots. PROC does not produce that evidence.

Constraints on the decision​

The decision must respect:

  • the no-fallback doctrine. Whichever option is chosen, the resolver's protect-set + ancestor walk + sidecar contract from Wave 2 stays intact. Options A and B reduce the camera bands that exercise close-zoom fallback; Option C documents that those bands operate above target but does not weaken the resolver.
  • the AAA targets in .claude/rules/orchestrator-mode.md and CLAUDE.md. "Never tune parameters as a substitute for architecture" rules out raising either target.
  • the dev environment. The continent-lod6 fixture and the canonical scenario suite are the reference, not synthetic micro-benchmarks.

MZ implementation notes​

  • z0 is now a real coarse continent rung (sample_step = 32) and z1 is the macro-region refinement (sample_step = 16), so z0/z1 are no longer same-sample physical refinements.
  • z6 (close-detail) and z7 (settlement-detail) use sample_step = 1 plus closeDetailScale = 8 metadata and generated closeDetailNormal assets.
  • The viewer computes raster/detail SSE from generated rasterSampleSpacingKm; it does not claim close correctness from tile count alone.
  • Close scenarios now gate semanticPolicyLoaded, semanticBandEquals: close, primaryZAtLeast: 6, closeDetailScaleMin: 8, and primaryRasterSsePx <= 6.
  • Visual baselines are not refreshed by this decision. They may be refreshed only after the new foundation behavior is accepted.

Out of scope for Wave 3b​

  • The two SSE targets themselves remain locked. Wave 3b decides how to satisfy them across the supported camera envelope, not whether to keep them.
  • The role-and-metric telemetry split landed in Wave 3a and is not revisited here.
  • The scale-ruler probe redesign landed in Wave 3a and is not revisited here.