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

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

@@ -0,0 +1,296 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {worldToLngLat} from '@math.gl/web-mercator';
+import {TerrainHeightField} from './terrain-height-field';
+import type {TerrainHeightGrid} from './terrain-data';
+import {getTerrainEdgeNodes} from './terrain-ground-topology';
+
+/** Spherical deck.gl common-space radius and physical reference radius, in meters. */
+const GLOBE_RADIUS = 256, EARTH_RADIUS = 6370972, MERCATOR_RADIUS = 6378137;
+
+/** Build an inclusive summed-area mask only when a source actually contains holes. */
+function* buildMissingTerrainPrefix(grid: TerrainHeightGrid): Generator<void, Uint32Array | null, void> {
+    let missingSample = false;
+    for (let offset = 0; offset < grid.valid.length && !missingSample; offset += 4096) {
+        for (let index = offset; index < Math.min(grid.valid.length, offset + 4096); index++) if (grid.valid[index] === 0) {missingSample = true; break;}
+        yield;
+    }
+    if (!missingSample) return null;
+    const stride = grid.width + 1, prefix = new Uint32Array(stride * (grid.height + 1));
+    for (let row = 0; row < grid.height; row++) {
+        let missing = 0;
+        for (let column = 0; column < grid.width; column++) {
+            missing += Number(grid.valid[row * grid.width + column] === 0);
+            prefix[(row + 1) * stride + column + 1] = prefix[row * stride + column + 1] + missing;
+        }
+        if (row % 8 === 7) yield;
+    }
+    return prefix;
+}
+
+/** Conservatively include every sample supporting bilinear interpolation over a cell footprint. */
+function hasMissingTerrain(grid: TerrainHeightGrid, prefix: Uint32Array, bounds: readonly [number, number, number, number]): boolean {
+    const west = Math.max(grid.bounds[0], bounds[0]), south = Math.max(grid.bounds[1], bounds[1]);
+    const east = Math.min(grid.bounds[2], bounds[2]), north = Math.min(grid.bounds[3], bounds[3]);
+    if (west > east || south > north) return false;
+    const pixelCenter = grid.registration === 'pixel-center';
+    const columnScale = (pixelCenter ? grid.width : grid.width - 1) / (grid.bounds[2] - grid.bounds[0]);
+    const rowScale = (pixelCenter ? grid.height : grid.height - 1) / (grid.bounds[3] - grid.bounds[1]);
+    const offset = pixelCenter ? 0.5 : 0;
+    const left = Math.floor(Math.max(0, (west - grid.bounds[0]) * columnScale - offset));
+    const right = Math.ceil(Math.min(grid.width - 1, (east - grid.bounds[0]) * columnScale - offset));
+    const top = Math.floor(Math.max(0, (grid.bounds[3] - north) * rowScale - offset));
+    const bottom = Math.ceil(Math.min(grid.height - 1, (grid.bounds[3] - south) * rowScale - offset));
+    const stride = grid.width + 1;
+    return prefix[(bottom + 1) * stride + right + 1] - prefix[top * stride + right + 1] - prefix[(bottom + 1) * stride + left] + prefix[top * stride + left] > 0;
+}
+
+/** Detached render/query buffers; original height grids are never exaggerated or modified. */
+export interface GlobeTerrainMesh {
+    /** Longitude/latitude degrees and displayed elevation meters for deck.gl projection. */
+    geographicPositions: Float32Array;
+    /** Radius-256 spherical XYZ matching those packed geographic vertices. */
+    positions: Float64Array;
+    /** Physical source elevation per vertex, independent of exaggeration and chord error. */
+    physicalHeights: Float32Array;
+    /** Outward triangle topology; cells touching no-data samples are omitted. */
+    indices: Uint32Array;
+    /** RGB relief colors with baked common-space lighting, independent of backend. */
+    colors: Float32Array;
+}
+
+/** Opaque immutable sampling/topology snapshot; keep it to rescale without reading source grids again. */
+export interface GlobeTerrainMeshTemplate {
+    /** Number of regular and stitched vertices in this snapshot. */
+    readonly vertexCount: number;
+    /** Number of outward triangles, excluding no-data cells. */
+    readonly triangleCount: number;
+    /** Owned typed-array backing storage; excludes source grids and temporary JavaScript arrays. */
+    readonly byteLength: number;
+}
+
+/** Private backing arrays cannot be modified through the public template handle. */
+const terrainTemplates = new WeakMap<GlobeTerrainMeshTemplate, {
+    coordinates: Float32Array;
+    heights: Float64Array;
+    gradients: Float64Array;
+    frame: Float64Array;
+    physicalHeights: Float32Array;
+    indices: Uint32Array;
+}>();
+
+/** Attenuate exaggerated relief to flat after one diameter doubling; explicit physical/subphysical settings stay fixed. */
+export function getGlobeTerrainExaggeration(globeScreenRatio: number, maximum = 100): number {
+    if (!Number.isFinite(maximum) || maximum < 0 || maximum > 1000 || !Number.isFinite(globeScreenRatio) || globeScreenRatio < 0) throw new Error('Invalid globe terrain exaggeration or screen ratio');
+    if (maximum <= 1) return maximum;
+    const progress = Math.max(0, Math.min(1, Math.log2(Math.max(1, globeScreenRatio))));
+    return (maximum + 1) ** (1 - progress * progress * (3 - 2 * progress)) - 1;
+}
+
+/** Resample a Mercator DEM onto curved triangles; neighbors reconcile matching tile edges. */
+export function buildGlobeTerrainMesh(grid: TerrainHeightGrid, options: {
+    /** Effective display multiplier, not the zoom-independent maximum. */
+    exaggeration?: number;
+    /** Cells along each tile axis, bounded to keep allocations predictable; defaults to 64. */
+    resolution?: number;
+    /** Same-datum, non-overlapping neighbors with balanced 2:1 edges and the same cell resolution. */
+    neighbors?: readonly TerrainHeightGrid[];
+} = {}): GlobeTerrainMesh {
+    getGlobeTerrainExaggeration(0, options.exaggeration ?? 1);
+    return scaleGlobeTerrainMesh(prepareGlobeTerrainMesh(grid, options), options.exaggeration ?? 1);
+}
+
+/** Snapshot source sampling, no-data, edge stitching and physical slopes once per immutable neighborhood. */
+export function prepareGlobeTerrainMesh(grid: TerrainHeightGrid, options: {
+    /** Uniform cells per tile axis, integer [2, 256]; defaults to 64. */
+    resolution?: number;
+    /** Same-datum non-overlapping neighbors with balanced 2:1 edges. */
+    neighbors?: readonly TerrainHeightGrid[];
+} = {}): GlobeTerrainMeshTemplate {
+    const steps = prepareGlobeTerrainMeshSteps(grid, options);
+    let result = steps.next();
+    while (!result.done) result = steps.next();
+    return result.value;
+}
+
+/** Cooperatively prepare identical topology; each yield releases control between bounded sampling chunks. */
+export function* prepareGlobeTerrainMeshSteps(grid: TerrainHeightGrid, options: {
+    /** Uniform cells per tile axis, integer [2, 256]; defaults to 64. */
+    resolution?: number;
+    /** Same-datum non-overlapping neighbors with balanced 2:1 edges. */
+    neighbors?: readonly TerrainHeightGrid[];
+    /** Exact final typed-array admission fence; scratch is excluded. The identity is not a usable template until completion. */
+    onAllocate?: (bytes: number, allocation: GlobeTerrainMeshTemplate) => void;
+} = {}): Generator<void, GlobeTerrainMeshTemplate, void> {
+    const resolution = options.resolution ?? 64;
+    if (!Number.isSafeInteger(resolution) || resolution < 2 || resolution > 256) throw new Error('Globe terrain resolution must be an integer in [2, 256]');
+    const grids = [grid, ...(options.neighbors ?? [])];
+    const halfWorld = Math.PI * MERCATOR_RADIUS;
+    for (const candidate of grids) {
+        if (!Number.isSafeInteger(candidate.width) || !Number.isSafeInteger(candidate.height) || candidate.width < 2 || candidate.height < 2 || candidate.heights.length !== candidate.width * candidate.height || candidate.valid.length !== candidate.heights.length ||
+            candidate.bounds.length !== 4 || !candidate.bounds.every(Number.isFinite) || candidate.bounds[0] >= candidate.bounds[2] || candidate.bounds[1] >= candidate.bounds[3] ||
+            candidate.bounds.some(value => Math.abs(value) > halfWorld + 1e-6) ||
+            !['grid-node', 'pixel-center'].includes(candidate.registration) || !['ellipsoidal', 'orthometric', 'unknown'].includes(candidate.verticalDatum) || candidate.verticalDatum !== grid.verticalDatum) throw new Error('Invalid globe terrain grid or incompatible vertical datum');
+    }
+    const circumference = 2 * Math.PI * MERCATOR_RADIUS;
+    const samplingGrids = grids.flatMap(candidate => [-1, 0, 1].map((world): TerrainHeightGrid => ({...candidate, bounds: [candidate.bounds[0] + world * circumference, candidate.bounds[1], candidate.bounds[2] + world * circumference, candidate.bounds[3]]})))
+        .filter(candidate => candidate.bounds[0] <= grid.bounds[2] && candidate.bounds[2] >= grid.bounds[0] && candidate.bounds[1] <= grid.bounds[3] && candidate.bounds[3] >= grid.bounds[1]);
+    const heightField = new TerrainHeightField(samplingGrids);
+    const missingRegions: {grid: TerrainHeightGrid; prefix: Uint32Array}[] = [];
+    for (const candidate of samplingGrids) {
+        const prefix = yield* buildMissingTerrainPrefix(candidate);
+        if (prefix) missingRegions.push({grid: candidate, prefix});
+    }
+    const [west, south, east, north] = grid.bounds;
+    const tolerance = Math.max(east - west, north - south) * 1e-10;
+    for (const candidate of samplingGrids) {
+        const horizontal = Math.min(east, candidate.bounds[2]) - Math.max(west, candidate.bounds[0]);
+        const vertical = Math.min(north, candidate.bounds[3]) - Math.max(south, candidate.bounds[1]);
+        const identical = candidate.bounds.every((value, index) => Math.abs(value - grid.bounds[index]) <= tolerance);
+        if (!identical && horizontal > tolerance && vertical > tolerance) throw new Error('Globe terrain neighbors must not overlap');
+        if (!identical && (horizontal > tolerance || vertical > tolerance)) {
+            const ratio = (candidate.bounds[2] - candidate.bounds[0]) / (east - west);
+            if (![0.5, 1, 2].some(value => Math.abs(ratio - value) < 1e-8) || Math.abs((candidate.bounds[3] - candidate.bounds[1]) / (north - south) - ratio) > 1e-8) throw new Error('Globe terrain edges require balanced 2:1 footprints');
+        }
+    }
+    const size = resolution + 1;
+    const geographicPositions: number[] = [], positions: number[] = [], physicalHeights: number[] = [], samplePositions: [number, number][] = [], valid: boolean[] = [];
+    const nodes = new Map<string, number>();
+    if ((east - west) / resolution >= halfWorld - 1e-6) throw new Error('Globe terrain cells must span less than 180 degrees longitude');
+    const worldScale = 512 / (2 * Math.PI * MERCATOR_RADIUS);
+    /** Shared nodes use the same packed geographic coordinates for drawing and queries. */
+    function vertex(column: number, row: number): number {
+        column = Math.round(column * 1e8) / 1e8; row = Math.round(row * 1e8) / 1e8;
+        const key = `${column},${row}`, retained = nodes.get(key);
+        if (retained !== undefined) return retained;
+        const index = physicalHeights.length; nodes.set(key, index);
+        const x = west + (east - west) * column / resolution, y = north - (north - south) * row / resolution;
+        const height = heightField.sampleHeight([x, y]);
+        if (height !== null && !Number.isFinite(height)) throw new Error('Invalid globe terrain elevation');
+        valid.push(height !== null); physicalHeights.push(height ?? NaN); samplePositions.push([x, y]);
+        const coordinate = worldToLngLat([x * worldScale + 256, y * worldScale + 256]);
+        const packed = [Math.fround(coordinate[0]), Math.fround(coordinate[1]), 0];
+        geographicPositions.push(...packed);
+        // Compute queries from the exact Float32 attributes submitted to deck.gl.
+        const longitude = packed[0] * Math.PI / 180, latitude = packed[1] * Math.PI / 180;
+        const radius = GLOBE_RADIUS;
+        positions.push(Math.sin(longitude) * Math.cos(latitude) * radius, -Math.cos(longitude) * Math.cos(latitude) * radius, Math.sin(latitude) * radius);
+        return index;
+    }
+    // Retain regular node ordering; additional nodes are confined to stitched boundary rings.
+    for (let row = 0; row < size; row++) {
+        for (let column = 0; column < size; column++) vertex(column, row);
+        yield;
+    }
+    const triangles: number[] = [];
+    /** Add one outward non-degenerate triangle to the shared render/query topology. */
+    function triangle(vertices: readonly number[]): void {
+        if (!vertices.every(index => valid[index])) return;
+        const [a, b, c] = vertices.map(index => index * 3);
+        const ab = [positions[b] - positions[a], positions[b + 1] - positions[a + 1], positions[b + 2] - positions[a + 2]], ac = [positions[c] - positions[a], positions[c + 1] - positions[a + 1], positions[c + 2] - positions[a + 2]];
+        const normal = [ab[1] * ac[2] - ab[2] * ac[1], ab[2] * ac[0] - ab[0] * ac[2], ab[0] * ac[1] - ab[1] * ac[0]];
+        if (Math.hypot(...normal) === 0) throw new Error('Globe terrain triangle collapses at packed coordinate precision');
+        const sign = normal[0] * positions[a] + normal[1] * positions[a + 1] + normal[2] * positions[a + 2] < 0 ? -1 : 1;
+        triangles.push(vertices[0], vertices[sign === 1 ? 1 : 2], vertices[sign === 1 ? 2 : 1]);
+    }
+    /** Include neighbor edge nodes so fine half-steps also exist on the coarse mesh. */
+    function edgeNodes(start: readonly [number, number], end: readonly [number, number]): number[] {
+        return getTerrainEdgeNodes(grid.bounds, samplingGrids.map(candidate => candidate.bounds), resolution, start, end).map(point => vertex(...point));
+    }
+    /** Only boundary triangles with extra edge nodes need a center fan. */
+    function reconstruct(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(start[0], start[1]), ...edgeNodes(start, end));
+        }
+        if (!ring.every(index => valid[index])) return;
+        if (ring.length === 3) triangle(ring);
+        else {
+            const center = vertex(corners.reduce((sum, point) => sum + point[0] / 3, 0), corners.reduce((sum, point) => sum + point[1] / 3, 0));
+            for (let edge = 0; edge < ring.length; edge++) triangle([center, ring[edge], ring[(edge + 1) % ring.length]]);
+        }
+    }
+    for (let row = 0; row < resolution; row++) {
+      for (let column = 0; column < resolution; column++) {
+        const first = row * size + column, second = first + 1, third = first + size, fourth = third + 1;
+        if (![first, second, third, fourth].every(vertex => valid[vertex])) continue;
+        const cellBounds: [number, number, number, number] = [west + (east - west) * column / resolution, north - (north - south) * (row + 1) / resolution,
+            west + (east - west) * (column + 1) / resolution, north - (north - south) * row / resolution];
+        if (missingRegions.some(region => hasMissingTerrain(region.grid, region.prefix, cellBounds))) continue;
+        reconstruct([[column, row], [column, row + 1], [column + 1, row]]);
+        reconstruct([[column + 1, row], [column, row + 1], [column + 1, row + 1]]);
+      }
+      yield;
+    }
+    const template = Object.freeze({vertexCount: physicalHeights.length, triangleCount: triangles.length / 3,
+        byteLength: physicalHeights.length * 68 + triangles.length * 4});
+    options.onAllocate?.(template.byteLength, template);
+    const gradients = new Float64Array(physicalHeights.length * 2), frame = new Float64Array(physicalHeights.length * 4);
+    /** Identical edge sample neighborhoods yield identical spherical lighting at either LOD. */
+    function slope(negative: number | null, positive: number | null, center: number, distance: number): number {
+        return negative !== null && positive !== null ? (positive - negative) / (2 * distance) : positive !== null ? (positive - center) / distance : negative !== null ? (center - negative) / distance : 0;
+    }
+    for (let index = 0; index < physicalHeights.length; index++) {
+        const offset = index * 3, [x, y] = samplePositions[index], height = physicalHeights[index];
+        const longitude = geographicPositions[offset] * Math.PI / 180, latitude = geographicPositions[offset + 1] * Math.PI / 180;
+        frame.set([Math.sin(longitude), Math.cos(longitude), Math.sin(latitude), Math.cos(latitude)], index * 4);
+        const touching = samplingGrids.filter(candidate => x >= candidate.bounds[0] - tolerance && x <= candidate.bounds[2] + tolerance && y >= candidate.bounds[1] - tolerance && y <= candidate.bounds[3] + tolerance);
+        const distanceX = Math.min(...touching.map(candidate => (candidate.bounds[2] - candidate.bounds[0]) / (candidate.registration === 'pixel-center' ? candidate.width : candidate.width - 1)));
+        const distanceY = Math.min(...touching.map(candidate => (candidate.bounds[3] - candidate.bounds[1]) / (candidate.registration === 'pixel-center' ? candidate.height : candidate.height - 1)));
+        const physicalScale = Math.cos(latitude) * EARTH_RADIUS / MERCATOR_RADIUS;
+        gradients[index * 2] = !valid[index] ? 0 : slope(heightField.sampleHeight([x - distanceX, y]), heightField.sampleHeight([x + distanceX, y]), height, distanceX * physicalScale);
+        gradients[index * 2 + 1] = !valid[index] ? 0 : slope(heightField.sampleHeight([x, y - distanceY]), heightField.sampleHeight([x, y + distanceY]), height, distanceY * physicalScale);
+        if (index % 128 === 127) yield;
+    }
+    const buffers = {
+        coordinates: Float32Array.from(geographicPositions.filter((_, index) => index % 3 !== 2)),
+        heights: Float64Array.from(physicalHeights), gradients, frame,
+        physicalHeights: Float32Array.from(physicalHeights), indices: Uint32Array.from(triangles)
+    };
+    terrainTemplates.set(template, buffers);
+    return template;
+}
+
+/** Rebuild detached display/query buffers without resampling or restitching the immutable template. */
+export function scaleGlobeTerrainMesh(template: GlobeTerrainMeshTemplate, exaggeration = 1): GlobeTerrainMesh {
+    const steps = scaleGlobeTerrainMeshSteps(template, exaggeration);
+    let result = steps.next();
+    while (!result.done) result = steps.next();
+    return result.value;
+}
+
+/** Cooperatively rescale identical packed vertices/lighting; yields every 128 vertices without resampling. */
+export function* scaleGlobeTerrainMeshSteps(template: GlobeTerrainMeshTemplate, exaggeration = 1): Generator<void, GlobeTerrainMesh, void> {
+    getGlobeTerrainExaggeration(0, exaggeration);
+    const prepared = terrainTemplates.get(template);
+    if (!prepared) throw new Error('Globe terrain template must come from prepareGlobeTerrainMesh');
+    const geographicPositions = new Float32Array(template.vertexCount * 3), positions = new Float64Array(template.vertexCount * 3), colors = new Float32Array(template.vertexCount * 3);
+    for (let index = 0; index < template.vertexCount; index++) {
+        const offset = index * 3, height = prepared.heights[index];
+        const valid = !Number.isNaN(height);
+        if (valid && EARTH_RADIUS + height * exaggeration <= 0) throw new Error('Invalid globe terrain elevation');
+        geographicPositions[offset] = prepared.coordinates[index * 2];
+        geographicPositions[offset + 1] = prepared.coordinates[index * 2 + 1];
+        geographicPositions[offset + 2] = (valid ? height : 0) * exaggeration;
+        if (!Number.isFinite(geographicPositions[offset + 2])) throw new Error('Globe terrain elevation exceeds packed display range');
+        const radiusScale = 1 + geographicPositions[offset + 2] / EARTH_RADIUS;
+        const gradientX = prepared.gradients[index * 2] * exaggeration / radiusScale, gradientY = prepared.gradients[index * 2 + 1] * exaggeration / radiusScale;
+        const sinLongitude = prepared.frame[index * 4], cosLongitude = prepared.frame[index * 4 + 1], sinLatitude = prepared.frame[index * 4 + 2], cosLatitude = prepared.frame[index * 4 + 3];
+        const radialX = sinLongitude * cosLatitude, radialY = -cosLongitude * cosLatitude;
+        const radius = GLOBE_RADIUS * radiusScale;
+        positions[offset] = radialX * radius; positions[offset + 1] = radialY * radius; positions[offset + 2] = sinLatitude * radius;
+        const normalX = radialX - gradientX * cosLongitude - gradientY * (-sinLongitude * sinLatitude);
+        const normalY = radialY - gradientX * sinLongitude - gradientY * (cosLongitude * sinLatitude);
+        const normalZ = sinLatitude - gradientX * 0 - gradientY * cosLatitude;
+        if (![normalX, normalY, normalZ].every(Number.isFinite)) throw new Error('Invalid globe terrain slope');
+        const light = 0.4 + 0.6 * Math.max(0, (normalX - normalY + normalZ) / (Math.hypot(normalX, normalY, normalZ) * Math.sqrt(3)));
+        colors[offset] = (height > 2500 ? 0.9 : height <= 0 ? 0.12 : 0.36) * light;
+        colors[offset + 1] = (height > 2500 ? 0.92 : height <= 0 ? 0.3 : 0.58) * light;
+        colors[offset + 2] = (height > 2500 ? 0.96 : height <= 0 ? 0.48 : 0.34) * light;
+        if (index % 128 === 127) yield;
+    }
+    return {geographicPositions, positions, physicalHeights: prepared.physicalHeights.slice(), indices: prepared.indices.slice(), colors};
+}

