@bitruvius/geo-core 0.3.1

package/dist/geo/ecef.d.ts

@@ -0,0 +1,70 @@
+/**
+ * WGS84 geocentric (ECEF) ↔ geodetic, plus the ECEF→ENU rotation used to rebase
+ * 3D-Tiles content near a scene anchor before handing it to a web map. Pure math
+ * (no DOM/GL); composes in f64. Reuses {@link fromBasis}/{@link fromTranslation}/
+ * {@link multiply} from `./mat4`; pairs with `./mercator`'s `placementMatrix` to
+ * complete ECEF → ENU(meters) → mercator.
+ */
+import type { Mat4 } from './mat4';
+/** A 3-component vector `[x, y, z]` (ECEF or ENU meters, per context). */
+export type Vec3 = readonly [number, number, number];
+/** A geodetic position on the WGS84 ellipsoid. */
+export interface Geodetic {
+    /** Longitude in degrees. */ lng: number;
+    /** Latitude in degrees. */ lat: number;
+    /** Height in meters above the WGS84 ellipsoid. */ height: number;
+}
+/**
+ * Geodetic → WGS84 geocentric (ECEF) meters.
+ * @param lngDeg - Longitude in degrees.
+ * @param latDeg - Latitude in degrees.
+ * @param h - Height in meters above the WGS84 ellipsoid.
+ * @returns ECEF `[x, y, z]` in meters.
+ */
+export declare function geodeticToEcef(lngDeg: number, latDeg: number, h: number): Vec3;
+/**
+ * WGS84 geocentric (ECEF) → geodetic, via the Bowring closed-form solution.
+ * @param x - ECEF X in meters.
+ * @param y - ECEF Y in meters.
+ * @param z - ECEF Z in meters.
+ * @returns {@link Geodetic} (lng/lat degrees, height meters above the ellipsoid).
+ */
+export declare function ecefToGeodetic(x: number, y: number, z: number): Geodetic;
+/**
+ * Build the matrix that maps ECEF (meters) → local East-North-Up (meters) at `anchor`:
+ * `enu = R · (p − anchor)`, where R's rows are the East / North / Up basis vectors
+ * expressed in ECEF.
+ * @param anchor - The ENU origin in ECEF meters.
+ * @param lngDeg - Anchor longitude in degrees (orients the East/North axes).
+ * @param latDeg - Anchor latitude in degrees.
+ * @returns A column-major f64 {@link Mat4} (ECEF → ENU meters).
+ */
+export declare function enuFromEcefMatrix(anchor: Vec3, lngDeg: number, latDeg: number): Mat4;
+/**
+ * glTF y-up → 3D-Tiles z-up (rotation +90° about X): (x,y,z) → (x,−z,y). 3D Tiles
+ * applies this to glTF content before the tile transform; Esri's glb carries an
+ * inverse node matrix that cancels it (content stored z-up).
+ * @internal
+ */
+export declare const Y_UP_TO_Z_UP: Mat4;
+/**
+ * Compose the matrix that takes glb-content vertices into the shared local ENU (meters)
+ * frame: `enuFromEcef · tileTransform · (yUpToZUp · nodeMatrix)`. A renderer then
+ * applies the mercator placement once to all content already in this frame.
+ * @param enuFromEcef - ECEF → scene ENU meters (from {@link enuFromEcefMatrix}).
+ * @param tileTransform - The cumulative tile transform (tile-local → ECEF).
+ * @param nodeMatrix - The glTF node's world matrix (glb root → primitive node).
+ * @param upAxis - Up-axis of the glb CONTENT, i.e. 3D Tiles' `asset.gltfUpAxis`. `'y'` — the
+ * spec default, and the default here — applies {@link Y_UP_TO_Z_UP}; `'z'` means the content
+ * is ALREADY z-up, so the flip is skipped.
+ *
+ * Applying the flip to z-up content rotates it 90° about X **inside its tile-local frame**,
+ * about that frame's origin rather than about the geometry. For a tile whose local
+ * coordinates sit tens of km from that origin — normal for a `box` volume with a per-tile
+ * `transform` — the content is thrown tens of km sideways and tens of km below the
+ * ellipsoid, so it draws for a frame and is then buried. Publishers declaring `Z` are a
+ * minority (Esri's `3DTilesServer`), which is why this went unnoticed: the default-`Y`
+ * datasets were all correct.
+ * @returns A column-major f64 {@link Mat4} (glb-local → scene ENU meters).
+ */
+export declare function tileToEnu(enuFromEcef: Mat4, tileTransform: Mat4, nodeMatrix: Mat4, upAxis?: 'y' | 'z'): Mat4;

