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

package/src/subdivide-rhumb-polyline.ts

@@ -0,0 +1,108 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original rhumb adapter for the existing adaptive subdivision engine.
+
+import {subdividePolyline} from '@math.gl/geometry/polygon';
+import type {
+  SubdividePolylineOptions,
+  SubdividedPolyline,
+  PolylineEdgeSampler
+} from '@math.gl/geometry/polygon';
+import {RhumbPath, type RhumbPathOptions} from './rhumb-path';
+import {validateGeographicPosition} from './geodesic-path';
+
+export type SubdivideRhumbPolylineOptions = Omit<
+  SubdividePolylineOptions,
+  'createEdgeSampler' | 'maxSegmentLength'
+> &
+  Omit<RhumbPathOptions, 'longitudeTurns'> & {
+    /** One safe integer turn count per original edge; copied before sampling. */
+    longitudeTurns?: readonly number[];
+    maxSurfaceDistance?: number;
+  };
+
+/** Rhumb sampling through a continuous transform. This is a sampled error test,
+ * not seam clipping or a universal error certificate. Source provenance is kept.
+ */
+export function subdivideRhumbPolyline(
+  input: ArrayLike<number>,
+  options: SubdivideRhumbPolylineOptions
+): SubdividedPolyline {
+  const {
+    rhumb,
+    longitudeTurns,
+    longitudeMode,
+    size = 2,
+    maxSurfaceDistance = Infinity,
+    ...subdivision
+  } = options;
+  const maxVertices = subdivision.maxVertices ?? 65536;
+  if (
+    (longitudeMode !== undefined && !['shortest', 'unrolled'].includes(longitudeMode)) ||
+    (longitudeMode === 'unrolled' && longitudeTurns !== undefined) ||
+    (size !== 2 && size !== 3) ||
+    !Number.isSafeInteger(input.length) ||
+    input.length < 0 ||
+    input.length % size !== 0 ||
+    !Number.isSafeInteger(maxVertices) ||
+    maxVertices < 1 ||
+    maxVertices > 0xffffffff ||
+    input.length / size > maxVertices ||
+    !(maxSurfaceDistance > 0) ||
+    (maxSurfaceDistance !== Infinity && !Number.isFinite(maxSurfaceDistance))
+  )
+    throw new RangeError('Invalid rhumb subdivision dimensions or limits');
+  const count = Math.max(0, input.length / size - 1);
+  const turns = longitudeTurns ? Array.from(longitudeTurns) : undefined;
+  if (turns && (turns.length !== count || !turns.every(Number.isSafeInteger)))
+    throw new RangeError('Expected one integer longitudeTurns value per rhumb edge');
+  const positions = Array.from(input);
+  for (let i = 0; i < positions.length; i += size)
+    validateGeographicPosition(positions.slice(i, i + size));
+  const original = positions.slice();
+  const paths: PolylineEdgeSampler[] = [];
+  for (let i = size; i < positions.length; i += size) {
+    const path = new RhumbPath(original.slice(i - size, i), original.slice(i, i + size), {
+      rhumb,
+      longitudeMode,
+      longitudeTurns: turns?.[paths.length]
+    });
+    // Select each signed interval before translating it into the accumulated
+    // world. Otherwise a preceding wrap can reverse an exact 180-degree tie.
+    const first = positions.slice(i - size, i);
+    const worldTurns = Math.round((first[0] - original[i - size]) / 360);
+    const offset = 360 * worldTurns;
+    if (!Number.isSafeInteger(worldTurns) || original[i - size] + offset !== first[0])
+      throw new RangeError('Unrepresentable rhumb longitude chart');
+    const last = path.end;
+    const endTurns = Math.round((last[0] - original[i]) / 360);
+    const translated = last[0] + offset;
+    const endpoint = original[i] + (offset + 360 * endTurns);
+    last[0] =
+      Number.isSafeInteger(endTurns) &&
+      Number.isFinite(endpoint) &&
+      Math.abs(endpoint - translated) <= 4 * Number.EPSILON * Math.max(360, Math.abs(translated))
+        ? endpoint
+        : translated;
+    if (path.length === 0) {
+      last[0] = first[0];
+      last[1] = first[1];
+    }
+    const sample = (fraction: number): number[] => {
+      if (fraction === 0) return first.slice();
+      if (fraction === 1) return last.slice();
+      const p = path.sample(fraction);
+      p[0] += offset;
+      return p;
+    };
+    paths.push({length: path.length, sample});
+    positions.splice(i, size, ...sample(1));
+  }
+  return subdividePolyline(positions, {
+    ...subdivision,
+    size,
+    maxSegmentLength: maxSurfaceDistance,
+    createEdgeSampler: (_start, _end, index) => paths[index]
+  });
+}