package/src/map-logic/index.ts

@@ -0,0 +1,37 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {resolveLabelPlacement} from './label-placement';
+export type {ScreenLabelCandidate, LabelPlacementOptions} from './label-placement';
+export {areGeographicLabelCopies} from './label-identity';
+export type {GeographicLabelAnchor, GeographicLabelIdentityOptions} from './label-identity';
+export {intersectsScreenBounds, unionScreenBounds, getScreenBoundsCells} from './screen-bounds';
+export type {ScreenBounds, LabelViewport} from './screen-bounds';
+export {default as TileBuildQueue} from './tile-build-queue';
+export type {TileBuildTask} from './tile-build-queue';
+export {TileResidency} from './tile-residency';
+export {TileCachePolicy} from './tile-cache-policy';
+export type {TileCacheRecord, TileCacheOptions, TileCacheStatistics} from './tile-cache-policy';
+export {TERRARIUM_DECODER, TERRAIN_RGB_DECODER, decodeTerrainHeightGrid, sampleTerrainHeight} from './terrain-data';
+export {sampleTerrainNeighborhood, resampleTerrainNodes} from './terrain-neighborhood';
+export {TerrainHeightField} from './terrain-height-field';
+export {TerrainResourceBudget} from './terrain-resource-budget';
+export type {TerrainResourceDomain, TerrainResourceLease, TerrainResourceRequest} from './terrain-resource-budget';
+export {measureTerrainError, boundTerrainMeshError, selectTerrainMeshResolution, boundProjectedDisplacement} from './terrain-error';
+export type {TerrainErrorEnvelope} from './terrain-error';
+export {guardTerrainMotion} from './terrain-navigation';
+export type {TerrainMotionResult} from './terrain-navigation';
+export type {TerrainFieldBounds, TerrainHeightFieldOptions, TerrainHeightFieldStatistics} from './terrain-height-field';
+export {createTerrainGroundTopology} from './terrain-ground-topology';
+export type {TerrainGroundTopology} from './terrain-ground-topology';
+export type {ElevationDecoder, TerrainGridOptions, TerrainHeightGrid} from './terrain-data';
+export {TriangleQueryIndex} from './triangle-query-index';
+export {adaptTerrainQuerySource} from './terrain-query';
+export type {TerrainQuerySource, TerrainQueryHit} from './terrain-query';
+export type {TerrainSurface, TerrainSurfaceBounds, TerrainRay, TerrainSurfaceHit} from '../selection/terrain_surface';
+export type {IndexedTriangleHit, TriangleQueryResult, TriangleQueryIndexOptions} from './triangle-query-index';
+export {buildGlobeTerrainMesh, prepareGlobeTerrainMesh, prepareGlobeTerrainMeshSteps, scaleGlobeTerrainMesh, scaleGlobeTerrainMeshSteps, getGlobeTerrainExaggeration} from './globe-terrain';
+export type {GlobeTerrainMesh, GlobeTerrainMeshTemplate} from './globe-terrain';
+export {GlobeTerrainPreparation, getPreparedGlobeTerrainTemplate, assertGlobeTerrainPreparationSnapshot} from './globe-terrain-preparation';
+export type {GlobeTerrainPreparationSnapshot, GlobeTerrainPreparationStatistics} from './globe-terrain-preparation';

