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

package/src/projection/experimental/rendering-profile/spherical-rendering-domain.ts

@@ -0,0 +1,175 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {AngularRanges} from './geographic-bounds';
+import {wrapLongitude} from '../parameters';
+
+export type Vector = readonly [number, number, number];
+export type AngularDomain = {latitude: number; distance: number};
+export function geographicVector(longitude: number, latitude: number): Vector {
+  return [
+    Math.cos(latitude) * Math.cos(longitude),
+    Math.cos(latitude) * Math.sin(longitude),
+    Math.sin(latitude)
+  ];
+}
+const dot = (a: Vector, b: Vector) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+
+/** Solve A cos(t) + B sin(t) = C; retain roots in the specified interval. */
+export function trigonometricRoots(
+  a: number,
+  b: number,
+  c: number,
+  low: number,
+  high: number
+): number[] {
+  const radius = Math.hypot(a, b);
+  if (!radius || Math.abs(c) > radius + 1e-14) return [];
+  const angle = Math.atan2(b, a);
+  const offset = Math.acos(Math.max(-1, Math.min(1, c / radius)));
+  const roots: number[] = [];
+  for (const phase of [angle - offset, angle + offset]) {
+    for (
+      let k = Math.ceil((low - phase) / (2 * Math.PI));
+      k <= Math.floor((high - phase) / (2 * Math.PI));
+      k++
+    ) {
+      roots.push(phase + k * 2 * Math.PI);
+    }
+  }
+  return roots;
+}
+
+/** Extremize a linear form on a geographic rectangle intersected with a spherical cap.
+ * Candidates are stationary points, edge intersections and cap tangent points;
+ * no tessellation or curve sampling is needed.
+ */
+export function sphericalExtremum(
+  vector: Vector,
+  parameters: AngularRanges,
+  domain?: AngularDomain,
+  maximize = true
+): {value: number; point: [number, number]} {
+  const [[west, south], [east, north]] = parameters;
+  const center = (west + east) / 2;
+  const axis: Vector = domain
+    ? [Math.cos(domain.latitude), 0, Math.sin(domain.latitude)]
+    : [1, 0, 0];
+  const limit = domain ? Math.cos(domain.distance) : -1;
+  let best = maximize ? -Infinity : Infinity;
+  let point: [number, number] = [NaN, NaN];
+  const consider = (longitude: number, latitude: number) => {
+    longitude = center + wrapLongitude(longitude - center);
+    if (
+      longitude < west - 1e-12 ||
+      longitude > east + 1e-12 ||
+      latitude < south - 1e-12 ||
+      latitude > north + 1e-12
+    )
+      return;
+    const position = geographicVector(longitude, latitude);
+    if (domain && dot(axis, position) < limit - 1e-13) return;
+    const value = dot(vector, position);
+    if (maximize ? value > best : value < best) {
+      best = value;
+      point = [longitude, latitude];
+    }
+  };
+  // Rectangle corners and stationary points of each longitude/latitude edge.
+  const longitudes = [west, east, ...trigonometricRoots(-vector[1], vector[0], 0, west, east)];
+  for (const longitude of longitudes) {
+    const coefficient = vector[0] * Math.cos(longitude) + vector[1] * Math.sin(longitude);
+    for (const latitude of [
+      south,
+      north,
+      ...trigonometricRoots(vector[2], -coefficient, 0, south, north)
+    ])
+      consider(longitude, latitude);
+  }
+  if (domain) {
+    const [a, , c] = axis;
+    // Intersections of the cap circle with the four geographic edges.
+    for (const latitude of [south, north]) {
+      for (const longitude of trigonometricRoots(
+        a * Math.cos(latitude),
+        0,
+        limit - c * Math.sin(latitude),
+        west,
+        east
+      ))
+        consider(longitude, latitude);
+    }
+    for (const longitude of [west, east]) {
+      for (const latitude of trigonometricRoots(a * Math.cos(longitude), c, limit, south, north))
+        consider(longitude, latitude);
+    }
+    // Extrema of the linear form on the cap circle: its two tangency points.
+    const parallel = dot(vector, axis);
+    let tangent = vector.map((value, index) => value - parallel * axis[index]);
+    let length = Math.hypot(...tangent);
+    if (length <= 1e-14) {
+      // Parallel forms are constant on the cap circle; choose its meridian tangency.
+      tangent = [-axis[2], 0, axis[0]];
+      length = 1;
+    }
+    if (length > 1e-14) {
+      for (const sign of [-1, 1]) {
+        const position = axis.map(
+          (value, index) =>
+            value * limit + (sign * tangent[index] * Math.sin(domain.distance)) / length
+        );
+        consider(
+          Math.atan2(position[1], position[0]),
+          Math.atan2(position[2], Math.hypot(position[0], position[1]))
+        );
+      }
+    }
+  }
+  if (!Number.isFinite(best))
+    throw new Error('CRS coverage does not intersect the rendering domain');
+  return {value: best, point};
+}
+
+export function sphericalRange(
+  vector: Vector,
+  parameters: AngularRanges,
+  domain?: AngularDomain
+): [number, number] {
+  return [
+    sphericalExtremum(vector, parameters, domain, false).value,
+    sphericalExtremum(vector, parameters, domain).value
+  ];
+}
+
+/** Extremize a linear-fractional projection by solving its support equation.
+ * A positive denominator makes max(N-qD)=0 monotone in q, so bisection
+ * brackets the true extremum instead of searching sampled boundary points.
+ */
+export function sphericalRatioRange(
+  numerator: Vector,
+  denominator: Vector,
+  constant: number,
+  parameters: AngularRanges,
+  domain?: AngularDomain
+): [number, number] {
+  const n = sphericalRange(numerator, parameters, domain);
+  const d = sphericalRange(denominator, parameters, domain).map(value => value + constant);
+  if (d[0] <= 0) throw new Error('Projection rendering denominator is not positive');
+  const quotients = n.flatMap(value => d.map(divisor => value / divisor));
+  return [false, true].map(maximize => {
+    let low = Math.min(...quotients),
+      high = Math.max(...quotients);
+    for (let iteration = 0; iteration < 60; iteration++) {
+      const middle = (low + high) / 2;
+      const vector = numerator.map(
+        (value, index) => value - middle * denominator[index]
+      ) as unknown as Vector;
+      const residual =
+        sphericalExtremum(vector, parameters, domain, maximize).value - middle * constant;
+      if (residual > 0) low = middle;
+      else high = middle;
+    }
+    return maximize ? high : low;
+  }) as [number, number];
+}

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

@@ -0,0 +1,77 @@
+// 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';
+
+import type {
+  CRSCoordinate as ProjectionCoordinate,
+  CRSOutput as ProjectionOutput
+} from '../../crs/crs-descriptor-types';
+export type {ProjectionCoordinate, ProjectionOutput};
+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';
+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,117 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {CRSDescriptor} from '../../crs/crs-descriptor-types';
+export type {
+  CRSDescriptor,
+  CRSConversion,
+  CRSConverter,
+  CRSBounds,
+  CRSRenderingScale,
+  CRSRenderingScaleCallback
+} from '../../crs/crs-descriptor-types';
+import type {TypeScriptCRSInput} from './crs/spatial-reference';
+import type {CreateProjectionOptions, ProjectionEngine} 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[];
+};
+
+/** 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>;
+}