package/src/triaxial/integrate.ts

@@ -0,0 +1,82 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original adaptive Dormand-Prince integration of the constrained Cartesian geodesic equation; mathematical coefficients, no third-party implementation copied.
+const C = [0, 1 / 5, 3 / 10, 4 / 5, 8 / 9, 1, 1];
+const A = [
+  [],
+  [1 / 5],
+  [3 / 40, 9 / 40],
+  [44 / 45, -56 / 15, 32 / 9],
+  [19372 / 6561, -25360 / 2187, 64448 / 6561, -212 / 729],
+  [9017 / 3168, -355 / 33, 46732 / 5247, 49 / 176, -5103 / 18656],
+  [35 / 384, 0, 500 / 1113, 125 / 192, -2187 / 6784, 11 / 84]
+];
+const B = [35 / 384, 0, 500 / 1113, 125 / 192, -2187 / 6784, 11 / 84, 0];
+const ERROR = [
+  35 / 384 - 5179 / 57600,
+  0,
+  500 / 1113 - 7571 / 16695,
+  125 / 192 - 393 / 640,
+  -2187 / 6784 + 92097 / 339200,
+  11 / 84 - 187 / 2100,
+  -1 / 40
+];
+export function integrateGeodesic(
+  initial: readonly number[],
+  q: readonly number[],
+  distance: number
+): number[] {
+  let state = Array.from(initial),
+    done = 0,
+    step = Math.sign(distance) * Math.min(0.01, Math.abs(distance));
+  const derivative = (y: readonly number[]) => {
+    const normal = [q[0] * y[0], q[1] * y[1], q[2] * y[2]];
+    const curvature =
+      (q[0] * y[3] ** 2 + q[1] * y[4] ** 2 + q[2] * y[5] ** 2) /
+      (normal[0] ** 2 + normal[1] ** 2 + normal[2] ** 2);
+    return [
+      y[3],
+      y[4],
+      y[5],
+      -curvature * normal[0],
+      -curvature * normal[1],
+      -curvature * normal[2]
+    ];
+  };
+  for (let attempt = 0; attempt < 50000; attempt++) {
+    if (done === distance) return state;
+    if (Math.abs(step) > Math.abs(distance - done)) step = distance - done;
+    const stages: number[][] = [];
+    for (let j = 0; j < C.length; j++) {
+      const y = state.map(
+        (v, i) => v + step * A[j].reduce((sum, a, k) => sum + a * stages[k][i], 0)
+      );
+      stages.push(derivative(y));
+    }
+    const next = state.map((v, i) => v + step * B.reduce((sum, b, j) => sum + b * stages[j][i], 0));
+    let error = 0;
+    for (let i = 0; i < 6; i++)
+      error = Math.max(
+        error,
+        Math.abs(step * ERROR.reduce((sum, e, j) => sum + e * stages[j][i], 0))
+      );
+    const tolerance = 2e-15;
+    if (error <= tolerance) {
+      state = next;
+      done += step;
+      // Restore the two constraints and unit speed only at accepted steps.
+      const surface = Math.sqrt(q[0] * state[0] ** 2 + q[1] * state[1] ** 2 + q[2] * state[2] ** 2);
+      for (let i = 0; i < 3; i++) state[i] /= surface;
+      const normal = state.slice(0, 3).map((x, i) => q[i] * x),
+        nn = normal.reduce((s, x) => s + x * x, 0);
+      const dot = normal.reduce((s, x, i) => s + x * state[i + 3], 0) / nn;
+      for (let i = 0; i < 3; i++) state[i + 3] -= normal[i] * dot;
+      const speed = Math.hypot(state[3], state[4], state[5]);
+      for (let i = 3; i < 6; i++) state[i] /= speed;
+    }
+    step *= Math.max(0.2, Math.min(4, 0.9 * (tolerance / Math.max(error, 1e-300)) ** 0.2));
+    if (done + step === done) throw new RangeError('Triaxial integration step underflow');
+  }
+  throw new RangeError('Triaxial integration work limit exceeded');
+}

package/src/triaxial.ts