package/dist/geo/hard-edges.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Extract a mesh's **hard edges** — the lines a person would draw if asked to sketch the model.
+ *
+ * @remarks
+ * No I3S or 3D Tiles service ships edge geometry; a building arrives as a triangle soup and the
+ * edges have to be derived from it. Two kinds count:
+ *
+ * - **Boundary** edges, used by exactly one triangle. These are the silhouette of an open surface.
+ * - **Crease** edges, where the two triangles sharing the edge meet at more than `creaseAngleDeg`.
+ *   These are the corners of a box, the eaves of a roof, the sill of a window.
+ *
+ * Everything else is tessellation — the diagonal splitting a flat wall into two triangles — and
+ * drawing it is the single most obvious way edge rendering looks wrong: the model reads as a
+ * wireframe rather than as a building.
+ *
+ * Two details matter more than they look:
+ *
+ * **Welding.** Uncompressed I3S geometry (and de-indexed Draco) repeats each position per triangle,
+ * so nothing shares vertices by index. Without welding by position, *every* edge looks like a
+ * boundary edge and the entire mesh draws as a wireframe. Positions are quantized to 0.1 mm and
+ * matched on that.
+ *
+ * **Welding stops at the feature.** Terraced houses share a coincident wall. Welded across
+ * features, that wall pairs up, reads as an interior edge and vanishes, taking the line between
+ * two adjacent buildings with it. So the feature id is part of the weld identity: each feature is
+ * outlined as if it were alone.
+ *
+ * Pure and allocation-conscious: this runs in the decode worker, once per tile, never per frame.
+ */
+/** What to extract edges from. */
+export interface HardEdgeInput {
+    /** 3·N vertex positions. */
+    readonly positions: Float32Array;
+    /** Triangle indices; omit for a non-indexed soup (positions are read three at a time). */
+    readonly indices?: Uint16Array | Uint32Array;
+    /** Per-VERTEX feature ordinal. When present, welding never crosses features. */
+    readonly featureIds?: Uint32Array;
+    /** Dihedral angle above which a shared edge counts as a crease. Default 25°. */
+    readonly creaseAngleDeg?: number;
+    /** Cap on emitted edges. Default 400 000. */
+    readonly maxEdges?: number;
+}
+/** Extracted edges as a flat line list. */
+export interface HardEdges {
+    /** 6·count: `[x0,y0,z0, x1,y1,z1]` per edge, in the same frame as the input positions. */
+    readonly positions: Float32Array;
+    /** Per-EDGE feature ordinal; present iff the input carried `featureIds`. Lets a renderer hide
+     *  an edge along with the feature it belongs to. */
+    readonly featureIds?: Uint32Array;
+    /**
+     * 2·count original VERTEX indices, one per endpoint.
+     *
+     * @remarks
+     * So a caller can gather any parallel per-vertex attribute the extractor knows nothing about.
+     * The one that matters today is the baked web-mercator offset: a planet-scale tile is placed
+     * from `mercatorOffset` rather than from ENU positions, so edges built only from ENU would
+     * float away from the buildings they outline.
+     */
+    readonly endpoints: Uint32Array;
+    readonly count: number;
+    /** True when {@link HardEdgeInput.maxEdges} cut the result short. */
+    readonly truncated: boolean;
+}
+/**
+ * Derive the hard edges of a triangle mesh.
+ *
+ * @param input - The geometry and extraction thresholds ({@link HardEdgeInput}).
+ * @returns The line list, or `null` when there is nothing to draw (empty, degenerate, or under
+ *   one triangle) — so a caller can skip allocating and uploading an empty buffer.
+ */
+export declare function extractHardEdges(input: HardEdgeInput): HardEdges | null;

