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

package/src/projection/experimental/scalar-output.ts

@@ -0,0 +1,74 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original caller-owned scalar output validation and commit helpers.
+import type {ProjectionPoint} from './types';
+
+export type ProjectionCoordinate = readonly number[] | Float32Array | Float64Array;
+export type ProjectionOutput = number[] | Float32Array | Float64Array;
+const FLOAT32_MAX = 3.4028234663852886e38;
+
+/** Validate storage before executing user hooks; no views or coordinate copies are created. */
+export function validateScalarOutput(
+  coordinate: ProjectionCoordinate,
+  output: ProjectionOutput,
+  length: number
+): void {
+  if (
+    !(
+      Array.isArray(coordinate) ||
+      coordinate instanceof Float32Array ||
+      coordinate instanceof Float64Array
+    )
+  )
+    throw new Error('Scalar input requires a number array, Float32Array or Float64Array');
+  if (
+    !(Array.isArray(output) || output instanceof Float32Array || output instanceof Float64Array) ||
+    output.length < length
+  )
+    throw new Error(
+      'Scalar output requires a preallocated number array, Float32Array or Float64Array with sufficient capacity'
+    );
+  if (coordinate === output || Array.isArray(coordinate) || Array.isArray(output)) return;
+  const input = coordinate as Float32Array | Float64Array;
+  const result = output as Float32Array | Float64Array;
+  const shared =
+    typeof SharedArrayBuffer !== 'undefined' &&
+    input.buffer instanceof SharedArrayBuffer &&
+    result.buffer instanceof SharedArrayBuffer;
+  // Cloned SharedArrayBuffer wrappers can refer to the same storage without === identity.
+  if (
+    (input.buffer === result.buffer || shared) &&
+    input.byteOffset < result.byteOffset + length * result.BYTES_PER_ELEMENT &&
+    result.byteOffset < input.byteOffset + input.byteLength
+  )
+    throw new Error('Scalar input/output views overlap; use the same view for in-place projection');
+}
+
+/** Numerical/storage overflow errors happen before committing any output ordinate. */
+export function writeScalarOutput<T extends ProjectionOutput>(
+  coordinate: ProjectionCoordinate,
+  output: T,
+  point: ProjectionPoint,
+  length: number
+): T {
+  if (output instanceof Float32Array) {
+    if (
+      Math.abs(point.x) > FLOAT32_MAX ||
+      Math.abs(point.y) > FLOAT32_MAX ||
+      (length >= 3 && Math.abs(point.z) > FLOAT32_MAX)
+    )
+      throw new Error('Projected coordinate exceeds Float32 range');
+    for (let i = 3; i < coordinate.length; i++) {
+      const value = coordinate[i];
+      if (Number.isFinite(value) && Math.abs(value) > FLOAT32_MAX)
+        throw new Error('Trailing ordinate exceeds Float32 range');
+    }
+  }
+  // XYZ have already been read into private scratch, so exact input/output identity is safe.
+  for (let i = 3; i < coordinate.length; i++) output[i] = coordinate[i];
+  output[0] = point.x;
+  output[1] = point.y;
+  if (length >= 3) output[2] = point.z;
+  return output;
+}

package/src/projection/experimental/spatial-deformation.ts