@@ -0,0 +1,172 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original normal/parametric/geocentric surface coordinates and Cartesian geodesic ODE. Qualified independently against GeographicLib 2.7 Jacobi trajectories (Charles Karney, MIT), not a port of that implementation.
+import type {NumericArray} from '@math.gl/core/types';
+import {integrateGeodesic} from './triaxial/integrate';
+export type TriaxialCoordinates = 'geodetic' | 'parametric' | 'geocentric';
+export type TriaxialParameters = {radii: readonly [number, number, number]};
+export type CartesianGeodesicState = {
+  position: [number, number, number];
+  direction: [number, number, number];
+  distance: number;
+};
+export interface TriaxialGeodesicLine {
+  position(distance: number): CartesianGeodesicState;
+}
+type Vec = Readonly<NumericArray>;
+function unit(v: Vec): [number, number, number] {
+  const scale = Math.max(Math.abs(v[0]), Math.abs(v[1]), Math.abs(v[2]));
+  if (!(scale > 0 && Number.isFinite(scale)))
+    throw new RangeError('Expected nonzero finite direction');
+  const x = v[0] / scale,
+    y = v[1] / scale,
+    z = v[2] / scale,
+    n = Math.hypot(x, y, z);
+  return [x / n, y / n, z / n];
+}
+function vector(v: Vec) {
+  if (v.length !== 3 || !v.every(Number.isFinite))
+    throw new RangeError('Expected three finite coordinates');
+}
+function system(s: TriaxialCoordinates) {
+  if (!['geodetic', 'parametric', 'geocentric'].includes(s))
+    throw new RangeError('Unknown triaxial coordinate system');
+}
+function trig(degrees: number) {
+  const x = (((degrees % 360) + 540) % 360) - 180;
+  return {
+    s: x === 0 || Math.abs(x) === 180 ? 0 : Math.sin((x * Math.PI) / 180),
+    c: Math.abs(x) === 90 ? 0 : Math.cos((x * Math.PI) / 180)
+  };
+}
+/** Surface-only coordinate/direction conversions on three-radius ellipsoids.
+ * Angles are degrees, pole longitude is zero. Shapes need not be axis-sorted.
+ */
+export class TriaxialEllipsoid {
+  private readonly snapshot: readonly [number, number, number];
+  private readonly scale: number;
+  private readonly axes: readonly number[];
+  constructor({radii}: TriaxialParameters) {
+    if (
+      radii.length !== 3 ||
+      !radii.every(x => Number.isFinite(x) && x >= 1e-60 && x <= 1e60) ||
+      Math.min(...radii) / Math.max(...radii) < 0.25
+    )
+      throw new RangeError('Triaxial axes require [1e-60,1e60] and min/max >= 0.25');
+    this.snapshot = Object.freeze([...radii]) as readonly [number, number, number];
+    this.scale = Math.max(...radii);
+    this.axes = Object.freeze(radii.map(r => r / this.scale));
+  }
+  get radii(): readonly [number, number, number] {
+    return this.snapshot;
+  }
+  toCartesian(
+    latitude: number,
+    longitude: number,
+    coordinates: TriaxialCoordinates = 'geodetic'
+  ): [number, number, number] {
+    system(coordinates);
+    if (!Number.isFinite(latitude) || Math.abs(latitude) > 90 || !Number.isFinite(longitude))
+      throw new RangeError('Invalid triaxial latitude/longitude');
+    const p = trig(latitude),
+      l = trig(longitude),
+      n = [p.c * l.c, p.c * l.s, p.s],
+      r = this.axes;
+    if (coordinates === 'parametric')
+      return n.map((x, i) => x * this.radii[i]) as [number, number, number];
+    const denominator =
+      coordinates === 'geodetic'
+        ? Math.hypot(...n.map((x, i) => x * r[i]))
+        : Math.hypot(...n.map((x, i) => x / r[i]));
+    return n.map(
+      (x, i) => (this.scale * x * (coordinates === 'geodetic' ? r[i] * r[i] : 1)) / denominator
+    ) as [number, number, number];
+  }
+  fromCartesian(
+    position: Vec,
+    coordinates: TriaxialCoordinates = 'geodetic'
+  ): {latitude: number; longitude: number} {
+    system(coordinates);
+    const p = this.surface(position);
+    const v = p.map((x, i) =>
+      coordinates === 'geodetic'
+        ? x / this.axes[i] ** 2
+        : coordinates === 'parametric'
+          ? x / this.axes[i]
+          : x
+    );
+    return {
+      latitude: (Math.atan2(v[2], Math.hypot(v[0], v[1])) * 180) / Math.PI,
+      longitude: v[0] === 0 && v[1] === 0 ? 0 : (Math.atan2(v[1], v[0]) * 180) / Math.PI
+    };
+  }
+  directionToCartesian(position: Vec, azimuth: number): [number, number, number] {
+    if (!Number.isFinite(azimuth)) throw new RangeError('Invalid triaxial bearing');
+    const {north, east} = this.basis(position),
+      a = trig(azimuth);
+    return unit(north.map((x, i) => x * a.c + east[i] * a.s));
+  }
+  directionFromCartesian(position: Vec, direction: Vec): number {
+    vector(direction);
+    const {north, east, normal} = this.basis(position),
+      v = unit(direction);
+    if (Math.abs(v.reduce((s, x, i) => s + x * normal[i], 0)) > 2e-12)
+      throw new RangeError('Direction must be tangent');
+    return (
+      (Math.atan2(
+        v.reduce((s, x, i) => s + x * east[i], 0),
+        v.reduce((s, x, i) => s + x * north[i], 0)
+      ) *
+        180) /
+      Math.PI
+    );
+  }
+  private surface(position: Vec): number[] {
+    vector(position);
+    const p = Array.from(position, x => x / this.scale);
+    const residual = p.reduce((s, x, i) => s + (x / this.axes[i]) ** 2, 0);
+    if (!Number.isFinite(residual) || Math.abs(residual - 1) > 2e-12)
+      throw new RangeError('Point must lie on the ellipsoid surface');
+    return p;
+  }
+  private basis(position: Vec) {
+    const p = this.surface(position),
+      normal = unit(p.map((x, i) => x / this.axes[i] ** 2));
+    const horizontal = Math.hypot(p[0], p[1]),
+      meridian = horizontal ? [-p[1] / horizontal, p[0] / horizontal, 0] : [0, 1, 0];
+    const cross = (a: Vec, b: Vec) => [
+      a[1] * b[2] - a[2] * b[1],
+      a[2] * b[0] - a[0] * b[2],
+      a[0] * b[1] - a[1] * b[0]
+    ];
+    const north = unit(cross(normal, meridian)),
+      east = unit(cross(north, normal));
+    return {north, east, normal};
+  }
+  /** Cartesian initial-value geodesic. No global triaxial inverse is implied. */
+  line(position: Vec, direction: Vec): TriaxialGeodesicLine {
+    const p = this.surface(position);
+    this.directionFromCartesian(position, direction);
+    const v = unit(direction),
+      initial = Object.freeze([...p, ...v]),
+      q = this.axes.map(r => 1 / (r * r)),
+      scale = this.scale;
+    return {
+      position: (distance: number) => {
+        if (!Number.isFinite(distance) || Math.abs(distance) > 2 * Math.PI * scale)
+          throw new RangeError('Triaxial distance exceeds one max-axis circuit');
+        const y =
+          distance === 0 ? Array.from(initial) : integrateGeodesic(initial, q, distance / scale);
+        return {
+          position: y.slice(0, 3).map(x => x * scale) as [number, number, number],
+          direction: y.slice(3) as [number, number, number],
+          distance
+        };
+      }
+    };
+  }
+  direct(position: Vec, direction: Vec, distance: number): CartesianGeodesicState {
+    return this.line(position, direction).position(distance);
+  }
+}

