@math.gl/geospatial 5.0.0-alpha.18 → 5.0.0-alpha.19

package/src/projection/experimental/flat-projection.ts

@@ -0,0 +1,80 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original batch adapter; numerical equations retain their own proj4js provenance.
+import {createProjection} from './mutable-projection';
+import {ProjectionScratch} from './projection-scratch';
+import type {ProjectionFlatContext, ProjectionFlatOperation, ProjectionPoint} from './types';
+
+/** Fuse eligible geographic/projected pipelines into one buffer traversal. */
+export function createFlatProjection(
+  forward: (point: ProjectionPoint) => void,
+  inverse: (point: ProjectionPoint) => void
+) {
+  return {
+    ...createProjection(forward, inverse),
+    createForwardFlat(context: ProjectionFlatContext) {
+      // A custom decorator that replaces a mutable hook must keep its own semantics.
+      return this.forwardInPlace === forward
+        ? createFlatOperation(forward, false, context)
+        : undefined;
+    },
+    createInverseFlat(context: ProjectionFlatContext) {
+      return this.inverseInPlace === inverse
+        ? createFlatOperation(inverse, true, context)
+        : undefined;
+    }
+  };
+}
+
+function createFlatOperation(
+  project: (point: ProjectionPoint) => void,
+  inverse: boolean,
+  {inputScale, outputScale}: ProjectionFlatContext
+): ProjectionFlatOperation {
+  const scratch = new ProjectionScratch();
+  return (coordinates, dimension) => {
+    const point = scratch.acquire();
+    try {
+      const float32 = coordinates instanceof Float32Array;
+      for (let offset = 0; offset < coordinates.length; offset += dimension) {
+        point.x = coordinates[offset];
+        point.y = coordinates[offset + 1];
+        point.z = dimension >= 3 ? coordinates[offset + 2] : 0;
+        if (!Number.isFinite(point.x) || !Number.isFinite(point.y) || !Number.isFinite(point.z))
+          throw new Error('Coordinates must contain finite x, y and optional z values');
+        if (inputScale !== 1) {
+          point.x *= inputScale;
+          point.y *= inputScale;
+        }
+        if (inverse) project(point);
+        if (
+          Math.abs(point.y) > Math.PI / 2 ||
+          !Number.isFinite(point.x) ||
+          !Number.isFinite(point.y)
+        )
+          throw new Error('Coordinate is outside the geographic domain');
+        // Match the general pipeline's zero prime-meridian arithmetic, including -0.
+        point.x += 0;
+        point.x -= 0;
+        if (!inverse) project(point);
+        if (outputScale !== 1) {
+          point.x /= outputScale;
+          point.y /= outputScale;
+        }
+        if (!Number.isFinite(point.x) || !Number.isFinite(point.y))
+          throw new Error('Projection produced non-finite coordinates');
+        if (
+          float32 &&
+          (Math.abs(point.x) > 3.4028234663852886e38 || Math.abs(point.y) > 3.4028234663852886e38)
+        )
+          throw new Error('Projected coordinate exceeds Float32 range');
+        // Only completed records are committed. Height and trailing ordinates stay in storage.
+        coordinates[offset] = point.x;
+        coordinates[offset + 1] = point.y;
+      }
+    } finally {
+      scratch.release(point);
+    }
+  };
+}

package/src/projection/experimental/grids/geotiff.ts

