@bitruvius/geo-core 0.3.1

package/dist/contracts/mesh.d.ts

@@ -0,0 +1,304 @@
+/**
+ * The shared **mesh vocabulary** for OGC 3D-Tiles / I3S textured-mesh streaming —
+ * the analog of {@link GltfSplatCloud} / `PackedPointTile` for triangle (and
+ * point) meshes. It lives in core so the parser (`@bitruvius/gltf`, produces the
+ * normalized model), the ENU packer ({@link packMeshEnu}), the engine, and the
+ * renderer (`@bitruvius/mesh`, consumes the packed model) all depend only on core.
+ *
+ * Two layers:
+ *   - **Normalized** (glb-local, indirection-free) — what the parser emits.
+ *   - **Packed** (ENU-rebased, f32-safe, GPU-ready) — what the renderer uploads.
+ *
+ * The material model is the **unlit-now / PBR-later seam**: the MVP renderer reads
+ * only baseColor + alpha; the metallic/roughness/normal/emissive/occlusion fields
+ * are carried so the Phase-2 PBR path is purely additive.
+ */
+import type { Mat4 } from '../geo/mat4';
+import type { TypedArray } from './mesh-codecs';
+import type { FeaturePropertiesData } from './feature-metadata';
+export type AlphaMode = 'OPAQUE' | 'MASK' | 'BLEND';
+export type PrimitiveMode = 'TRIANGLES' | 'POINTS';
+/** A texture binding: which texture + which UV set (TEXCOORD_n). */
+export interface NormalizedTextureRef {
+    readonly textureIndex: number;
+    readonly texCoord: number;
+}
+export interface NormalizedMaterial {
+    readonly baseColorFactor: readonly [number, number, number, number];
+    readonly baseColorTexture?: NormalizedTextureRef;
+    readonly alphaMode: AlphaMode;
+    readonly alphaCutoff: number;
+    readonly doubleSided: boolean;
+    /** KHR_materials_unlit present (photogrammetry / reality meshes). */
+    readonly unlit: boolean;
+    readonly metallicFactor: number;
+    readonly roughnessFactor: number;
+    readonly metallicRoughnessTexture?: NormalizedTextureRef;
+    readonly normalTexture?: NormalizedTextureRef & {
+        readonly scale: number;
+    };
+    readonly occlusionTexture?: NormalizedTextureRef & {
+        readonly strength: number;
+    };
+    readonly emissiveFactor: readonly [number, number, number];
+    readonly emissiveTexture?: NormalizedTextureRef;
+}
+/** The glTF default material (no `material` on a primitive). */
+export declare const DEFAULT_MATERIAL: NormalizedMaterial;
+/** A decoded-but-unmapped vertex attribute carried through from Draco. `componentType` is the raw
+ *  GL enum (e.g. 5121 UNSIGNED_BYTE, 5126 FLOAT) so downstream widening (u8→u16 intensity) is correct. */
+export interface ExtraVertexAttribute {
+    readonly array: TypedArray;
+    readonly componentType: number;
+    readonly componentCount: number;
+}
+export interface NormalizedPrimitive {
+    readonly mode: PrimitiveMode;
+    /** 3·N vertex positions (glb-local meters; ENU rebasing happens in packMeshEnu). */
+    readonly positions: Float32Array;
+    readonly normals?: Float32Array;
+    readonly uv0?: Float32Array;
+    /** 4·N RGBA — `Float32Array` normalized 0..1 (glTF COLOR_0) or RAW `Uint8Array` 0..255
+     *  (I3S `color`, GPU-normalized at upload). The renderer branches on the array type. */
+    readonly color0?: Float32Array | Uint8Array;
+    /** 4·N I3S texture-atlas region `(uMin,vMin,uMax,vMax)` as raw u16 — present only on
+     *  atlased I3S 3DObject; the shader wraps uv0 into this region. */
+    readonly uvRegion?: Uint16Array;
+    readonly indices?: Uint16Array | Uint32Array;
+    /** Per-vertex feature id (EXT_mesh_features / _FEATURE_ID_0) for picking. */
+    readonly featureIds?: Uint32Array;
+    /** Decoded Draco attributes not consumed as a geometry semantic (e.g. `_INTENSITY`,
+     *  `_CLASSIFICATION`), keyed by glTF attribute semantic. `EXT_structural_metadata` reads these for
+     *  Draco point clouds, whose property-attribute accessors carry no bufferView and otherwise read as
+     *  all-zeros. Undefined for uncompressed primitives. */
+    readonly extraAttributes?: ReadonlyMap<string, ExtraVertexAttribute>;
+    readonly materialIndex?: number;
+    /** Column-major 4×4 node world transform (glb root → this primitive's node). */
+    readonly nodeMatrix: Mat4;
+}
+export interface NormalizedMesh {
+    readonly primitives: readonly NormalizedPrimitive[];
+    readonly materials: readonly NormalizedMaterial[];
+    /**
+     * Which node produced which run of {@link NormalizedMesh.primitives}, populated ONLY
+     * when at least one node carries `EXT_mesh_gpu_instancing`. Ordinary tiles leave it
+     * undefined and allocate nothing.
+     *
+     * @remarks
+     * Node identity is normally flattened away here, and for a plain tile that is the
+     * right trade. A 1.1 instanced tile needs it back: instancing is per-node, so the
+     * decoder has to know which primitives belong to an instanced node (their placement
+     * goes into instance matrices) and which do not. For those nodes the primitive's
+     * `nodeMatrix` is left as identity and the real transform travels here instead, so
+     * it is not also baked into the vertices.
+     */
+    readonly nodeSpans?: readonly {
+        /** `[start, end)` into {@link NormalizedMesh.primitives}. */
+        readonly primitiveRange: readonly [number, number];
+        /** The node's composed world transform (glTF model space). */
+        readonly worldMatrix: Mat4;
+        /** Present iff this node carries `EXT_mesh_gpu_instancing`. */
+        readonly instancing?: {
+            readonly attributes: Readonly<Record<string, number>>;
+        };
+    }[];
+}
+export interface PackedTextureLevel {
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8Array;
+}
+export interface PackedTexture {
+    /** A GPU-compressed payload (KTX2/Basis-transcoded), OR `rgba` for raw upload, OR a decoded
+     *  `bitmap` for a zero-readback upload. */
+    readonly compressed?: {
+        readonly format: number;
+        readonly levels: readonly PackedTextureLevel[];
+    };
+    readonly rgba?: PackedTextureLevel;
+    /** A decoded `ImageBitmap` (JPEG/PNG) uploaded DIRECTLY via `texImage2D` — skips the OffscreenCanvas
+     *  `getImageData` RGBA readback (a full-res CPU copy per tile) the `rgba` path pays. The renderer closes
+     *  it after upload. Transferable across the worker→main boundary. (The I3S decoder still uses `rgba`.) */
+    readonly bitmap?: ImageBitmap;
+    /** baseColor textures are sRGB. */
+    readonly srgb: boolean;
+    readonly sampler: {
+        readonly wrapS: number;
+        readonly wrapT: number;
+        readonly minFilter: number;
+        readonly magFilter: number;
+    };
+}
+export interface PackedInstances {
+    readonly count: number;
+    /** 16·count column-major instance matrices (ENU, relative to the tile origin). */
+    readonly matrices: Float32Array;
+}
+/**
+ * One instanced draw group: a run of {@link PackedMeshTile.primitives} that shares a
+ * single set of per-instance matrices.
+ *
+ * @remarks
+ * A tile is not always instanced as a whole. `EXT_mesh_gpu_instancing` (3D Tiles 1.1)
+ * is a **per-node** extension, so one glTF can carry several independently instanced
+ * nodes beside plain non-instanced ones, and a `cmpt` composite can hold an instanced
+ * `i3dm` next to a plain `b3dm`. `primitiveRange` is what lets one tile express that.
+ *
+ * Primitives outside every group's range are drawn normally (no instancing). The
+ * renderer already worked this way internally via its per-primitive instance-count
+ * override; this is the contract catching up.
+ */
+export interface PackedInstanceGroup extends PackedInstances {
+    /** `[start, end)` into {@link PackedMeshTile.primitives}. */
+    readonly primitiveRange: readonly [number, number];
+}
+/**
+ * The instance groups of a tile, normalized across both spellings.
+ *
+ * @remarks
+ * Every reader must go through this rather than branching on which field is set.
+ * {@link PackedMeshTile.instances} is the older per-tile form and is still produced
+ * directly by hand-built tiles (the model-instances layers), so it is normalized here
+ * to a single group spanning every primitive.
+ *
+ * @param tile - The packed tile.
+ * @returns Its groups, or a shared empty array when the tile is not instanced.
+ */
+export declare function instanceGroupsOf(tile: PackedMeshTile): readonly PackedInstanceGroup[];
+export interface PackedMeshPrimitive {
+    readonly mode: PrimitiveMode;
+    /** 3·N positions in ENU meters relative to the tile origin (f32-safe). */
+    readonly positions: Float32Array;
+    /** 3·N TRUE web-mercator positions ([0,1] x/y, altitude·meterInMercatorUnits z) relative to
+     *  {@link PackedMeshTile.mercatorOrigin} — baked per vertex at decode (Cesium SceneMode2DPipelineStage
+     *  style) when `bakeMercator` is set, so the renderer places each vertex EXACTLY (no per-tile affine
+     *  tangent → no intra-tile parallax-swim on global datasets). Absent for localized datasets (the ENU
+     *  `positions` + per-tile placement path is byte-identical). The `positions` array is still produced
+     *  (ENU) for normals/shadow. */
+    readonly mercatorOffset?: Float32Array;
+    readonly normals?: Float32Array;
+    readonly uv0?: Float32Array;
+    readonly color0?: Float32Array | Uint8Array;
+    /** 4·N I3S texture-atlas region `(uMin,vMin,uMax,vMax)` as raw u16 (GPU-normalized). */
+    readonly uvRegion?: Uint16Array;
+    readonly indices?: Uint16Array | Uint32Array;
+    readonly featureIds?: Uint32Array;
+    /** Resolved material (textures referenced by index into {@link PackedMeshTile.textures}). */
+    readonly material: NormalizedMaterial;
+}
+/**
+ * A tile's hard edges as one flat line list — the lines a person would draw sketching the model.
+ *
+ * @remarks
+ * Derived at decode (no service ships edge geometry), merged across the tile's primitives so the
+ * edge pass is one draw. Positions are in the same frame as {@link PackedMeshPrimitive.positions};
+ * {@link PackedEdges.mercatorOffsets} mirrors {@link PackedMeshPrimitive.mercatorOffset} for baked
+ * planet-scale tiles, which are placed from mercator rather than ENU.
+ */
+export interface PackedEdges {
+    /** 6·count ENU positions relative to the tile origin: `[x0,y0,z0, x1,y1,z1]` per edge. */
+    readonly positions: Float32Array;
+    /** 6·count baked web-mercator positions, present iff the tile was baked. */
+    readonly mercatorOffsets?: Float32Array;
+    /** Per-edge feature ordinal, so an edge hides with the feature it outlines. */
+    readonly featureIds?: Uint32Array;
+    readonly count: number;
+    /** True when the per-tile edge budget cut the result short. */
+    readonly truncated: boolean;
+}
+export interface PackedMeshTile {
+    /** Per-tile ENU origin (meters); add in the shader to recover world ENU. */
+    readonly origin: readonly [number, number, number];
+    /** Per-tile TRUE web-mercator reference point ([0,1] x/y, altitude·meterInMercatorUnits z) that
+     *  {@link PackedMeshPrimitive.mercatorOffset} is relative to (the tile's geodetic-center mercator).
+     *  Present iff the tile was baked (`bakeMercator`). The renderer places mercator tiles with
+     *  `mvpWorld · translate(mercatorOrigin + datumMercZ)` — no per-tile placement tangent. */
+    readonly mercatorOrigin?: readonly [number, number, number];
+    readonly primitives: readonly PackedMeshPrimitive[];
+    /** Decoded textures, indexed by glTF texture index. Populated by the decoder. */
+    readonly textures: readonly PackedTexture[];
+    /**
+     * Per-tile instancing: one group over every primitive.
+     *
+     * @deprecated Prefer {@link PackedMeshTile.instanceGroups}, which can also express a
+     * tile that is only partly instanced. Still read (via {@link instanceGroupsOf}) and
+     * still produced by the hand-built model-instances layers, so it is not going away
+     * without notice.
+     */
+    readonly instances?: PackedInstances;
+    /** Instanced draw groups, each covering a run of {@link PackedMeshTile.primitives}.
+     *  Read it through {@link instanceGroupsOf}, never directly. */
+    readonly instanceGroups?: readonly PackedInstanceGroup[];
+    readonly featureCount: number;
+    /** Hard edges for the whole tile, present iff the decoder was asked for them
+     *  ({@link MeshDecodeContext.edges}). */
+    readonly edges?: PackedEdges;
+    /** Per-feature BIM metadata (3D Tiles batch table / EXT_structural_metadata), in a structured-
+     *  cloneable plain form so it survives the worker→main hand-off; materialized to
+     *  {@link FeatureProperties} for picking/styling. Indexed by the `featureIds` ordinal. CPU-side. */
+    readonly featureMetadata?: FeaturePropertiesData;
+    /** Resident byte estimate (geometry + textures) for the engine memory budget. */
+    readonly bytes: number;
+    /** Content data attribution from the glTF `asset.copyright` (semicolon-separated
+     *  data providers, e.g. Google Photorealistic 3D Tiles). The engine aggregates these
+     *  across visible tiles so the consumer can display the required dynamic credits. */
+    readonly copyright?: string;
+}
+/** Everything a {@link MeshTileDecoder} needs to georeference a tile into the
+ *  shared scene ENU frame. */
+export interface MeshDecodeContext {
+    /** ECEF → shared-scene ENU (meters), column-major 4×4. */
+    readonly enuFromEcef: Mat4;
+    /** The EFFECTIVE cumulative tile transform: tile-local → ECEF. Normally the tileset's own composed
+     *  transform; for a tileset that DECLARES a gravity-related (orthometric) vertical CRS the engine
+     *  pre-multiplies a rigid ECEF translation of the geoid undulation N along the ellipsoid normal, so
+     *  the decoded geometry is ellipsoidal-absolute — the height reference every consumer of this frame
+     *  assumes. Decoders just use it; nothing here needs to know which case it is. */
+    readonly tileTransformEcef: Mat4;
+    /** Up-axis the tileset declares for its glb content (`asset.gltfUpAxis`). Default `'y'`,
+     *  the 3D Tiles spec default. `'z'` means the content is already z-up and the y-up→z-up
+     *  flip must be SKIPPED — see `tileToEnu`. Declared per tileset, so an external tileset
+     *  can differ from its parent and each tile carries its own. */
+    readonly gltfUpAxis?: 'y' | 'z';
+    readonly geometricError: number;
+    /**
+     * Absolute URL the tile's content was fetched from, used to resolve URIs the content
+     * itself references (today: an `i3dm` with `gltfFormat` 0, whose body is a relative
+     * path to a shared glTF rather than an embedded GLB).
+     *
+     * @remarks
+     * Optional because most content is self-contained. When it is absent and a tile does
+     * reference an external model, decode fails naming this field rather than guessing at
+     * a base.
+     */
+    readonly contentBaseUrl?: string;
+    /** Bake the exact per-vertex web-mercator offset at decode (Cesium SceneMode2DPipelineStage style) so
+     *  the renderer places each vertex without a per-tile ENU tangent → no intra-tile parallax-swim on
+     *  global tilesets. Off (undefined/false) ⇒ the ENU-only path, byte-identical. Set by the engine for
+     *  planet-scale datasets. */
+    readonly bakeMercator?: boolean;
+    /** Extract hard edges for this tile ({@link PackedMeshTile.edges}). Absent ⇒ no extraction and
+     *  no cost; the work is real (one pass over every triangle) so it is never done speculatively. */
+    readonly edges?: EdgeExtractOptions;
+}
+/** How much geometry to turn into edges, and how sharp a fold has to be to count. */
+export interface EdgeExtractOptions {
+    /** Dihedral angle above which a shared edge is a crease. Default 25°. */
+    readonly creaseAngleDeg?: number;
+    /** Cap on edges per tile. Default 400 000. */
+    readonly maxEdges?: number;
+}
+/** Decodes one 3D-Tiles mesh tile (b3dm/i3dm/cmpt/glb) into a GPU-ready,
+ *  ENU-rebased {@link PackedMeshTile}, regardless of which compression the tile
+ *  uses. The engine and renderer depend only on this interface. */
+export interface MeshTileDecoder {
+    /** @param buffer - The tile bytes (b3dm/i3dm/cmpt/glb).
+     *  @param ctx - Georeference context ({@link MeshDecodeContext}).
+     *  @returns The ENU-rebased {@link PackedMeshTile}. */
+    decode(buffer: ArrayBuffer, ctx: MeshDecodeContext): Promise<PackedMeshTile>;
+    /** Worker pool size (worker variants) — size the engine's decode concurrency to match. */
+    readonly concurrency?: number;
+    dispose?(): void;
+}
+/** Built-in mesh-decoder identifiers a layer/engine can resolve to an impl. */
+export type MeshTileDecoderKind = 'gltf';