package/src/type-utils.ts

@@ -5,7 +5,7 @@
 // SPDX-FileComment: Derived from Cesium. See the repository LICENSE for upstream attribution and Apache-2.0 terms. The numeric-component cartographic adapter is original math.gl code.
 
 // This file is derived from the Cesium math library under Apache 2 license
-// See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
+// See ../LICENSE for the retained Cesium notice and Apache-2.0 terms.
 
 import type {NumericArray} from '@math.gl/core';
 import {Vector3, toRadians, toDegrees, config} from '@math.gl/core';

package/src/vendor/geographiclib-geodesic/README.md

@@ -0,0 +1,21 @@
+<!--
+SPDX-License-Identifier: MIT
+SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+-->
+
+# GeographicLib geodesic source
+
+Upstream: https://github.com/geographiclib/geographiclib-js
+Version: 2.2.0
+Commit: 9c4036d6242aa997e08e43a20df789e2007fbe6f
+License: MIT, Charles Karney; see ../../../GEOGRAPHICLIB-LICENSE.txt.
+
+`runtime.js` combines `geodesic/Math.js.in`, `geodesic/Geodesic.js` and
+`geodesic/GeodesicLine.js`, in that order. Version placeholders in Math.js.in
+are filled with 2, 2, 0; an ESM `export {geodesic}` and SPDX header are added.
+Upstream implementation and comments are retained. The Math.js input already includes Accumulator. The typed facade exposes inverse, direct, arc and line calculations with optional longitude unrolling and edge area. Prolate geodesics are supported. The separate typed GeodesicPolygon uses the existing accumulator and adapts the MIT GeographicLib 2.7 polygon transit/reduction rules; PolygonArea.js is not vendored.
+
+Original math.gl short-edge area follow-up replaces cancellation in the C4 cosine-series subtraction with the trigonometric difference identity, for arcs below 0.01 radians. Native series/Exact disagreements at tiny areas are retained as diagnostics and independently gated by 80-digit small-triangle integrals. See the ellipsoid accuracy audit for qualified domains. No npm dependency is introduced.
+
+Do not replace this robust geodesic solver with a spherical or Vincenty fallback:
+the nearly antipodal tests and reduced-length/scale gnomonic checks must pass.