@@ -0,0 +1,115 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original shared source-sampled displacement and bounded inverse kernel; no upstream implementation copied.
+import type {inverseDisplacement} from './deformation-inverse';
+import {createLocalFrameBasis, eastNorthUpBasis, localToFixed} from '@math.gl/core/local-frame';
+import {geocentricToGeodeticInPlace} from './datum';
+import type {ProjectionPoint} from './types';
+import type {DeformationModel, DeformationModelOptions} from './deformation';
+export type DisplacementSampler = (
+  longitude: number,
+  latitude: number,
+  output: ProjectionPoint,
+  source: number,
+  target: number
+) => boolean;
+export function createSpatialDeformationModel(
+  options: Omit<DeformationModelOptions, 'grid'>,
+  sample: DisplacementSampler,
+  velocity = false,
+  inverseSolver?: typeof inverseDisplacement
+): DeformationModel {
+  const range = options.epochRange;
+  if (
+    !Array.isArray(range) ||
+    range.length !== 2 ||
+    !range.every(Number.isFinite) ||
+    range[0] > range[1]
+  )
+    throw new Error('Finite ordered deformation epochRange required');
+  const start = range[0],
+    end = range[1];
+  const a = options.ellipsoid?.semiMajorAxis ?? 6378137;
+  const f = options.ellipsoid?.flattening ?? 1 / 298.257223563;
+  if (!Number.isFinite(a) || a <= 0 || !Number.isFinite(f) || f < 0 || f >= 1)
+    throw new Error('Invalid deformation ellipsoid');
+  if (!(a * (1 - f) > 0) || !(f * (2 - f) < 1)) throw new Error('Invalid deformation ellipsoid');
+  const ellipsoid = Object.freeze({
+    semiMajorAxis: a,
+    semiMinorAxis: a * (1 - f),
+    eccentricitySquared: f * (2 - f)
+  });
+  function validateEpochs(source: number, target: number): void {
+    if (
+      !Number.isFinite(source) ||
+      !Number.isFinite(target) ||
+      source < start ||
+      source > end ||
+      target < start ||
+      target > end ||
+      !Number.isFinite(target - source)
+    )
+      throw new Error('Deformation epochs outside model epochRange or non-finite');
+  }
+  const frame = createLocalFrameBasis();
+  function displacement(point: ProjectionPoint, source: number, target: number): void {
+    geocentricToGeodeticInPlace(point, ellipsoid);
+    const longitude = point.x,
+      latitude = point.y;
+    if (!sample(longitude, latitude, point, source, target))
+      throw new Error(
+        velocity ? 'No velocity grid covers coordinate' : 'No deformation field covers coordinate'
+      );
+    if (!eastNorthUpBasis(longitude, latitude, frame) || !localToFixed(point, frame))
+      throw new Error('Non-finite deformation output');
+  }
+  function apply(point: ProjectionPoint, source: number, target: number, inverse: boolean): void {
+    validateEpochs(source, target);
+    const x = point.x,
+      y = point.y,
+      z = point.z;
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+      throw new Error('Finite deformation XYZ required');
+    try {
+      if (inverse && inverseSolver) {
+        inverseSolver(point, x, y, z, source, target, displacement);
+        return;
+      }
+      let px = x,
+        py = y,
+        pz = z;
+      for (let iteration = 0; iteration < (inverse ? 32 : 1); iteration++) {
+        point.x = px;
+        point.y = py;
+        point.z = pz;
+        displacement(point, source, target);
+        const scale = (inverse ? -1 : 1) * (velocity ? target - source : 1);
+        const nx = x + scale * point.x,
+          ny = y + scale * point.y,
+          nz = z + scale * point.z;
+        if (!Number.isFinite(nx) || !Number.isFinite(ny) || !Number.isFinite(nz))
+          throw new Error('Non-finite deformation output');
+        if (!inverse || Math.hypot(nx - px, ny - py, nz - pz) <= 1e-8) {
+          point.x = nx;
+          point.y = ny;
+          point.z = nz;
+          return;
+        }
+        px = nx;
+        py = ny;
+        pz = nz;
+      }
+      throw new Error('Deformation inverse did not converge');
+    } catch (error) {
+      point.x = x;
+      point.y = y;
+      point.z = z;
+      throw error;
+    }
+  }
+  return Object.freeze({
+    forward: (point, source, target) => apply(point, source, target, false),
+    inverse: (point, source, target) => apply(point, source, target, true)
+  });
+}

package/src/projection/experimental/types.ts

