@math.gl/geospatial 5.0.0-alpha.9 → 5.0.0-beta.1

package/src/terrain/index.ts

@@ -0,0 +1,82 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {HeightField} from './height-field';
+export {TerrainSampleStatus} from './types';
+export type {
+  HeightFieldProps,
+  TerrainArray,
+  TerrainDiagonal,
+  TerrainInterpolation,
+  TerrainRegistration,
+  TerrainSample,
+  TerrainSampleOptions,
+  TerrainSampleBatch
+} from './types';
+export {createTerrainSkirt} from './mesh-skirts';
+export type {TerrainSkirtOptions, TerrainSkirtMesh} from './mesh-skirts';
+
+// Public named exports. Implementations remain in independently tree-shakable files.
+export {HeightFieldGeometry} from './geometry';
+export type {HeightFieldGeometryOptions} from './geometry';
+export {GeographicHeightField} from './geographic';
+export type {GeographicHeightFieldProps} from './geographic';
+export {TiledHeightField} from './tiled';
+export type {
+  TerrainTileId,
+  TerrainHaloChange,
+  TerrainTileUpdate,
+  TerrainTile,
+  TiledHeightFieldProps,
+  TiledTerrainSample
+} from './tiled';
+export {packTerrainHeightField, unpackTerrainHeightField, TERRAIN_BUFFER_VERSION} from './packed';
+export type {PackedTerrain, PackTerrainOptions} from './packed';
+export {createTerrainSurface, TerrainSurface} from './surface';
+export type {
+  TerrainSurfaceProps,
+  TerrainSurfaceSample,
+  TerrainSurfaceHit,
+  TerrainSurfaceRayHit,
+  TerrainQueryOptions,
+  TerrainQueryResult,
+  TerrainSphereContact,
+  TerrainSegmentHit,
+  TerrainCapsuleContact,
+  TerrainSurfaceTopology
+} from './surface';
+export {HeightFieldMinMax} from './bounds';
+export type {TerrainCellWindow, TerrainHeightBounds, TerrainBoundsLevel} from './bounds';
+export {createTerrainMesh} from './mesh';
+export type {TerrainGridMesh, TerrainMeshOptions} from './mesh';
+export {measureTerrainMeshError} from './mesh-error';
+export type {TerrainMeshError} from './mesh-error';
+export {getTerrainMeshEdge} from './mesh-edges';
+export type {TerrainMeshEdge} from './mesh-edges';
+export {createMartiniTerrainMesh} from './martini';
+export type {AdaptiveTerrainMesh, MartiniTerrainMeshOptions} from './martini';
+export {createDelatinTerrainMesh} from './delatin';
+export type {DelatinTerrainMeshOptions} from './delatin';
+export {createTerrainGradientGrid} from './derivatives';
+export type {TerrainGradientMethod, TerrainGradientGrid} from './derivatives';
+export {getTerrainSlopeAspect, createTerrainSlopeAspectGrid} from './slope-aspect';
+export type {TerrainSlopeAspectGrid} from './slope-aspect';
+export {sampleTerrainProfile} from './profile';
+export type {TerrainProfileSampler, TerrainProfile} from './profile';
+export {createTerrainContours} from './contours';
+export type {TerrainContours, TerrainContourOptions} from './contours';
+export {stitchTerrainContours} from './contour-paths';
+export type {TerrainContourPaths, TerrainContourPathLimits} from './contour-paths';
+export {simplifyTerrainContourPaths} from './contour-simplify';
+export type {TerrainSimplifiedContourPaths} from './contour-simplify';
+export {measureTerrainProfile} from './profile-measure';
+export type {TerrainProfileMeasurements} from './profile-measure';
+export {reconcileTerrainVertexTiles} from './vertex-tiles';
+export type {
+  TerrainVertexTile,
+  TerrainVertexTileOptions,
+  ReconciledTerrainVertexTile
+} from './vertex-tiles';
+export {stitchTerrainMeshEdges} from './mesh-stitch';
+export type {TerrainSeamMesh, TerrainMeshStitchOptions} from './mesh-stitch';

package/src/terrain/martini.ts