package/dist/geo/mat4.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Minimal column-major 4x4 matrix math, following the standard WebGL /
+ * gl-matrix convention: storage is column-major (`m[col*4 + row]`),
+ * `multiply(a, b)` returns `a*b`, and matrices act on column vectors on
+ * the right (`gl_Position = P * V * M * v`).
+ *
+ * Backed by **Float64Array**: mercator world coordinates (~0.5) and
+ * meter-scale offsets (~1e-8) must coexist in the same matrix, which f32
+ * cannot resolve (R3). CPU-side composition (placement, view-matrix
+ * recovery, covariance transforms) stays f64; only the final GPU uniform
+ * is downcast via `toFloat32` at the WebGL boundary.
+ *
+ * Independently implemented from textbook linear algebra — no third-party
+ * renderer code.
+ */
+/** A column-major 4×4 matrix: a length-16 `Float64Array` (`m[col*4 + row]`). */
+export type Mat4 = Float64Array;
+/** A column-major 3×3 matrix: a length-9 `Float64Array` (`m[col*3 + row]`). */
+export type Mat3 = Float64Array;
+/** A 4-component vector `[x, y, z, w]`. */
+export type Vec4 = readonly [number, number, number, number];
+/** Downcast a CPU f64 matrix to a new `Float32Array` for a WebGL uniform.
+ *  @param m - The f64 matrix. @returns A new length-16 `Float32Array`. */
+export declare function toFloat32(m: Mat4): Float32Array;
+/** Downcast into a caller-owned `Float32Array` (no allocation) — for per-frame uniform writes.
+ *  @param m - The f64 source. @param out - The length-16 destination (written in place).
+ *  @returns `out`. */
+export declare function toFloat32Into(m: Mat4, out: Float32Array): Float32Array;
+/** Copy any array-like (e.g. a viewer's matrix) into a new f64 {@link Mat4}.
+ *  @param a - A length-16 column-major array-like. @returns A new {@link Mat4}. */
+export declare function fromArrayLike(a: ArrayLike<number>): Mat4;
+/** @returns A new 4×4 identity {@link Mat4}. */
+export declare function identity(): Mat4;
+/** @param a - The matrix to copy. @returns A new {@link Mat4} with the same values. */
+export declare function clone(a: Mat4): Mat4;
+/** Matrix product `out = a · b` (column-major; column vectors on the right).
+ *  @param a - Left matrix. @param b - Right matrix.
+ *  @param out - Optional destination (defaults to a new {@link Mat4}); may not alias `a`/`b`.
+ *  @returns `out`. */
+export declare function multiply(a: Mat4, b: Mat4, out?: Mat4): Mat4;
+/** Transpose: `out = aᵀ`.
+ *  @param a - The matrix. @param out - Optional destination. @returns `out`. */
+export declare function transpose(a: Mat4, out?: Mat4): Mat4;
+/** Extract the upper-left 3×3 (the linear part used for covariance/normals).
+ *  @param a - The 4×4 matrix. @param out - Optional length-9 {@link Mat3} destination.
+ *  @returns `out`. */
+export declare function mat3FromMat4(a: Mat4, out?: Mat3): Mat3;
+/** Transform a 4-vector: `out = m · v` (column vector).
+ *  @param m - The matrix. @param v - The {@link Vec4}. @returns The transformed `[x,y,z,w]`. */
+export declare function multiplyVec4(m: Mat4, v: Vec4): [number, number, number, number];
+/** Build a translation matrix.
+ *  @param x - X translation. @param y - Y translation. @param z - Z translation.
+ *  @returns A new {@link Mat4} translating by `(x, y, z)`. */
+export declare function fromTranslation(x: number, y: number, z: number): Mat4;
+/** Build a (possibly non-uniform) scaling matrix.
+ *  @param x - X scale. @param y - Y scale. @param z - Z scale.
+ *  @returns A new {@link Mat4} scaling by `(x, y, z)`. */
+export declare function fromScaling(x: number, y: number, z: number): Mat4;
+/** Build a rotation about the +X axis (right-handed: counter-clockwise when +X
+ *  points at the viewer; gl-matrix convention, column-major).
+ *  @param rad - The rotation angle in radians.
+ *  @param out - Optional destination (defaults to a new {@link Mat4}).
+ *  @returns `out`. */
+export declare function fromRotationX(rad: number, out?: Mat4): Mat4;
+/** Build a rotation about the +Y axis (right-handed: counter-clockwise when +Y
+ *  points at the viewer; gl-matrix convention, column-major).
+ *  @param rad - The rotation angle in radians.
+ *  @param out - Optional destination (defaults to a new {@link Mat4}).
+ *  @returns `out`. */
+export declare function fromRotationY(rad: number, out?: Mat4): Mat4;
+/** Build a rotation about the +Z axis (right-handed: counter-clockwise when +Z
+ *  points at the viewer; gl-matrix convention, column-major).
+ *  @param rad - The rotation angle in radians.
+ *  @param out - Optional destination (defaults to a new {@link Mat4}).
+ *  @returns `out`. */
+export declare function fromRotationZ(rad: number, out?: Mat4): Mat4;
+/**
+ * Full general 4×4 inverse via cofactors: `out = a⁻¹`.
+ * @param a - The matrix to invert.
+ * @param out - Optional destination (defaults to a new {@link Mat4}).
+ * @returns `out`.
+ * @throws Error `'mat4.invert: singular matrix'` when the determinant is `0` or
+ *   non-finite (a uniformly tiny determinant — e.g. the mercator meter placement,
+ *   det ~1e-23 — is well-conditioned and inverts fine; only true singularities throw).
+ */
+export declare function invert(a: Mat4, out?: Mat4): Mat4;
+/** Apply an affine 4×4 to a point (`w = 1`).
+ *  @param m - The matrix. @param p - The point `[x, y, z]`.
+ *  @returns The transformed point `[x, y, z]`. */
+export declare function transformPoint(m: Mat4, p: readonly [number, number, number]): [number, number, number];
+/** Apply only the 3×3 linear part of an affine 4×4 to a direction (no translation).
+ *  @param m - The matrix. @param d - The direction `[x, y, z]`.
+ *  @returns The rotated/scaled direction `[x, y, z]` (not renormalized). */
+export declare function transformDir(m: Mat4, d: readonly [number, number, number]): [number, number, number];
+/**
+ * Orthographic projection (column-major), mapping the view-space box
+ * x∈[left,right], y∈[bottom,top], z∈[-far,-near] (right-handed; the view looks down −Z, so
+ * `near`/`far` are positive distances) into NDC [-1,1]³. Used to fit a directional (sun) light's
+ * frustum to a scene. Matches the gl-matrix convention.
+ *
+ * @param left - View-space left bound.
+ * @param right - View-space right bound.
+ * @param bottom - View-space bottom bound.
+ * @param top - View-space top bound.
+ * @param near - Near plane distance (positive, in front of the camera).
+ * @param far - Far plane distance (positive).
+ * @param out - Optional destination (defaults to a new {@link Mat4}).
+ * @returns `out`.
+ */
+export declare function orthoInto(left: number, right: number, bottom: number, top: number, near: number, far: number, out?: Mat4): Mat4;
+/** Build a column-major 4×4 from three basis columns + a translation column (row 3 = `[0,0,0,1]`).
+ *  @param col0 - First basis column. @param col1 - Second. @param col2 - Third.
+ *  @param translation - The translation column.
+ *  @param out - Optional destination. @returns `out`. */
+export declare function fromBasis(col0: readonly [number, number, number], col1: readonly [number, number, number], col2: readonly [number, number, number], translation: readonly [number, number, number], out?: Mat4): Mat4;