package/dist/contracts/renderer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Renderer contract — viewer-agnostic. A renderer consumes decoded
+ * (quantized) tiles and a {@link ViewerAdapter}, owns its GPU
+ * resources, and draws each frame using the adapter's matrices. The
+ * same renderer instance is reused across MapLibre, three.js, Cesium,
+ * etc. — only the adapter differs.
+ */
+import type { DecodedTile } from './decoder';
+import type { FrameState, ViewerAdapter } from './viewer-adapter';
+/** An opaque handle to one uploaded tile's GPU resources (returned by
+ *  {@link Renderer.upload}, passed back to {@link Renderer.release}). */
+export type TileHandle = number & {
+    readonly __brand: 'TileHandle';
+};
+/** A viewer-agnostic renderer: it consumes decoded (quantized) tiles and a
+ *  {@link ViewerAdapter}, owns its GPU resources, and draws each frame using the
+ *  adapter's matrices. The same instance is reused across MapLibre / three.js / Cesium.
+ *  @typeParam TTile - The decoded tile shape this renderer accepts. */
+export interface Renderer<TTile extends DecodedTile = DecodedTile> {
+    /** Bind to a viewer's GL context; compile programs, allocate static state.
+     *  @param adapter - The host {@link ViewerAdapter}. */
+    init(adapter: ViewerAdapter): void;
+    /** Upload one decoded tile to GPU buffers/textures.
+     *  @param tile - The decoded tile. @returns A {@link TileHandle} for later release. */
+    upload(tile: TTile): TileHandle;
+    /** Render all uploaded tiles for the current frame.
+     *  @param frame - The current {@link FrameState}. */
+    render(frame: FrameState): void;
+    /** Drop one tile's GPU resources.
+     *  @param handle - The {@link TileHandle} from {@link Renderer.upload}. */
+    release(handle: TileHandle): void;
+    /** Tear down all GL resources (does not own the context). */
+    dispose(): void;
+}

