@math.gl/projection 0.0.0-stage → 5.0.0-alpha.12

package/src/experimental/grids/scalar-geotiff.ts

@@ -0,0 +1,231 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original adapter for PROJ's Geodetic TIFF Grid specification, not a proj4js/PROJ fork. Decoding is caller-owned; no TIFF library is imported at runtime.
+import {createVerticalGrid} from './vertical';
+import type {VerticalGrid} from './types';
+
+type Metadata = Record<string, unknown> | null;
+type DirectoryTag = 'ModelPixelScale' | 'ModelTiepoint' | 'ModelTransformation' | 'NewSubfileType';
+/** Structural subset of geotiff.js v2/v3. Metadata may be synchronous or asynchronous. */
+export type VerticalGridGeoTIFFImage = {
+  getWidth(): number;
+  getHeight(): number;
+  getGeoKeys(): Record<string, unknown> | null;
+  getGDALMetadata(sample?: number | null): Metadata | Promise<Metadata>;
+  getGDALNoData?(): number | null;
+  fileDirectory: Partial<Record<DirectoryTag, unknown>> | {getValue(name: DirectoryTag): unknown};
+  readRasters(options: {
+    samples: number[];
+    interleave: false;
+  }): Promise<ArrayLike<number | ArrayLike<number>>>;
+};
+export type VerticalGridGeoTIFF = {
+  getImageCount(): Promise<number>;
+  getImage(index: number): Promise<VerticalGridGeoTIFFImage>;
+};
+
+/** Plain decoded raster input, structurally compatible with loaders.gl GeoTIFFRasterData. */
+export type VerticalGridGeoTIFFData = {
+  /** Images in original file order, with parents before nested children. */
+  images: readonly {
+    /** Original dimensions in pixels. */
+    width: number;
+    /** Original dimensions in pixels. */
+    height: number;
+    /** Raw bands; original band zero must be present. */
+    bands: readonly {
+      /** Original zero-based sample index, retained when selecting bands. */
+      index: number;
+      /** Native, unscaled samples in TIFF row order. */
+      data: ArrayLike<number>;
+      /** Per-band GDAL metadata. */
+      metadata: Metadata;
+    }[];
+    /** Decoded CRS and pixel-registration GeoKeys. */
+    geoKeys: Metadata;
+    /** Image-level GDAL metadata. */
+    metadata: Metadata;
+    /** Declared nodata value, before scale/offset. */
+    noData: number | null;
+    /** Original geometry and image-kind tags. */
+    fileDirectory: Partial<Record<DirectoryTag, unknown>>;
+  }[];
+};
+
+/** Adapts plain numeric rasters without importing or retaining a TIFF decoder. */
+function getRasterImage(data: VerticalGridGeoTIFFData, index: number): VerticalGridGeoTIFFImage {
+  const image = data.images[index];
+  const band = image.bands.find(candidate => candidate.index === 0);
+  if (!band) throw new Error('Vertical GeoTIFF requires original band zero');
+  return {
+    getWidth: () => image.width,
+    getHeight: () => image.height,
+    getGeoKeys: () => image.geoKeys,
+    getGDALMetadata: sample => (sample === 0 ? band.metadata : image.metadata),
+    getGDALNoData: () => image.noData,
+    fileDirectory: image.fileDirectory,
+    readRasters: async () => [band.data]
+  };
+}
+
+function number(value: unknown, fallback: number): number {
+  if (value === undefined) return fallback;
+  if (
+    (typeof value !== 'number' && typeof value !== 'string') ||
+    (typeof value === 'string' && !value.trim()) ||
+    !Number.isFinite(Number(value))
+  )
+    throw new Error('Invalid vertical GeoTIFF scale or offset');
+  return Number(value);
+}
+function vector(value: unknown, length: number): number[] {
+  if (!value || typeof value !== 'object' || !('length' in value) || value.length !== length)
+    throw new Error('Vertical GeoTIFF requires one tiepoint and pixel scale');
+  const result = Array.from(value as ArrayLike<number>);
+  if (!result.every(Number.isFinite)) throw new Error('Invalid vertical GeoTIFF geometry');
+  return result;
+}
+
+/** Prepare metre geoid undulations from geographic, north-up PROJ Geodetic TIFF grids.
+ * The first band must declare geoid_undulation; dataset TYPE must be
+ * VERTICAL_OFFSET_GEOGRAPHIC_TO_VERTICAL. PixelIsPoint and PixelIsArea are supported.
+ * Later nested images take precedence. Overviews, ambiguous overlaps, rotations,
+ * non-metre bands and other operation types are rejected rather than inferred.
+ */
+export async function prepareScalarGeoTIFFGrids(
+  tiff: VerticalGridGeoTIFF | VerticalGridGeoTIFFData
+): Promise<VerticalGrid[]> {
+  const count = 'images' in tiff ? tiff.images.length : await tiff.getImageCount();
+  if (!Number.isSafeInteger(count) || count < 1)
+    throw new Error('Vertical GeoTIFF requires at least one image');
+  const prepared: {
+    grid: VerticalGrid;
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+    dx: number;
+    dy: number;
+  }[] = [];
+  for (let n = 0; n < count; n++) {
+    const image = 'images' in tiff ? getRasterImage(tiff, n) : await tiff.getImage(n);
+    const directory = image.fileDirectory;
+    const tag = (name: DirectoryTag) =>
+      'getValue' in directory ? directory.getValue(name) : directory[name];
+    if (tag('NewSubfileType') !== undefined && tag('NewSubfileType') !== 0)
+      throw new Error('Vertical GeoTIFF overviews and masks are unsupported');
+    if (tag('ModelTransformation') !== undefined)
+      throw new Error('Vertical GeoTIFF requires axis-aligned tiepoint/scale geometry');
+    const keys = image.getGeoKeys();
+    if (
+      keys?.['GTModelTypeGeoKey'] !== 2 ||
+      (keys['GeogAngularUnitsGeoKey'] !== undefined && keys['GeogAngularUnitsGeoKey'] !== 9102)
+    )
+      throw new Error('Vertical GeoTIFF requires a geographic degree grid');
+    if (
+      (keys['GeogPrimeMeridianGeoKey'] !== undefined && keys['GeogPrimeMeridianGeoKey'] !== 8901) ||
+      (keys['GeogPrimeMeridianLongGeoKey'] !== undefined &&
+        keys['GeogPrimeMeridianLongGeoKey'] !== 0)
+    )
+      throw new Error('Vertical GeoTIFF requires Greenwich longitudes');
+    const rasterType = keys['GTRasterTypeGeoKey'];
+    if (rasterType !== 1 && rasterType !== 2)
+      throw new Error('Vertical GeoTIFF requires explicit PixelIsPoint or PixelIsArea');
+    const metadata = await image.getGDALMetadata();
+    const band = await image.getGDALMetadata(0);
+    if (
+      metadata?.['TYPE'] !== 'VERTICAL_OFFSET_GEOGRAPHIC_TO_VERTICAL' ||
+      band?.['DESCRIPTION'] !== 'geoid_undulation'
+    )
+      throw new Error('Vertical GeoTIFF requires a geographic-to-vertical geoid_undulation band');
+    if (band['UNITTYPE'] !== undefined && band['UNITTYPE'] !== 'metre')
+      throw new Error('Vertical GeoTIFF geoid undulations must be in metres');
+    if (
+      metadata['interpolation_method'] !== undefined &&
+      metadata['interpolation_method'] !== 'bilinear'
+    )
+      throw new Error('Vertical GeoTIFF supports only bilinear interpolation');
+    const scale = number(band['SCALE'], 1),
+      offset = number(band['OFFSET'], 0);
+    const [dx, dy] = vector(tag('ModelPixelScale'), 3);
+    const [i, j, k, x, y, z] = vector(tag('ModelTiepoint'), 6);
+    const width = image.getWidth(),
+      height = image.getHeight();
+    if (
+      !(dx > 0 && dy > 0) ||
+      k !== 0 ||
+      z !== 0 ||
+      ![width, height].every(v => Number.isSafeInteger(v) && v >= 2)
+    )
+      throw new Error('Invalid vertical GeoTIFF geometry or dimensions');
+    const half = rasterType === 1 ? 0.5 : 0;
+    const west = x + (half - i) * dx;
+    const north = y - (half - j) * dy;
+    const south = north - (height - 1) * dy,
+      east = west + (width - 1) * dx;
+    if (
+      ![west, south, east, north].every(Number.isFinite) ||
+      !(east > west && north > south) ||
+      east - west > 360 ||
+      south < -90 ||
+      north > 90 ||
+      !Number.isSafeInteger(width * height)
+    )
+      throw new Error('Invalid vertical GeoTIFF geographic extent');
+    // Require ordered nested or disjoint images, so TIFF ordering cannot silently
+    // replace a fine child with a coarse parent or an ambiguous overlapping grid.
+    for (const other of prepared) {
+      const overlaps =
+        west < other.east && east > other.west && south < other.north && north > other.south;
+      if (
+        overlaps &&
+        !(
+          west >= other.west &&
+          east <= other.east &&
+          south >= other.south &&
+          north <= other.north &&
+          dx <= other.dx &&
+          dy <= other.dy
+        )
+      )
+        throw new Error(
+          'Vertical GeoTIFF images must be ordered parent before nested child or disjoint'
+        );
+    }
+    const rasters = await image.readRasters({samples: [0], interleave: false});
+    const values = rasters[0];
+    if (!values || typeof values === 'number' || values.length !== width * height)
+      throw new Error('Vertical GeoTIFF requires a complete non-interleaved height band');
+    const declaredNoData = image.getGDALNoData?.();
+    // GDAL_NODATA is text; compare it in the decoded band's numeric precision.
+    const nodata =
+      values instanceof Float32Array && typeof declaredNoData === 'number'
+        ? Math.fround(declaredNoData)
+        : declaredNoData;
+    const offsets = new Float64Array(width * height);
+    for (let row = 0; row < height; row++)
+      for (let col = 0; col < width; col++) {
+        const raw = values[row * width + col];
+        const value = raw === nodata || !Number.isFinite(raw) ? NaN : raw * scale + offset;
+        if (Number.isFinite(raw) && raw !== nodata && !Number.isFinite(value))
+          throw new Error('Vertical GeoTIFF scale/offset produced a non-finite height');
+        offsets[(height - 1 - row) * width + col] = value;
+      }
+    prepared.push({
+      grid: createVerticalGrid({
+        origin: [west, south],
+        step: [dx, dy],
+        size: [width, height],
+        offsets
+      }),
+      west,
+      south,
+      east,
+      north,
+      dx,
+      dy
+    });
+  }
+  return prepared.map(image => image.grid);
+}