@@ -0,0 +1,77 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import Martini from '@mapbox/martini';
+import type {HeightField} from './height-field';
+import {assembleTerrainMesh, type TerrainMeshEdge} from './mesh-data';
+import {measureTerrainMeshError} from './mesh-error';
+import type {AdaptiveTerrainMesh, AdaptiveTerrainMeshOptions} from './adaptive-mesh-types';
+export type {AdaptiveTerrainMesh} from './adaptive-mesh-types';
+
+export type MartiniTerrainMeshOptions = AdaptiveTerrainMeshOptions & {
+  /** Force every sample on selected grid edges into the mesh, independently of maxError. */
+  fullEdges?: readonly TerrainMeshEdge[];
+};
+
+/** Optional MARTINI RTIN adapter, with independent nodal-error measurement and explicit edge constraints.
+ * Requires a complete square (2^k+1) grid. Output is plain data; no renderer or query index is built.
+ */
+export function createMartiniTerrainMesh(
+  field: HeightField,
+  options: MartiniTerrainMeshOptions
+): AdaptiveTerrainMesh {
+  const size = field.width,
+    cells = size - 1;
+  const maxSamples = options.maxSamples ?? 1_100_000,
+    maxTriangles = options.maxTriangles ?? 2 * cells * cells;
+  if (!Number.isFinite(options.maxError) || options.maxError < 0)
+    throw new Error('Adaptive terrain maxError must be finite and nonnegative');
+  for (const value of [maxSamples, maxTriangles])
+    if (!Number.isSafeInteger(value) || value < 0)
+      throw new Error('Invalid adaptive terrain capacity');
+  if (size !== field.height || cells < 1 || cells > 32768 || (cells & (cells - 1)) !== 0)
+    throw new Error('Adaptive terrain requires a square (2^k+1) grid within uint16 coordinates');
+  if (size * size > maxSamples) throw new Error('Adaptive terrain sample capacity exceeded');
+  if (field.validCount !== size * size)
+    throw new Error('Adaptive terrain requires complete source data; use a regular mesh for holes');
+  const edges = options.fullEdges ?? [];
+  for (const edge of edges)
+    if (!['minColumn', 'maxColumn', 'minRow', 'maxRow'].includes(edge))
+      throw new Error('Unknown adaptive terrain edge');
+  const {heights} = field.copyData();
+  const tile = new Martini(size).createTile(heights);
+  // Pinned MARTINI 0.2.0 exposes its error grid. Infinity forces selected edge midpoints;
+  // update propagates these requirements to ancestors, retaining conforming RTIN splits.
+  for (const edge of edges)
+    for (let i = 0; i < size; i++) {
+      const column = edge === 'minColumn' ? 0 : edge === 'maxColumn' ? cells : i;
+      const row = edge === 'minRow' ? 0 : edge === 'maxRow' ? cells : i;
+      tile.errors[row * size + column] = Infinity;
+    }
+  if (edges.length) tile.update();
+  let threshold = options.maxError;
+  // MARTINI's f32 midpoint-error heuristic is not treated as an error certificate.
+  // Refine failed candidates; the final pass forces the full RTIN triangulation.
+  for (let pass = 0; pass <= 8; pass++) {
+    const {vertices, triangles} = tile.getMesh(pass === 8 ? -1 : threshold);
+    if (triangles.length / 3 > maxTriangles)
+      throw new Error('Adaptive terrain triangle capacity exceeded');
+    // MARTINI emits clockwise grid triangles. Our shared assembler takes CCW grid indices.
+    const indices = Uint32Array.from(triangles);
+    for (let i = 0; i < indices.length; i += 3)
+      [indices[i + 1], indices[i + 2]] = [indices[i + 2], indices[i + 1]];
+    const mesh = assembleTerrainMesh(field, Uint32Array.from(vertices), indices, options);
+    const error = measureTerrainMeshError(field, mesh, {maxSampleTests: options.maxSampleTests});
+    if (!error.uncoveredSampleCount && error.maxSampleError <= options.maxError)
+      return {
+        ...mesh,
+        error,
+        requestedMaxError: options.maxError,
+        refinementPasses: pass + 1,
+        tessellator: 'martini'
+      };
+    threshold /= 2;
+  }
+  throw new Error('Adaptive terrain could not meet the requested sample error');
+}

package/src/terrain/mesh-data.ts