package/dist/contracts/viewer-adapter.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Viewer adapter contract — the thin, per-viewer seam.
+ *
+ * Every renderer ({@link ./renderer}) is viewer-agnostic and is driven
+ * entirely through this interface, so a new viewer is a ~1-file adapter.
+ * Each target supplies the same four things per frame:
+ *
+ *  - a WebGL2 context
+ *  - a view matrix (world → camera)
+ *  - a projection matrix (camera → clip)
+ *  - a model matrix placing the local-meters scene in the viewer's world
+ *
+ * Mapping per viewer (only MapLibre, then three.js, are P1/P2):
+ *  - MapLibre:  gl from onAdd; projection from render args; VIEW recovered
+ *               as P^-1 · MVP; model from MercatorCoordinate placement.
+ *  - three.js:  gl = renderer.getContext(); view = camera.matrixWorldInverse;
+ *               projection = camera.projectionMatrix; model = anchor
+ *               Object3D.matrixWorld. (No recovery needed — heavy overlap
+ *               with MapLibre; same renderer core.)
+ *  - Cesium:    view = camera.viewMatrix; projection =
+ *               camera.frustum.projectionMatrix; model from
+ *               Transforms.eastNorthUpToFixedFrame.
+ *  - ArcGIS:    view/projection from RenderCamera; model from the render
+ *               coordinate transform.
+ */
+import type { Mat4 } from '../geo/mat4';
+import type { GeoAnchor } from '../geo/mercator';
+/** The per-frame matrices and viewport a {@link ViewerAdapter} snapshots for the
+ *  renderer. All matrices are column-major f64 {@link Mat4}s. */
+export interface FrameState {
+    /** world → view (camera). Splat covariance projection needs this alone. */
+    readonly viewMatrix: Mat4;
+    /** view → clip (projection). */
+    readonly projectionMatrix: Mat4;
+    /** local-scene (meters) → world (geo anchor + meter scaling). */
+    readonly modelMatrix: Mat4;
+    /** Convenience: `projection · view · model` (what the viewer ultimately applies). */
+    readonly modelViewProjection: Mat4;
+    /** Camera position in world space `[x, y, z]`. */
+    readonly cameraPositionWorld: readonly [number, number, number];
+    /** Near clip plane distance. */
+    readonly nearZ: number;
+    /** Far clip plane distance. */
+    readonly farZ: number;
+    /** Vertical field of view in radians. */
+    readonly fovY: number;
+    /** Viewport width in device pixels. */
+    readonly viewportWidth: number;
+    /** Viewport height in device pixels. */
+    readonly viewportHeight: number;
+    /** Device pixel ratio. */
+    readonly devicePixelRatio: number;
+    /** `true` under a non-affine projection (e.g. MapLibre globe) — renderers degrade. */
+    readonly nonAffineProjection: boolean;
+}
+/** The thin, per-viewer seam every renderer is driven through. Implement one per host
+ *  (MapLibre, three.js, Cesium, …); the renderer core is otherwise viewer-agnostic. */
+export interface ViewerAdapter {
+    /** The live WebGL2 context owned by the viewer. */
+    readonly gl: WebGL2RenderingContext;
+    /** Snapshot the per-frame matrices/viewport for the renderer.
+     *  @returns The current {@link FrameState}. */
+    getFrameState(): FrameState;
+    /** Ask the viewer to schedule another frame (e.g. when a tile finishes decoding). */
+    requestRender(): void;
+    /** Where the scene is anchored, so the adapter can build the model matrix. */
+    readonly anchor: GeoAnchor;
+}