package/src/experimental/grids/types.ts

@@ -0,0 +1,35 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+/** Prepared horizontal datum grid. Inputs/outputs are east-positive longitude/latitude radians. */
+export type DatumGrid = {
+  readonly subgridCount: number;
+  /** Optional mutable hook. On false, x/y must remain unchanged; always preserve z. */
+  shiftInPlace?(point: {x: number; y: number}, inverse: boolean): boolean;
+  /** undefined means no usable subgrid covers this coordinate; other failures throw. */
+  shift(longitude: number, latitude: number, inverse: boolean): [number, number] | undefined;
+};
+/** Per-instance registration. Readers produce grids before synchronous construction. */
+export type DatumGridCollection = Readonly<Record<string, DatumGrid>>;
+export type DatumGridReference = {
+  readonly name: string;
+  readonly optional: boolean;
+  readonly grid?: DatumGrid;
+};
+/** Internal west-positive node layout, matching the pinned proj4js grid convention. */
+export type Subgrid = {
+  readonly origin: readonly [number, number];
+  readonly step: readonly [number, number];
+  readonly size: readonly [number, number];
+  /** Reader-owned west-positive longitude/latitude shift pairs in radians. */
+  readonly shifts: Float64Array;
+};
+
+/** Geoid undulation N in metres: ellipsoidal height h = gravity-related height H + N.
+ * Inputs are east-positive Greenwich longitude and latitude in radians, in the
+ * horizontal datum of the CRS carrying +geoidgrids. Undefined means no coverage.
+ */
+export type VerticalGrid = {
+  getOffset(longitude: number, latitude: number): number | undefined;
+};
+export type VerticalGridCollection = Readonly<Record<string, VerticalGrid>>;

