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

package/src/ellipsoid.ts

@@ -1,26 +1,34 @@
 // 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. See the repository LICENSE for upstream attribution and Apache-2.0 terms. Original math.gl follow-up uses stable atan2 latitude and numeric cartographic output.
 
 // 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.
 
 /* eslint-disable */
-import {Vector3, Matrix4, assert, equals, _MathUtils, NumericArray} from '@math.gl/core';
-import * as vec3 from '@math.gl/core/vec3';
+import {Vector3, assert, _MathUtils, NumericArray, config} from '@math.gl/core';
+import type {SpheroidParameters} from '@math.gl/core/types';
+import {
+  spheroidToCartesian,
+  cartesianToSpheroid,
+  type SpheroidGeometry
+} from '@math.gl/core/spheroid';
 
 import {WGS84_RADIUS_X, WGS84_RADIUS_Y, WGS84_RADIUS_Z} from './constants';
-import {fromCartographicToRadians, toCartographicFromRadians} from './type-utils';
+import {
+  fromCartographic,
+  fromCartographicToRadians,
+  toCartographicFromRadiansComponents
+} from './type-utils';
 
-import type {AxisDirection} from './ellipsoid-helpers/ellipsoid-transform';
-import {localFrameToFixedFrame} from './ellipsoid-helpers/ellipsoid-transform';
-import {scaleToGeodeticSurface} from './ellipsoid-helpers/scale-to-geodetic-surface';
+import {scaleToGeodeticSurface, writeResult} from './ellipsoid-helpers/scale-to-geodetic-surface';
 
+const spheroidScratch = {x: 0, y: 0, z: 0};
 const scratchVector = new Vector3();
 const scratchNormal = new Vector3();
-const scratchK = new Vector3();
 const scratchPosition = new Vector3();
-const scratchHeight = new Vector3();
 const scratchCartesian = new Vector3();
 
 /**
@@ -32,6 +40,15 @@ export class Ellipsoid {
   /** An Ellipsoid instance initialized to the WGS84 standard. */
   static readonly WGS84: Ellipsoid = new Ellipsoid(WGS84_RADIUS_X, WGS84_RADIUS_Y, WGS84_RADIUS_Z);
 
+  /** Construct from two-axis geometry, including normalized projection ellipsoids.
+   * The equatorial X/Y radii are equal; no CRS or datum information is inferred.
+   */
+  static fromSpheroid(parameters: SpheroidParameters): Ellipsoid {
+    const {semiMajorAxis, semiMinorAxis} = parameters;
+    validateSpheroid(semiMajorAxis, semiMinorAxis);
+    return new Ellipsoid(semiMajorAxis, semiMajorAxis, semiMinorAxis);
+  }
+
   readonly radii: Vector3;
   readonly radiiSquared: Vector3;
   readonly radiiToTheFourth: Vector3;