@@ -0,0 +1,111 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {HeightField} from './height-field';
+
+/** Detached grid-derived mesh data. No renderer, query index, normals or physics state. */
+export type TerrainGridMesh = {
+  positions: Float64Array;
+  indices: Uint32Array;
+  /** Packed integer [column, row] for each vertex. */
+  gridCoordinates: Uint32Array;
+  width: number;
+  height: number;
+  origin: readonly [number, number, number];
+  heightReference: string;
+};
+export type TerrainMeshOptions = {origin?: readonly [number, number, number]};
+export type TerrainMeshEdge = 'minColumn' | 'maxColumn' | 'minRow' | 'maxRow';
+
+/** Internal assembly shared by regular and optional adaptive builders. */
+export function assembleTerrainMesh(
+  field: HeightField,
+  gridCoordinates: Uint32Array,
+  indices: Uint32Array,
+  options: TerrainMeshOptions
+): TerrainGridMesh {
+  const origin = options.origin ?? [field.origin[0], field.origin[1], 0];
+  if (
+    origin.length !== 3 ||
+    !Number.isFinite(origin[0]) ||
+    !Number.isFinite(origin[1]) ||
+    !Number.isFinite(origin[2])
+  )
+    throw new Error('Terrain mesh origin must be finite XYZ');
+  const positions = new Float64Array((gridCoordinates.length / 2) * 3);
+  for (let i = 0; i < gridCoordinates.length / 2; i++) {
+    const column = gridCoordinates[2 * i],
+      row = gridCoordinates[2 * i + 1];
+    const shift = field.registration === 'cell' ? 0.5 : 0;
+    positions[3 * i] =
+      field.origin[0] -
+      origin[0] +
+      (column + shift) * field.columnStep[0] +
+      (row + shift) * field.rowStep[0];
+    positions[3 * i + 1] =
+      field.origin[1] -
+      origin[1] +
+      (column + shift) * field.columnStep[1] +
+      (row + shift) * field.rowStep[1];
+    const height = field.getHeight(column, row);
+    positions[3 * i + 2] = height === undefined ? 0 : height - origin[2];
+  }
+  if (!positions.every(Number.isFinite)) throw new Error('Terrain mesh coordinate overflow');
+  const reverse =
+    field.columnStep[0] * field.rowStep[1] - field.columnStep[1] * field.rowStep[0] < 0;
+  for (let i = 0; i < indices.length; i += 3) {
+    if (reverse) [indices[i + 1], indices[i + 2]] = [indices[i + 2], indices[i + 1]];
+    const a = indices[i] * 3,
+      b = indices[i + 1] * 3,
+      c = indices[i + 2] * 3;
+    const area =
+      (positions[b] - positions[a]) * (positions[c + 1] - positions[a + 1]) -
+      (positions[b + 1] - positions[a + 1]) * (positions[c] - positions[a]);
+    if (!Number.isFinite(area) || area <= 0)
+      throw new Error('Terrain mesh triangles degenerate or overflow; use a local origin');
+  }
+  return {
+    positions,
+    indices,
+    gridCoordinates,
+    width: field.width,
+    height: field.height,
+    origin: Object.freeze([...origin] as [number, number, number]),
+    heightReference: field.heightReference
+  };
+}
+
+/** Validate detached caller-owned data before inspection. Does not certify manifoldness. */
+export function validateTerrainGridMesh(mesh: TerrainGridMesh): void {
+  if (
+    !Number.isSafeInteger(mesh.width) ||
+    !Number.isSafeInteger(mesh.height) ||
+    mesh.width < 2 ||
+    mesh.height < 2 ||
+    mesh.width * mesh.height > 0xffffffff
+  )
+    throw new Error('Invalid terrain mesh grid dimensions');
+  if (
+    !(mesh.positions instanceof Float64Array) ||
+    mesh.positions.length % 3 ||
+    !mesh.positions.every(Number.isFinite) ||
+    !(mesh.indices instanceof Uint32Array) ||
+    mesh.indices.length % 3 ||
+    !(mesh.gridCoordinates instanceof Uint32Array) ||
+    mesh.gridCoordinates.length !== (mesh.positions.length / 3) * 2
+  )
+    throw new Error('Invalid terrain mesh buffers');
+  if (
+    mesh.origin.length !== 3 ||
+    !Number.isFinite(mesh.origin[0]) ||
+    !Number.isFinite(mesh.origin[1]) ||
+    !Number.isFinite(mesh.origin[2])
+  )
+    throw new Error('Invalid terrain mesh origin');
+  for (let i = 0; i < mesh.gridCoordinates.length; i += 2)
+    if (mesh.gridCoordinates[i] >= mesh.width || mesh.gridCoordinates[i + 1] >= mesh.height)
+      throw new Error('Terrain mesh grid coordinate out of bounds');
+  for (const i of mesh.indices)
+    if (i >= mesh.positions.length / 3) throw new Error('Terrain mesh vertex index out of bounds');
+}