package/src/map-logic/label-identity.ts

@@ -0,0 +1,36 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Geographic identity retained independently of rendered geometry and cameras. */
+export interface GeographicLabelAnchor {
+    /** Source/style/feature/text identity; absent identities cannot deduplicate. */
+    readonly identity?: string;
+    /** Tile identity; multiple mesh parts of the same tile are not buffered copies. */
+    readonly sourceTileIdentity: object | string;
+    /** Absolute projected XY in the same units as the world width. */
+    readonly anchor: readonly [number, number];
+    /** Quantized physical elevation; distinct elevations remain separate labels. */
+    readonly height: number;
+    /** Source detail used for coordinate quantization, independent of style zoom. */
+    readonly sourceZoom: number;
+}
+
+/** Explicit coordinate conventions; no renderer projection or Earth radius is assumed. */
+export interface GeographicLabelIdentityOptions {
+    /** Width of a complete projected world in anchor units. */
+    readonly worldWidth: number;
+    /** Treat horizontally wrapped copies as the same surface, as on a globe. */
+    readonly wrapHorizontal: boolean;
+}
+
+/** Match buffered copies within two 4096-unit source-tile quantization steps. */
+export function areGeographicLabelCopies(candidate: GeographicLabelAnchor, previous: GeographicLabelAnchor,
+    options: GeographicLabelIdentityOptions): boolean {
+    if (!candidate.identity || candidate.identity !== previous.identity || candidate.sourceTileIdentity === previous.sourceTileIdentity) return false;
+    if (candidate.height !== previous.height) return false;
+    const tolerance = 2 * options.worldWidth / (4096 * 2 ** Math.min(candidate.sourceZoom, previous.sourceZoom));
+    const horizontal = candidate.anchor[0] - previous.anchor[0];
+    const difference = options.wrapHorizontal ? horizontal - Math.round(horizontal / options.worldWidth) * options.worldWidth : horizontal;
+    return Math.hypot(difference, candidate.anchor[1] - previous.anchor[1]) <= tolerance;
+}

