@tangram.gl/tangram-renderer 0.0.0-stage → 0.0.0

package/src/map-logic/terrain-error.ts

@@ -0,0 +1,134 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TerrainHeightGrid} from './terrain-data';
+
+/** Immutable DEM-derived envelope; it says nothing about unloaded finer source detail. */
+export interface TerrainErrorEnvelope {
+    /** Lowest and highest valid physical source elevations. */
+    readonly minimumHeight: number;
+    readonly maximumHeight: number;
+    /** Conservative directional bilinear gradient bounds per Mercator meter. */
+    readonly eastSlope: number;
+    readonly northSlope: number;
+    /** Mercator footprint width and height. */
+    readonly width: number;
+    readonly height: number;
+    /** Invalid samples prevent certification of the complete footprint. */
+    readonly complete: boolean;
+}
+
+/** Cache by immutable grid identity; camera movement must not rescan decoded samples. */
+const envelopes = new WeakMap<TerrainHeightGrid, TerrainErrorEnvelope>();
+
+/**
+ * Conservative CSS-pixel Lipschitz bound for a projective transform over an
+ * absolute XYZ box. Null means the box crosses the eye plane: never substitute
+ * a center-only derivative and call it a bounded screen error.
+ */
+export function boundProjectedDisplacement(matrix: readonly number[], minimum: readonly [number, number, number], maximum: readonly [number, number, number],
+    viewport: {width: number; height: number}): number | null {
+    if (matrix.length !== 16 || ![...matrix, ...minimum, ...maximum, viewport.width, viewport.height].every(Number.isFinite) ||
+        minimum.some((value, axis) => value > maximum[axis]) || viewport.width <= 0 || viewport.height <= 0) throw new Error('Invalid terrain projection bound');
+    let minimumW = Infinity, horizontal = 0, vertical = 0;
+    for (let corner = 0; corner < 8; corner++) {
+        const position = minimum.map((value, axis) => corner & 1 << axis ? maximum[axis] : value);
+        const component = (row: number) => matrix[row] * position[0] + matrix[row + 4] * position[1] + matrix[row + 8] * position[2] + matrix[row + 12];
+        minimumW = Math.min(minimumW, component(3));
+        horizontal = Math.max(horizontal, Math.abs(component(0))); vertical = Math.max(vertical, Math.abs(component(1)));
+    }
+    if (minimumW <= 0) return null;
+    const norm = (row: number) => Math.hypot(matrix[row], matrix[row + 4], matrix[row + 8]);
+    const result = Math.hypot(viewport.width / 2 * (norm(0) / minimumW + horizontal / minimumW * norm(3) / minimumW),
+        viewport.height / 2 * (norm(1) / minimumW + vertical / minimumW * norm(3) / minimumW));
+    return Number.isFinite(result) ? result : null;
+}
+
+/** Measure source extrema and adjacent gradients once, retaining no additional sample arrays. */
+export function measureTerrainError(grid: TerrainHeightGrid): TerrainErrorEnvelope {
+    const cached = envelopes.get(grid);
+    if (cached) return cached;
+    const width = grid.bounds[2] - grid.bounds[0], height = grid.bounds[3] - grid.bounds[1];
+    if (!Number.isSafeInteger(grid.width) || !Number.isSafeInteger(grid.height) || grid.width < 2 || grid.height < 2 ||
+        grid.heights.length !== grid.width * grid.height || grid.valid.length !== grid.heights.length || grid.bounds.length !== 4 || !grid.bounds.every(Number.isFinite) ||
+        !Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0 || !['grid-node', 'pixel-center'].includes(grid.registration)) throw new Error('Invalid terrain error grid');
+    const horizontalSpacing = width / (grid.registration === 'pixel-center' ? grid.width : grid.width - 1);
+    const verticalSpacing = height / (grid.registration === 'pixel-center' ? grid.height : grid.height - 1);
+    let minimumHeight = Infinity, maximumHeight = -Infinity, eastSlope = 0, northSlope = 0, complete = true;
+    for (let index = 0; index < grid.heights.length; index++) {
+        if (!grid.valid[index]) {complete = false; continue;}
+        if (!Number.isFinite(grid.heights[index])) throw new Error('Terrain error envelope requires finite valid heights');
+        const value = grid.heights[index];
+        minimumHeight = Math.min(minimumHeight, value); maximumHeight = Math.max(maximumHeight, value);
+        if (index % grid.width && grid.valid[index - 1]) eastSlope = Math.max(eastSlope, Math.abs(value - grid.heights[index - 1]) / horizontalSpacing);
+        if (index >= grid.width && grid.valid[index - grid.width]) northSlope = Math.max(northSlope, Math.abs(value - grid.heights[index - grid.width]) / verticalSpacing);
+    }
+    if (minimumHeight === Infinity) {minimumHeight = 0; maximumHeight = 0;}
+    if (![minimumHeight, maximumHeight, eastSlope, northSlope].every(Number.isFinite)) throw new Error('Terrain error envelope exceeds finite range');
+    const envelope = Object.freeze({minimumHeight, maximumHeight, eastSlope, northSlope, width, height, complete});
+    envelopes.set(grid, envelope); return envelope;
+}
+
+/**
+ * Bound vertical interpolation error by the bilinear field's Lipschitz envelope.
+ * Deliberately conservative on ramps: this is not a fitted/sample-only RMSE.
+ * A separate spherical sagitta covers surface curvature, in globe-radius units.
+ */
+export function boundTerrainMeshError(envelope: TerrainErrorEnvelope, resolution: number): {heightError: number; globeCurvatureError: number} {
+    if (!Number.isSafeInteger(resolution) || resolution < 2 || resolution > 64 || (resolution & (resolution - 1)) ||
+        ![envelope.width, envelope.height, envelope.minimumHeight, envelope.maximumHeight, envelope.eastSlope, envelope.northSlope].every(Number.isFinite) ||
+        envelope.width <= 0 || envelope.height <= 0 || envelope.maximumHeight < envelope.minimumHeight || envelope.eastSlope < 0 || envelope.northSlope < 0) throw new Error('Invalid terrain error policy');
+    const heightError = Math.min(envelope.maximumHeight - envelope.minimumHeight,
+        (envelope.eastSlope * envelope.width + envelope.northSlope * envelope.height) / resolution);
+    // Mercator's inverse derivative bounds angular change by Mercator distance/R.
+    const angularDiameter = Math.min(Math.PI, (envelope.width + envelope.height) / (6378137 * resolution));
+    // Any chord point is within R*(1-cos(diameter)) of the corresponding radial sphere.
+    const globeCurvatureError = 256 * 2 * Math.sin(angularDiameter / 2) ** 2;
+    return {heightError, globeCurvatureError};
+}
+
+/** Select a dyadic resolution with hysteresis from a caller's conservative pixels-per-unit bounds. */
+export function selectTerrainMeshResolution(grids: readonly TerrainHeightGrid[], options: {
+    /** Maximum acceptable interpolation-plus-curvature error, CSS pixels; default 2. */
+    targetPixels?: number;
+    /** Upper bound on projected displacement per physical vertical meter, including exaggeration. */
+    pixelsPerMeter: number;
+    /** Upper bound on projected displacement per radius-256 globe unit; zero for a planar view. */
+    pixelsPerGlobeUnit?: number;
+    /** Prior dyadic resolution supplies a 20% coarsening deadband. */
+    previousResolution?: number;
+}): {resolution: number; projectedError: number; limited: boolean; complete: boolean} {
+    const target = options.targetPixels ?? 2, globeScale = options.pixelsPerGlobeUnit ?? 0;
+    if (![target, options.pixelsPerMeter, globeScale].every(Number.isFinite) || target <= 0 || options.pixelsPerMeter < 0 || globeScale < 0) throw new Error('Invalid projected terrain error scale');
+    const envelopes = grids.map(measureTerrainError);
+    // Canonical terrain averages touching-edge samples. Independent flat tiles
+    // with different heights therefore cannot claim zero reconstruction error.
+    // A range envelope is conservative until tighter edge-conformance metadata
+    // is available; never hide that uncertainty behind a smaller mesh cell.
+    const seamErrors = grids.map((grid, index) => {
+        let error = 0;
+        for (let other = 0; other < grids.length; other++) {
+            if (other === index) continue;
+            const neighbor = grids[other], circumference = 2 * Math.PI * 6378137;
+            const tolerance = Math.max(envelopes[index].width, envelopes[other].width) * 1e-10;
+            if ([-circumference, 0, circumference].some(shift => {
+                const horizontal = Math.min(grid.bounds[2], neighbor.bounds[2] + shift) - Math.max(grid.bounds[0], neighbor.bounds[0] + shift);
+                const vertical = Math.min(grid.bounds[3], neighbor.bounds[3]) - Math.max(grid.bounds[1], neighbor.bounds[1]);
+                return horizontal >= -tolerance && vertical >= -tolerance;
+            })) error = Math.max(error, Math.abs(envelopes[index].maximumHeight - envelopes[other].minimumHeight), Math.abs(envelopes[other].maximumHeight - envelopes[index].minimumHeight));
+        }
+        return error;
+    });
+    const errorAt = (resolution: number, includeSeams = false) => Math.max(0, ...envelopes.map((envelope, index) => {
+        const error = boundTerrainMeshError(envelope, resolution);
+        return Math.max(error.heightError, includeSeams ? seamErrors[index] : 0) * options.pixelsPerMeter + error.globeCurvatureError * globeScale;
+    }));
+    let resolution = options.previousResolution ?? 2;
+    boundTerrainMeshError({minimumHeight: 0, maximumHeight: 0, eastSlope: 0, northSlope: 0, width: 1, height: 1, complete: true}, resolution);
+    while (resolution < 64 && errorAt(resolution) > target) resolution *= 2;
+    while (resolution > 2 && errorAt(resolution / 2) < target * 0.8) resolution /= 2;
+    // More vertices cannot reduce a conservative shared-edge uncertainty bound.
+    const projectedError = errorAt(resolution, true), complete = envelopes.every(envelope => envelope.complete);
+    return {resolution, projectedError, limited: projectedError > target || !complete, complete};
+}