@@ -41,15 +58,16 @@ export class Ellipsoid {
   readonly maximumRadius: number;
   readonly centerToleranceSquared: number = _MathUtils.EPSILON1;
   readonly squaredXOverSquaredZ: number;
+  private readonly spheroidGeometry?: SpheroidGeometry;
 
   /** Creates an Ellipsoid from a Cartesian specifying the radii in x, y, and z directions. */
   constructor(x: number, y: number, z: number);
   constructor();
 
   constructor(x = 0.0, y = 0.0, z = 0.0) {
-    assert(x >= 0.0);
-    assert(y >= 0.0);
-    assert(z >= 0.0);
+    assert(Number.isFinite(x) && x >= 0.0);
+    assert(Number.isFinite(y) && y >= 0.0);
+    assert(Number.isFinite(z) && z >= 0.0);
 
     this.radii = new Vector3(x, y, z);
 
@@ -73,19 +91,50 @@ export class Ellipsoid {
 
     this.maximumRadius = Math.max(x, y, z);
 
-    if (this.radiiSquared.z !== 0) {
-      this.squaredXOverSquaredZ = this.radiiSquared.x / this.radiiSquared.z;
+    if (z !== 0) {
+      this.squaredXOverSquaredZ = (x / z) ** 2;
     }
 
+    // Setup only: retain the three-radius path for unsupported/lossy shapes.
+    if (
+      x === y &&
+      z > 0 &&
+      z <= x &&
+      Number.isFinite(this.radiiSquared.x) &&
+      this.radiiSquared.z > 0
+    )
+      this.spheroidGeometry = Object.freeze({
+        semiMajorAxis: x,
+        semiMinorAxis: z,
+        eccentricitySquared: 1 - (z / x) ** 2
+      });
+    // Geometry and all derived caches are one immutable snapshot. Mutating a
+    // public vector previously changed some algorithms while leaving others stale.
+    Object.freeze(this.radii);
+    Object.freeze(this.radiiSquared);
+    Object.freeze(this.radiiToTheFourth);
+    Object.freeze(this.oneOverRadii);
+    Object.freeze(this.oneOverRadiiSquared);
     Object.freeze(this);
   }
 
+  /** Return an owned geometry snapshot for a sphere or oblate spheroid.
+   * Triaxial, prolate and degenerate ellipsoids cannot be represented by this contract.
+   * Call during setup, outside coordinate loops.
+   */
+  toSpheroid(): SpheroidParameters {
+    const {x, y, z} = this.radii;
+    if (x !== y) throw new Error('Spheroid requires equal X/Y radii');
+    validateSpheroid(x, z);
+    return Object.freeze({semiMajorAxis: x, semiMinorAxis: z});
+  }
+
   /** Compares this Ellipsoid against the provided Ellipsoid componentwise */
   equals(right: Ellipsoid): boolean {
     return this === right || Boolean(right && this.radii.equals(right.radii));
   }
 
-  /** Creates a string representing this Ellipsoid in the format '(radii.x, radii.y, radii.z)'. */
+  /** Creates a string representing this Ellipsoid in the format '[radii.x, radii.y, radii.z]'. */
   toString(): string {
     return this.radii.toString();
   }
@@ -98,21 +147,45 @@ export class Ellipsoid {
   cartographicToCartesian(cartographic: number[], result?: number[]): number[];
 
   cartographicToCartesian(cartographic: Readonly<NumericArray>, result = [0, 0, 0]) {
+    const llh = fromCartographicToRadians(cartographic, scratchCartesian);
+    const longitude = llh[0],
+      latitude = llh[1],
+      height = llh[2];
+    if (
+      !Number.isFinite(longitude) ||
+      !Number.isFinite(latitude) ||
+      !Number.isFinite(height) ||
+      !(this.minimumRadius > 0) ||
+      !Number.isFinite(this.maximumRadius * this.maximumRadius)
+    )
+      return undefined;
+    // Degree inputs near a pole retain their complement before conversion. A
+    // rounded radian latitude loses angle bits amplified by thin-shape curvature.
+    if (
+      this.spheroidGeometry &&
+      (config._cartographicRadians || Math.abs(latitude) <= Math.PI / 4)
+    ) {
+      spheroidScratch.x = longitude;
+      spheroidScratch.y = latitude;
+      spheroidScratch.z = height;
+      if (!spheroidToCartesian(spheroidScratch, this.spheroidGeometry)) return undefined;
+      return writeResult(result, spheroidScratch.x, spheroidScratch.y, spheroidScratch.z);
+    }
     const normal = scratchNormal;
-    const k = scratchK;
-
-    const [, , height] = cartographic;
     this.geodeticSurfaceNormalCartographic(cartographic, normal);
-    k.copy(this.radiiSquared).scale(normal);
-
-    const gamma = Math.sqrt(normal.dot(k));
-    k.scale(1 / gamma);
-
-    normal.scale(height);
-
-    k.add(normal);
-
-    return k.to(result);
+    const nx = normal.x,
+      ny = normal.y,
+      nz = normal.z;
+    const rx = this.radii.x,
+      ry = this.radii.y,
+      rz = this.radii.z;
+    // Form support from scaled axes, not rounded (possibly subnormal) squares.
+    const gamma = Math.hypot(rx * nx, ry * ny, rz * nz);
+    const x = rx * ((rx * nx) / gamma) + height * nx;
+    const y = ry * ((ry * ny) / gamma) + height * ny;
+    const z = rz * ((rz * nz) / gamma) + height * nz;
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) return undefined;
+    return writeResult(result, x, y, z);
   }
 
   /** Converts the provided Cartesian position to [longitude, latitude, height],
@@ -123,62 +196,71 @@ export class Ellipsoid {
   cartesianToCartographic(cartesian: Readonly<NumericArray>, result?: number[]): number[];
 
   cartesianToCartographic(cartesian: Readonly<NumericArray>, result = [0, 0, 0]) {
-    scratchCartesian.from(cartesian);
+    const object = cartesian as unknown as {x: number; y: number; z: number};
+    const x = 'x' in cartesian ? object.x : cartesian[0];
+    const y = 'x' in cartesian ? object.y : cartesian[1];
+    const z = 'x' in cartesian ? object.z : cartesian[2];
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) return undefined;
+    // Sphere/oblate conversion chooses the unique nearest normal, including interiors.
+    // Preserve legacy geometry magnitude limits; prolate/triaxial keep their own kernel.
+    if (
+      this.spheroidGeometry &&
+      Number.isFinite(x * x + y * y + z * z) &&
+      Number.isFinite(this.oneOverRadiiSquared.x) &&
+      Number.isFinite(this.oneOverRadiiSquared.z)
+    ) {
+      spheroidScratch.x = x;
+      spheroidScratch.y = y;
+      spheroidScratch.z = z;
+      const shape = this.spheroidGeometry;
+      const nearBoundary =
+        z === 0 &&
+        shape.semiMinorAxis < shape.semiMajorAxis &&
+        Math.abs(Math.hypot(x, y) - shape.semiMajorAxis * shape.eccentricitySquared) <=
+          64 * Number.EPSILON * shape.semiMajorAxis;
+      // On the cusp plane classify exact axes/coordinates, not a rounded hypot.
+      if (!nearBoundary && cartesianToSpheroid(spheroidScratch, shape)) {
+        // Preserve signed-zero atan2 at exact poles rather than projection's canonical zero.
+        const longitude = x === 0 && y === 0 ? Math.atan2(y, x) : spheroidScratch.x;
+        return toCartographicFromRadiansComponents(
+          longitude,
+          spheroidScratch.y,
+          spheroidScratch.z,
+          result
+        );
+      }
+      // Exact three-axis fallback can recover a unique root when the shared
+      // bounded numeric solve cannot represent its intermediate scaling.
+    }
+    // Retain the legacy representable squared-axis domain for normal arithmetic.
+    if (
+      !(this.minimumRadius > 0) ||
+      !Number.isFinite(this.maximumRadius * this.maximumRadius) ||
+      !Number.isFinite(1 / (this.minimumRadius * this.minimumRadius))
+    )
+      return undefined;
+    scratchCartesian.set(x, y, z);
     const point = this.scaleToGeodeticSurface(scratchCartesian, scratchPosition);
 
     if (!point) {
       return undefined;
     }
 
-    const normal = this.geodeticSurfaceNormal(point, scratchNormal);
-
-    const h = scratchHeight;
-    h.copy(scratchCartesian).subtract(point);
-
-    const longitude = Math.atan2(normal.y, normal.x);
-    const latitude = Math.asin(normal.z);
-    const height = Math.sign(vec3.dot(h, scratchCartesian)) * vec3.length(h);
-
-    return toCartographicFromRadians([longitude, latitude, height], result);
-  }
-
-  /** Computes a 4x4 transformation matrix from a reference frame with an east-north-up axes
-   * centered at the provided origin to the provided ellipsoid's fixed reference frame. */
-  eastNorthUpToFixedFrame(origin: Readonly<NumericArray>, result?: Matrix4): Matrix4;
-  eastNorthUpToFixedFrame(origin: Readonly<NumericArray>, result: number[]): number[];
-
-  eastNorthUpToFixedFrame(origin: Readonly<NumericArray>, result = new Matrix4()) {
-    return localFrameToFixedFrame(this, 'east', 'north', 'up', origin, result);
-  }
-
-  /** Computes a 4x4 transformation matrix from a reference frame centered at
-   * the provided origin to the ellipsoid's fixed reference frame.
-   */
-  localFrameToFixedFrame(
-    firstAxis: AxisDirection,
-    secondAxis: AxisDirection,
-    thirdAxis: AxisDirection,
-    origin: Readonly<NumericArray>,
-    result?: Matrix4
-  ): Matrix4;
-  localFrameToFixedFrame<_Matrix4T>(
-    firstAxis: AxisDirection,
-    secondAxis: AxisDirection,
-    thirdAxis: AxisDirection,
-    origin: Readonly<NumericArray>,
-    result: number[]
-  ): number[];
-
-  // Computes a 4x4 transformation matrix from a reference frame centered at
-  // the provided origin to the ellipsoid's fixed reference frame.
-  localFrameToFixedFrame(
-    firstAxis: AxisDirection,
-    secondAxis: AxisDirection,
-    thirdAxis: AxisDirection,
-    origin: Readonly<NumericArray>,
-    result = new Matrix4()
-  ) {
-    return localFrameToFixedFrame(this, firstAxis, secondAxis, thirdAxis, origin, result);
+    const gx = point[0] * this.oneOverRadiiSquared.x;
+    const gy = point[1] * this.oneOverRadiiSquared.y;
+    const gz = point[2] * this.oneOverRadiiSquared.z;
+    const length = Math.hypot(gx, gy, gz);
+    if (!(length > 0) || !Number.isFinite(length)) return undefined;
+    const nx = gx / length,
+      ny = gy / length,
+      nz = gz / length;
+    const longitude = Math.atan2(ny, nx);
+    const latitude = Math.atan2(nz, Math.hypot(nx, ny));
+    // Project onto the unit normal. The former sign(h dot input) can underflow
+    // for a deep interior even when its signed height is representable.
+    const height = (x - point[0]) * nx + (y - point[1]) * ny + (z - point[2]) * nz;
+
+    return toCartographicFromRadiansComponents(longitude, latitude, height, result);
   }
 
   /** Computes the unit vector directed from the center of this ellipsoid toward
@@ -186,7 +268,9 @@ export class Ellipsoid {
   geocentricSurfaceNormal(cartesian: number[], result?: number[]): number[];
   geocentricSurfaceNormal<NumArray>(cartesian: number[], result: NumArray): NumArray;
   geocentricSurfaceNormal(cartesian: Readonly<NumericArray>, result = [0, 0, 0]) {
-    return scratchVector.from(cartesian).normalize().to(result);
+    fromCartographic(cartesian, scratchVector);
+    const point = scratchVector;
+    return normalResult(point.x, point.y, point.z, result);
   }
 
   /** Computes the normal of the plane tangent to the surface of the ellipsoid at the provided
@@ -198,25 +282,72 @@ export class Ellipsoid {
   ): NumArray;
   geodeticSurfaceNormalCartographic(cartographic: number[]): number[];
   geodeticSurfaceNormalCartographic(cartographic: Readonly<NumericArray>, result = [0, 0, 0]) {
-    const cartographicVectorRadians = fromCartographicToRadians(cartographic);
-
-    const longitude = cartographicVectorRadians[0];
-    const latitude = cartographicVectorRadians[1];
-
-    const cosLatitude = Math.cos(latitude);
-
-    scratchVector
-      .set(cosLatitude * Math.cos(longitude), cosLatitude * Math.sin(longitude), Math.sin(latitude))
-      .normalize();
-
-    return scratchVector.to(result);
+    const point = fromCartographic(cartographic, scratchCartesian);
+    const longitude = config._cartographicRadians ? point[0] : (point[0] * Math.PI) / 180;
+    const latitude = config._cartographicRadians ? point[1] : (point[1] * Math.PI) / 180;
+    const polarDegrees = !config._cartographicRadians && Math.abs(point[1]) > 45;
+    const complement = ((90 - Math.abs(point[1])) * Math.PI) / 180;
+    const cosLatitude = polarDegrees
+      ? Math.sin(complement)
+      : Math.abs(latitude) === Math.PI / 2
+        ? 0
+        : Math.cos(latitude);
+    const sinLatitude = polarDegrees
+      ? Math.sign(point[1]) * Math.cos(complement)
+      : Math.sin(latitude);
+    return normalResult(
+      cosLatitude * Math.cos(longitude),
+      cosLatitude * Math.sin(longitude),
+      sinLatitude,
+      result
+    );
   }
 
   /** Computes the normal of the plane tangent to the surface of the ellipsoid at the provided position. */
   geodeticSurfaceNormal<NumArrayT>(cartesian: number[], result: NumArrayT): NumArrayT;
   geodeticSurfaceNormal(cartesian: number[]): number[];
   geodeticSurfaceNormal(cartesian: Readonly<NumericArray>, result = [0, 0, 0]) {
-    return scratchVector.from(cartesian).scale(this.oneOverRadiiSquared).normalize().to(result);
+    if (!(this.minimumRadius > 0)) return undefined;
+    fromCartographic(cartesian, scratchVector);
+    const point = scratchVector;
+    const scale = Math.max(Math.abs(point.x), Math.abs(point.y), Math.abs(point.z));
+    if (!(scale > 0) || !Number.isFinite(scale)) return undefined;
+    const nx = (point.x / scale) * (this.minimumRadius / this.radii.x) ** 2;
+    const ny = (point.y / scale) * (this.minimumRadius / this.radii.y) ** 2;
+    const nz = (point.z / scale) * (this.minimumRadius / this.radii.z) ** 2;
+    if (
+      (point.x === 0 || Math.abs(nx) >= 2 ** -1022) &&
+      (point.y === 0 || Math.abs(ny) >= 2 ** -1022) &&
+      (point.z === 0 || Math.abs(nz) >= 2 ** -1022)
+    )
+      return normalResult(nx, ny, nz, result);
+
+    // Original exponent-scaled gradient fallback: evaluate x/a² only after
+    // extracting exact powers of two. Squared radius ratios and scaled input
+    // coordinates can underflow independently before their weights compensate.
+    const ex = point.x === 0 ? 0 : Math.min(1023, Math.floor(Math.log2(Math.abs(point.x))));
+    const ey = point.y === 0 ? 0 : Math.min(1023, Math.floor(Math.log2(Math.abs(point.y))));
+    const ez = point.z === 0 ? 0 : Math.min(1023, Math.floor(Math.log2(Math.abs(point.z))));
+    const ax = Math.min(1023, Math.floor(Math.log2(this.radii.x)));
+    const ay = Math.min(1023, Math.floor(Math.log2(this.radii.y)));
+    const az = Math.min(1023, Math.floor(Math.log2(this.radii.z)));
+    const common = Math.max(
+      point.x === 0 ? -Infinity : ex - 2 * ax,
+      point.y === 0 ? -Infinity : ey - 2 * ay,
+      point.z === 0 ? -Infinity : ez - 2 * az
+    );
+    return normalResult(
+      point.x === 0
+        ? point.x
+        : (point.x / 2 ** ex / (this.radii.x / 2 ** ax) ** 2) * 2 ** (ex - 2 * ax - common),
+      point.y === 0
+        ? point.y
+        : (point.y / 2 ** ey / (this.radii.y / 2 ** ay) ** 2) * 2 ** (ey - 2 * ay - common),
+      point.z === 0
+        ? point.z
+        : (point.z / 2 ** ez / (this.radii.z / 2 ** az) ** 2) * 2 ** (ez - 2 * az - common),
+      result
+    );
   }
 
   /** Scales the provided Cartesian position along the geodetic surface normal
@@ -229,34 +360,47 @@ export class Ellipsoid {
   /** Scales the provided Cartesian position along the geocentric surface normal
    * so that it is on the surface of this ellipsoid. */
   scaleToGeocentricSurface(cartesian: number[], result: number[] = [0, 0, 0]): number[] {
-    scratchPosition.from(cartesian);
-
-    const positionX = scratchPosition.x;
-    const positionY = scratchPosition.y;
-    const positionZ = scratchPosition.z;
-    const oneOverRadiiSquared = this.oneOverRadiiSquared;
-
-    const beta =
-      1.0 /
-      Math.sqrt(
-        positionX * positionX * oneOverRadiiSquared.x +
-          positionY * positionY * oneOverRadiiSquared.y +
-          positionZ * positionZ * oneOverRadiiSquared.z
-      );
-
-    return scratchPosition.multiplyByScalar(beta).to(result);
+    fromCartographic(cartesian, scratchPosition);
+    const point = scratchPosition;
+    const scale = Math.max(Math.abs(point.x), Math.abs(point.y), Math.abs(point.z));
+    if (!(this.minimumRadius > 0) || !(scale > 0) || !Number.isFinite(scale)) return undefined;
+    const squared =
+      point.x * point.x * this.oneOverRadiiSquared.x +
+      point.y * point.y * this.oneOverRadiiSquared.y +
+      point.z * point.z * this.oneOverRadiiSquared.z;
+    // Preserve the ordinary path's established rounding; scale only when its
+    // squared intermediates are unsafe. Commit scalar snapshots in both paths.
+    if (
+      squared >= 2 ** -1022 &&
+      Number.isFinite(squared) &&
+      scale * scale >= 2 ** -1022 &&
+      Number.isFinite(scale * scale)
+    ) {
+      const beta = 1 / Math.sqrt(squared);
+      return writeResult(result, point.x * beta, point.y * beta, point.z * beta);
+    }
+    const x = point.x / scale,
+      y = point.y / scale,
+      z = point.z / scale;
+    const norm = Math.hypot(x / this.radii.x, y / this.radii.y, z / this.radii.z);
+    if (!(norm > 0) || !Number.isFinite(norm)) return undefined;
+    return writeResult(result, x / norm, y / norm, z / norm);
   }
 
   /** Transforms a Cartesian X, Y, Z position to the ellipsoid-scaled space by multiplying
    * its components by the result of `Ellipsoid#oneOverRadii` */
   transformPositionToScaledSpace(position: number[], result: number[] = [0, 0, 0]): number[] {
-    return scratchPosition.from(position).scale(this.oneOverRadii).to(result);
+    fromCartographic(position, scratchPosition);
+    const point = scratchPosition.scale(this.oneOverRadii);
+    return writeResult(result, point.x, point.y, point.z);
   }
 
   /** Transforms a Cartesian X, Y, Z position from the ellipsoid-scaled space by multiplying
    * its components by the result of `Ellipsoid#radii`. */
   transformPositionFromScaledSpace(position: number[], result: number[] = [0, 0, 0]): number[] {
-    return scratchPosition.from(position).scale(this.radii).to(result);
+    fromCartographic(position, scratchPosition);
+    const point = scratchPosition.scale(this.radii);
+    return writeResult(result, point.x, point.y, point.z);
   }
 
   /** Computes a point which is the intersection of the surface normal with the z-axis. */
@@ -266,16 +410,40 @@ export class Ellipsoid {
     result: number[] = [0, 0, 0]
   ): number[] {
     // Ellipsoid must be an ellipsoid of revolution (radii.x == radii.y)
-    assert(equals(this.radii.x, this.radii.y, _MathUtils.EPSILON15));
-    assert(this.radii.z > 0);
-
-    scratchPosition.from(position);
+    assert(this.radii.x === this.radii.y && this.minimumRadius > 0);
+
+    fromCartographic(position, scratchPosition);
+    if (
+      !Number.isFinite(scratchPosition.x) ||
+      !Number.isFinite(scratchPosition.y) ||
+      !Number.isFinite(scratchPosition.z) ||
+      !Number.isFinite(buffer)
+    )
+      return undefined;
     const z = scratchPosition.z * (1 - this.squaredXOverSquaredZ);
+    if (!Number.isFinite(z)) return undefined;
 
     if (Math.abs(z) >= this.radii.z - buffer) {
       return undefined;
     }
 
-    return scratchPosition.set(0.0, 0.0, z).to(result);
+    return writeResult(result, 0, 0, z);
   }
 }
+
+// Original parameter adapter; conversion and surface kernels above retain Cesium attribution.
+function validateSpheroid(a: number, b: number): void {
+  if (!Number.isFinite(a) || !Number.isFinite(b) || a <= 0 || b <= 0 || b > a)
+    throw new Error('Spheroid requires finite positive axes with semiMinorAxis <= semiMajorAxis');
+}
+
+/** Original scaled normalization and scalar commit; safe for tiny/huge rays and reentrant setters. */
+function normalResult(x: number, y: number, z: number, result: number[]): number[] {
+  const scale = Math.max(Math.abs(x), Math.abs(y), Math.abs(z));
+  if (!(scale > 0) || !Number.isFinite(scale)) return undefined;
+  const nx = x / scale,
+    ny = y / scale,
+    nz = z / scale;
+  const length = Math.hypot(nx, ny, nz);
+  return writeResult(result, nx / length, ny / length, nz / length);
+}

package/src/entries/ellipsoid.ts

@@ -0,0 +1,44 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {Ellipsoid} from '../ellipsoid';
+export {EllipsoidTangentPlane} from '../ellipsoid-tangent-plane';
+export {isWGS84} from '../type-utils';
+export type {SpheroidParameters} from '@math.gl/core/types';
+export {EllipsoidGeodesic} from '../ellipsoid-geodesic';
+export type {
+  GeodesicResult,
+  GeodesicLine,
+  GeodesicParameters,
+  GeodesicOptions
+} from '../ellipsoid-geodesic';
+export {LocalReferenceFrame} from '../local-reference-frame';
+export type {LocalReferenceFrameOptions, HeadingPitchRoll} from '../local-reference-frame';
+export type {TangentPlaneProjectionMode, TangentPlaneProjection} from '../ellipsoid-tangent-plane';
+
+export {EllipsoidMetrics} from '../ellipsoid-metrics';
+export type {AuxiliaryLatitude} from '../ellipsoid-metrics';
+export {GeodesicPolygon} from '../geodesic-polygon';
+export type {GeodesicPolygonResult, GeodesicPolygonOptions} from '../geodesic-polygon';
+
+export {EllipsoidRhumb, RhumbDomainError} from '../ellipsoid-rhumb';
+export type {RhumbOptions, RhumbResult, RhumbLine} from '../ellipsoid-rhumb';
+export {RhumbPolygon} from '../rhumb-polygon';
+export type {RhumbPolygonOptions, RhumbPolygonResult, RhumbPointOptions} from '../rhumb-polygon';
+export {GeodesicIntersections} from '../geodesic-intersections';
+export type {
+  GeodesicPath as GeodesicIntersectionPath,
+  IntersectionPoint,
+  IntersectionSearchOptions,
+  IntersectionSearch,
+  ClosestIntersection,
+  SegmentIntersection
+} from '../geodesic-intersections';
+export {GeodesicPath} from '../geodesic-path';
+export type {GeodesicPathOptions} from '../geodesic-path';
+export {RhumbPath} from '../rhumb-path';
+export type {RhumbPathOptions} from '../rhumb-path';
+
+export {eastNorthUpToFixedFrame, localFrameToFixedFrame} from '../ellipsoid-transforms';
+export type {AxisDirection} from '../ellipsoid-transforms';

package/src/expressions.ts

@@ -0,0 +1,35 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return */
+
+import {eastNorthUpToFixedFrame} from './ellipsoid-transforms';
+import {Ellipsoid} from './ellipsoid';
+import {isWGS84} from './type-utils';
+import {toDegrees, toRadians} from '@math.gl/core';
+import type {ExpressionFunctionLibrary} from '@math.gl/core/expressions';
+
+/** WGS84 ellipsoid helpers available to the expression evaluator. */
+export const GEOSPATIAL_FUNCTION_LIBRARY: ExpressionFunctionLibrary = {
+  cartesianToCartographic: (cartesian: number[], result?: number[]) =>
+    Ellipsoid.WGS84.cartesianToCartographic(cartesian, result),
+  cartographicToCartesian: (cartographic: number[], result?: number[]) =>
+    Ellipsoid.WGS84.cartographicToCartesian(cartographic, result),
+  eastNorthUpToFixedFrame: (origin: number[], result?: number[]) =>
+    eastNorthUpToFixedFrame(Ellipsoid.WGS84, origin, result),
+  geodeticSurfaceNormal: (cartesian: number[], result?: number[]) =>
+    Ellipsoid.WGS84.geodeticSurfaceNormal(cartesian, result),
+  geodeticSurfaceNormalCartographic: (cartographic: number[], result?: number[]) =>
+    Ellipsoid.WGS84.geodeticSurfaceNormalCartographic(cartographic, result),
+  isWGS84,
+  scaleToGeocentricSurface: (cartesian: number[], result?: number[]) =>
+    Ellipsoid.WGS84.scaleToGeocentricSurface(cartesian, result),
+  scaleToGeodeticSurface: (cartesian: number[], result?: number[]) =>
+    Ellipsoid.WGS84.scaleToGeodeticSurface(cartesian, result),
+  toDegrees,
+  toRadians,
+  transformPositionFromScaledSpace: (position: number[], result?: number[]) =>
+    Ellipsoid.WGS84.transformPositionFromScaledSpace(position, result),
+  transformPositionToScaledSpace: (position: number[], result?: number[]) =>
+    Ellipsoid.WGS84.transformPositionToScaledSpace(position, result)
+};

package/src/geoarrow/builder-entry.ts

@@ -0,0 +1,18 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/** Optional builder subpath. Importing it avoids pulling codec and tessellation helpers. */
+export type {
+  GeoArrowBuilderEncoding,
+  GeoArrowBuilderMeasurement,
+  GeoArrowBuilderModeOptions,
+  GeoArrowBuilderOptions,
+  GeoArrowColumnFromRowsOptions,
+  GeoArrowBuilderTarget
+} from './builder';
+export {
+  allocateGeoArrowBuilderTarget,
+  GeoArrowBuilder,
+  makeGeoArrowColumnFromGeometryRows
+} from './builder';