package/src/map-logic/label-placement.ts

@@ -0,0 +1,117 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getScreenBoundsCells, intersectsScreenBounds} from './screen-bounds';
+import type {ScreenBounds, LabelViewport} from './screen-bounds';
+
+/** Renderer-independent candidate, already projected and ordered by the caller. */
+export interface ScreenLabelCandidate {
+    /** Unique ID within this invocation; also identifies linked candidates. */
+    readonly id: string;
+    /** Visible, padded local CSS-pixel bounds per named view. Empty means hidden. */
+    readonly boxes: ReadonlyMap<string, ScreenBounds>;
+    /** False skips overlap rejection but retains repeat and identity rules. */
+    readonly collide?: boolean;
+    /** Optional dependency; reciprocal links form an atomic pair. */
+    readonly linkedId?: string;
+    /** Key used to compare candidate copies via the supplied identity policy. */
+    readonly identity?: string;
+    /** Optional repeat group shared by labels representing the same content. */
+    readonly repeatGroup?: string;
+    /** Minimum CSS-pixel separation between box centers in every shared view. */
+    readonly repeatDistance?: number;
+}
+
+/** Geometry and identity policy supplied by the host, not owned by this algorithm. */
+export interface LabelPlacementOptions<Candidate extends ScreenLabelCandidate> {
+    /** Dimensions for every view named by candidate bounds. */
+    readonly viewports: ReadonlyMap<string, LabelViewport>;
+    /** Optional buffered-copy policy; called only within matching identity groups. */
+    readonly isDuplicate?: (candidate: Candidate, previous: Candidate) => boolean;
+}
+
+/**
+ * Resolve one visibility mask across all views in caller-supplied priority order.
+ * Inputs must have unique IDs and finite, ordered, already clipped/padded bounds.
+ * No input mutation, global state, camera, tile, worker, DOM or GPU dependency.
+ * Reciprocal links are placed atomically; optional children may overlap their parent.
+ */
+export function resolveLabelPlacement<Candidate extends ScreenLabelCandidate>(ordered: readonly Candidate[],
+    options: LabelPlacementOptions<Candidate>): ReadonlyMap<Candidate, boolean> {
+    const candidates = new Map(ordered.map(candidate => [candidate.id, candidate]));
+    const shown = new Map<Candidate, boolean>();
+    const identities = new Map<string, Candidate[]>();
+    const repeatGroups = new Map<string, Candidate[]>();
+    const grids = new Map<string, Map<string, Set<Candidate>>>();
+    const placing = new Set<Candidate>();
+    /** Require a matching local viewport for spatial indexing. */
+    function getViewport(view: string): LabelViewport {
+        const viewport = options.viewports.get(view);
+        if (!viewport) throw new Error(`Missing label viewport: ${view}`);
+        return viewport;
+    }
+    /** Resolve dependencies before committing one candidate or reciprocal pair. */
+    function place(candidate: Candidate): boolean {
+        const visibility = shown.get(candidate);
+        if (visibility !== undefined) return visibility;
+        if (placing.has(candidate)) return false;
+        placing.add(candidate);
+        const linked = candidate.linkedId === undefined ? undefined : candidates.get(candidate.linkedId);
+        const required = linked && linked.linkedId === candidate.id;
+        const group = required ? [candidate, linked] : [candidate];
+        if (linked && !required && !place(linked)) {
+            shown.set(candidate, false);
+            placing.delete(candidate);
+            return false;
+        }
+        const show = group.every(member => member.boxes.size > 0 &&
+            !(identities.get(member.identity ?? '') ?? []).some(previous => options.isDuplicate?.(member, previous)) &&
+            !(repeatGroups.get(member.repeatGroup ?? '') ?? []).some(previous => repeats(member, previous))) &&
+            group.every(member => member.collide === false || [...member.boxes].every(([view, box]) => {
+                const grid = grids.get(view);
+                if (!grid) return true;
+                const nearby = new Set<Candidate>();
+                for (const cell of getScreenBoundsCells(box, getViewport(view))) for (const previous of grid.get(cell) ?? []) nearby.add(previous);
+                return [...nearby].every(previous => previous === linked || !intersectsScreenBounds(box, previous.boxes.get(view)!));
+            }));
+        for (const member of group) {
+            shown.set(member, show);
+            if (!show) continue;
+            if (member.identity) {
+                const copies = identities.get(member.identity) ?? [];
+                copies.push(member);
+                identities.set(member.identity, copies);
+            }
+            if (member.repeatGroup && member.repeatDistance) {
+                const repeated = repeatGroups.get(member.repeatGroup) ?? [];
+                repeated.push(member);
+                repeatGroups.set(member.repeatGroup, repeated);
+            }
+            for (const [view, box] of member.boxes) {
+                let grid = grids.get(view);
+                if (!grid) grids.set(view, grid = new Map());
+                for (const cell of getScreenBoundsCells(box, getViewport(view))) {
+                    let bucket = grid.get(cell);
+                    if (!bucket) grid.set(cell, bucket = new Set());
+                    bucket.add(member);
+                }
+            }
+        }
+        placing.delete(candidate);
+        return show;
+    }
+    ordered.forEach(place);
+    return shown;
+}
+
+/** Preserve authored spacing in any view shared by the candidate and prior label. */
+function repeats(candidate: ScreenLabelCandidate, previous: ScreenLabelCandidate): boolean {
+    const repeatDistance = candidate.repeatDistance;
+    if (!repeatDistance || !candidate.repeatGroup || candidate.repeatGroup !== previous.repeatGroup) return false;
+    return [...candidate.boxes].some(([view, box]) => {
+        const other = previous.boxes.get(view);
+        return other !== undefined && Math.hypot((box[0] + box[2] - other[0] - other[2]) / 2,
+            (box[1] + box[3] - other[1] - other[3]) / 2) < repeatDistance;
+    });
+}