@@ -0,0 +1,181 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {CRSMetadata} from '../../crs/index';
+import type {TypeScriptCRSInput} from './crs/spatial-reference';
+import type {
+  CreateProjectionOptions,
+  ProjectionEngine,
+  ProjectionCoordinate,
+  ProjectionOutput
+} from '../types';
+
+/** Raw PROJ parameters. Angles are decimal degrees and lengths are meters. */
+export type ProjectionParameters = Readonly<Record<string, string | undefined>>;
+
+/** Mutable scratch owned by the caller. Hooks must update synchronously and never retain it. */
+export type ProjectionPoint = {x: number; y: number; z: number};
+
+/** Engine-validated interleaved floating-point storage. */
+export type ProjectionFlatOperation = (
+  coordinates: Float32Array | Float64Array,
+  dimension: number
+) => void;
+/** Unit conversion for a horizontal geographic/projected batch, in pipeline order. */
+export type ProjectionFlatContext = {
+  readonly inputScale: number;
+  readonly outputScale: number;
+};
+
+/** Greenwich longitude/latitude coverage in degrees. Longitude endpoints are in
+ * [-180, 180]; west > east crosses the dateline. [-180, south, 180, north]
+ * covers all longitudes; equal longitude endpoints describe a meridian.
+ * Latitude satisfies -90 <= south <= north <= 90.
+ */
+export type GeographicBounds = readonly [west: number, south: number, east: number, north: number];
+
+/** Projection-owned native reference-surface envelope and Greenwich degree normalization. */
+export type ProjectionRenderingProfile = {
+  /** Finite native XYZ envelope chosen as an appropriate rendering target.
+   * This is a rendering policy, not the algorithm's mathematical validity domain.
+   * Coordinates outside it may still be converted; membership does not validate a coordinate.
+   * Horizontal projections use zero reference height; geocentric profiles enclose XYZ.
+   */
+  readonly bounds: readonly [readonly [number, number, number], readonly [number, number, number]];
+  /** Optional rendering-domain clamp on Greenwich longitude/latitude in degrees; preserve altitude.
+   * Conversion kernels remain unrestricted by this rendering envelope.
+   */
+  normalize?(point: ProjectionPoint): void;
+};
+
+/** A projection operates on radians and meters; the engine handles CRS units. */
+export type ProjectionImplementation = {
+  /** Effective central longitude in native radians, including algorithm-derived origins. */
+  readonly longitudeOrigin?: number;
+  /** Resolve projection-owned bounds and normalization, optionally for declared coverage.
+   * Coverage is the declared Greenwich geographic area, in degrees; wrapped endpoints are preserved.
+   * Omit coverage for the default rendering target. Descriptor retrieval retries
+   * without coverage if the coverage-specific profile cannot be resolved.
+   * Required for CRS descriptor retrieval; ordinary conversion can omit it.
+   */
+  getRenderingProfile?(coverage?: GeographicBounds): ProjectionRenderingProfile;
+  /** Optional whole-buffer specialization. Return undefined to keep the general pipeline.
+   * Called only for geographic/projected pairs without datum, axis, prime-meridian,
+   * vertical-unit, longitude-wrap or lossy stages. The engine validates storage and stride.
+   * The operation must validate each XYZ, scale XY before/after projection, check domains
+   * and Float32 range, preserve Z/trailing ordinates, and commit only completed records.
+   * Factories run at construction; operations must not retain buffers or scratch across calls.
+   */
+  createForwardFlat?(context: ProjectionFlatContext): ProjectionFlatOperation | undefined;
+  createInverseFlat?(context: ProjectionFlatContext): ProjectionFlatOperation | undefined;
+  /** Optional mutable hooks avoid scalar coordinate arrays; preserve z for horizontal projections. */
+  forwardInPlace?(point: ProjectionPoint): void;
+  inverseInPlace?(point: ProjectionPoint): void;
+  /** Optional Cartesian operations used by geocentric plugins. */
+  forward3D?(point: [number, number, number]): [number, number, number];
+  inverse3D?(point: [number, number, number]): [number, number, number];
+  forward(longitude: number, latitude: number): [number, number];
+  inverse(x: number, y: number): [number, number];
+};
+
+/** Initialized geometry shared by projection plugins. No datum shift is implied. */
+export type ProjectionContext = {
+  /** Greenwich longitude of the CRS prime meridian, in radians. */
+  readonly primeMeridian?: number;
+  /** Preserve the normalized polar axis; recovering it from eccentricity can lose precision. */
+  readonly semiMinorAxis?: number;
+  readonly semiMajorAxis: number;
+  readonly eccentricitySquared: number;
+  readonly parameters: ProjectionParameters;
+};
+
+/** Explicit registration avoids global state and imports of unused projections. */
+export type ProjectionPlugin = {
+  readonly name: string;
+  readonly aliases?: readonly string[];
+  /** Projection-specific PROJ parameters accepted in addition to the core parameters. */
+  readonly parameters: readonly string[];
+  /** Parameters accepted without a value, such as +south. */
+  readonly flags?: readonly string[];
+  create(context: ProjectionContext): ProjectionImplementation;
+};
+
+/** Coordinate conventions used when resolving a single CRS. */
+export type GetCRSOptions = Pick<CreateProjectionOptions, 'enforceAxis' | 'mode'> & {
+  /** Additional source CRS strings to prepare; WGS84 is always included. */
+  converters?: readonly string[];
+};
+
+/** Finite target-coordinate XYZ envelope describing an appropriate rendering target.
+ * This is not the projection algorithm's validity domain or a coordinate validity test.
+ */
+export type CRSBounds = readonly [
+  minimum: readonly [number, number, number],
+  maximum: readonly [number, number, number]
+];
+
+/** Rendering factors in effective target-axis order. Horizontal factors measure
+ * WGS84 reference-surface metres per stored coordinate unit through the full inverse
+ * transform. For projected CRSs the vertical factor uses the square root of the
+ * inverse horizontal area scale, expressed in the declared vertical unit.
+ * This sizing convention is independent of altitude conversion; use the component
+ * unit metadata and converters for physical heights. Geocentric/identity factors
+ * are constant physical unit conversions.
+ */
+export type CRSRenderingScale = readonly [x: number, y: number, z: number];
+
+/** Evaluate at a position in the descriptor's CRS; null means scale calculation failed. */
+export type CRSRenderingScaleCallback = (
+  coordinate: ProjectionCoordinate
+) => CRSRenderingScale | null;
+
+/** Synchronous conversion; omit output to allocate an array, or supply storage to reuse it. */
+export interface CRSConversion {
+  (coordinate: ProjectionCoordinate): number[];
+  <T extends ProjectionOutput>(coordinate: ProjectionCoordinate, output: T): T;
+}
+
+/** Prepared bidirectional conversion between a source CRS and a descriptor's target CRS. */
+export interface CRSConverter {
+  /** Convert source coordinates to target coordinates, optionally reusing output storage. */
+  readonly from: CRSConversion;
+  /** Convert target coordinates to source coordinates, optionally reusing output storage. */
+  readonly to: CRSConversion;
+  /** Normalize source coordinates for the target projection, optionally reusing output storage. */
+  readonly normalize: CRSConversion;
+}
+
+/** Prepared CRS metadata, target-space behavior, and converters keyed by source CRS string.
+ * WGS84 uses longitude/latitude in degrees and ellipsoidal height in metres. Converters
+ * retain the engine's datum policy; fourth and later components pass through.
+ */
+export interface CRSDescriptor extends CRSMetadata {
+  /** Original string under default conventions; otherwise a resolved @math.gl/geospatial/crs signature.
+   * Opaque to consumers; no arbitrary CRS equivalence comparison is implied.
+   * Does not fingerprint algorithm implementations or grid contents; equality does
+   * not guarantee packed-coordinate interchangeability across engines.
+   */
+  readonly signature: string;
+  /** Finite XYZ envelope chosen as an appropriate rendering target, in effective units and axis order.
+   * Bounds describe a rendering policy for the reference surface, not the algorithm's
+   * mathematical validity domain or altitude limits. Coordinates outside the envelope
+   * may still be converted; being inside it does not guarantee a valid conversion.
+   */
+  readonly renderingBounds: CRSBounds;
+  /** Constant scale or target-position callback; no viewport fallback is applied. */
+  readonly renderingScale: CRSRenderingScale | CRSRenderingScaleCallback;
+  /** Return rendering sizing factors at the anchor; null means sampling is unavailable
+   * or derivatives fail numerical agreement. Invalid finite geometry raises an error. */
+  getRenderingScale(coordinate: ProjectionCoordinate): CRSRenderingScale | null;
+  /** Prepared converters; WGS84 is always available, plus explicitly requested source strings. */
+  readonly converter: Readonly<Record<string, CRSConverter>> & {
+    readonly WGS84: CRSConverter;
+  };
+}
+
+/** General CRS-capable engine; specialized pair-only engines need not implement retrieval. */
+export interface CRSEngine extends ProjectionEngine {
+  /** Resolve metadata and preload only required algorithms. Returned conversions are synchronous. */
+  getCRS(definition: TypeScriptCRSInput, options?: GetCRSOptions): Promise<CRSDescriptor>;
+}