package/src/experimental/grids/velocity-geotiff.ts

@@ -0,0 +1,82 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original adapter inspired by PROJ's Geodetic TIFF Grid specification, not a fork. Caller-owned TIFF decoding; no proj4js, PROJ or TIFF decoder code is copied here.
+import {prepareScalarGeoTIFFGrids} from './scalar-geotiff';
+import {velocityGridFromComponents} from './velocity';
+import type {VelocityGrid} from './velocity';
+import type {
+  VerticalGridGeoTIFF,
+  VerticalGridGeoTIFFData,
+  VerticalGridGeoTIFFImage
+} from './vertical-geotiff';
+export type VelocityGridGeoTIFF = VerticalGridGeoTIFF;
+export type VelocityGridGeoTIFFImage = VerticalGridGeoTIFFImage;
+export type VelocityGridGeoTIFFData = VerticalGridGeoTIFFData;
+
+/** Prepare geographic, north-up GTG VELOCITY images with explicit first-three ENU
+ * bands in millimetres per year. Accuracy bands are ignored. No model/frame/epoch
+ * inference. Decoded loaders.gl rasters and structural geotiff.js objects are accepted.
+ */
+export async function loadVelocityGeoTIFFGrid(
+  tiff: VelocityGridGeoTIFF | VelocityGridGeoTIFFData
+): Promise<VelocityGrid> {
+  const count = 'images' in tiff ? tiff.images.length : await tiff.getImageCount();
+  if (!Number.isSafeInteger(count) || count < 1)
+    throw new Error('Velocity GeoTIFF requires images');
+  const images: VerticalGridGeoTIFFImage[][] = [[], [], []];
+  const names = ['east_velocity', 'north_velocity', 'up_velocity'];
+  for (let index = 0; index < count; index++) {
+    const raster = 'images' in tiff ? tiff.images[index] : undefined;
+    const image = raster ? undefined : await (tiff as VelocityGridGeoTIFF).getImage(index);
+    const metadata = raster ? raster.metadata : await image.getGDALMetadata();
+    if (metadata?.['TYPE'] !== 'VELOCITY')
+      throw new Error('Velocity GeoTIFF requires TYPE=VELOCITY');
+    for (let component = 0; component < 3; component++) {
+      const band = raster?.bands.find(b => b.index === component);
+      if (raster && !band) throw new Error('Velocity GeoTIFF requires original ENU bands 0, 1, 2');
+      const bandMetadata = raster ? band.metadata : await image.getGDALMetadata(component);
+      if (
+        bandMetadata?.['DESCRIPTION'] !== names[component] ||
+        !['millimetres per year', 'mm/year'].includes(bandMetadata?.['UNITTYPE'] as string)
+      )
+        throw new Error(
+          'Velocity GeoTIFF requires explicit ENU descriptions and millimetres per year'
+        );
+      // Reuse scalar geometry, scale/offset, nodata, ownership and hierarchy checks.
+      // This internal view presents native millimetres as generic scalar values;
+      // conversion to metres/year occurs only after all three components are sampled.
+      images[component].push({
+        getWidth: () => (raster ? raster.width : image.getWidth()),
+        getHeight: () => (raster ? raster.height : image.getHeight()),
+        getGeoKeys: () => (raster ? raster.geoKeys : image.getGeoKeys()),
+        getGDALMetadata: sample =>
+          sample === 0
+            ? {...bandMetadata, DESCRIPTION: 'geoid_undulation', UNITTYPE: 'metre'}
+            : {...metadata, TYPE: 'VERTICAL_OFFSET_GEOGRAPHIC_TO_VERTICAL'},
+        getGDALNoData: () => (raster ? raster.noData : (image.getGDALNoData?.() ?? null)),
+        fileDirectory: raster ? raster.fileDirectory : image.fileDirectory,
+        readRasters: async () =>
+          raster ? [band.data] : image.readRasters({samples: [component], interleave: false})
+      });
+    }
+  }
+  const bands = await Promise.all(
+    images.map(list =>
+      prepareScalarGeoTIFFGrids({
+        getImageCount: async () => list.length,
+        getImage: async index => list[index]
+      })
+    )
+  );
+  const grids = bands[0].map((east, index) =>
+    velocityGridFromComponents(east, bands[1][index], bands[2][index], 0.001)
+  );
+  return Object.freeze({
+    sample(longitude, latitude, output): boolean {
+      for (let i = grids.length - 1; i >= 0; i--)
+        if (grids[i].sample(longitude, latitude, output)) return true;
+      return false;
+    }
+  });
+}