package/dist/geo/measure.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Geodesic measurement math — distances, bearings, interpolation, and polygon
+ * area/perimeter over the WGS84 ellipsoid. Everything works in local ENU metres
+ * via the exact ECEF↔ENU primitives in `./ecef` (chord-vs-arc error is d³/24R² —
+ * ~2 mm at 10 km, ~3 m at 100 km — matching the SDK's city-scale precision
+ * philosophy; the bound is documented per function). Pure f64 math, no DOM/GL.
+ */
+import { type Geodetic } from './ecef';
+/** A measured position: lng/lat in degrees, `height` in metres (default 0 where optional). */
+export interface MeasurePoint {
+    lng: number;
+    lat: number;
+    height?: number;
+}
+/**
+ * The local ENU offset (metres) of `b` relative to `a` — the workhorse the other
+ * measures build on: `[east, north, up]` in the tangent frame at `a`.
+ * @param a - The origin point.
+ * @param b - The target point.
+ * @returns `[east, north, up]` metres.
+ */
+export declare function enuOffset(a: MeasurePoint, b: MeasurePoint): [number, number, number];
+/**
+ * Direct (slope) 3D distance between two points in metres — the straight chord
+ * through space, including the height difference.
+ */
+export declare function distance3d(a: MeasurePoint, b: MeasurePoint): number;
+/**
+ * Horizontal (map-plane) distance in metres — the ground component, heights
+ * ignored. Chord error vs the true geodesic arc is `d³/24R²` (~2 mm at 10 km,
+ * ~3 m at 100 km).
+ */
+export declare function horizontalDistance(a: MeasurePoint, b: MeasurePoint): number;
+/** Signed height difference `b.height − a.height` in metres. */
+export declare function verticalDelta(a: MeasurePoint, b: MeasurePoint): number;
+/**
+ * Initial compass bearing from `a` to `b`, degrees clockwise from north in `[0, 360)`.
+ */
+export declare function bearingDeg(a: MeasurePoint, b: MeasurePoint): number;
+/**
+ * Great-circle distance on the mean sphere (metres) — the long-range cross-check
+ * and the axis measure for long elevation profiles. Haversine on {@link EARTH_RADIUS}.
+ */
+export declare function haversineDistance(a: MeasurePoint, b: MeasurePoint): number;
+/**
+ * Interpolate between two points at fraction `t` (0 = `a`, 1 = `b`): positions
+ * lerp in ECEF then renormalize to the surface direction (antimeridian- and
+ * pole-safe); heights lerp linearly and independently.
+ * @param a - Start point. @param b - End point. @param t - Fraction in `[0, 1]`.
+ * @returns The interpolated {@link Geodetic} (lng/lat degrees, height metres).
+ */
+export declare function interpolatePosition(a: MeasurePoint, b: MeasurePoint, t: number): Geodetic;
+/**
+ * Total polyline length in metres.
+ * @param points - The vertices (≥ 2 for a nonzero result).
+ * @param mode - `'3d'` sums {@link distance3d} per segment; `'horizontal'` sums
+ * {@link horizontalDistance}.
+ */
+export declare function polylineLength(points: readonly MeasurePoint[], mode: '3d' | 'horizontal'): number;
+/**
+ * Planar polygon area in square metres — the ring is projected into the ENU
+ * tangent plane at its centroid (heights ignored) and measured with the shoelace
+ * formula. Exact to city scale; the tangent-plane error grows with extent and is
+ * negligible below ~50 km. Vertex order (CW/CCW) doesn't matter (absolute value);
+ * self-intersecting rings are not supported.
+ * @param ring - The polygon vertices (unclosed; ≥ 3 for a nonzero result).
+ */
+export declare function polygonAreaM2(ring: readonly MeasurePoint[]): number;
+/**
+ * A raster grid of cell CENTRES (lng/lat) inside a polygon — the sampling stations for an
+ * area-integral measure (e.g. volume = Σ over cells of fill × cellArea). Cells are square in a
+ * local planar frame at the ring's mean latitude; the long bbox axis gets ≤128 cells (≥0.25 m),
+ * and the total is capped at `maxCells` (cell size grows to fit). Pure — the caller samples a
+ * surface/DEM at the returned centres and integrates. City-scale accuracy (same tangent-plane
+ * philosophy as {@link polygonAreaM2}).
+ *
+ * The `grid` descriptor lets a caller scatter the sampled values back into a full raster (for a
+ * heatmap / contour overlay): `centers[k]` lives in row-major cell `cellIndex[k]` (`= jy·nx + ix`)
+ * of an `nx × ny` grid whose cell `(ix, jy)` centre is `[minLng+(ix+0.5)·dLng, minLat+(jy+0.5)·dLat]`
+ * (`jy` counts NORTH from the bbox's south edge). Cells outside the ring have no `centers` entry.
+ * @param ring - Polygon vertices (unclosed; ≥ 3).
+ * @param maxCells - Hard cap on the returned cell count (default 8192).
+ * @returns `centers` (cell centres strictly inside the ring), the uniform per-cell area (m²), and the
+ * `grid` descriptor (`nx`, `ny`, SW origin `minLng`/`minLat`, per-cell steps `dLng`/`dLat`, and the
+ * `cellIndex` of each centre).
+ */
+export declare function volumeGridCells(ring: readonly MeasurePoint[], maxCells?: number): {
+    centers: {
+        lng: number;
+        lat: number;
+    }[];
+    cellAreaM2: number;
+    grid: {
+        nx: number;
+        ny: number;
+        minLng: number;
+        minLat: number;
+        dLng: number;
+        dLat: number;
+        cellIndex: number[];
+    };
+};
+/**
+ * Marching-squares iso-lines of a scalar raster, as independent line SEGMENTS in fractional grid
+ * coordinates. Grid sample `field[j·nx + i]` sits at continuous coordinate `(i, j)`; a returned
+ * point `[fi, fj]` maps to lng/lat as `[minLng+(fi+0.5)·dLng, minLat+(fj+0.5)·dLat]` (matching
+ * {@link volumeGridCells}'s cell-centre convention). Cells touching a `NaN` sample are skipped, so
+ * contours never cross the polygon boundary. Pure & allocation-light (no stitching — abutting
+ * segments render as a continuous line).
+ * @param field - Row-major `nx × ny` samples (`NaN` = no data).
+ * @param nx - Columns.
+ * @param ny - Rows.
+ * @param level - Iso value.
+ * @returns Segments `[[fi0, fj0], [fi1, fj1]]` in fractional grid coordinates.
+ */
+export declare function contourSegments(field: ReadonlyArray<number> | Float32Array, nx: number, ny: number, level: number): [[number, number], [number, number]][];
+/**
+ * Choose a "nice" contour interval (a 1-2-5 multiple of `baseIntervalM`) and the iso levels spanning
+ * `(0, maxFillM]`, targeting at most `maxLines` lines. Base interval is the unit's step — 1 m
+ * (metric) or 0.3048 m (1 ft, imperial) — widened to 2/5/10/… for tall piles.
+ * @param maxFillM - Peak value of the field (metres).
+ * @param baseIntervalM - The unit's base contour step (metres).
+ * @param maxLines - Cap on the number of levels (default 12).
+ * @returns The chosen `intervalM` and the ascending `levels` (metres).
+ */
+export declare function contourLevels(maxFillM: number, baseIntervalM: number, maxLines?: number): {
+    intervalM: number;
+    levels: number[];
+};
+/**
+ * Polygon perimeter in metres (horizontal, ring closed automatically).
+ * @param ring - The polygon vertices (unclosed).
+ */
+export declare function polygonPerimeterM(ring: readonly MeasurePoint[]): number;