package/src/terrain/mesh-edges.ts

@@ -0,0 +1,27 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {validateTerrainGridMesh, type TerrainGridMesh, type TerrainMeshEdge} from './mesh-data';
+export type {TerrainMeshEdge} from './mesh-data';
+
+/** Referenced vertices on a grid side, sorted by ascending coordinate along that side.
+ * A grid side is not necessarily geographic north/south/east/west. No boundary-loop inference.
+ */
+export function getTerrainMeshEdge(mesh: TerrainGridMesh, edge: TerrainMeshEdge): Uint32Array {
+  validateTerrainGridMesh(mesh);
+  if (!['minColumn', 'maxColumn', 'minRow', 'maxRow'].includes(edge))
+    throw new Error('Unknown terrain mesh edge');
+  const column = edge === 'minColumn' || edge === 'maxColumn';
+  const axis = column ? 0 : 1;
+  const value = edge.startsWith('min') ? 0 : (column ? mesh.width : mesh.height) - 1;
+  const vertices = new Set<number>();
+  for (const index of mesh.indices)
+    if (mesh.gridCoordinates[2 * index + axis] === value) vertices.add(index);
+  return Uint32Array.from(
+    [...vertices].sort(
+      (a, b) =>
+        mesh.gridCoordinates[2 * a + 1 - axis] - mesh.gridCoordinates[2 * b + 1 - axis] || a - b
+    )
+  );
+}

package/src/terrain/mesh-error.ts