package/src/map-logic/terrain-ground-topology.ts

@@ -0,0 +1,164 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TerrainHeightGrid} from './terrain-data';
+import type {TerrainFieldBounds} from './terrain-height-field';
+
+const CIRCUMFERENCE = 2 * Math.PI * 6378137;
+/** Immutable field identities own one validated periodic patch neighborhood, not generated mesh buffers. */
+const patchPlans = new WeakMap<readonly TerrainHeightGrid[], readonly TerrainFieldBounds[]>();
+
+/** Source-independent triangles; tile ownership is clipped after projection, never by moving boundary nodes. */
+export interface TerrainGroundTopology {
+    /** Absolute unwrapped EPSG:3857 XY, two components per vertex. */
+    positions: Float64Array;
+    /** Exact dyadic world fractions: X from the western world edge, Y southward from the northern edge. */
+    normalizedPositions: Float64Array;
+    /** Exact periodic sampling XY before whole-world translation; may share the positions array in world zero. */
+    samplePositions: Float64Array;
+    /** Counterclockwise top triangles, including conforming coarse/fine edge nodes. */
+    indices: Uint32Array;
+    /** Subtract this whole-world X offset before sampling the periodic DEM neighborhood. */
+    sampleOffset: number;
+}
+
+/** Include every touching neighbor's edge knots on a patch boundary, preserving traversal order. */
+export function getTerrainEdgeNodes(bounds: TerrainFieldBounds, neighbors: readonly TerrainFieldBounds[], resolution: number,
+    start: readonly [number, number], end: readonly [number, number]): [number, number][] {
+    const [west, south, east, north] = bounds;
+    const vertical = start[0] === end[0], axis = vertical ? 1 : 0;
+    if (!(vertical && (start[0] === 0 || start[0] === resolution) || start[1] === end[1] && (start[1] === 0 || start[1] === resolution))) return [];
+    const tolerance = Math.max(east - west, north - south) * 1e-10;
+    const fixed = vertical ? west + start[0] / resolution * (east - west) : north - start[1] / resolution * (north - south);
+    const values = new Set<number>();
+    for (const candidate of neighbors) {
+        if (vertical ? Math.min(Math.abs(fixed - candidate[0]), Math.abs(fixed - candidate[2])) > tolerance : Math.min(Math.abs(fixed - candidate[1]), Math.abs(fixed - candidate[3])) > tolerance) continue;
+        for (let step = 0; step <= resolution; step++) {
+            const value = vertical ? (north - (candidate[3] - step / resolution * (candidate[3] - candidate[1]))) / (north - south) * resolution :
+                (candidate[0] + step / resolution * (candidate[2] - candidate[0]) - west) / (east - west) * resolution;
+            if (value > Math.min(start[axis], end[axis]) + 1e-8 && value < Math.max(start[axis], end[axis]) - 1e-8) values.add(Math.round(value * 1e8) / 1e8);
+        }
+    }
+    return [...values].sort((first, second) => (first - second) * Math.sign(end[axis] - start[axis])).map(value => vertical ? [start[0], value] : [value, start[1]]);
+}
+
+/** Snap a decoded tile footprint to one world lattice; opt-in ground topology requires square quadtree tiles. */
+function snapTileBounds(bounds: TerrainFieldBounds, normalizeToPrimaryWorld = false): TerrainFieldBounds {
+    if (bounds.length !== 4) throw new Error('Canonical terrain ground requires quadtree DEM footprints');
+    const edge = bounds[2] - bounds[0], zoom = Math.round(Math.log2(CIRCUMFERENCE / edge));
+    if (!Number.isSafeInteger(zoom) || zoom < 0 || zoom > 30) throw new Error('Canonical terrain ground requires quadtree DEM footprints');
+    const span = CIRCUMFERENCE / 2 ** zoom;
+    const column = Math.round((bounds[0] + CIRCUMFERENCE / 2) / span), row = Math.round((CIRCUMFERENCE / 2 - bounds[3]) / span);
+    const snapped: TerrainFieldBounds = [column * span - CIRCUMFERENCE / 2, CIRCUMFERENCE / 2 - (row + 1) * span,
+        (column + 1) * span - CIRCUMFERENCE / 2, CIRCUMFERENCE / 2 - row * span];
+    if (row < 0 || row >= 2 ** zoom || bounds.some((value, index) => !Number.isFinite(value) || Math.abs(value - snapped[index]) > Math.max(1e-6, span * 1e-8))) throw new Error('Canonical terrain ground requires quadtree DEM footprints');
+    if (normalizeToPrimaryWorld) {
+        const normalizedColumn = ((column % 2 ** zoom) + 2 ** zoom) % 2 ** zoom;
+        return [normalizedColumn * span - CIRCUMFERENCE / 2, snapped[1], (normalizedColumn + 1) * span - CIRCUMFERENCE / 2, snapped[3]];
+    }
+    return snapped;
+}
+
+/** Retain every neighbor, including those outside a source clip whose knots affect an intersecting cell. */
+function getPatchPlan(grids: readonly TerrainHeightGrid[]): readonly TerrainFieldBounds[] {
+    const cached = patchPlans.get(grids);
+    if (cached) return cached;
+    const patches = grids.flatMap(grid => {
+        const bounds = snapTileBounds(grid.bounds, true);
+        return [-1, 0, 1].map(world => [bounds[0] + world * CIRCUMFERENCE, bounds[1], bounds[2] + world * CIRCUMFERENCE, bounds[3]] as const);
+    });
+    for (let index = 0; index < patches.length; index++) for (let previous = 0; previous < index; previous++) {
+        const patch = patches[index], other = patches[previous], tolerance = Math.max(patch[2] - patch[0], other[2] - other[0]) * 1e-10;
+        const horizontal = Math.min(patch[2], other[2]) - Math.max(patch[0], other[0]);
+        const vertical = Math.min(patch[3], other[3]) - Math.max(patch[1], other[1]);
+        if (horizontal > tolerance && vertical > tolerance) throw new Error('Canonical terrain ground footprints overlap');
+        if (horizontal > tolerance && vertical >= -tolerance || vertical > tolerance && horizontal >= -tolerance) {
+            const ratio = (patch[2] - patch[0]) / (other[2] - other[0]);
+            if (![0.5, 1, 2].some(value => Math.abs(value - ratio) < 1e-8)) throw new Error('Canonical terrain ground requires balanced 2:1 edges');
+        }
+    }
+    patchPlans.set(grids, patches);
+    return patches;
+}
+
+/** Quadtree copies shift to the sampling world; optional generic previous fields retain their absolute domain. */
+export function wrapTerrainGroundGrids(grids: readonly TerrainHeightGrid[], requireQuadtree = true, samplingWorldOffset = 0): TerrainHeightGrid[] {
+    return grids.flatMap(grid => {
+        let bounds: TerrainFieldBounds;
+        try {bounds = snapTileBounds(grid.bounds, true);}
+        catch (error) {if (requireQuadtree) throw error; return [grid];}
+        return [-1, 0, 1].map(world => ({...grid, bounds: [bounds[0] + world * CIRCUMFERENCE + samplingWorldOffset, bounds[1], bounds[2] + world * CIRCUMFERENCE + samplingWorldOffset, bounds[3]] as const}));
+    });
+}
+
+/**
+ * Build complete DEM-owned cells intersecting a source tile. Do not clip triangles
+ * at source/fallback edges: both owners must submit the same curved triangle there.
+ * Fragment/query half-open clips select ownership. Current fields must have balanced
+ * 2:1 quadtree edges; unsupported fields and exhausted budgets reject, never truncate.
+ */
+export function createTerrainGroundTopology(grids: readonly TerrainHeightGrid[], bounds: TerrainFieldBounds,
+    resolution = 32, maxVertices = 131072): TerrainGroundTopology {
+    if (grids.length > 96 || !Number.isSafeInteger(resolution) || resolution < 2 || resolution > 64 || (resolution & (resolution - 1)) !== 0 ||
+        !Number.isSafeInteger(maxVertices) || maxVertices < 0 || bounds.length !== 4 || !bounds.every(Number.isFinite) || bounds[0] >= bounds[2] || bounds[1] >= bounds[3] ||
+        bounds[2] - bounds[0] > CIRCUMFERENCE * (1 + 1e-10)) throw new Error('Invalid canonical terrain ground limits or bounds');
+    const sampleOffset = Math.floor(((bounds[0] + bounds[2]) / 2 + CIRCUMFERENCE / 2) / CIRCUMFERENCE) * CIRCUMFERENCE;
+    const localBounds: TerrainFieldBounds = [bounds[0] - sampleOffset, bounds[1], bounds[2] - sampleOffset, bounds[3]];
+    const patches = getPatchPlan(grids);
+    const positions: number[] = [], normalizedPositions: number[] = [], indices: number[] = [], nodes = new Map<string, number>();
+    /** Reuse lattice nodes across DEM patch boundaries and independent source-tile builds. */
+    function vertex(patch: TerrainFieldBounds, column: number, row: number): number {
+        const zoom = Math.round(Math.log2(CIRCUMFERENCE / (patch[2] - patch[0]))), span = CIRCUMFERENCE / 2 ** zoom;
+        const worldColumn = Math.round((patch[0] + CIRCUMFERENCE / 2) / span), worldRow = Math.round((CIRCUMFERENCE / 2 - patch[3]) / span);
+        const x = span / resolution * (worldColumn * resolution + column) - CIRCUMFERENCE / 2;
+        const y = CIRCUMFERENCE / 2 - span / resolution * (worldRow * resolution + row);
+        const key = `${x},${y}`;
+        let index = nodes.get(key);
+        if (index === undefined) {
+            if (nodes.size >= maxVertices) throw new Error('Canonical terrain ground vertex budget exceeded');
+            index = nodes.size; nodes.set(key, index); positions.push(x, y);
+            normalizedPositions.push((worldColumn + column / resolution) / 2 ** zoom + Math.round(sampleOffset / CIRCUMFERENCE),
+                (worldRow + row / resolution) / 2 ** zoom);
+        }
+        return index;
+    }
+    /** Preserve the same DEM triangles on both sides of a source ownership boundary. */
+    function triangle(patch: TerrainFieldBounds, corners: readonly [number, number][]): void {
+        const ring: number[] = [];
+        for (let edge = 0; edge < 3; edge++) {
+            const start = corners[edge], end = corners[(edge + 1) % 3];
+            ring.push(vertex(patch, ...start), ...getTerrainEdgeNodes(patch, patches, resolution, start, end).map(point => vertex(patch, ...point)));
+        }
+        if (ring.length === 3) indices.push(...ring);
+        else {
+            // Dyadic interior weights keep local positions exactly representable
+            // across independent source zooms; one-third centroids do not.
+            const center = vertex(patch, corners[0][0] / 2 + corners[1][0] / 4 + corners[2][0] / 4,
+                corners[0][1] / 2 + corners[1][1] / 4 + corners[2][1] / 4);
+            for (let edge = 0; edge < ring.length; edge++) indices.push(center, ring[edge], ring[(edge + 1) % ring.length]);
+        }
+    }
+    for (const patch of patches) {
+        const west = Math.max(localBounds[0], patch[0]), east = Math.min(localBounds[2], patch[2]);
+        const south = Math.max(localBounds[1], patch[1]), north = Math.min(localBounds[3], patch[3]);
+        if (west >= east || south >= north) continue;
+        const cellSpan = (patch[2] - patch[0]) / resolution;
+        // Whole-world translation can shift an exact ownership edge by a few
+        // double ulps. Snap only within representational error, not a fixed
+        // fraction that could erase tiny high-zoom ownership windows.
+        const tolerance = Math.max(CIRCUMFERENCE, ...patch.map(Math.abs)) / cellSpan * Number.EPSILON * 4;
+        const cell = (value: number) => Math.abs(value - Math.round(value)) <= tolerance ? Math.round(value) : value;
+        const firstColumn = Math.max(0, Math.floor(cell((west - patch[0]) / (patch[2] - patch[0]) * resolution)));
+        const lastColumn = Math.min(resolution, Math.ceil(cell((east - patch[0]) / (patch[2] - patch[0]) * resolution)));
+        const firstRow = Math.max(0, Math.floor(cell((patch[3] - north) / (patch[3] - patch[1]) * resolution)));
+        const lastRow = Math.min(resolution, Math.ceil(cell((patch[3] - south) / (patch[3] - patch[1]) * resolution)));
+        for (let row = firstRow; row < lastRow; row++) for (let column = firstColumn; column < lastColumn; column++) {
+            triangle(patch, [[column, row], [column, row + 1], [column + 1, row]]);
+            triangle(patch, [[column + 1, row], [column, row + 1], [column + 1, row + 1]]);
+        }
+    }
+    const samplePositions = Float64Array.from(positions);
+    return {positions: sampleOffset ? Float64Array.from(samplePositions, (value, index) => index % 2 ? value : value + sampleOffset) : samplePositions,
+        samplePositions, normalizedPositions: Float64Array.from(normalizedPositions), indices: Uint32Array.from(indices), sampleOffset};
+}