package/dist/dequant/formulas.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Canonical BVC dequantization reference (CPU).
+ *
+ * These are the exact inverse-quantization formulas the decoder's
+ * quantized output must be expanded with. The WebGL2 render shaders
+ * port THESE functions; this module is the parity oracle the shaders
+ * are tested against, so it must stay byte-faithful to the canonical
+ * dequantization.
+ *
+ * The decoder hands back QUANTIZED structure-of-arrays; nothing here is
+ * applied on the CPU at load time (dequant is deferred to shaders).
+ * This module exists for (a) parity tests and (b) the rare CPU paths
+ * that need real coordinates (e.g. computing splat depth for sorting).
+ */
+/** Spherical-harmonics band-0 basis constant (Y_0^0). @internal */
+export declare const SH_C0 = 0.28209479177387814;
+/** Smallest-three quaternion magnitude scale: 1 / (sqrt(2) * 511). @internal */
+export declare const ROT_INV: number;
+/** Per-degree SH band increments (channel-inner, RGB interleaved). @internal */
+export declare const SH_BAND_SIZES: {
+    readonly sh1: 9;
+    readonly sh2: 15;
+    readonly sh3: 21;
+};
+/** Total SH float coefficients per splat for a given degree.
+ *  @param degree - SH degree 0..3. @returns Cumulative coefficient count (0, 9, 24, or 45). */
+export declare function shCoeffsPerSplat(degree: number): number;
+/** Splat position: quantized i32 grid → meters in the local frame.
+ *  @param q - Quantized grid value. @param fractionalBits - Grid divisor exponent.
+ *  @returns Position in meters (`q / 2^fractionalBits`). */
+export declare function splatPositionToMeters(q: number, fractionalBits: number): number;
+/** Splat scale: log-quantized u8 → linear scale.
+ *  @param b - The scale byte. @returns The linear scale `exp(b/16 − 10)`. */
+export declare function splatScale(b: number): number;
+/** Splat opacity: u8 → alpha in `[0,1]` (BVC opacity is the rendered, post-sigmoid byte).
+ *  @param b - The opacity byte. @returns Alpha in `[0,1]`. */
+export declare function splatOpacity(b: number): number;
+/** Splat SH degree-0 DC coefficient from a color byte.
+ *  @param b - The color byte. @returns The DC SH coefficient. */
+export declare function splatColorDc(b: number): number;
+/** Splat rendered base-color channel (degree-0 SH → linear color in `[0,1]`-ish).
+ *  @param b - The color byte. @returns The base-color channel value. */
+export declare function splatBaseColorChannel(b: number): number;
+/** Splat SH rest-band coefficient: u8 grid → float in `[-1,1)`.
+ *  @param b - The coefficient byte. @returns `(b − 128) / 128`. */
+export declare function splatShCoeff(b: number): number;
+/**
+ * Reconstruct a unit quaternion (x, y, z, w) from the smallest-three
+ * encoding: `rotIdx` is the slot of the omitted (largest) component;
+ * `a`, `b`, `c` are the three stored i16 components (in slot order,
+ * skipping `rotIdx`). The largest component is non-negative by encoder
+ * canonicalization, so it is reconstructed as +sqrt(1 - a²-b²-c²).
+ *
+ * @param rotIdx - Slot (0..3) of the omitted (largest) component.
+ * @param a - First stored i16 component (in slot order, skipping `rotIdx`).
+ * @param b - Second stored component.
+ * @param c - Third stored component.
+ * @returns A length-4 `Float32Array` unit quaternion `(x, y, z, w)`.
+ */
+export declare function decodeSmallestThree(rotIdx: number, a: number, b: number, c: number): Float32Array;
+/**
+ * Encode a quaternion (x, y, z, w) into the smallest-three form — the exact
+ * inverse of {@link decodeSmallestThree}. The input is defensively
+ * normalized (a zero quaternion encodes identity). `rotIdx` is the slot
+ * (0..3, order x,y,z,w) of the largest-magnitude component (first-max
+ * tiebreak); if that component is negative the whole quaternion is negated
+ * (same rotation) so the decoder's `+sqrt` reconstruction is exact. The
+ * remaining three components are stored in ascending slot order skipping
+ * `rotIdx`, each quantized as `round(comp * sqrt(2) * 511)` — the inverse
+ * of the {@link ROT_INV} scale — and clamped to `[-511, 511]` so
+ * slightly-super-unit inputs cannot overflow an `Int16Array` slot.
+ *
+ * @param x - Quaternion x component.
+ * @param y - Quaternion y component.
+ * @param z - Quaternion z component.
+ * @param w - Quaternion w component.
+ * @returns `{ rotIdx, a, b, c }`: the omitted slot and the three stored
+ *   i16 integers (in slot order, skipping `rotIdx`), ready for
+ *   `decodeSmallestThree(rotIdx, a, b, c)`.
+ */
+export declare function encodeSmallestThree(x: number, y: number, z: number, w: number): {
+    rotIdx: number;
+    a: number;
+    b: number;
+    c: number;
+};
+/** Point-cloud coordinate: quantized i32 → world via per-axis scale/offset.
+ *  @param q - Quantized value. @param scale - Per-axis scale (m). @param offset - Per-axis offset (m).
+ *  @returns `q * scale + offset`. */
+export declare function pointToWorld(q: number, scale: number, offset: number): number;
+/** Normalize a LAS-native u16 channel (rgb / intensity) to `[0, 1]`.
+ *  @param v - The u16 value (0..65535). @returns `v / 65535`. */
+export declare function normU16(v: number): number;