package/src/experimental/grids/velocity.ts

@@ -0,0 +1,58 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original ENU grid preparation inspired by PROJ's velocity grid conventions. Bilinear interpolation reuses original math.gl vertical grids; no upstream fork.
+import {createVerticalGrid} from './vertical';
+import type {VerticalGridOptions} from './vertical';
+import type {ProjectionPoint} from '../types';
+import type {VerticalGrid} from './types';
+
+/** Prepared velocities in metres per decimal year at Greenwich lon/lat radians.
+ * sample writes ENU into output.x/y/z only on success. False means no coverage.
+ */
+export type VelocityGrid = {
+  sample(longitude: number, latitude: number, output: ProjectionPoint): boolean;
+};
+export type VelocityGridOptions = Omit<VerticalGridOptions, 'offsets'> & {
+  readonly units: 'm/year' | 'mm/year';
+  /** Owned snapshots, row-major south-to-north and west-to-east. */
+  readonly east: ArrayLike<number>;
+  readonly north: ArrayLike<number>;
+  readonly up: ArrayLike<number>;
+};
+/** Internal atomic three-band sampler: never mix components from different images. */
+export function velocityGridFromComponents(
+  east: VerticalGrid,
+  north: VerticalGrid,
+  up: VerticalGrid,
+  scale: number
+): VelocityGrid {
+  return Object.freeze({
+    sample(longitude: number, latitude: number, output: ProjectionPoint): boolean {
+      const e = east.getOffset(longitude, latitude),
+        n = north.getOffset(longitude, latitude),
+        u = up.getOffset(longitude, latitude);
+      if (e === undefined || n === undefined || u === undefined) return false;
+      const x = e * scale,
+        y = n * scale,
+        z = u * scale;
+      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+        throw new Error('Non-finite velocity interpolation');
+      output.x = x;
+      output.y = y;
+      output.z = z;
+      return true;
+    }
+  });
+}
+/** No extrapolation; nodata in any contributing component makes the sample unavailable. */
+export function createVelocityGrid(options: VelocityGridOptions): VelocityGrid {
+  if (!['m/year', 'mm/year'].includes(options.units))
+    throw new Error('Explicit velocity units required');
+  return velocityGridFromComponents(
+    createVerticalGrid({...options, offsets: options.east}),
+    createVerticalGrid({...options, offsets: options.north}),
+    createVerticalGrid({...options, offsets: options.up}),
+    options.units === 'mm/year' ? 0.001 : 1
+  );
+}