@@ -0,0 +1,88 @@
+// 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) vis.gl contributors
+// SPDX-FileComment: GeoTIFF node orientation directly adapted from proj4js 2.22.0 lib/nadgrid.js. See ../../../PROJ4-LICENSE.md. Modified for explicit async loading, validation and nodata handling; no geotiff runtime import.
+import {createDatumGrid} from './grid';
+import type {DatumGrid, Subgrid} from './types';
+
+/** Structural subset supported by geotiff.js v2/v3; callers own file/network decoding. */
+export type DatumGridGeoTIFFImage = {
+  getWidth(): number;
+  getHeight(): number;
+  getBoundingBox(): number[];
+  fileDirectory:
+    | {ModelPixelScale?: ArrayLike<number>}
+    | {getValue(name: 'ModelPixelScale'): unknown};
+  readRasters(): Promise<ArrayLike<number | ArrayLike<number>>>;
+  getGDALNoData?(): number | null;
+};
+export type DatumGridGeoTIFF = {
+  getImageCount(): Promise<number>;
+  getImage(index: number): Promise<DatumGridGeoTIFFImage>;
+};
+/** Load horizontal latitude/longitude offset bands in arcseconds on a geographic degree grid.
+ * Images are tried last-to-first, matching proj4js's child-before-parent GeoTIFF ordering.
+ */
+export async function loadGeoTIFFGrid(tiff: DatumGridGeoTIFF): Promise<DatumGrid> {
+  const count = await tiff.getImageCount();
+  if (!Number.isSafeInteger(count) || count < 1)
+    throw new Error('GeoTIFF requires at least one image');
+  const subgrids: Subgrid[] = [];
+  for (let n = count - 1; n >= 0; n--) {
+    const image = await tiff.getImage(n),
+      width = image.getWidth(),
+      height = image.getHeight();
+    if (![width, height].every(v => Number.isSafeInteger(v) && v >= 2))
+      throw new Error('Invalid GeoTIFF grid dimensions');
+    const bbox = image.getBoundingBox();
+    const directory = image.fileDirectory;
+    const scale =
+      'getValue' in directory ? directory.getValue('ModelPixelScale') : directory.ModelPixelScale;
+    if (!scale || typeof scale !== 'object' || !('0' in scale) || !('1' in scale))
+      throw new Error('GeoTIFF requires ModelPixelScale');
+    const sx = Number(scale[0]),
+      sy = Number(scale[1]);
+    if (
+      bbox.length !== 4 ||
+      !bbox.every(Number.isFinite) ||
+      !(sx > 0 && sy > 0 && Number.isFinite(sx) && Number.isFinite(sy))
+    )
+      throw new Error('Invalid GeoTIFF geographic grid geometry');
+    const rasters = await image.readRasters(),
+      latitude = rasters[0],
+      longitude = rasters[1];
+    if (
+      !latitude ||
+      !longitude ||
+      typeof latitude === 'number' ||
+      typeof longitude === 'number' ||
+      latitude.length !== width * height ||
+      longitude.length !== width * height
+    )
+      throw new Error('GeoTIFF requires latitude and longitude offset bands');
+    const nodata = image.getGDALNoData?.();
+    const shifts = new Float64Array(width * height * 2);
+    let node = 0;
+    for (let row = height - 1; row >= 0; row--)
+      for (let col = width - 1; col >= 0; col--) {
+        const index = row * width + col,
+          lat = latitude[index],
+          lon = longitude[index];
+        const missing =
+          lat === nodata || lon === nodata || !Number.isFinite(lat) || !Number.isFinite(lon);
+        shifts[node++] = missing ? NaN : (-lon * Math.PI) / 648000;
+        shifts[node++] = missing ? NaN : (lat * Math.PI) / 648000;
+      }
+    subgrids.push({
+      origin: [
+        (-(bbox[0] + (width - 1) * sx) * Math.PI) / 180,
+        ((bbox[3] - (height - 1) * sy) * Math.PI) / 180
+      ],
+      step: [(sx * Math.PI) / 180, (sy * Math.PI) / 180],
+      size: [width, height],
+      shifts
+    });
+  }
+  return createDatumGrid(subgrids);
+}

package/src/projection/experimental/grids/grid.ts

