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

package/src/ellipsoid-tangent-plane.ts

@@ -1,68 +1,229 @@
 // math.gl
-// SPDX-License-Identifier: MIT and Apache-2.0
-// Copyright (c) vis.gl contributors
+// SPDX-License-Identifier: MIT AND Apache-2.0
+// SPDX-FileCopyrightText: Copyright 2011-2018 CesiumJS Contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Derived from Cesium. Original math.gl follow-up adds explicit radial/normal inverses, packed projection and an orthonormal three-radius tangent basis. See the repository LICENSE for upstream attribution and Apache-2.0 terms.
 
 // This file is derived from the Cesium 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 {Vector2, Vector3, Matrix4} from '@math.gl/core';
-import {Plane} from '@math.gl/culling';
+import {Vector2, Vector3} from '@math.gl/core';
+import type {NumericArray} from '@math.gl/core';
+import {Plane} from '@math.gl/geometry/culling';
 import {Ellipsoid} from './ellipsoid';
+import {compensatedDot3, exactNormalIntersection} from './ellipsoid-helpers/tangent-plane-numerics';
 
-const scratchOrigin = new Vector3();
-const scratchCart3 = new Vector3();
-const scratchEastNorthUp = new Matrix4();
-const scratchProjectPointOntoPlaneCartesian3 = new Vector3();
+export type TangentPlaneProjectionMode = 'normal' | 'radial';
+export type TangentPlaneProjection = {
+  positions: Float64Array;
+  /** One byte per input point: 1 for success, 0 for no radial intersection. */
+  valid: Uint8Array;
+};
 
 /** A two-dimensional east-north plane tangent to an ellipsoid. */
 export class EllipsoidTangentPlane {
-  private _origin: Vector3;
-  private _xAxis: Vector3;
-  private _yAxis: Vector3;
+  private anchor: Vector3;
+  private east: Vector3;
+  private north: Vector3;
   private _plane: Plane;
+  private readonly radii: readonly number[];
+  private readonly radius?: number;
 
   /**
-   * Creates a new plane tangent to the WGS84 ellipsoid at the provided origin.
+   * Creates a new plane tangent to an ellipsoid at the provided origin.
    * If origin is not on the surface of the ellipsoid, its surface projection will be used.
    *
    * @param origin A nonzero Cartesian point on or near the ellipsoid.
    * @param ellipsoid The ellipsoid to which the origin belongs. Defaults to WGS84.
    */
-  constructor(origin: number[], ellipsoid: Ellipsoid = Ellipsoid.WGS84) {
-    const originOnSurface = ellipsoid.scaleToGeodeticSurface(origin, scratchOrigin);
+  constructor(origin: Readonly<NumericArray>, ellipsoid: Ellipsoid = Ellipsoid.WGS84) {
+    finiteInput(origin, 3);
+    this.radii = Object.freeze(Array.from(ellipsoid.radii));
+    if (this.radii[0] === this.radii[1] && this.radii[1] === this.radii[2])
+      this.radius = this.radii[0];
+    if (!this.radii.every(radius => radius > 0 && Number.isFinite(radius))) {
+      throw new RangeError('Tangent plane requires positive finite ellipsoid radii');
+    }
+    const originOnSurface = ellipsoid.scaleToGeodeticSurface(Array.from(origin), new Vector3());
+    if (!originOnSurface) throw new RangeError('Origin has no unique ellipsoid surface point');
 
-    const eastNorthUp = ellipsoid.eastNorthUpToFixedFrame(originOnSurface, scratchEastNorthUp);
-
-    this._origin = new Vector3(originOnSurface);
-    this._xAxis = new Vector3(scratchCart3.from(eastNorthUp.getColumn(0)));
-    this._yAxis = new Vector3(scratchCart3.from(eastNorthUp.getColumn(1)));
-    const normal = new Vector3(scratchCart3.from(eastNorthUp.getColumn(2)));
-
-    this._plane = new Plane().fromPointNormal(this._origin, normal);
+    this.anchor = new Vector3(originOnSurface);
+    const normal = new Vector3(ellipsoid.geodeticSurfaceNormal(originOnSurface));
+    if (!normal.every(Number.isFinite) || !(normal.len() > 0)) {
+      throw new RangeError('Cannot resolve tangent-plane normal');
+    }
+    normal.normalize();
+    // Use the surface normal, rather than the radial position, so unequal X/Y
+    // radii still produce an orthonormal tangent basis.
+    const horizontal = Math.hypot(normal[0], normal[1]);
+    this.east =
+      horizontal > 0
+        ? new Vector3(-normal[1] / horizontal, normal[0] / horizontal, 0)
+        : new Vector3(0, 1, 0);
+    this.north = new Vector3(normal).cross(this.east).normalize();
+    this._plane = new Plane().fromPointNormal(this.anchor, normal);
   }
 
   /**
    * Computes the projection of the provided 3D position onto the 2D plane, along the plane normal.
    *
-   * @param cartesian The WGS84 Cartesian point to project.
+   * @param cartesian The fixed Cartesian point to project.
    * @param result The optional object in which to store the local east-north coordinates.
    * @returns The supplied result or a new Vector2.
    */
-  projectPointToNearestOnPlane(cartesian: Vector3, result?: Vector2): Vector2 {
-    if (!result) result = new Vector2();
+  projectPointToNearestOnPlane(cartesian: Readonly<NumericArray>, result = new Vector2()): Vector2 {
+    finiteInput(cartesian, 3);
+    // Tangential dot products equal orthogonal projection without constructing the 3D footpoint.
+    const x = cartesian[0] - this.anchor[0];
+    const y = cartesian[1] - this.anchor[1];
+    const z = cartesian[2] - this.anchor[2];
+    const projected = writePlanePoint(this, x, y, z, result, this.radius);
+    if (!projected) throw new RangeError('Tangent-plane projection overflow');
+    return projected;
+  }
 
-    const intersectionPoint = this._plane.projectPointOntoPlane(
-      cartesian,
-      scratchProjectPointOntoPlaneCartesian3
+  /** Project along the outward ray from the ellipsoid center.
+   * Back-facing, horizon and nonfinite intersections return undefined without writing result.
+   */
+  projectPointRadiallyOntoPlane(
+    cartesian: Readonly<NumericArray>,
+    result = new Vector2()
+  ): Vector2 | undefined {
+    finiteInput(cartesian, 3);
+    const scale = Math.max(Math.abs(cartesian[0]), Math.abs(cartesian[1]), Math.abs(cartesian[2]));
+    if (scale === 0) return undefined;
+    const sx = cartesian[0] / scale,
+      sy = cartesian[1] / scale,
+      sz = cartesian[2] / scale;
+    const length = Math.hypot(sx, sy, sz);
+    const x = sx / length;
+    const y = sy / length;
+    const z = sz / length;
+    const n = this.zAxis;
+    const denominator = x * n[0] + y * n[1] + z * n[2];
+    if (denominator <= 1e-14) return undefined;
+    const distance = this.anchor.dot(n) / denominator;
+    return writePlanePoint(
+      this,
+      x * distance - this.anchor[0],
+      y * distance - this.anchor[1],
+      z * distance - this.anchor[2],
+      result,
+      this.radius
     );
+  }
 
-    const v = intersectionPoint.subtract(this._origin);
-    const x = this._xAxis.dot(v);
-    const y = this._yAxis.dot(v);
+  /** Lift a local east/north point to the ellipsoid. Radial is the inverse of radial
+   * projection. Normal selects the nearest-facing line intersection and can miss.
+   * Neither operation restores a source point's height. Failure leaves result untouched.
+   */
+  projectPointOntoEllipsoid(
+    point: Readonly<NumericArray>,
+    mode: TangentPlaneProjectionMode = 'radial',
+    result = new Vector3()
+  ): Vector3 | undefined {
+    finiteInput(point, 2);
+    checkMode(mode);
+    const [rx, ry, rz] = this.radii;
+    if (mode === 'radial') {
+      const scale = Math.max(
+        Math.abs(this.anchor[0]),
+        Math.abs(this.anchor[1]),
+        Math.abs(this.anchor[2]),
+        Math.abs(point[0]),
+        Math.abs(point[1])
+      );
+      const u = point[0] / scale,
+        v = point[1] / scale;
+      const x = this.anchor[0] / scale + this.east[0] * u + this.north[0] * v;
+      const y = this.anchor[1] / scale + this.east[1] * u + this.north[1] * v;
+      const z = this.anchor[2] / scale + this.east[2] * u + this.north[2] * v;
+      const minimum = Math.min(rx, ry, rz);
+      const ax = x * (minimum / rx),
+        ay = y * (minimum / ry),
+        az = z * (minimum / rz);
+      const length = Math.hypot(ax, ay, az);
+      if (!(length > 0 && Number.isFinite(length))) return undefined;
+      return writeSurfacePoint(rx * (ax / length), ry * (ay / length), rz * (az / length), result);
+    }
+    const n = this.zAxis;
+    const p = [
+      this.anchor[0] + this.east[0] * point[0] + this.north[0] * point[1],
+      this.anchor[1] + this.east[1] * point[0] + this.north[1] * point[1],
+      this.anchor[2] + this.east[2] * point[0] + this.north[2] * point[1]
+    ];
+    if (!p.every(Number.isFinite)) return undefined;
+    const ax = n[0] / rx,
+      ay = n[1] / ry,
+      az = n[2] / rz;
+    const px = p[0] / rx,
+      py = p[1] / ry,
+      pz = p[2] / rz;
+    const a = ax * ax + ay * ay + az * az;
+    const b = ax * px + ay * py + az * pz;
+    const c = px * px + py * py + pz * pz - 1;
+    const squaredB = b * b,
+      ac = a * c;
+    const error = 1e-6 * (Math.abs(squaredB) + Math.abs(ac));
+    const discriminant = squaredB - ac;
+    if (!(a > 0) || !Number.isFinite(discriminant) || Math.abs(discriminant) <= error) {
+      const exact = exactNormalIntersection(
+        this.radii,
+        this.anchor,
+        this.east,
+        this.north,
+        n,
+        point,
+        this.radius
+      );
+      return exact && writeSurfacePoint(exact[0], exact[1], exact[2], result);
+    }
+    if (discriminant < 0) return undefined;
+    // Stable form of the nearer root (-b + sqrt(discriminant)) / a.
+    const root = Math.sqrt(Math.max(0, discriminant));
+    const t = b > 0 ? -c / (b + root) : (-b + root) / a;
+    return writeSurfacePoint(p[0] + t * n[0], p[1] + t * n[1], p[2] + t * n[2], result);
+  }
 
-    result.x = x;
-    result.y = y;
-    return result;
+  /** Packed XYZ to packed east/north. Invalid radial points produce NaN pairs and a zero mask.
+   * Optional output must have exactly two components per point and must not overlap input.
+   */
+  projectPointsFlat(
+    input: Readonly<NumericArray>,
+    mode: TangentPlaneProjectionMode = 'normal',
+    output?: Float64Array
+  ): TangentPlaneProjection {
+    checkMode(mode);
+    if (input.length % 3) throw new RangeError('Expected packed XYZ coordinates');
+    const count = input.length / 3;
+    const positions = output || new Float64Array(count * 2);
+    if (positions.length !== count * 2) throw new RangeError('Invalid tangent-plane output length');
+    if (
+      ArrayBuffer.isView(input) &&
+      input.buffer === positions.buffer &&
+      input.byteOffset < positions.byteOffset + positions.byteLength &&
+      positions.byteOffset < input.byteOffset + input.byteLength
+    ) {
+      throw new RangeError('Input and output buffers must not overlap');
+    }
+    // Validate before writing any output, including malformed later records.
+    for (let i = 0; i < input.length; i++) {
+      if (!Number.isFinite(input[i])) throw new RangeError('Expected finite coordinates');
+    }
+    const valid = new Uint8Array(count);
+    const point = new Vector3();
+    const projected = new Vector2();
+    for (let i = 0; i < count; i++) {
+      point.set(input[i * 3], input[i * 3 + 1], input[i * 3 + 2]);
+      const value =
+        mode === 'normal'
+          ? this.projectPointToNearestOnPlane(point, projected)
+          : this.projectPointRadiallyOntoPlane(point, projected);
+      valid[i] = value ? 1 : 0;
+      positions[i * 2] = value ? value[0] : NaN;
+      positions[i * 2 + 1] = value ? value[1] : NaN;
+    }
+    return {positions, valid};
   }
 
   get plane(): Plane {
@@ -70,18 +231,55 @@ export class EllipsoidTangentPlane {
   }
 
   get origin(): Vector3 {
-    return this._origin;
+    return this.anchor;
   }
 
   get xAxis(): Vector3 {
-    return this._xAxis;
+    return this.east;
   }
 
   get yAxis(): Vector3 {
-    return this._yAxis;
+    return this.north;
   }
 
   get zAxis(): Vector3 {
     return this._plane.normal;
   }
 }
+
+function finiteInput(point: Readonly<NumericArray>, length: number): void {
+  if (point.length !== length) throw new RangeError(`Expected ${length} finite coordinates`);
+  for (let i = 0; i < length; i++) {
+    if (!Number.isFinite(point[i])) throw new RangeError(`Expected ${length} finite coordinates`);
+  }
+}
+
+function checkMode(mode: TangentPlaneProjectionMode): void {
+  if (mode !== 'normal' && mode !== 'radial') throw new RangeError('Invalid tangent-plane mode');
+}
+
+function writePlanePoint(
+  plane: EllipsoidTangentPlane,
+  x: number,
+  y: number,
+  z: number,
+  result: Vector2,
+  radius?: number
+): Vector2 | undefined {
+  let east = x * plane.xAxis[0] + y * plane.xAxis[1] + z * plane.xAxis[2];
+  let north = x * plane.yAxis[0] + y * plane.yAxis[1] + z * plane.yAxis[2];
+  if (
+    radius !== undefined &&
+    Math.abs((east / radius) ** 2 + (north / radius) ** 2 - 1) <= 32 * Number.EPSILON
+  ) {
+    east = compensatedDot3(x, y, z, plane.xAxis[0], plane.xAxis[1], plane.xAxis[2]);
+    north = compensatedDot3(x, y, z, plane.yAxis[0], plane.yAxis[1], plane.yAxis[2]);
+  }
+  if (!Number.isFinite(east) || !Number.isFinite(north)) return undefined;
+  return result.set(east, north);
+}
+
+function writeSurfacePoint(x: number, y: number, z: number, result: Vector3): Vector3 | undefined {
+  if (![x, y, z].every(Number.isFinite)) return undefined;
+  return result.set(x, y, z);
+}

package/src/ellipsoid-transforms.ts

@@ -0,0 +1,61 @@
+// math.gl
+// SPDX-License-Identifier: MIT AND Apache-2.0
+// SPDX-FileCopyrightText: Copyright 2011-2018 CesiumJS Contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Extracted Cesium-derived frame adapters; see ../LICENSE for attribution.
+
+import {Matrix4} from '@math.gl/core';
+import type {NumericArray} from '@math.gl/core';
+import type {Ellipsoid} from './ellipsoid';
+import {localFrameToFixedFrame as computeLocalFrame} from './ellipsoid-helpers/ellipsoid-transform';
+import type {AxisDirection} from './ellipsoid-helpers/ellipsoid-transform';
+
+export type {AxisDirection} from './ellipsoid-helpers/ellipsoid-transform';
+
+/** Compute an east-north-up frame at a Cartesian origin on the given ellipsoid. */
+export function eastNorthUpToFixedFrame(
+  ellipsoid: Ellipsoid,
+  origin: Readonly<NumericArray>,
+  result?: Matrix4
+): Matrix4;
+export function eastNorthUpToFixedFrame<T extends number[]>(
+  ellipsoid: Ellipsoid,
+  origin: Readonly<NumericArray>,
+  result: T
+): T;
+export function eastNorthUpToFixedFrame(
+  ellipsoid: Ellipsoid,
+  origin: Readonly<NumericArray>,
+  result = new Matrix4()
+): number[] {
+  return computeLocalFrame(ellipsoid, 'east', 'north', 'up', origin, result);
+}
+
+/** Compute a frame with the specified axes at a Cartesian origin. */
+export function localFrameToFixedFrame(
+  ellipsoid: Ellipsoid,
+  firstAxis: AxisDirection,
+  secondAxis: AxisDirection,
+  thirdAxis: AxisDirection,
+  origin: Readonly<NumericArray>,
+  result?: Matrix4
+): Matrix4;
+export function localFrameToFixedFrame<T extends number[]>(
+  ellipsoid: Ellipsoid,
+  firstAxis: AxisDirection,
+  secondAxis: AxisDirection,
+  thirdAxis: AxisDirection,
+  origin: Readonly<NumericArray>,
+  result: T
+): T;
+// eslint-disable-next-line max-params
+export function localFrameToFixedFrame(
+  ellipsoid: Ellipsoid,
+  firstAxis: AxisDirection,
+  secondAxis: AxisDirection,
+  thirdAxis: AxisDirection,
+  origin: Readonly<NumericArray>,
+  result = new Matrix4()
+): number[] {
+  return computeLocalFrame(ellipsoid, firstAxis, secondAxis, thirdAxis, origin, result);
+}