package/src/map-logic/screen-bounds.ts

@@ -0,0 +1,34 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Axis-aligned CSS-pixel bounds: minimum X/Y followed by maximum X/Y. */
+export type ScreenBounds = readonly [number, number, number, number];
+
+/** Local viewport dimensions; bounds do not include a canvas/eye origin. */
+export interface LabelViewport {
+    /** Local CSS-pixel width. */
+    readonly width: number;
+    /** Local CSS-pixel height. */
+    readonly height: number;
+}
+
+/** Strict rectangle overlap; touching padded edges do not collide. */
+export function intersectsScreenBounds(left: ScreenBounds, right: ScreenBounds): boolean {
+    return left[0] < right[2] && left[2] > right[0] && left[1] < right[3] && left[3] > right[1];
+}
+
+/** Combine parts of one annotation without modifying either input. */
+export function unionScreenBounds(left: ScreenBounds | undefined, right: ScreenBounds): ScreenBounds {
+    return left ? [Math.min(left[0], right[0]), Math.min(left[1], right[1]),
+        Math.max(left[2], right[2]), Math.max(left[3], right[3])] : right;
+}
+
+/** Enumerate 64-pixel spatial-index cells, clipped to the visible viewport. */
+export function* getScreenBoundsCells(box: ScreenBounds, viewport: LabelViewport): Generator<string> {
+    for (let horizontal = Math.floor(Math.max(0, box[0]) / 64); horizontal <= Math.floor(Math.min(viewport.width, box[2]) / 64); horizontal++) {
+        for (let vertical = Math.floor(Math.max(0, box[1]) / 64); vertical <= Math.floor(Math.min(viewport.height, box[3]) / 64); vertical++) {
+            yield `${horizontal},${vertical}`;
+        }
+    }
+}

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

