GeoMap: continuous drape terrain design - one heightfield, patches as views, no holes or cliffs ever

[DonLakeFlyer]

Problem

The GeoMap 3D terrain surface can currently show holes and cliffs that appear and later fill in: flat-zero patches rendered beside real-height neighbors (cliff at the shared edge), pending patches suppressed or covered by retiring predecessors (holes when that hiding has a gap), and failed fetches degrading to flat ground next to lifted terrain. This is wrong as a product experience — partial data should never look broken.

The root cause is architectural: heights are per-patch independent facts. Each patch renders whatever it personally received (or flat zero), and continuity between neighbors is nobody's responsibility. The covered/retiring/degraded machinery exists to hide the discontinuities that model inevitably produces, and every gap in the hiding is visible as a cliff or hole.

Design principle

The map is always a continuous drape, regardless of what data is or isn't available.

• The surface starts fully draped at zero height.
• As terrain data becomes available, the carpet lifts up in that region.
• Where data is missing (not yet fetched, fetch failed, coarser LOD), the surface renders the best available estimate, and edges always match the surrounding heights — never a cliff, never a hole.

Architecture: one heightfield, patches are views

Invert the data model: there is one continuous heightfield; patch meshes are views into it, never owners of private height data.

HeightField (new)

• Owns the current best estimate of terrain height everywhere: real data where delivered, ancestor-interpolated estimates where only coarser data exists, zero where nothing is known.
• Continuous by construction — there is no "missing" region, only coarser-estimate regions.
• Backed by the slippy elevation pyramid (GeoMap: client-side slippy elevation tile pyramid - zoom-level terrain queries with derived-tile cache #14820): pyramid tiles are the storage, ancestor seeding is the estimate mechanism. These are one system — the pyramid is the data layer, the field is its rendering contract.

Patch meshing

• Patches sample the field at their vertex world positions. Two patches sharing an edge sample identical positions → identical heights → edges match structurally, not via suppression logic.
• Cross-LOD edges use the standard stitching rule: fine-edge vertices adjacent to a coarser neighbor are constrained to the coarse edge's interpolation (eliminates T-junction cracks).

Data arrival

• A delivery updates a region of the field → affected patches (plus edge-adjacent neighbors) re-sample and re-mesh.
• The field eases toward new data (~300 ms) so the carpet visibly lifts; because the animation lives in the field, adjacent patches lift coherently — no transient edge mismatch.

Failure handling

• "Degraded" ceases to exist as a state: a failed fetch simply means the region keeps its current estimate (ancestor data or zero). A later retry improves it. No flat-zero cliff is possible.

What this eliminates

• The covered/z-fight suppression for pending patches (they render the field estimate, which matches any cover)
• Most retiring-cover height semantics (imagery fallback remains a separate, existing mechanism)
• The degraded-patch special case and its retry-ladder visual consequences
• The entire bug class "hole/cliff that fills in later"

Replaced by one invariant, testable in one line: adjacent rendered edge vertices are always equal.

Relationship to existing work

• GeoMap: client-side slippy elevation tile pyramid - zoom-level terrain queries with derived-tile cache #14820 (slippy elevation pyramid) is the natural backing store; its ancestor-seeding follow-on is this field's estimate mechanism. Suggest GeoMap: client-side slippy elevation tile pyramid - zoom-level terrain queries with derived-tile cache #14820 be implemented in service of this design.
• TerrainTileManager: serial single-flight elevation fetching + shared cache queue starvation makes terrain data extremely slow to load #14819 (terrain fetch pipeline) is orthogonal: it makes estimates improve faster, this design makes waiting look correct.
• The blend band in TerrainHeightSource (kMinTerrainZoom..kFullTerrainZoom height scaling) was a stopgap for the same continuity problem and can likely be retired once estimates are continuous.
• GeoMap: refinement backlog from MapLibre Native architecture comparison #14822 item 2 (tile fade-in) is subsumed for heights by the field's easing; imagery fade remains separate.

Suggested phases

1. Design doc: field data structure (pyramid-tile sampling + interpolation rules), cross-LOD edge stitching rule, dirty-region → re-mesh flow, easing model, migration path from the current per-patch delivery.
2. Field + re-sampling: introduce HeightField over the existing height sources; patches sample it; delete covered/degraded height logic. Invariant test: edge-vertex equality across all resident patch pairs, under churn and failure injection.
3. Easing: temporal blend on field updates ("carpet lift").
4. Pyramid integration (GeoMap: client-side slippy elevation tile pyramid - zoom-level terrain queries with derived-tile cache #14820): persistent estimates across sessions.

Acceptance criteria

• From cold start over any terrain, the surface is never anything but a continuous sheet: starts flat, lifts as data arrives.
• Kill the network mid-load: surface remains continuous (partially lifted), no cliffs at data boundaries.
• LOD churn (zoom in/out, high-tilt orbit) never opens a hole or crack.
• Automated: edge-vertex equality invariant holds in unit tests under slow-heights churn and injected fetch failures.

[DonLakeFlyer]

Update: #14820 is closed as superseded by #14842 (Terrarium elevation tile source), which changes this design's data-layer story for the better:

• The backing store now exists as real data: terrarium is a native z0–15 slippy pyramid in the shared tile cache DB. The HeightField's "best available estimate" lookup becomes cache reads walking up the ancestor chain — no derived-tile generation, versioning, or invalidation layer to build.
• Ancestor estimation is already implemented: TerrariumHeightSource's deep-zoom path (ancestor fetch + sub-window bilinear sampling) is exactly the field's estimate mechanism; it just needs to serve cache-resident ancestors at any zoom (deliver immediately, refine when the finer tile lands) instead of only above z15.
• The blend band is already retired — deleted in feat(GeoMap): source terrain heights from AWS terrarium elevation tiles #14842.
• Uniform patch cost: one tile per patch at every zoom makes re-sample/re-mesh on data arrival cheap; no 16-base-tile assembly making coarse regions the expensive case.
• Persistence for free: write-back caching means the field starts each session already lifted wherever previously flown.

One addition this design should absorb: terrarium tiles do not share edge pixels, so per-tile sampling has a ~half-pixel edge clamp that can leave hairline cracks (documented in #14842). The field's "sample at world positions" model is the right place to fix it — sample across tile boundaries using the neighbor tile's edge row — so the crack caveat disappears as a side effect.

The rendering-side work (patches as views, re-meshing, T-junction stitching, easing) is unchanged.