package/src/experimental/grids/vertical-geotiff.ts

@@ -0,0 +1,28 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original adapter for PROJ's GTG conventions; no upstream decoder code is copied.
+import {prepareScalarGeoTIFFGrids} from './scalar-geotiff';
+import type {VerticalGrid} from './types';
+import type {VerticalGridGeoTIFF, VerticalGridGeoTIFFData} from './scalar-geotiff';
+export type {
+  VerticalGridGeoTIFF,
+  VerticalGridGeoTIFFImage,
+  VerticalGridGeoTIFFData
+} from './scalar-geotiff';
+
+/** Prepare owned geoid grids; later nested images take precedence with nodata fallback. */
+export async function loadVerticalGeoTIFFGrid(
+  tiff: VerticalGridGeoTIFF | VerticalGridGeoTIFFData
+): Promise<VerticalGrid> {
+  const grids = await prepareScalarGeoTIFFGrids(tiff);
+  return Object.freeze({
+    getOffset(longitude: number, latitude: number): number | undefined {
+      for (let i = grids.length - 1; i >= 0; i--) {
+        const value = grids[i].getOffset(longitude, latitude);
+        if (value !== undefined) return value;
+      }
+      return undefined;
+    }
+  });
+}

package/src/experimental/grids/vertical.ts