package/dist/dequant/stray-cull.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Stray-splat culling over QUANTIZED decoded tiles — the decoder-agnostic
+ * runtime analog of the Bitruvius BVC encoder's stray-cull transcode (and of turbo-spz's
+ * float-side `computeStrayMask`): 3DGS captures surround their subject with a
+ * sparse ball of huge far-field background splats (±200 m around an 8 m
+ * subject is typical) that renders as a giant ghost sphere over the map when
+ * the container was transcoded 1:1. Splats farther from the robust (per-axis
+ * MEDIAN) center than `factor ×` the 90th-percentile distance are culled.
+ * Load-time only (a few typed-array sorts); splat tiles only — LiDAR point
+ * clouds are real data, never culled.
+ */
+import type { ContainerMeta, DecodedTile } from '../contracts/decoder';
+/**
+ * Cull far-outlier stray splats across a container's decoded splat tiles.
+ *
+ * @remarks
+ * Distances are measured in WORLD units (the container's dequant applied in
+ * f64), from the per-axis median center; the cutoff is `factor × r90` (the
+ * 90th-percentile distance) — self-scaling, so halo-free captures pass
+ * through untouched (the input array is returned as-is). Point-cloud tiles
+ * are never modified.
+ *
+ * @param tiles - The decoded tiles (splat tiles are filtered; others pass through).
+ * @param meta - The container dequant metadata.
+ * @param factor - Cutoff multiple of the 90th-percentile distance. Default 1.5
+ * (matches the look of a stray-culled BVC transcode).
+ * @returns The tiles with strays removed (same array instance when nothing was culled).
+ */
+export declare function cullStraySplats(tiles: readonly DecodedTile[], meta: ContainerMeta, factor?: number): readonly DecodedTile[];