@@ -0,0 +1,141 @@
+// 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) vis.gl contributors
+// SPDX-FileComment: Bilinear interpolation and inverse grid equations directly adapted from proj4js 2.22.0 lib/datum_transform.js. See ../../../PROJ4-LICENSE.md. Modified for immutable explicit state, inclusive edges, nodata and bounded two-axis convergence.
+import type {DatumGrid, Subgrid} from './types';
+import {wrapLongitude} from '../parameters';
+
+const TOLERANCE = 1e-12;
+type PreparedSubgrid = Subgrid & {maxShift: readonly [number, number]};
+
+type Point = {x: number; y: number};
+function interpolate(
+  grid: PreparedSubgrid,
+  x: number,
+  y: number,
+  output: Point,
+  clamp = false
+): boolean {
+  let col = (x - grid.origin[0]) / grid.step[0],
+    row = (y - grid.origin[1]) / grid.step[1];
+  const width = grid.size[0],
+    height = grid.size[1];
+  if (
+    !clamp &&
+    (col < -1e-10 || row < -1e-10 || col > width - 1 + 1e-10 || row > height - 1 + 1e-10)
+  )
+    return false;
+  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)),
+    j = Math.min(height - 2, Math.floor(row));
+  const u = col - i,
+    v = row - j;
+  let dx = 0,
+    dy = 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 === 0) continue;
+    const index = ((j + (upper ? 1 : 0)) * width + i + right) * 2;
+    const xShift = grid.shifts[index],
+      yShift = grid.shifts[index + 1];
+    if (!Number.isFinite(xShift) || !Number.isFinite(yShift)) return false;
+    dx += weight * xShift;
+    dy += weight * yShift;
+  }
+  output.x = dx;
+  output.y = dy;
+  return true;
+}
+function shiftSubgrid(
+  grid: PreparedSubgrid,
+  x: number,
+  y: number,
+  inverse: boolean,
+  output: Point
+): boolean {
+  if (!inverse) {
+    if (!interpolate(grid, x, y, output)) return false;
+    output.x += x;
+    output.y += y;
+    return true;
+  }
+  // Seed shifted boundary nodes within the measured displacement envelope.
+  for (let i = 0; i < 2; i++) {
+    const value = i === 0 ? x : y;
+    if (
+      value < grid.origin[i] - grid.maxShift[i] - TOLERANCE ||
+      value > grid.origin[i] + (grid.size[i] - 1) * grid.step[i] + grid.maxShift[i] + TOLERANCE
+    )
+      return false;
+  }
+  if (!interpolate(grid, x, y, output, true)) return false;
+  let guessX = x - output.x,
+    guessY = y - output.y;
+  for (let iteration = 0; iteration < 20; iteration++) {
+    if (!interpolate(grid, guessX, guessY, output, true)) return false;
+    const dx = x - guessX - output.x,
+      dy = y - guessY - output.y;
+    guessX += dx;
+    guessY += dy;
+    if (Math.max(Math.abs(dx), Math.abs(dy)) <= TOLERANCE) {
+      // Never accept the clamped extrapolation outside actual source coverage.
+      if (!interpolate(grid, guessX, guessY, output)) return false;
+      output.x = wrapLongitude(guessX);
+      output.y = guessY;
+      return true;
+    }
+  }
+  throw new Error('Inverse datum grid shift did not converge');
+}
+/** Readers own their decoded arrays; keep the snapshot private behind a frozen executable grid. */
+export function createDatumGrid(subgrids: Subgrid[]): DatumGrid {
+  if (!subgrids.length) throw new Error('Datum grid requires at least one subgrid');
+  const prepared: PreparedSubgrid[] = subgrids.map(grid => {
+    const [width, height] = grid.size;
+    if (
+      ![width, height].every(n => Number.isSafeInteger(n) && n >= 2) ||
+      width * height * 2 !== grid.shifts.length ||
+      !grid.origin.every(Number.isFinite) ||
+      !grid.step.every(n => Number.isFinite(n) && n > 0)
+    )
+      throw new Error('Invalid datum subgrid geometry or node count');
+    const maxShift: [number, number] = [0, 0];
+    for (let index = 0; index < grid.shifts.length; index++) {
+      const value = grid.shifts[index];
+      if (Number.isFinite(value))
+        maxShift[index % 2] = Math.max(maxShift[index % 2], Math.abs(value));
+    }
+    return {...grid, maxShift};
+  });
+  const shiftInPlace = (point: Point, inverse: boolean): boolean => {
+    const longitude = point.x,
+      latitude = point.y;
+    if (!Number.isFinite(longitude) || !Number.isFinite(latitude))
+      throw new Error('Grid coordinates must be finite');
+    for (const grid of prepared) {
+      if (shiftSubgrid(grid, -longitude, latitude, inverse, point)) {
+        point.x = -point.x;
+        return true;
+      }
+    }
+    point.x = longitude;
+    point.y = latitude;
+    return false;
+  };
+  // This private point never escapes or invokes application hooks. A returned
+  // tuple owns its values; the next call resets both coordinates even after failure.
+  const tupleScratch: Point = {x: NaN, y: NaN};
+  return Object.freeze({
+    subgridCount: prepared.length,
+    shiftInPlace,
+    shift(longitude: number, latitude: number, inverse: boolean): [number, number] | undefined {
+      tupleScratch.x = longitude;
+      tupleScratch.y = latitude;
+      return shiftInPlace(tupleScratch, inverse) ? [tupleScratch.x, tupleScratch.y] : undefined;
+    }
+  });
+}

package/src/projection/experimental/grids/gtx.ts

