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

package/src/projection/experimental/entries/projections/somerc.ts

@@ -0,0 +1,5 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {swissObliqueMercator} from '../../projections/somerc';

package/src/projection/experimental/entries/projections/stere.ts

@@ -0,0 +1,5 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {stereographic} from '../../projections/stere';

package/src/projection/experimental/entries/projections/sterea.ts

@@ -0,0 +1,5 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {obliqueStereographic} from '../../projections/sterea';

package/src/projection/experimental/entries/projections/tmerc.ts

@@ -0,0 +1,5 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {transverseMercator} from '../../projections/transverse-mercator';

package/src/projection/experimental/entries/projections/tpers.ts

@@ -0,0 +1,5 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {tiltedPerspective} from '../../projections/tpers';

package/src/projection/experimental/entries/projections/utm.ts

@@ -0,0 +1,5 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {universalTransverseMercator} from '../../projections/utm';

package/src/projection/experimental/entries/projections/vandg.ts

@@ -0,0 +1,5 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {vanDerGrinten} from '../../projections/vandg';

package/src/projection/experimental/exact-helmert.ts

@@ -0,0 +1,58 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) 2016, Thomas Knudsen / SDFE (PROJ)
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Exact rotation matrix adapted from PROJ 9.5.1 src/transformations/helmert.cpp. See ../../../projection/PROJ-LICENSE.txt. Modified into prepared, typed, allocation-free point operations. Existing small-angle Helmert equations remain the proj4js adaptation in datum.ts.
+import type {ProjectionPoint} from './types';
+
+type Operation = (point: ProjectionPoint) => void;
+export function createExactHelmert(
+  translation: readonly number[],
+  rotation: readonly number[],
+  scalePPM: number,
+  coordinateFrame: boolean
+): {forward: Operation; inverse: Operation; coefficients: readonly number[]} {
+  const radians = Math.PI / (180 * 3600);
+  const [rx, ry, rz] = rotation.map(angle => angle * radians);
+  const cx = Math.cos(rx),
+    sx = Math.sin(rx),
+    cy = Math.cos(ry),
+    sy = Math.sin(ry),
+    cz = Math.cos(rz),
+    sz = Math.sin(rz);
+  // Coordinate-frame convention. Position-vector convention transposes the
+  // whole matrix; simply negating Euler angles is not equivalent for finite rotations.
+  let r01 = cx * sz + sx * sy * cz,
+    r02 = sx * sz - cx * sy * cz,
+    r10 = -cy * sz,
+    r12 = sx * cz + cx * sy * sz,
+    r20 = sy,
+    r21 = -sx * cy;
+  const r00 = cy * cz,
+    r11 = cx * cz - sx * sy * sz,
+    r22 = cx * cy;
+  if (!coordinateFrame) {
+    [r01, r10] = [r10, r01];
+    [r02, r20] = [r20, r02];
+    [r12, r21] = [r21, r12];
+  }
+  const scale = 1 + scalePPM / 1e6;
+  const [dx, dy, dz] = translation;
+  return {
+    coefficients: [r00, r01, r02, r10, r11, r12, r20, r21, r22, dx, dy, dz, scale],
+    forward(point) {
+      const {x, y, z} = point;
+      point.x = scale * (r00 * x + r01 * y + r02 * z) + dx;
+      point.y = scale * (r10 * x + r11 * y + r12 * z) + dy;
+      point.z = scale * (r20 * x + r21 * y + r22 * z) + dz;
+    },
+    inverse(point) {
+      const x = (point.x - dx) / scale,
+        y = (point.y - dy) / scale,
+        z = (point.z - dz) / scale;
+      point.x = r00 * x + r10 * y + r20 * z;
+      point.y = r01 * x + r11 * y + r21 * z;
+      point.z = r02 * x + r12 * y + r22 * z;
+    }
+  };
+}

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 ../../../../projection/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 ../../../../projection/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 ../../../../projection/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);
+}