package/dist/dequant/tile-bounds.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Quantized tile bounds accumulator.
+ *
+ * Streams over decoded tiles' quantized i32 position planes and keeps a
+ * running min/max in the QUANTIZED grid, then dequantizes the six
+ * extremes once at the end via the container metadata. This keeps the
+ * per-splat work to a plain integer compare (allocation-free, O(count))
+ * and defers every float multiply to `toLocalBounds`.
+ */
+import type { ContainerMeta, DecodedTile } from '../contracts/decoder';
+/**
+ * Axis-aligned bounding box in the model's SOURCE coordinates (meters).
+ *
+ * The shared bounds type for model placement: engines derive anchor
+ * points, footprints, and pick volumes from it. `min`/`max` are ordered
+ * per axis (`min[i] <= max[i]`) regardless of the sign of the dequant
+ * scale that produced them.
+ */
+export interface LocalBounds {
+    /** Per-axis minimum corner `(x, y, z)` in source meters. */
+    readonly min: readonly [number, number, number];
+    /** Per-axis maximum corner `(x, y, z)` in source meters. */
+    readonly max: readonly [number, number, number];
+    /**
+     * Robust per-axis 5th percentile, present when the producer ran the
+     * histogram pass (see `QuantBoundsAccumulator.beginHistogram`). Gaussian-
+     * splat captures surround their subject with a sparse halo of huge
+     * background splats (a ±200 m halo around an 8 m subject is typical), so
+     * raw `min`/`max` are outlier-hostage — anchoring uses these instead.
+     */
+    readonly p05?: readonly [number, number, number];
+    /** Robust per-axis median (see {@link LocalBounds.p05}). */
+    readonly p50?: readonly [number, number, number];
+    /** Robust per-axis 95th percentile (see {@link LocalBounds.p05}). */
+    readonly p95?: readonly [number, number, number];
+}
+/**
+ * Running min/max accumulator over the quantized position planes of
+ * {@link DecodedTile}s.
+ *
+ * Feed every streamed tile to {@link QuantBoundsAccumulator.add}, then call
+ * {@link QuantBoundsAccumulator.toLocalBounds} with the container's
+ * {@link ContainerMeta} to get the dequantized {@link LocalBounds}.
+ * State is six scalars, so the accumulator is safe to keep across an
+ * entire decode stream without retaining any tile memory.
+ *
+ * @example
+ * ```ts
+ * const acc = new QuantBoundsAccumulator();
+ * for await (const tile of decoder.decodeTiles(model, bytes)) {
+ *   acc.add(tile);
+ * }
+ * const bounds = acc.toLocalBounds(model.meta);
+ * ```
+ */
+export declare class QuantBoundsAccumulator {
+    private minX;
+    private minY;
+    private minZ;
+    private maxX;
+    private maxY;
+    private maxZ;
+    private hist;
+    private histBins;
+    private histCount;
+    private histMin;
+    private histInv;
+    private histWidth;
+    /**
+     * Fold one tile's quantized positions into the running min/max.
+     * Allocation-free O(count) scan; a `count === 0` tile is a no-op.
+     * @param tile - A decoded splat or point-cloud tile (only `x`/`y`/`z`/`count` are read).
+     */
+    add(tile: DecodedTile): void;
+    /** `true` until the first non-empty {@link QuantBoundsAccumulator.add} (and again after {@link QuantBoundsAccumulator.reset}). */
+    get isEmpty(): boolean;
+    /**
+     * Arm the optional percentile pass: allocate per-axis histograms over the
+     * min/max range captured so far, then feed every tile a SECOND time through
+     * {@link QuantBoundsAccumulator.addToHistogram}. Percentile precision is
+     * `range / bins` per axis (a 400 m capture at the default 2048 bins resolves
+     * to ~20 cm — far finer than the seating it drives).
+     *
+     * @param bins - Histogram resolution per axis (default 2048; 3×bins u32 ≈ 24 KB).
+     */
+    beginHistogram(bins?: number): void;
+    /**
+     * Fold one tile's quantized positions into the armed histograms
+     * (allocation-free O(count); a no-op before {@link QuantBoundsAccumulator.beginHistogram}).
+     * @param tile - A decoded splat or point-cloud tile (only `x`/`y`/`z`/`count` are read).
+     */
+    addToHistogram(tile: DecodedTile): void;
+    /** Nearest-rank quantile of one axis in QUANTIZED units (bin-center estimate). */
+    private histQuantile;
+    /**
+     * Dequantize the accumulated extremes into source-coordinate bounds.
+     *
+     * Splat containers use `meters = q / 2^fractionalBits`; point-cloud
+     * containers use the per-axis f64 affine `world = q * scale + offset`.
+     * A negative `scale[axis]` flips ordering on that axis, so the
+     * dequantized min/max are swapped per axis to keep `min <= max`.
+     *
+     * @param meta - The container's dequant metadata ({@link ContainerMeta}).
+     * @returns The {@link LocalBounds}, or `null` when nothing was accumulated.
+     */
+    toLocalBounds(meta: ContainerMeta): LocalBounds | null;
+    /** Clear the accumulated extremes (and any histogram) back to the empty state. */
+    reset(): void;
+}