@@ -0,0 +1,31 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original reader for the NOAA GTX format documented by GDAL and PROJ. No upstream implementation is copied. Independent tests use PROJ 9.5.1.
+import {createVerticalGrid} from './vertical';
+import type {VerticalGrid} from './types';
+
+/** Read a big-endian GTX grid (float32 metre offsets) into an owned snapshot.
+ * The conventional -88.8888 float32 sentinel and offsets outside ±1000 metres are nodata, matching PROJ GTX semantics.
+ * Fetching/decompression remain caller-owned; the prepared grid is synchronous.
+ */
+export function parseGTXGrid(buffer: ArrayBuffer): VerticalGrid {
+  const data = new DataView(buffer);
+  if (data.byteLength < 40) throw new Error('Truncated GTX header');
+  const height = data.getInt32(32),
+    width = data.getInt32(36);
+  if (width < 2 || height < 2 || data.byteLength !== 40 + width * height * 4)
+    throw new Error('Invalid GTX dimensions or data length');
+  const offsets = new Float32Array(width * height);
+  for (let i = 0; i < offsets.length; i++) {
+    const value = data.getFloat32(40 + i * 4);
+    offsets[i] = Math.abs(value) > 1000 ? NaN : value;
+  }
+  return createVerticalGrid({
+    origin: [data.getFloat64(8), data.getFloat64(0)],
+    step: [data.getFloat64(24), data.getFloat64(16)],
+    size: [width, height],
+    offsets,
+    noData: Math.fround(-88.8888)
+  });
+}

package/src/projection/experimental/grids/ntv2.ts

@@ -0,0 +1,71 @@
+// 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) vis.gl contributors
+// SPDX-FileComment: NTv2 decoding directly adapted from proj4js 2.22.0 lib/nadgrid.js. See ../../../PROJ4-LICENSE.md. Modified for explicit ownership, bounds/geometry validation and no global registration.
+import {createDatumGrid} from './grid';
+import type {DatumGrid, Subgrid} from './types';
+
+export type NTv2GridOptions = {
+  /** False selects compact 8-byte nodes; true (default) selects 16-byte nodes with accuracy fields. */
+  includeErrorFields?: boolean;
+};
+const ARC_SECOND = Math.PI / 648000;
+/** Decode an owned grid snapshot. The input buffer may be changed or released after this returns. */
+export function parseNTv2Grid(data: ArrayBuffer, options: NTv2GridOptions = {}): DatumGrid {
+  const view = new DataView(data);
+  if (view.byteLength < 176) throw new Error('Truncated NTv2 overview header');
+  const little = view.getInt32(8, true) === 11;
+  if (!little && view.getInt32(8, false) !== 11)
+    throw new Error('Invalid NTv2 header or byte order');
+  const integer = (offset: number) => view.getInt32(offset, little);
+  const real = (offset: number) => view.getFloat64(offset, little);
+  const label = (offset: number) =>
+    String.fromCharCode(...new Uint8Array(data, offset, 8))
+      .replace(/\0/g, '')
+      .trim();
+  if (label(0) !== 'NUM_OREC' || integer(24) !== 11 || label(56) !== 'SECONDS')
+    throw new Error('Unsupported NTv2 header or shift units');
+  const count = integer(40),
+    stride = options.includeErrorFields === false ? 8 : 16;
+  if (count < 1 || count > Math.floor((view.byteLength - 176) / (176 + 4 * stride)))
+    throw new Error('Invalid NTv2 subgrid count');
+  let offset = 176;
+  const subgrids: Subgrid[] = [];
+  for (let n = 0; n < count; n++) {
+    if (offset + 176 > view.byteLength) throw new Error('Truncated NTv2 subgrid header');
+    const lowerLat = real(offset + 72),
+      upperLat = real(offset + 88),
+      lowerLon = real(offset + 104),
+      upperLon = real(offset + 120);
+    const latStep = real(offset + 136),
+      lonStep = real(offset + 152),
+      nodes = integer(offset + 168);
+    const width = 1 + (upperLon - lowerLon) / lonStep,
+      height = 1 + (upperLat - lowerLat) / latStep;
+    if (
+      ![width, height].every(
+        v => Number.isFinite(v) && v >= 2 && Math.abs(v - Math.round(v)) < 1e-7
+      ) ||
+      !(lonStep > 0 && latStep > 0) ||
+      nodes !== Math.round(width) * Math.round(height)
+    )
+      throw new Error('Invalid NTv2 subgrid dimensions');
+    const start = offset + 176,
+      end = start + nodes * stride;
+    if (end > view.byteLength) throw new Error('Truncated NTv2 node records');
+    const shifts = new Float64Array(nodes * 2);
+    for (let i = 0; i < nodes; i++) {
+      shifts[i * 2] = view.getFloat32(start + i * stride + 4, little) * ARC_SECOND;
+      shifts[i * 2 + 1] = view.getFloat32(start + i * stride, little) * ARC_SECOND;
+    }
+    subgrids.push({
+      origin: [lowerLon * ARC_SECOND, lowerLat * ARC_SECOND],
+      step: [lonStep * ARC_SECOND, latStep * ARC_SECOND],
+      size: [Math.round(width), Math.round(height)],
+      shifts
+    });
+    offset = end;
+  }
+  return createDatumGrid(subgrids);
+}

package/src/projection/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/projection/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>>;