package/src/map-logic/terrain-height-field.ts

@@ -0,0 +1,254 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {sampleTerrainHeight, type TerrainHeightGrid} from './terrain-data';
+
+/** Absolute EPSG:3857 [west, south, east, north], including zero-width probe bounds. */
+export type TerrainFieldBounds = readonly [number, number, number, number];
+
+/** Retained mask admission; geometry, source arrays and JavaScript metadata are separate. */
+export interface TerrainHeightFieldOptions {
+    /** Maximum retained summed-area mask bytes; default 8 MiB. Zero uses exact sample scans. */
+    maxMaskBytes?: number;
+}
+
+/** Detached operation counts, suitable for deterministic performance tests rather than FPS estimates. */
+export interface TerrainHeightFieldStatistics {
+    /** Number of retained immutable source references. */
+    grids: number;
+    /** Retained summed-area mask bytes, excluding source arrays and tree metadata. */
+    maskBytes: number;
+    /** Admitted mask constructions, each built at most once per grid. */
+    maskBuilds: number;
+    /** Validity samples read during mask construction or exact fallback scans. */
+    maskSamples: number;
+    /** Spatial tree envelopes tested by sampling and coverage queries. */
+    boundsTests: number;
+    /** Candidate grid footprints visited after tree pruning. */
+    candidateGrids: number;
+}
+
+/** Private source identity, detached footprint and lazy mask state. */
+interface FieldEntry {
+    /** Detached descriptor sharing immutable sample arrays. */
+    grid: TerrainHeightGrid;
+    /** Original accumulation order, independent of spatial sorting. */
+    index: number;
+    /** Exact source footprint. */
+    bounds: TerrainFieldBounds;
+    /** Legacy touching-edge tolerance envelope. */
+    sampleBounds: TerrainFieldBounds;
+    /** Lazy prefix; null means fully valid, undefined means unprepared/unadmitted. */
+    mask?: Uint32Array | null;
+}
+
+/** Balanced spatial envelope; leaves contain exactly one source. */
+interface FieldNode {
+    /** Closed union of every descendant sampling envelope. */
+    bounds: TerrainFieldBounds;
+    /** Source owner on a leaf. */
+    entry?: FieldEntry;
+    /** Median-partitioned child envelopes on an internal node. */
+    children?: readonly [FieldNode, FieldNode];
+}
+
+/**
+ * Immutable-source physical height sampling and conservative footprint admission.
+ * Snapshots membership/bounds, not height arrays: do not mutate shared grids.
+ * No provider, worker, deck view, GPU resource or implicit longitude wrapping is owned.
+ */
+export class TerrainHeightField {
+    /** Original order for small-field direct sampling, avoiding tree/sort overhead. */
+    private readonly entries: readonly FieldEntry[];
+    /** Immutable spatial tree built once per admitted field. */
+    private readonly root: FieldNode | null;
+    /** Fixed retained summed-area mask admission limit. */
+    private readonly maxMaskBytes: number;
+    /** Mutable counters never exposed by reference. */
+    private readonly statistics: TerrainHeightFieldStatistics;
+
+    /** Retain structurally valid decoded grids with one datum; overlaps preserve ordered sample averaging. */
+    constructor(grids: readonly TerrainHeightGrid[], options: TerrainHeightFieldOptions = {}) {
+        this.maxMaskBytes = options.maxMaskBytes ?? 8 * 1024 * 1024;
+        if (!Number.isSafeInteger(this.maxMaskBytes) || this.maxMaskBytes < 0) throw new Error('Invalid terrain field mask budget');
+        this.statistics = {grids: grids.length, maskBytes: 0, maskBuilds: 0, maskSamples: 0, boundsTests: 0, candidateGrids: 0};
+        const entries = grids.map((grid, index): FieldEntry => {
+            const [west, south, east, north] = grid.bounds;
+            if (grid.bounds.length !== 4 || !grid.bounds.every(Number.isFinite) || west >= east || south >= north ||
+                !Number.isFinite(east - west) || !Number.isFinite(north - south) ||
+                !Number.isSafeInteger(grid.width) || !Number.isSafeInteger(grid.height) || grid.width < 2 || grid.height < 2 ||
+                grid.heights.length !== grid.width * grid.height || grid.valid.length !== grid.heights.length ||
+                !['pixel-center', 'grid-node'].includes(grid.registration) || !['unknown', 'ellipsoidal', 'orthometric'].includes(grid.verticalDatum) ||
+                grid.verticalDatum !== grids[0].verticalDatum) throw new Error('Invalid terrain field grid or datum');
+            const bounds: TerrainFieldBounds = [west, south, east, north];
+            const tolerance = Math.max(east - west, north - south) * 1e-10;
+            return {grid: {...grid, bounds}, index, bounds, sampleBounds: [west - tolerance, south - tolerance, east + tolerance, north + tolerance]};
+        });
+        this.entries = entries;
+        this.root = entries.length ? buildFieldNode([...entries]) : null;
+    }
+
+    /** Same ordered bilinear arithmetic, touching-edge tolerance and no-data rule as sampleTerrainNeighborhood. */
+    sampleHeight(position: readonly [number, number]): number | null {
+        if (position.length !== 2 || !position.every(Number.isFinite)) return null;
+        const direct = this.entries.length <= 16;
+        const bounds: TerrainFieldBounds = [position[0], position[1], position[0], position[1]];
+        const candidates = direct ? this.entries : this.findEntries(bounds);
+        let sum = 0, count = 0;
+        for (const entry of candidates) {
+            if (direct) this.statistics.boundsTests++;
+            if (!intersectsBounds(entry.sampleBounds, bounds)) continue;
+            if (direct) this.statistics.candidateGrids++;
+            const [west, south, east, north] = entry.bounds;
+            const height = sampleTerrainHeight(entry.grid, [Math.max(west, Math.min(east, position[0])), Math.max(south, Math.min(north, position[1]))]);
+            if (height === null) return null;
+            sum += height; count++;
+        }
+        return count ? sum / count : null;
+    }
+
+    /** Require complete rectangular footprint coverage and no invalid bilinear-support sample; not an exact triangle mask. */
+    coversBounds(bounds: TerrainFieldBounds): boolean {
+        if (bounds.length !== 4 || !bounds.every(Number.isFinite) || bounds[0] > bounds[2] || bounds[1] > bounds[3] ||
+            !Number.isFinite(bounds[2] - bounds[0]) || !Number.isFinite(bounds[3] - bounds[1])) throw new Error('Invalid terrain field probe bounds');
+        const width = bounds[2] - bounds[0], height = bounds[3] - bounds[1];
+        if (!Number.isFinite(width * height) || width > 0 && height > 0 && width * height === 0) throw new Error('Terrain field probe area must be finite and representable');
+        if (!width && !height) return this.sampleHeight([bounds[0], bounds[1]]) !== null;
+        const clipped: TerrainFieldBounds[] = [];
+        for (const entry of this.findEntries(bounds)) {
+            const left = Math.max(bounds[0], entry.bounds[0]), right = Math.min(bounds[2], entry.bounds[2]);
+            const bottom = Math.max(bounds[1], entry.bounds[1]), top = Math.min(bounds[3], entry.bounds[3]);
+            if (left > right || bottom > top || width && left === right || height && bottom === top) continue;
+            if (this.hasMissingSamples(entry, [left, bottom, right, top])) return false;
+            clipped.push([left, bottom, right, top]);
+        }
+        // Union, not additive area: overlapping footprints must not hide an unloaded gap.
+        const single = clipped.length === 1 ? clipped[0] : null;
+        const covered = single ? width && height ? (single[2] - single[0]) * (single[3] - single[1]) : width ? single[2] - single[0] : single[3] - single[1] :
+            width && height ? unionArea(clipped) : unionLength(clipped.map(rectangle => width ? [rectangle[0], rectangle[2]] : [rectangle[1], rectangle[3]]));
+        return covered >= (width && height ? width * height : width || height) * (1 - 1e-10);
+    }
+
+    /** Scalar counters only; callers cannot mutate cache ownership through diagnostics. */
+    getStatistics(): TerrainHeightFieldStatistics {return {...this.statistics};}
+
+    /**
+     * Physical extrema over bilinear cell rectangles in a fully covered probe.
+     * A missing footprint or invalid sample returns null, not a clearance
+     * certificate. Overlapping grids use a conservative per-grid envelope.
+     */
+    getHeightRange(bounds: TerrainFieldBounds): {minimum: number; maximum: number} | null {
+        if (!this.coversBounds(bounds)) return null;
+        let minimum = Infinity, maximum = -Infinity;
+        for (const entry of this.findEntries(bounds)) {
+            const {grid} = entry, pixelCenter = grid.registration === 'pixel-center';
+            const west = Math.max(bounds[0], grid.bounds[0]), east = Math.min(bounds[2], grid.bounds[2]);
+            const south = Math.max(bounds[1], grid.bounds[1]), north = Math.min(bounds[3], grid.bounds[3]);
+            if (west > east || south > north) continue;
+            const columns = [west, east], rows = [south, north];
+            for (let column = 0; column < grid.width; column++) {
+                const x = grid.bounds[0] + (column + (pixelCenter ? 0.5 : 0)) / (pixelCenter ? grid.width : grid.width - 1) * (grid.bounds[2] - grid.bounds[0]);
+                if (x > west && x < east) columns.push(x);
+            }
+            for (let row = 0; row < grid.height; row++) {
+                const y = grid.bounds[3] - (row + (pixelCenter ? 0.5 : 0)) / (pixelCenter ? grid.height : grid.height - 1) * (grid.bounds[3] - grid.bounds[1]);
+                if (y > south && y < north) rows.push(y);
+            }
+            // A bilinear patch has no strict interior maximum/minimum. Its
+            // extrema over an axis-aligned clipped cell occur at these knots.
+            for (const y of rows) for (const x of columns) {
+                const value = sampleTerrainHeight(grid, [x, y]);
+                if (value === null || !Number.isFinite(value)) return null;
+                minimum = Math.min(minimum, value); maximum = Math.max(maximum, value);
+            }
+        }
+        return Number.isFinite(minimum) ? {minimum, maximum} : null;
+    }
+
+    /** Traverse closed envelopes, then preserve original source order for floating-point accumulation. */
+    private findEntries(bounds: TerrainFieldBounds): FieldEntry[] {
+        const entries: FieldEntry[] = [], pending = this.root ? [this.root] : [];
+        while (pending.length) {
+            const node = pending.pop()!;
+            this.statistics.boundsTests++;
+            if (!intersectsBounds(node.bounds, bounds)) continue;
+            if (node.entry) {entries.push(node.entry); this.statistics.candidateGrids++;}
+            else if (node.children) pending.push(...node.children);
+        }
+        return entries.sort((first, second) => first.index - second.index);
+    }
+
+    /** Admit a lazy reusable prefix or scan the same support rectangle exactly when it does not fit. */
+    private hasMissingSamples(entry: FieldEntry, bounds: TerrainFieldBounds): boolean {
+        const {grid} = entry, stride = grid.width + 1;
+        const required = stride * (grid.height + 1) * Uint32Array.BYTES_PER_ELEMENT;
+        if (entry.mask === undefined && required <= this.maxMaskBytes - this.statistics.maskBytes) {
+            let hasMissing = false;
+            for (const valid of grid.valid) {
+                this.statistics.maskSamples++;
+                if (!valid) {hasMissing = true; break;}
+            }
+            if (!hasMissing) {entry.mask = null; return false;}
+            const prefix = new Uint32Array(stride * (grid.height + 1));
+            for (let row = 0; row < grid.height; row++) for (let column = 0; column < grid.width; column++) {
+                const offset = (row + 1) * stride + column + 1, invalid = Number(!grid.valid[row * grid.width + column]);
+                prefix[offset] = invalid + prefix[offset - 1] + prefix[offset - stride] - prefix[offset - stride - 1];
+            }
+            this.statistics.maskSamples += grid.valid.length;
+            entry.mask = prefix;
+            this.statistics.maskBytes += required; this.statistics.maskBuilds++;
+        }
+        if (entry.mask === null) return false;
+        const pixel = grid.registration === 'pixel-center';
+        const column = (x: number) => Math.max(0, Math.min(grid.width - 1, (x - grid.bounds[0]) / (grid.bounds[2] - grid.bounds[0]) * (pixel ? grid.width : grid.width - 1) - (pixel ? 0.5 : 0)));
+        const row = (y: number) => Math.max(0, Math.min(grid.height - 1, (grid.bounds[3] - y) / (grid.bounds[3] - grid.bounds[1]) * (pixel ? grid.height : grid.height - 1) - (pixel ? 0.5 : 0)));
+        const firstColumn = Math.floor(column(bounds[0])), lastColumn = Math.ceil(column(bounds[2]));
+        const firstRow = Math.floor(row(bounds[3])), lastRow = Math.ceil(row(bounds[1]));
+        if (entry.mask) return Boolean(entry.mask[(lastRow + 1) * stride + lastColumn + 1] - entry.mask[firstRow * stride + lastColumn + 1] -
+            entry.mask[(lastRow + 1) * stride + firstColumn] + entry.mask[firstRow * stride + firstColumn]);
+        for (let row = firstRow; row <= lastRow; row++) for (let column = firstColumn; column <= lastColumn; column++) {
+            this.statistics.maskSamples++;
+            if (!grid.valid[row * grid.width + column]) return true;
+        }
+        return false;
+    }
+}
+
+/** Closed rectangle intersection, including tolerance-expanded sampling envelopes. */
+function intersectsBounds(first: TerrainFieldBounds, second: TerrainFieldBounds): boolean {
+    return first[0] <= second[2] && first[2] >= second[0] && first[1] <= second[3] && first[3] >= second[1];
+}
+
+/** Median split on the longest axis; no external spatial-index dependency is needed. */
+function buildFieldNode(entries: FieldEntry[]): FieldNode {
+    const bounds: [number, number, number, number] = [Infinity, Infinity, -Infinity, -Infinity];
+    for (const entry of entries) {
+        bounds[0] = Math.min(bounds[0], entry.sampleBounds[0]); bounds[1] = Math.min(bounds[1], entry.sampleBounds[1]);
+        bounds[2] = Math.max(bounds[2], entry.sampleBounds[2]); bounds[3] = Math.max(bounds[3], entry.sampleBounds[3]);
+    }
+    if (entries.length === 1) return {bounds, entry: entries[0]};
+    const axis = bounds[2] - bounds[0] >= bounds[3] - bounds[1] ? 0 : 1;
+    entries.sort((first, second) => (first.bounds[axis] / 2 + first.bounds[axis + 2] / 2) - (second.bounds[axis] / 2 + second.bounds[axis + 2] / 2) || first.index - second.index);
+    const middle = Math.floor(entries.length / 2);
+    return {bounds, children: [buildFieldNode(entries.slice(0, middle)), buildFieldNode(entries.slice(middle))]};
+}
+
+/** Length of an interval union, never counting overlapping source coverage twice. */
+function unionLength(intervals: [number, number][]): number {
+    intervals.sort((first, second) => first[0] - second[0]);
+    let total = 0, end = -Infinity;
+    for (const [left, right] of intervals) {total += Math.max(0, right - Math.max(left, end)); end = Math.max(end, right);}
+    return total;
+}
+
+/** Rectangle union using independent vertical slabs; only spatially admitted sources participate. */
+function unionArea(rectangles: TerrainFieldBounds[]): number {
+    const columns = [...new Set(rectangles.flatMap(rectangle => [rectangle[0], rectangle[2]]))].sort((first, second) => first - second);
+    let area = 0;
+    for (let column = 1; column < columns.length; column++) {
+        const left = columns[column - 1], right = columns[column];
+        area += (right - left) * unionLength(rectangles.filter(rectangle => rectangle[0] <= left && rectangle[2] >= right).map(rectangle => [rectangle[1], rectangle[3]]));
+    }
+    return area;
+}