@@ -0,0 +1,99 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original bilinear vertical grid and structural math.gl/geoid adapter. PROJ supplies independent numeric references; no upstream code is copied.
+import type {VerticalGrid} from './types';
+export type {VerticalGrid, VerticalGridCollection} from './types';
+
+export type VerticalGridOptions = {
+  /** Southwest node, [longitude, latitude] in degrees. */
+  origin: readonly [number, number];
+  /** Positive [longitude, latitude] node spacing in degrees. */
+  step: readonly [number, number];
+  size: readonly [number, number];
+  /** Row-major south-to-north, west-to-east geoid undulations in metres. Copied. */
+  offsets: ArrayLike<number>;
+  /** Non-finite values are also treated as nodata. */
+  noData?: number;
+};
+
+/** Prepare an owned, synchronous grid with inclusive edges and no extrapolation. */
+export function createVerticalGrid(options: VerticalGridOptions): VerticalGrid {
+  const [west, south] = options.origin;
+  const [dx, dy] = options.step;
+  const [width, height] = options.size;
+  const east = west + (width - 1) * dx;
+  const north = south + (height - 1) * dy;
+  if (
+    ![west, south, dx, dy, east, north].every(Number.isFinite) ||
+    ![width, height].every(n => Number.isSafeInteger(n) && n >= 2) ||
+    !(dx > 0 && dy > 0) ||
+    east - west > 360 ||
+    south < -90 ||
+    north > 90 ||
+    width * height !== options.offsets.length
+  )
+    throw new Error('Invalid vertical grid geometry or node count');
+  const noData = options.noData;
+  const values = Float64Array.from(options.offsets, value =>
+    value === noData || !Number.isFinite(value) ? NaN : value
+  );
+  return Object.freeze({
+    getOffset(longitude: number, latitude: number): number | undefined {
+      if (!Number.isFinite(longitude) || !Number.isFinite(latitude))
+        throw new Error('Vertical grid coordinates must be finite');
+      // Choose the equivalent longitude nearest the grid's centre, including
+      // grids expressed in 0..360 degrees or crossing the antimeridian.
+      let x = longitude * (180 / Math.PI);
+      const epsilon = 1e-10;
+      // Preserve either explicit edge of a grid with duplicate seam nodes.
+      if (x < west - epsilon * dx || x > east + epsilon * dx)
+        x += 360 * Math.round(((west + east) / 2 - x) / 360);
+      let col = (x - west) / dx;
+      let row = (latitude * (180 / Math.PI) - south) / dy;
+      if (
+        !Number.isFinite(col) ||
+        !Number.isFinite(row) ||
+        col < -epsilon ||
+        row < -epsilon ||
+        col > width - 1 + epsilon ||
+        row > height - 1 + epsilon
+      )
+        return undefined;
+      col = Math.max(0, Math.min(width - 1, col));
+      row = Math.max(0, Math.min(height - 1, row));
+      const i = Math.min(width - 2, Math.floor(col));
+      const j = Math.min(height - 2, Math.floor(row));
+      const u = col - i,
+        v = row - j;
+      let offset = 0;
+      for (let n = 0; n < 4; n++) {
+        const right = n % 2,
+          upper = n > 1;
+        const weight = (right ? u : 1 - u) * (upper ? v : 1 - v);
+        if (!weight) continue;
+        const value = values[(j + (upper ? 1 : 0)) * width + i + right];
+        if (!Number.isFinite(value)) return undefined;
+        offset += weight * value;
+      }
+      return offset;
+    }
+  });
+}
+
+/** Adapt an already loaded @math.gl/geoid Geoid without importing its implementation.
+ * The supplied model owns its data and interpolation choice; do not mutate it while in use.
+ */
+export function createGeoidGrid(geoid: {
+  getHeight(latitude: number, longitude: number): number;
+}): VerticalGrid {
+  if (!geoid || typeof geoid.getHeight !== 'function') throw new Error('Invalid geoid model');
+  return Object.freeze({
+    getOffset(longitude: number, latitude: number): number | undefined {
+      if (!Number.isFinite(longitude) || !Number.isFinite(latitude))
+        throw new Error('Vertical grid coordinates must be finite');
+      const offset = geoid.getHeight(latitude * (180 / Math.PI), longitude * (180 / Math.PI));
+      return Number.isFinite(offset) ? offset : undefined;
+    }
+  });
+}