@@ -0,0 +1,158 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {HeightField} from './height-field';
+import {validateTerrainGridMesh, type TerrainGridMesh} from './mesh-data';
+
+export type TerrainMeshError = {
+  maxSampleError: number;
+  rmsSampleError: number;
+  coveredSampleCount: number;
+  uncoveredSampleCount: number;
+  sampleTests: number;
+};
+
+/** Measure vertical error at valid source-grid nodes. This is not a continuous-surface certificate.
+ * Overlapping triangles contribute the worst error per node. Uncovered samples remain explicit.
+ */
+export function measureTerrainMeshError(
+  field: HeightField,
+  mesh: TerrainGridMesh,
+  options: {maxSampleTests?: number} = {}
+): TerrainMeshError {
+  validateTerrainGridMesh(mesh);
+  if (
+    mesh.width !== field.width ||
+    mesh.height !== field.height ||
+    mesh.heightReference !== field.heightReference
+  )
+    throw new Error('Terrain mesh and field metadata differ');
+  const limit = options.maxSampleTests ?? 10_000_000;
+  if (!Number.isSafeInteger(limit) || limit < 0)
+    throw new Error('Invalid terrain mesh sample-test limit');
+  // Verify that grid coordinates describe the actual XY geometry, not a stale/forged index grid.
+  const shift = field.registration === 'cell' ? 0.5 : 0;
+  for (let i = 0; i < mesh.positions.length / 3; i++) {
+    const x = mesh.gridCoordinates[i * 2] + shift,
+      y = mesh.gridCoordinates[i * 2 + 1] + shift;
+    for (let axis = 0; axis < 2; axis++) {
+      const expected =
+        field.origin[axis] -
+        mesh.origin[axis] +
+        x * field.columnStep[axis] +
+        y * field.rowStep[axis];
+      if (!Number.isFinite(expected) || mesh.positions[i * 3 + axis] !== expected)
+        throw new Error('Terrain mesh XY does not match the source grid frame');
+    }
+  }
+  const baseX = field.origin[0] - mesh.origin[0],
+    baseY = field.origin[1] - mesh.origin[1];
+  const [columnX, columnY] = field.columnStep,
+    [rowX, rowY] = field.rowStep;
+  const frameArea = Math.abs(columnX * rowY - columnY * rowX);
+  // Bound coordinate construction roundoff in grid units. Below 1/8 of a cell,
+  // expanding each integer bounding box by one includes all possibly shifted nodes.
+  // Reject distant origins / ill-conditioned frames rather than certify aliased XY.
+  const roundX =
+    16 *
+    Number.EPSILON *
+    (Math.abs(baseX) + (field.width + 1) * Math.abs(columnX) + (field.height + 1) * Math.abs(rowX));
+  const roundY =
+    16 *
+    Number.EPSILON *
+    (Math.abs(baseY) + (field.width + 1) * Math.abs(columnY) + (field.height + 1) * Math.abs(rowY));
+  const gridRoundoff = Math.max(
+    (Math.abs(rowY) * roundX + Math.abs(rowX) * roundY) / frameArea,
+    (Math.abs(columnY) * roundX + Math.abs(columnX) * roundY) / frameArea
+  );
+  if (!Number.isFinite(gridRoundoff) || gridRoundoff >= 0.125)
+    throw new Error(
+      'Terrain mesh XY precision is insufficient; use a local origin and a well-conditioned frame'
+    );
+  const errors = new Float64Array(field.width * field.height);
+  const covered = new Uint8Array(errors.length);
+  let sampleTests = 0,
+    coveredSampleCount = 0,
+    maxSampleError = 0;
+  for (let t = 0; t < mesh.indices.length; t += 3) {
+    const a = mesh.indices[t],
+      b = mesh.indices[t + 1],
+      c = mesh.indices[t + 2];
+    const ax = mesh.gridCoordinates[a * 2],
+      ay = mesh.gridCoordinates[a * 2 + 1];
+    const bx = mesh.gridCoordinates[b * 2],
+      by = mesh.gridCoordinates[b * 2 + 1];
+    const cx = mesh.gridCoordinates[c * 2],
+      cy = mesh.gridCoordinates[c * 2 + 1];
+    const determinant = (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+    if (!Number.isFinite(determinant) || determinant === 0)
+      throw new Error('Degenerate terrain mesh grid triangle');
+    const px = mesh.positions[a * 3],
+      py = mesh.positions[a * 3 + 1];
+    const ux = mesh.positions[b * 3] - px,
+      uy = mesh.positions[b * 3 + 1] - py;
+    const vx = mesh.positions[c * 3] - px,
+      vy = mesh.positions[c * 3 + 1] - py;
+    const xyArea = ux * vy - uy * vx;
+    if (!Number.isFinite(xyArea) || xyArea === 0)
+      throw new Error('Degenerate terrain mesh XY triangle');
+    for (
+      let row = Math.max(0, Math.min(ay, by, cy) - 1);
+      row <= Math.min(field.height - 1, Math.max(ay, by, cy) + 1);
+      row++
+    )
+      for (
+        let column = Math.max(0, Math.min(ax, bx, cx) - 1);
+        column <= Math.min(field.width - 1, Math.max(ax, bx, cx) + 1);
+        column++
+      ) {
+        if (sampleTests++ === limit) throw new Error('Terrain mesh sample-test budget exceeded');
+        const dx = baseX + (column + shift) * columnX + (row + shift) * rowX - px;
+        const dy = baseY + (column + shift) * columnY + (row + shift) * rowY - py;
+        const sign = Math.sign(xyArea),
+          area = Math.abs(xyArea);
+        const nu = (dx * vy - dy * vx) * sign;
+        const nv = (ux * dy - uy * dx) * sign;
+        const tolerance =
+          16 *
+          Number.EPSILON *
+          (Math.abs(dx * vy) + Math.abs(dy * vx) + Math.abs(ux * dy) + Math.abs(uy * dx) + area);
+        if (nu < -tolerance || nv < -tolerance || nu + nv > area + tolerance) continue;
+        const u = nu / area,
+          v = nv / area,
+          w = (area - nu - nv) / area;
+        const height = field.getHeight(column, row);
+        if (height === undefined) continue;
+        const predicted =
+          w * mesh.positions[a * 3 + 2] +
+          u * mesh.positions[b * 3 + 2] +
+          v * mesh.positions[c * 3 + 2];
+        // Error-free TwoDiff retains the low part lost when rebasing source Z.
+        // Comparing only with the rounded local height would certify that loss as zero.
+        const localHeight = height - mesh.origin[2];
+        const virtualOrigin = height - localHeight;
+        const remainder = height - (localHeight + virtualOrigin) + (virtualOrigin - mesh.origin[2]);
+        const error = Math.abs(predicted - localHeight - remainder);
+        if (!Number.isFinite(error)) throw new Error('Terrain mesh error arithmetic overflow');
+        const index = row * field.width + column;
+        if (!covered[index]) {
+          covered[index] = 1;
+          coveredSampleCount++;
+        }
+        errors[index] = Math.max(errors[index], error);
+        maxSampleError = Math.max(maxSampleError, error);
+      }
+  }
+  let squares = 0;
+  if (maxSampleError) for (const error of errors) squares += (error / maxSampleError) ** 2;
+  return {
+    maxSampleError,
+    rmsSampleError: coveredSampleCount
+      ? maxSampleError * Math.sqrt(squares / coveredSampleCount)
+      : 0,
+    coveredSampleCount,
+    uncoveredSampleCount: field.validCount - coveredSampleCount,
+    sampleTests
+  };
+}

package/src/terrain/mesh-skirts.ts

@@ -0,0 +1,166 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export type TerrainSkirtOptions = {
+  /** Positive downward distance in the same units as positions. */
+  height: number;
+  /** Optional unordered pairs of boundary vertex IDs. Omit to skirt every boundary, including holes. */
+  edges?: Uint16Array | Uint32Array;
+  maxVertices?: number;
+  maxTriangles?: number;
+};
+
+export type TerrainSkirtMesh = {
+  positions: Float32Array | Float64Array;
+  indices: Uint16Array | Uint32Array;
+  /** Each appended vertex maps to its source vertex; original vertices are unchanged. */
+  sourceVertexIndices: Uint32Array;
+  skirtVertexOffset: number;
+  skirtTriangleOffset: number;
+  /** One for original triangles, zero for visual skirt triangles. */
+  triangleValidity: Uint8Array;
+  /** Local XYZ bounds including the skirt. */
+  bounds: readonly [readonly [number, number, number], readonly [number, number, number]];
+};
+
+/** Build detached visual skirts from the directed boundary of an upward-facing terrain mesh.
+ * Supplied edge pairs select boundaries but do not determine winding. Shared edges must have
+ * opposite directions; nonmanifold, degenerate, and downward-facing source triangles are rejected.
+ */
+export function createTerrainSkirt(
+  mesh: {positions: Float32Array | Float64Array; indices: Uint16Array | Uint32Array},
+  options: TerrainSkirtOptions
+): TerrainSkirtMesh {
+  const {positions, indices} = mesh,
+    {height, edges} = options;
+  const maxVertices = options.maxVertices ?? 2_000_000,
+    maxTriangles = options.maxTriangles ?? 4_000_000;
+  if (
+    !Number.isFinite(height) ||
+    height <= 0 ||
+    !Number.isSafeInteger(maxVertices) ||
+    maxVertices < 0 ||
+    maxVertices > 0xffffffff ||
+    !Number.isSafeInteger(maxTriangles) ||
+    maxTriangles < 0 ||
+    maxTriangles > 0xffffffff
+  )
+    throw new Error('Invalid terrain skirt height or capacity');
+  if (
+    !(positions instanceof Float32Array || positions instanceof Float64Array) ||
+    positions.length < 3 ||
+    positions.length % 3 ||
+    !positions.every(Number.isFinite) ||
+    !(indices instanceof Uint16Array || indices instanceof Uint32Array) ||
+    indices.length % 3 ||
+    positions.length / 3 > maxVertices ||
+    indices.length / 3 > maxTriangles
+  )
+    throw new Error('Invalid terrain skirt mesh or capacity');
+  if (
+    edges !== undefined &&
+    (!(edges instanceof Uint16Array || edges instanceof Uint32Array) || edges.length % 2)
+  )
+    throw new Error('Invalid terrain skirt edge pairs');
+  const vertexCount = positions.length / 3,
+    triangleCount = indices.length / 3;
+  const boundary = new Map<string, {a: number; b: number; count: number}>();
+  for (let i = 0; i < indices.length; i += 3) {
+    const ids = [indices[i], indices[i + 1], indices[i + 2]];
+    if (ids.some(id => id >= vertexCount)) throw new Error('Terrain skirt index out of range');
+    const [a, b, c] = ids.map(id => id * 3);
+    const area =
+      (positions[b] - positions[a]) * (positions[c + 1] - positions[a + 1]) -
+      (positions[b + 1] - positions[a + 1]) * (positions[c] - positions[a]);
+    if (!Number.isFinite(area) || area <= 0)
+      throw new Error('Terrain skirt requires upward nondegenerate XY triangles');
+    for (let j = 0; j < 3; j++) {
+      const u = ids[j],
+        v = ids[(j + 1) % 3],
+        key = edgeKey(u, v),
+        prior = boundary.get(key);
+      if (!prior) boundary.set(key, {a: u, b: v, count: 1});
+      else {
+        if (prior.count !== 1 || prior.a !== v || prior.b !== u)
+          throw new Error('Terrain skirt mesh has nonmanifold or inconsistent edges');
+        prior.count++;
+      }
+    }
+  }
+  let selected: {a: number; b: number}[];
+  if (edges) {
+    selected = [];
+    const used = new Set<string>();
+    for (let i = 0; i < edges.length; i += 2) {
+      const key = edgeKey(edges[i], edges[i + 1]),
+        edge = boundary.get(key);
+      if (!edge || edge.count !== 1 || used.has(key))
+        throw new Error('Terrain skirt selection must contain unique boundary edges');
+      used.add(key);
+      selected.push(edge);
+    }
+  } else selected = [...boundary.values()].filter(edge => edge.count === 1);
+  const outputVertices = vertexCount + selected.length * 2,
+    outputTriangles = triangleCount + selected.length * 2;
+  if (
+    !Number.isSafeInteger(outputVertices) ||
+    outputVertices > maxVertices ||
+    outputVertices > 0xffffffff ||
+    !Number.isSafeInteger(outputTriangles) ||
+    outputTriangles > maxTriangles
+  )
+    throw new Error('Terrain skirt output capacity exceeded');
+  const resultPositions =
+    positions instanceof Float32Array
+      ? new Float32Array(outputVertices * 3)
+      : new Float64Array(outputVertices * 3);
+  resultPositions.set(positions);
+  const resultIndices =
+    indices instanceof Uint16Array && outputVertices <= 65536
+      ? new Uint16Array(outputTriangles * 3)
+      : new Uint32Array(outputTriangles * 3);
+  resultIndices.set(indices);
+  const sourceVertexIndices = new Uint32Array(selected.length * 2),
+    triangleValidity = new Uint8Array(outputTriangles);
+  triangleValidity.fill(1, 0, triangleCount);
+  for (let i = 0; i < selected.length; i++) {
+    const {a, b} = selected[i],
+      lowerA = vertexCount + 2 * i,
+      lowerB = lowerA + 1;
+    for (const [source, target] of [
+      [a, lowerA],
+      [b, lowerB]
+    ]) {
+      resultPositions.set(positions.subarray(3 * source, 3 * source + 3), 3 * target);
+      resultPositions[3 * target + 2] = positions[3 * source + 2] - height;
+      if (
+        !Number.isFinite(resultPositions[3 * target + 2]) ||
+        resultPositions[3 * target + 2] >= positions[3 * source + 2]
+      )
+        throw new Error('Terrain skirt height cannot be represented in position precision');
+      sourceVertexIndices[target - vertexCount] = source;
+    }
+    resultIndices.set([a, lowerB, b, lowerB, a, lowerA], indices.length + i * 6);
+  }
+  const min: [number, number, number] = [Infinity, Infinity, Infinity],
+    max: [number, number, number] = [-Infinity, -Infinity, -Infinity];
+  for (let i = 0; i < resultPositions.length; i++) {
+    const axis = i % 3;
+    min[axis] = Math.min(min[axis], resultPositions[i]);
+    max[axis] = Math.max(max[axis], resultPositions[i]);
+  }
+  return {
+    positions: resultPositions,
+    indices: resultIndices,
+    sourceVertexIndices,
+    skirtVertexOffset: vertexCount,
+    skirtTriangleOffset: triangleCount,
+    triangleValidity,
+    bounds: [min, max]
+  };
+}
+
+function edgeKey(a: number, b: number): string {
+  return a < b ? `${a},${b}` : `${b},${a}`;
+}