package/src/map-logic/terrain-navigation.ts

@@ -0,0 +1,50 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TerrainHeightField} from './terrain-height-field';
+
+/** Conservative swept square-footprint guard; it is not a rigid-body physics solver. */
+export interface TerrainMotionResult {
+    /** True only when every admitted path rectangle has valid source coverage. */
+    readonly available: boolean;
+    /** No translation should be published when true; orientation can still change. */
+    readonly blocked: boolean;
+    /** Explicit distinction between an obstacle, no-data and a bounded-work refusal. */
+    readonly reason: 'clear' | 'terrain' | 'missing' | 'budget';
+    /** Exact rectangle queries performed, useful for deterministic work-budget tests. */
+    readonly probes: number;
+}
+
+/**
+ * Guard all intermediate XY coverage and the entire body footprint, not just
+ * endpoint/centerline rays. XY and radius are EPSG:3857 meters; Z/clearance are
+ * physical vertical meters. A square conservatively contains a circular avatar.
+ */
+export function guardTerrainMotion(field: TerrainHeightField, start: readonly [number, number, number], end: readonly [number, number, number], options: {
+    /** Half-width of the conservative horizontal footprint in Mercator meters. */
+    radius: number;
+    /** Required physical eye-to-ground distance. */
+    clearance: number;
+    /** Maximum horizontal travel per query rectangle, default 2 Mercator meters. */
+    maxStep?: number;
+    /** Hard rectangle-query cap, default 128. Excessive movement holds translation. */
+    maxProbes?: number;
+}): TerrainMotionResult {
+    const maxStep = options.maxStep ?? 2, maxProbes = options.maxProbes ?? 128;
+    if (start.length !== 3 || end.length !== 3 || ![...start, ...end, options.radius, options.clearance, maxStep].every(Number.isFinite) ||
+        options.radius < 0 || options.clearance < 0 || maxStep <= 0 || !Number.isSafeInteger(maxProbes) || maxProbes < 1 || maxProbes > 1024) throw new Error('Invalid swept terrain motion');
+    const distance = Math.hypot(end[0] - start[0], end[1] - start[1]);
+    const steps = Math.max(1, Math.ceil(distance / maxStep));
+    if (steps > maxProbes) return {available: false, blocked: true, reason: 'budget', probes: 0};
+    let obstacle = false;
+    for (let step = 0; step < steps; step++) {
+        const first = start.map((value, axis) => value + (end[axis] - value) * step / steps);
+        const second = start.map((value, axis) => value + (end[axis] - value) * (step + 1) / steps);
+        const range = field.getHeightRange([Math.min(first[0], second[0]) - options.radius, Math.min(first[1], second[1]) - options.radius,
+            Math.max(first[0], second[0]) + options.radius, Math.max(first[1], second[1]) + options.radius]);
+        if (!range) return {available: false, blocked: true, reason: 'missing', probes: step + 1};
+        obstacle ||= Math.min(first[2], second[2]) - options.clearance < range.maximum;
+    }
+    return {available: true, blocked: obstacle, reason: obstacle ? 'terrain' : 'clear', probes: steps};
+}