@@ -0,0 +1,107 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Affine coefficients applied to byte-valued linear RGB, with output in meters. */
+export interface ElevationDecoder {
+    /** Red channel multiplier. */
+    readonly rScaler: number;
+    /** Green channel multiplier. */
+    readonly gScaler: number;
+    /** Blue channel multiplier. */
+    readonly bScaler: number;
+    /** Meter offset after channel scaling. */
+    readonly offset: number;
+}
+
+/** Terrarium encoding used by Mapterhorn; compatible with loaders.gl terrain options. */
+export const TERRARIUM_DECODER: ElevationDecoder = Object.freeze({rScaler: 256, gScaler: 1, bScaler: 1 / 256, offset: -32768});
+/** Mapbox Terrain-RGB encoding, independent of the tile service. */
+export const TERRAIN_RGB_DECODER: ElevationDecoder = Object.freeze({rScaler: 6553.6, gScaler: 25.6, bScaler: 0.1, offset: -10000});
+
+/** Explicit raster georeferencing; row zero is north and column zero is west. */
+export interface TerrainGridOptions {
+    /** Number of columns, at least two. */
+    width: number;
+    /** Number of rows, at least two. */
+    height: number;
+    /** Interleaved RGBA bytes, not sRGB-converted samples. */
+    pixels: Uint8Array | Uint8ClampedArray;
+    /** Decoder shared with loaders.gl. */
+    decoder: ElevationDecoder;
+    /** [west, south, east, north] in absolute EPSG:3857 meters. */
+    bounds: readonly [number, number, number, number];
+    /** Explicit vertical reference; do not infer a datum from the provider name. */
+    verticalDatum: 'ellipsoidal' | 'orthometric' | 'unknown';
+    /** Pixel-aligned validity mask; zero means no data. Alpha is not implicitly interpreted. */
+    valid?: Uint8Array;
+    /** Raster pixel centers, or samples including both grid edges. */
+    registration: 'pixel-center' | 'grid-node';
+}
+
+/** Detached decoded elevation data; meters are physical heights, never exaggerated. */
+export interface TerrainHeightGrid {
+    /** Number of columns. */
+    readonly width: number;
+    /** Number of rows. */
+    readonly height: number;
+    /** North-to-south, west-to-east row-major elevation values in meters. */
+    readonly heights: Float32Array;
+    /** Detached validity mask; invalid heights are NaN. */
+    readonly valid: Uint8Array;
+    /** Absolute Mercator footprint in meters. */
+    readonly bounds: readonly [number, number, number, number];
+    /** Vertical reference, without implicit conversions. */
+    readonly verticalDatum: TerrainGridOptions['verticalDatum'];
+    /** Sampling convention of the decoded pixels. */
+    readonly registration: TerrainGridOptions['registration'];
+}
+
+/** Decode identical byte coefficients to loaders.gl; preserve no-data explicitly. */
+export function decodeTerrainHeightGrid(options: TerrainGridOptions): TerrainHeightGrid {
+    const {width, height, pixels, decoder, bounds, verticalDatum, registration} = options;
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 2 || height < 2 || pixels.length !== width * height * 4) {
+        throw new Error('Terrain requires a complete RGBA grid of at least 2 by 2');
+    }
+    if (bounds.length !== 4 || !bounds.every(Number.isFinite) || bounds[0] >= bounds[2] || bounds[1] >= bounds[3]) throw new Error('Terrain bounds must have finite positive extent');
+    if (![decoder.rScaler, decoder.gScaler, decoder.bScaler, decoder.offset].every(Number.isFinite)) throw new Error('Terrain decoder must be finite');
+    if (!['ellipsoidal', 'orthometric', 'unknown'].includes(verticalDatum) || !['pixel-center', 'grid-node'].includes(registration)) throw new Error('Terrain datum and registration must be explicit');
+    if (options.valid && options.valid.length !== width * height) throw new Error('Terrain validity mask must match the pixels');
+    const heights = new Float32Array(width * height);
+    const valid = new Uint8Array(width * height);
+    for (let index = 0; index < heights.length; index++) {
+        valid[index] = options.valid ? Number(options.valid[index] !== 0) : 1;
+        const offset = index * 4;
+        heights[index] = valid[index] ? pixels[offset] * decoder.rScaler + pixels[offset + 1] * decoder.gScaler + pixels[offset + 2] * decoder.bScaler + decoder.offset : NaN;
+        if (valid[index] && !Number.isFinite(heights[index])) throw new Error('Terrain elevation exceeds the finite Float32 range');
+    }
+    return {width, height, heights, valid, bounds: [bounds[0], bounds[1], bounds[2], bounds[3]], verticalDatum, registration};
+}
+
+/** Bilinear height lookup; outside footprints and no-data neighborhoods return null. */
+export function sampleTerrainHeight(grid: TerrainHeightGrid, position: readonly [number, number]): number | null {
+    const [west, south, east, north] = grid.bounds;
+    if (!position.every(Number.isFinite) || position[0] < west || position[0] > east || position[1] < south || position[1] > north) return null;
+    const pixelCenter = grid.registration === 'pixel-center';
+    const column = snapTerrainSample(Math.max(0, Math.min(grid.width - 1, (position[0] - west) / (east - west) * (pixelCenter ? grid.width : grid.width - 1) - (pixelCenter ? 0.5 : 0))), position[0], west, east, grid.width);
+    const row = snapTerrainSample(Math.max(0, Math.min(grid.height - 1, (north - position[1]) / (north - south) * (pixelCenter ? grid.height : grid.height - 1) - (pixelCenter ? 0.5 : 0))), position[1], south, north, grid.height);
+    const left = Math.floor(column), top = Math.floor(row);
+    const horizontal = column - left, vertical = row - top;
+    const samples = [top * grid.width + left, top * grid.width + Math.min(left + 1, grid.width - 1),
+        Math.min(top + 1, grid.height - 1) * grid.width + left, Math.min(top + 1, grid.height - 1) * grid.width + Math.min(left + 1, grid.width - 1)];
+    const weights = [(1 - horizontal) * (1 - vertical), horizontal * (1 - vertical), (1 - horizontal) * vertical, horizontal * vertical];
+    let height = 0;
+    for (let index = 0; index < samples.length; index++) {
+        if (weights[index] === 0) continue;
+        if (!grid.valid[samples[index]]) return null;
+        height += grid.heights[samples[index]] * weights[index];
+    }
+    return height;
+}
+
+/** Match shared-grid exact-sample semantics at world-scale bounds; do not broaden support beyond 1e-6 pixels. */
+function snapTerrainSample(value: number, coordinate: number, minimum: number, maximum: number, size: number): number {
+    const nearest = Math.round(value);
+    const tolerance = Math.min(1e-6, 8 * Number.EPSILON * Math.max(1, Math.abs(coordinate), Math.abs(minimum), Math.abs(maximum)) / (maximum - minimum) * size);
+    return Math.abs(value - nearest) <= tolerance ? nearest : value;
+}