package/src/experimental/helmert-flat.ts

@@ -0,0 +1,76 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2014 Mike Adair, Richard Greenwood, Didier Richard, Stephen Irons, Olivier Terral and Calvin Metcalf (proj4js)
+// SPDX-FileCopyrightText: Copyright (c) 2016, Thomas Knudsen / SDFE (PROJ)
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original whole-buffer dispatch. Small-angle equations follow the proj4js adaptation in datum.ts; see ../../PROJ4-LICENSE.md. Exact equations follow exact-helmert.ts, adapted from PROJ 9.5.1 helmert.cpp; see ../../PROJ-LICENSE.txt. Consume its prepared matrix without recomputing rotations.
+import type {NumericFlatOperation} from './numeric-flat';
+
+/** Setup-owned coefficients: small-angle rx/ry/rz or row-major exact matrix, then dx/dy/dz/scale. */
+export function createHelmertFlat(
+  coefficients: readonly number[],
+  inverse: boolean,
+  exact: boolean
+): NumericFlatOperation {
+  const dx = coefficients[9],
+    dy = coefficients[10],
+    dz = coefficients[11],
+    scale = coefficients[12];
+  const a = coefficients[0],
+    b = coefficients[1],
+    c = coefficients[2],
+    d = coefficients[3],
+    e = coefficients[4],
+    f = coefficients[5],
+    g = coefficients[6],
+    h = coefficients[7],
+    j = coefficients[8];
+  return (coordinates, dimension, epochs) => {
+    const float32 = coordinates instanceof Float32Array;
+    const epochBuffer = typeof epochs === 'number' ? undefined : epochs;
+    for (let offset = 0, record = 0; offset < coordinates.length; offset += dimension, record++) {
+      let x = coordinates[offset],
+        y = coordinates[offset + 1],
+        z = coordinates[offset + 2];
+      if (epochBuffer && !Number.isFinite(epochBuffer[record]))
+        throw new Error('Coordinate epoch must be a finite decimal year');
+      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+        throw new Error('Pipeline coordinate must be finite');
+      if (inverse) {
+        x = (x - dx) / scale;
+        y = (y - dy) / scale;
+        z = (z - dz) / scale;
+      }
+      let outX: number, outY: number, outZ: number;
+      if (exact) {
+        if (inverse) {
+          outX = a * x + d * y + g * z;
+          outY = b * x + e * y + h * z;
+          outZ = c * x + f * y + j * z;
+        } else {
+          outX = scale * (a * x + b * y + c * z) + dx;
+          outY = scale * (d * x + e * y + f * z) + dy;
+          outZ = scale * (g * x + h * y + j * z) + dz;
+        }
+      } else if (inverse) {
+        outX = x + c * y - b * z;
+        outY = -c * x + y + a * z;
+        outZ = b * x - a * y + z;
+      } else {
+        outX = scale * (x - c * y + b * z) + dx;
+        outY = scale * (c * x + y - a * z) + dy;
+        outZ = scale * (-b * x + a * y + z) + dz;
+      }
+      if (!Number.isFinite(outX) || !Number.isFinite(outY) || !Number.isFinite(outZ))
+        throw new Error('Pipeline coordinate must be finite');
+      if (
+        float32 &&
+        Math.max(Math.abs(outX), Math.abs(outY), Math.abs(outZ)) > 3.4028234663852886e38
+      )
+        throw new Error('Pipeline output exceeds Float32 range');
+      coordinates[offset] = outX;
+      coordinates[offset + 1] = outY;
+      coordinates[offset + 2] = outZ;
+    }
+  };
+}