package/dist/geo/mercator.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Standard Web Mercator conversions, matching MapLibre's
+ * `MercatorCoordinate` exactly so this core math is interchangeable
+ * with the viewer's own conversion. Implemented from the public Web
+ * Mercator definition (not from any renderer library).
+ *
+ * Mercator unit square: x,y in [0,1] over the world; z is altitude in
+ * the same units (meters / circumferenceAtLatitude). A scene authored
+ * in local meters is placed by `placementMatrix`.
+ */
+import { type Mat4 } from './mat4';
+/** Mean Earth radius (m) used for the mercator circumference. @internal */
+export declare const EARTH_RADIUS = 6371008.8;
+/** Earth circumference (m) at the equator (`2π·EARTH_RADIUS`). @internal */
+export declare const EARTH_CIRCUMFERENCE: number;
+/** A geographic anchor placing a local-meters scene in the world. */
+export interface GeoAnchor {
+    /** Longitude in degrees. */
+    readonly lng: number;
+    /** Latitude in degrees. */
+    readonly lat: number;
+    /** Height in meters above the WGS84 ellipsoid. */
+    readonly altitude: number;
+}
+/** A point in MapLibre-compatible web-mercator: `x`,`y` in `[0,1]` over the world,
+ *  `z` altitude in the same normalized units (meters / circumferenceAtLatitude). */
+export interface MercatorXYZ {
+    /** Normalized mercator X in `[0,1]` (west→east). */
+    readonly x: number;
+    /** Normalized mercator Y in `[0,1]` (north→south). */
+    readonly y: number;
+    /** Normalized mercator Z (altitude in mercator units). */
+    readonly z: number;
+}
+/** World circumference (m) at a latitude (shrinks toward the poles by `cos lat`).
+ *  @param lat - Latitude in degrees.
+ *  @returns Circumference in meters. */
+export declare function circumferenceAtLatitude(lat: number): number;
+/** Longitude (degrees) → normalized mercator X in `[0,1]`. */
+export declare function mercatorXfromLng(lng: number): number;
+/** Latitude (degrees) → normalized mercator Y in `[0,1]`. */
+export declare function mercatorYfromLat(lat: number): number;
+/** Altitude (m above ellipsoid) → normalized mercator Z at a latitude.
+ *  @param altitude - Height in meters. @param lat - Latitude in degrees. */
+export declare function mercatorZfromAltitude(altitude: number, lat: number): number;
+/** Normalized mercator X in `[0,1]` → longitude (degrees). Inverse of {@link mercatorXfromLng}. */
+export declare function lngFromMercatorX(x: number): number;
+/** Normalized mercator Y in `[0,1]` → latitude (degrees). Inverse of {@link mercatorYfromLat}
+ *  (the Gudermannian). */
+export declare function latFromMercatorY(y: number): number;
+/** Normalized mercator Z → altitude in meters at a latitude. Inverse of {@link mercatorZfromAltitude}.
+ *  @param z - Normalized mercator Z. @param lat - Latitude in degrees. */
+export declare function altitudeFromMercatorZ(z: number, lat: number): number;
+/** Mercator units per meter at a latitude (latitude-dependent — never a constant); the
+ *  linear scale that places a local-meters scene into mercator.
+ *  @param lat - Latitude in degrees. @returns Mercator units per meter. */
+export declare function meterInMercatorCoordinateUnits(lat: number): number;
+/** Convert lng/lat (degrees) + altitude (meters) to {@link MercatorXYZ}.
+ *  @param lngLat - `{ lng, lat }` in degrees.
+ *  @param altitude - Height in meters above the ellipsoid (default 0).
+ *  @returns The normalized web-mercator coordinate. */
+export declare function mercatorFromLngLat(lngLat: {
+    lng: number;
+    lat: number;
+}, altitude?: number): MercatorXYZ;
+/** Options for {@link placementMatrix}. */
+export interface PlacementOptions {
+    /**
+     * Optional basis rotation (column-major {@link Mat4}) applied BEFORE the meter
+     * scaling, to reconcile the asset's axis convention (e.g. Y-up) with the mercator
+     * frame (x east, y south, z up). Defaults to identity — i.e. the local frame is
+     * already x-east / y-south / z-up in meters.
+     */
+    readonly basis?: Mat4;
+}
+/**
+ * Build the model matrix that maps a local-meters scene anchored at `anchor` into
+ * web-mercator world space: `T(merc) · S(meter) · [basis]`.
+ *
+ * @remarks
+ * The meter scaling is latitude-dependent (see {@link meterInMercatorCoordinateUnits});
+ * the same linear part is what the splat covariance transform must include so ellipsoids
+ * scale with the map.
+ *
+ * @param anchor - Where the scene is anchored ({@link GeoAnchor}: lng/lat degrees, altitude meters).
+ * @param opts - Optional {@link PlacementOptions} (axis `basis`).
+ * @returns A column-major f64 {@link Mat4} (local meters → mercator).
+ *
+ * @example
+ * ```ts
+ * const model = placementMatrix({ lng: -73.99, lat: 40.75, altitude: 0 });
+ * gl.uniformMatrix4fv(uModel, false, toFloat32(model));
+ * ```
+ */
+export declare function placementMatrix(anchor: GeoAnchor, opts?: PlacementOptions): Mat4;

