Common terrain surfaces and elevation queries

setTerrain/getTerrain/queryTerrainElevation use common raster-dem sources, our decoder and the existing real shared-depth/lighting/picking renderer. No display layer is required. Select Mercator first. Registration downloads nothing; terrain binding schedules visible tiles. Exaggeration defaults to 1 and ranges from 0 to 20. Null disables terrain and releases its reference.

import {map} from 'sqsmap';
map.setProjection({type:'mercator'});
map.addSource('dem',{type:'raster-dem',tiles:['https://your-provider/{z}/{x}/{y}.png'],
 encoding:'terrarium',attribution:'Provider credit'});
await map.setTerrain({source:'dem',exaggeration:1.5});
map.setPitch(45);
await map.sqs.flush({render:true});
const config=await map.getTerrain();
const height=await map.queryTerrainElevation([116.4,39.9]);
map.on('terrain',event=>{console.log(event.terrain);});

Common queries return number/null: bilinear decoded meters multiplied by current exaggeration. Disabled, unloaded, nodata or unavailable tiles return null, never implicit zero. Queries read the highest cached level and fetch nothing. Bound source instances remain stable; removing a referenced source conflicts, and disabling releases it. getTerrain is normalized configuration; getSourceInfo supplies actual readiness/errors/revisions. Terrain events contain historical configuration in terrain, or null. Credits participate in getAttributions; callers display them.

Enabling preserves logical camera settings and does not automatically change pitch. Display LOD grids contain up to 33x33 vertices per tile with latitude-scaled meter heights, real triangle normals and matching surface indices. Bilinear data query precision differs from mesh LOD. Conservative CPU mesh/raster/pick accounting is limited to 32 MiB; displayed z has an absolute limit of 1e9 Mercator meters. Shared PNG/elevation cache budgets apply. Style objects support the terrain root; full replacement updates/disables terrain and cancels old tile work.

Current scope is Mercator plus existing GeoJSON circle/line/fill 3D paths. Common tile rasters and hillshade/color-relief now drape in layer order. Registered image/video/canvas convex quads also drape; independent URL raster styles and symbol/heatmap/background combinations retain explicit limits; fill-extrusion is connected within terrain-buildings. Disable terrain before globe. Neighbour DEM sample stitching and adaptive LOD, overlay draping/elevated focus/terrain gesture anchors and overlay queries, and native/mobile device acceptance remain separate work; complete MapLibre terrain compatibility is not claimed.

The desktop map.sources.add local DEM path remains available. Its getTerrain may return TerrainState; queryTerrainElevation returns a TerrainElevation object with raw height, datum and nodata reason, without display exaggeration. Use common map.addSource for consistent cross-platform number/null results. Local file extensions remain capability-dependent. Standalone C ABI reuses source JSON commands setTerrain/getTerrain/queryTerrainElevation, adding no ABI symbols.

Names follow MapLibre setTerrain and elevation query. SqsMap implements its own meshes and rendering.

With common terrain enabled, map.project samples the actual loaded display triangles before projecting to logical pixels. map.unproject intersects the same camera ray with the nearest real surface. Both honor exaggeration, pitch, bearing, padding and DPR. Missing loaded geometry, nodata regions and sky misses fail explicitly instead of substituting zero elevation. Disabling terrain restores flat coordinates. These methods use display LOD geometry, whose sampling precision can differ from the bilinear DEM elevation query. Overlay draping, elevated camera focus and terrain gesture anchors remain separate work.

The complete terrain-coordinate HTML includes every control, roundtrip query and attribution display.

Bounded skirts are connected for shared terrain; walls are excluded from real-surface queries.

Parent tile fallback retains cached ground while child terrain is pending; readiness still reflects actual child data.

Effective tile metadata documents current overrides, actual sizing/DEM decoding and accepted data during refresh waits/failures. Earlier evidence is not relabeled.

The web workbench also supports local single-band DEMs as a 3D surface. The top visible DEM shapes the ground, missing values remain absent, and workspace and engine task Worker restoration are supported. SeeLocal DEM 3D surface.