package/src/experimental/index.ts

@@ -0,0 +1,59 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export * from './core';
+export {mercator} from './projections/mercator';
+export {equidistantCylindrical} from './projections/equidistant-cylindrical';
+export {lambertConformalConic} from './projections/lcc';
+export {albersEqualArea} from './projections/aea';
+export {equidistantConic} from './projections/eqdc';
+export {lambertAzimuthalEqualArea} from './projections/laea';
+export {stereographic} from './projections/stere';
+export {obliqueStereographic} from './projections/sterea';
+export {azimuthalEquidistant} from './projections/aeqd';
+export {transverseMercator, extendedTransverseMercator} from './projections/transverse-mercator';
+export {universalTransverseMercator} from './projections/utm';
+export {geocentric} from './projections/geocentric';
+export {bonne} from './projections/bonne';
+export {cassiniSoldner} from './projections/cass';
+export {cylindricalEqualArea} from './projections/cea';
+export {eckertVI} from './projections/eck6';
+export {equalEarth} from './projections/eqearth';
+export {equirectangular} from './projections/equi';
+export {geostationary} from './projections/geos';
+export {gnomonic} from './projections/gnom';
+export {gaussSchreiberTransverseMercator} from './projections/gstmerc';
+export {krovak} from './projections/krovak';
+export {millerCylindrical} from './projections/mill';
+export {mollweide} from './projections/moll';
+export {newZealandMapGrid} from './projections/nzmg';
+export {obliqueMercator} from './projections/omerc';
+export {orthographic} from './projections/ortho';
+export {polyconic} from './projections/poly';
+export {quadrilateralizedSphericalCube} from './projections/qsc';
+export {robinson} from './projections/robin';
+export {sinusoidal} from './projections/sinu';
+export {swissObliqueMercator} from './projections/somerc';
+export {tiltedPerspective} from './projections/tpers';
+export {vanDerGrinten} from './projections/vandg';
+export {obliqueTransformation} from './projections/ob-tran';
+export {wktCRSParser} from './crs/wkt';
+export {projJSONCRSParser} from './crs/projjson';
+export {parseNTv2Grid} from './grids/ntv2';
+export type {NTv2GridOptions} from './grids/ntv2';
+export {loadGeoTIFFGrid} from './grids/geotiff';
+export type {DatumGridGeoTIFF, DatumGridGeoTIFFImage} from './grids/geotiff';
+
+export {parseGTXGrid} from './grids/gtx';
+export {createVerticalGrid, createGeoidGrid} from './grids/vertical';
+export type {VerticalGridOptions} from './grids/vertical';
+
+export {loadVerticalGeoTIFFGrid} from './grids/vertical-geotiff';
+export type {
+  VerticalGridGeoTIFF,
+  VerticalGridGeoTIFFImage,
+  VerticalGridGeoTIFFData
+} from './grids/vertical-geotiff';
+
+export * from './projection-pipeline';