package/dist/geo/model-placement.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Friendly model placement — the user-facing vocabulary that replaces raw
+ * `Mat4` basis math for placing a single local-meters model (gaussian splat,
+ * point cloud, …) on the map.
+ *
+ * A capture's coordinate frame is a format/pipeline property (SPZ-style
+ * assets are typically Y-up, LAS/BVC are Z-up), its heading/scale are
+ * per-capture tuning, and MapLibre's mercator frame quirks (Y grows SOUTH,
+ * so the frame is left-handed) are an SDK implementation detail. This module
+ * keeps each concern in its place: `ModelPlacement` exposes only
+ * degrees/meters/presets, and `placementBasis` composes the correct
+ * column-major basis — including the internal mercator Y-flip the user must
+ * never see.
+ */
+import { type Mat4 } from './mat4';
+import { type GeoAnchor } from './mercator';
+import type { LocalBounds } from '../dequant/tile-bounds';
+export type { LocalBounds } from '../dequant/tile-bounds';
+/**
+ * Which SOURCE axis points up in the asset's own frame — a format/pipeline
+ * property, never user matrix math. `'z'` = already Z-up (LAS/BVC native);
+ * `'y'` = glTF/SPZ-style Y-up; `'-y'` = COLMAP/3DGS Y-down; `'x' | '-x' |
+ * '-z'` cover exotic captures.
+ */
+export type UpAxis = 'z' | 'y' | '-y' | 'x' | '-x' | '-z';
+/**
+ * Which local point of the model sits exactly at the `GeoAnchor` — the
+ * vertical seat is an explicit top/middle/bottom choice:
+ * `'center'` (default) = the model's center at the anchor altitude;
+ * `'bottom-center'` = base at the anchor altitude ("sits on the ground");
+ * `'top-center'` = top at the anchor altitude (hang from a height);
+ * `'origin'` = the capture's raw local origin (legacy behavior); a tuple =
+ * an explicit source-space point in meters (deterministic — skips bounds
+ * entirely; useful for pinning production placements).
+ *
+ * @remarks
+ * When the bounds carry robust percentiles (`LocalBounds.p05/p50/p95` — the
+ * layers always compute them), anchoring is OUTLIER-PROOF: `'center'` is the
+ * per-axis median and bottom/top are the 5th/95th percentiles along the up
+ * axis. Gaussian-splat captures surround their subject with a huge sparse
+ * halo of background splats (±200 m around an 8 m subject is typical), so
+ * raw min/max anchoring would seat the halo, not the subject.
+ */
+export type AnchorPoint = 'center' | 'bottom-center' | 'top-center' | 'origin' | readonly [number, number, number];
+/**
+ * Friendly per-capture placement — everything a user tunes to seat a model
+ * on the map, with no matrices. Shared by every single-model layer
+ * (`BvcMapLibreLayer`, `SpzMapLibreLayer`, …).
+ */
+export interface ModelPlacement {
+    /** Up axis of the source asset (`UpAxis`). Default `'z'` (layers may document a format-specific default). */
+    readonly upAxis?: UpAxis;
+    /** Heading in degrees clockwise from north viewed from above (0 = the model's local +y faces north).
+     *  Same semantics as `GeodeticInstance.heading`. Default 0. */
+    readonly heading?: number;
+    /** Pitch in degrees about the model's local x axis (east at heading 0) — positive tips the
+     *  +y (north-facing) side up. A leveling aid for off-level captures. Default 0. */
+    readonly pitch?: number;
+    /** Roll in degrees about the model's local y axis (north at heading 0) — positive lowers the
+     *  +x (east-facing) side. A leveling aid for off-level captures. Default 0. */
+    readonly roll?: number;
+    /** Unitless scale: uniform number or per-axis `[x, y, z]` in the UP-FIXED frame (z = height,
+     *  regardless of `ModelPlacement.upAxis`). Same shape as `GeodeticInstance.scale`. Default 1. */
+    readonly scale?: number | readonly [number, number, number];
+    /** Which local point sits at the anchor (`AnchorPoint`: top/middle/bottom,
+     *  origin, or an explicit point). Default `'center'`. */
+    readonly anchorPoint?: AnchorPoint;
+}
+/**
+ * `diag(1, −1, 1)` — right-handed local ENU-meters → MapLibre's left-handed
+ * mercator frame (mercator Y grows SOUTH). The ONLY handedness flip in the
+ * placement composition (det −1); applied internally by
+ * `placementBasis`, never user-visible.
+ */
+export declare const MERCATOR_Y_FLIP: Mat4;
+/**
+ * Pure rotations (det +1) taking each source frame to x-east / y-north /
+ * z-up. Exact signed permutations (literals, not trig — no 1e-17 residue);
+ * `'y'` equals the glTF/SPZ `Y_UP_TO_Z_UP` rotation (+90° about X).
+ */
+export declare const UP_AXIS_BASIS: Readonly<Record<UpAxis, Mat4>>;
+/**
+ * The signed unit vector of an `UpAxis` in the model's SOURCE frame — the
+ * direction "height" runs along before the up-axis fix (e.g. `'y'` →
+ * `[0, 1, 0]`, `'-y'` → `[0, -1, 0]`).
+ *
+ * @param upAxis - The source up axis.
+ * @returns The signed unit source-frame up vector.
+ */
+export declare function upAxisVector(upAxis: UpAxis): readonly [number, number, number];
+/**
+ * Resolve the SOURCE-space point that `placementBasis` pins to the anchor.
+ * `'bottom-center'`/`'top-center'` are sign-aware along the source axis that
+ * maps to up (e.g. `'-y'` → bottom = the source MAX y).
+ *
+ * @remarks
+ * Robust percentiles win when the bounds carry them (`p50` for centers, the
+ * up-axis `p05`/`p95` for bottom/top) — see the `AnchorPoint` remarks on
+ * outlier halos. Plain AABBs fall back to midpoint/min/max.
+ *
+ * @param bounds - The model's bounds in source coordinates (`LocalBounds`).
+ * @param upAxis - The source up axis (decides which axis top/bottom runs along).
+ * @param anchorPoint - The requested `AnchorPoint`.
+ * @returns The source-space point (meters) to place at the anchor.
+ */
+export declare function anchorPointSource(bounds: LocalBounds, upAxis: UpAxis, anchorPoint: AnchorPoint): [number, number, number];
+/**
+ * Build the local→mercator basis from a friendly `ModelPlacement`:
+ *
+ * `B = MERCATOR_Y_FLIP · Rz(−heading) · Rx(pitch) · Ry(roll) · S(scale) · U(upAxis) · T(−anchorSource)`
+ *
+ * @remarks
+ * The innermost recenter translation is in SOURCE coordinates, so `B ·
+ * anchorSource = 0` exactly — heading/pitch/roll/scale pivot about the
+ * anchored point by construction. With every field defaulted and
+ * `anchorSource` at the origin, the result is byte-identical to the legacy
+ * default basis `diag(1, −1, 1)`.
+ *
+ * @param placement - The friendly placement fields (all optional; see `ModelPlacement`).
+ * @param anchorSource - The source-space point pinned to the anchor (from
+ *   `anchorPointSource`); default `[0, 0, 0]`.
+ * @returns A column-major f64 `Mat4` basis for `placementMatrix`.
+ */
+export declare function placementBasis(placement?: ModelPlacement, anchorSource?: readonly [number, number, number]): Mat4;
+/**
+ * The one-call model matrix every single-model layer uses:
+ * `T(merc) · S(meterPerMercUnit) · placementBasis(placement, anchorSource)`.
+ *
+ * @remarks
+ * `bounds` are only needed for the `'center'` / `'bottom-center'` anchor
+ * modes; when they are not yet known (tiles still streaming) pass `null` and
+ * rebuild once they are — the fallback anchors the source origin, exactly the
+ * legacy behavior. `'origin'` and explicit-tuple anchor points never consult
+ * bounds.
+ *
+ * @param anchor - Where the model sits (`GeoAnchor`: lng/lat degrees, altitude meters).
+ * @param placement - The friendly placement (`ModelPlacement`); default all-defaults.
+ * @param bounds - The model's source-space AABB, or `null`/omitted before it is known.
+ * @returns A column-major f64 `Mat4` (source coordinates → mercator).
+ */
+export declare function modelPlacementMatrix(anchor: GeoAnchor, placement?: ModelPlacement, bounds?: LocalBounds | null): Mat4;