nordisk/facett

CDLOD terrain quadtree — design

The chosen design for FLIGHT-SIM roadmap §6 (continuous-distance terrain LOD): a pure-CPU CDLOD (Filip Strugar's Continuous Distance-dependent Level Of Detail) quadtree that selects which terrain patches to draw at which resolution given the camera, draped on the already-landed real terrain (terrain.rs) by reusing build_terrain_mesh — never forking it. The GPU vertex height-morph is proven equal to the CPU oracle behind the wgpu feature; the landed 21-pass facett-map3d pipeline is untouched (L2 additive, no regression).

Why CDLOD (and not a fixed grid / geomipmapping)

A single flat grid over a DEM tile is wrong at both ends: too coarse near the camera (blocky ridgelines) and ruinously heavy far away (millions of sub-pixel triangles). CDLOD keeps the drawn triangle count roughly constant by subdividing a quadtree only where the camera is close, and it fixes the two failure modes a naive LOD hits:

• T-junction cracks — a fine patch meeting a coarser neighbour has edge vertices the coarse edge lacks, opening a one-pixel gap you see sky through. CDLOD guarantees adjacent selected nodes differ by ≤ 1 level, then morphs the fine edge onto the coarse edge as distance grows, closing the seam continuously.
• LOD popping — the morph factor ramps 0 → 1 across the outer third of each node's range, blending a node's geometry toward its parent grid before the hard switch, so the change is imperceptible in flight.

(The rejected alternatives — uniform grid, geomipmapping with skirts, ROAM — and why they lose to CDLOD live in cdlod-terrain-reasoning.md, per the docs doctrine: this design doc names only the chosen path.)

The pieces (src/cdlod.rs)

• CdlodConfig — the selection knobs: max_depth (quadtree depth = LOD-level count), leaf_range_m (the finest level's visibility range), range_ratio (2.0 — each coarser level reaches twice as far), morph_start_ratio (0.66 — where in a range the morph band begins), grid (vertices per side of every node's shared patch mesh).
• Cdlod { region, config } — a quadtree over a fixed GeoRegion, holding no per-node state: select walks the tree geometrically (children are the four lon/lat quadrants), so a frame's selection is a pure function of the camera (FC-7).
• Cdlod::select(camera) -> Vec<SelectedNode> — the CDLOD recursion: draw a node whole at its level unless the finer level's range reaches it, in which case subdivide; children the finer range reaches recurse, the rest are drawn at the parent level (the rule that guarantees the ≤ 1-level neighbour invariant). The selected regions exactly tile the extent (no gaps, no overlaps).
• Cdlod::morph_factor(level, dist) -> f32 — 0 inside range·morph_start_ratio, ramping to 1 at the outer edge range(level), clamped beyond. The root level (no coarser parent) is exempt (0).
• morph_height(h, h_parent, morph) — the per-vertex crack-closing blend the terrain vertex shader runs: h → h_parent by the node's morph. This is the oracle the GPU pass is validated against.
• Cdlod::build_meshes(camera, elev, origin, vexag) — the drape: one TerrainMesh per selected node via build_terrain_mesh over that node's region, so a near (small) node samples finer topography and a far (large) node is coarser — the LOD falls out of the patch size, at a constant per-node grid.

Distance metric (the range seam)

Ranges are ground distances in the f64 Web-Mercator WorldPos frame the floating origin + streamer already key on: ground_dist_to_region projects a node's lon/lat corners (Mercator is monotone, so they map to the node's world AABB) and returns the nearest-point distance (0 when the camera is over the node). One metric frame across floating origin (§1), tile streaming (§5), and CDLOD (§6) — L5 reuse, no twin.

The GPU seam (src/cdlod_morph.wgsl, behind wgpu)

cs_morph is a @workgroup_size(64) compute twin of morph_height: it blends an array of (h, h_parent) pairs under one morph factor, and CdlodMorphGpu::morph reads the result back so the vertex shader's crack-closing blend is proven texel-for-texel equal to the CPU oracle (max_abs_error_vs_oracle < 1e-3). This mirrors the scattering-LUT pass exactly. The full render-pass wiring into facett-map3d's pipeline (uploading the node instances + a terrain vertex shader that morphs in-shader) is the next roadmap step, just as the scattering LUT deferred its sky.wgsl sampling — so nothing in the landed pipeline changes here.

Testability without a GPU (session constraint)

Every correctness property is a RED-when-broken, GPU-less assertion in src/cdlod.rs: subdivision-follows-distance, watertight tiling, the ≤ 1-level neighbour invariant, the morph-factor ramp endpoints + monotonicity, the morph-height blend, the bounded triangle budget, deterministic selection, and the drape. The GPU parity test self-skips with a recorded sentinel when no adapter is present, so a laptop tester with no GPU still runs the whole selection-math proof green.