@math.gl/geospatial 5.0.0-alpha.10 → 5.0.0-alpha.12

package/package.json

@@ -6,7 +6,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "5.0.0-alpha.10",
+  "version": "5.0.0-alpha.12",
   "keywords": [
     "webgl",
     "javascript",
@@ -39,9 +39,9 @@
     "src"
   ],
   "dependencies": {
-    "@math.gl/core": "5.0.0-alpha.10",
-    "@math.gl/culling": "5.0.0-alpha.10",
-    "@math.gl/types": "5.0.0-alpha.10"
+    "@math.gl/core": "5.0.0-alpha.12",
+    "@math.gl/culling": "5.0.0-alpha.12",
+    "@math.gl/types": "5.0.0-alpha.12"
   },
-  "gitHead": "e95bbd3387b7f760889f50cf2e6e439560f058af"
+  "gitHead": "9f9ed72b110b898a5e2df55984b6cff67f8feab2"
 }

package/src/constants.ts

@@ -1,6 +1,8 @@
 // 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.
 
 // 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

package/src/ellipsoid-helpers/ellipsoid-transform.ts

@@ -1,6 +1,8 @@
 // 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.
 
 import {NumericArray} from '@math.gl/types';
 import {Vector3, assert, equals as equalsEpsilon} from '@math.gl/core';

package/src/ellipsoid-helpers/scale-to-geodetic-surface.ts

@@ -1,9 +1,11 @@
 // 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 bounds Newton iteration and commits numeric components without a temporary array.
 
 /* eslint-disable */
-import {Vector3, _MathUtils} from '@math.gl/core';
+import {Vector3, _MathUtils, isArray} from '@math.gl/core';
 import type {Ellipsoid} from '../ellipsoid';
 
 const scratchVector = new Vector3();
@@ -20,11 +22,15 @@ export function scaleToGeodeticSurface(
 ): number[] {
   const {oneOverRadii, oneOverRadiiSquared, centerToleranceSquared} = ellipsoid;
 
-  scratchVector.from(cartesian);
-
-  const positionX = scratchVector.x;
-  const positionY = scratchVector.y;
-  const positionZ = scratchVector.z;
+  // Snapshot numeric inputs before touching scratch or debug-mode vectors.
+  const object = cartesian as unknown as {x: number; y: number; z: number};
+  const positionX = 'x' in cartesian ? object.x : cartesian[0];
+  const positionY = 'x' in cartesian ? object.y : cartesian[1];
+  const positionZ = 'x' in cartesian ? object.z : cartesian[2];
+  if (!Number.isFinite(positionX) || !Number.isFinite(positionY) || !Number.isFinite(positionZ)) {
+    return undefined;
+  }
+  scratchVector.set(positionX, positionY, positionZ);
 
   const oneOverRadiiX = oneOverRadii.x;
   const oneOverRadiiY = oneOverRadii.y;
@@ -39,17 +45,17 @@ export function scaleToGeodeticSurface(
   const ratio = Math.sqrt(1.0 / squaredNorm);
 
   // When very close to center or at center
-  if (!Number.isFinite(ratio)) {
+  if (!Number.isFinite(ratio) || !Number.isFinite(squaredNorm)) {
     return undefined;
   }
 
   // As an initial approximation, assume that the radial intersection is the projection point.
   const intersection = scaleToGeodeticSurfaceIntersection;
-  intersection.copy(cartesian).scale(ratio);
+  intersection.set(positionX, positionY, positionZ).scale(ratio);
 
   // If the position is near the center, the iteration will not converge.
   if (squaredNorm < centerToleranceSquared) {
-    return intersection.to(result);
+    return writeResult(result, intersection.x, intersection.y, intersection.z);
   }
 
   const oneOverRadiiSquaredX = oneOverRadiiSquared.x;
@@ -74,7 +80,8 @@ export function scaleToGeodeticSurface(
   let zMultiplier;
   let func;
 
-  do {
+  // Bound the original Newton iteration; unsupported inputs leave caller output untouched.
+  for (let iteration = 0; iteration < 64; iteration++) {
     lambda -= correction;
 
     xMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredX);
@@ -91,6 +98,17 @@ export function scaleToGeodeticSurface(
 
     func = x2 * xMultiplier2 + y2 * yMultiplier2 + z2 * zMultiplier2 - 1.0;
 
+    if (!Number.isFinite(func)) return undefined;
+    if (Math.abs(func) <= _MathUtils.EPSILON12) {
+      // Numeric components avoid the former temporary multiplier array.
+      return writeResult(
+        result,
+        positionX * xMultiplier,
+        positionY * yMultiplier,
+        positionZ * zMultiplier
+      );
+    }
+
     // "denominator" here refers to the use of this expression in the velocity and acceleration
     // computations in the sections to follow.
     const denominator =
@@ -100,8 +118,24 @@ export function scaleToGeodeticSurface(
 
     const derivative = -2.0 * denominator;
 
+    if (!Number.isFinite(derivative) || derivative === 0) return undefined;
     correction = func / derivative;
-  } while (Math.abs(func) > _MathUtils.EPSILON12);
+    if (!Number.isFinite(correction)) return undefined;
+  }
+  return undefined;
+}
 
-  return scratchVector.scale([xMultiplier, yMultiplier, zMultiplier]).to(result);
+/** Original numeric commit: application setters cannot overwrite remaining scratch ordinates. */
+export function writeResult(result: number[], x: number, y: number, z: number): number[] {
+  if (isArray(result)) {
+    result[0] = x;
+    result[1] = y;
+    result[2] = z;
+  } else {
+    const point = result as unknown as {x: number; y: number; z: number};
+    point.x = x;
+    point.y = y;
+    point.z = z;
+  }
+  return result;
 }

package/src/ellipsoid-tangent-plane.ts

@@ -1,6 +1,8 @@
 // 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.
 
 // 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

package/src/ellipsoid.ts

@@ -1,21 +1,30 @@
 // 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
 
 /* eslint-disable */
 import {Vector3, Matrix4, assert, equals, _MathUtils, NumericArray} from '@math.gl/core';
+import type {SpheroidParameters} from '@math.gl/types';
+import {
+  spheroidToCartesian,
+  cartesianToSpheroid,
+  type SpheroidGeometry
+} from '@math.gl/core/spheroid';
 import * as vec3 from '@math.gl/core/vec3';
 
 import {WGS84_RADIUS_X, WGS84_RADIUS_Y, WGS84_RADIUS_Z} from './constants';
-import {fromCartographicToRadians, toCartographicFromRadians} from './type-utils';
+import {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();
@@ -32,6 +41,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,6 +59,7 @@ 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);
@@ -77,9 +96,33 @@ export class Ellipsoid {
       this.squaredXOverSquaredZ = this.radiiSquared.x / this.radiiSquared.z;
     }
 
+    // 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 - this.radiiSquared.z / this.radiiSquared.x
+      });
     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));
@@ -98,6 +141,14 @@ export class Ellipsoid {
   cartographicToCartesian(cartographic: number[], result?: number[]): number[];
 
   cartographicToCartesian(cartographic: Readonly<NumericArray>, result = [0, 0, 0]) {
+    if (this.spheroidGeometry) {
+      const llh = fromCartographicToRadians(cartographic, scratchCartesian);
+      spheroidScratch.x = llh[0];
+      spheroidScratch.y = llh[1];
+      spheroidScratch.z = llh[2];
+      if (!spheroidToCartesian(spheroidScratch, this.spheroidGeometry)) return undefined;
+      return writeResult(result, spheroidScratch.x, spheroidScratch.y, spheroidScratch.z);
+    }
     const normal = scratchNormal;
     const k = scratchK;
 
@@ -123,7 +174,36 @@ 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;
+    // Shared inverse is qualified for the unambiguous surface/exterior domain.
+    // Interior/radial-fallback and non-spheroid behavior retain the Cesium kernel.
+    const a = this.radii.x,
+      b = this.radii.z;
+    const normSquared = (x / a) ** 2 + (y / a) ** 2 + (z / b) ** 2;
+    if (
+      this.spheroidGeometry &&
+      Number.isFinite(normSquared) &&
+      normSquared >= 1 - 16 * Number.EPSILON &&
+      Number.isFinite(x * x + y * y + z * z)
+    ) {
+      spheroidScratch.x = x;
+      spheroidScratch.y = y;
+      spheroidScratch.z = z;
+      if (!cartesianToSpheroid(spheroidScratch, this.spheroidGeometry)) return undefined;
+      // 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
+      );
+    }
+    scratchCartesian.set(x, y, z);
     const point = this.scaleToGeodeticSurface(scratchCartesian, scratchPosition);
 
     if (!point) {
@@ -136,10 +216,11 @@ export class Ellipsoid {
     h.copy(scratchCartesian).subtract(point);
 
     const longitude = Math.atan2(normal.y, normal.x);
-    const latitude = Math.asin(normal.z);
+    // atan2 retains latitude precision when the normal is almost vertical.
+    const latitude = Math.atan2(normal.z, Math.hypot(normal.x, normal.y));
     const height = Math.sign(vec3.dot(h, scratchCartesian)) * vec3.length(h);
 
-    return toCartographicFromRadians([longitude, latitude, height], result);
+    return toCartographicFromRadiansComponents(longitude, latitude, height, result);
   }
 
   /** Computes a 4x4 transformation matrix from a reference frame with an east-north-up axes
@@ -279,3 +360,9 @@ export class Ellipsoid {
     return scratchPosition.set(0.0, 0.0, z).to(result);
   }
 }
+
+// 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');
+}

package/src/index.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 export {Ellipsoid} from './ellipsoid';
 export {EllipsoidTangentPlane} from './ellipsoid-tangent-plane';
@@ -8,3 +8,5 @@ export {LngLatRectangle} from './lng-lat-rectangle';
 export {makeOBBFromRegion} from './make-obb-from-region';
 export type {GeodeticRegion, MakeOBBFromRegionOptions} from './make-obb-from-region';
 export {isWGS84} from './type-utils';
+
+export type {SpheroidParameters} from '@math.gl/types';

package/src/lng-lat-rectangle.ts

@@ -1,6 +1,8 @@
 // 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.
 
 // 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

package/src/make-obb-from-region.ts

@@ -1,6 +1,8 @@
 // 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.
 
 // 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

package/src/type-utils.ts

@@ -1,6 +1,8 @@
 // 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. 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
@@ -114,6 +116,32 @@ export function toCartographicFromRadians<T extends Cartographic>(
   return toCartographic(vector, cartographic, config._cartographicRadians ? identity : toDegrees);
 }
 
+/** Original numeric adapter: snapshot values before writing application-owned outputs. */
+export function toCartographicFromRadiansComponents<T extends Cartographic>(
+  longitude: number,
+  latitude: number,
+  height: number,
+  cartographic: T
+): T {
+  const map = config._cartographicRadians ? identity : toDegrees;
+  const mappedLongitude = map(longitude),
+    mappedLatitude = map(latitude);
+  if ('longitude' in cartographic) {
+    cartographic.longitude = mappedLongitude;
+    cartographic.latitude = mappedLatitude;
+    cartographic.height = height;
+  } else if ('x' in cartographic) {
+    cartographic.x = mappedLongitude;
+    cartographic.y = mappedLatitude;
+    cartographic.z = height;
+  } else {
+    cartographic[0] = mappedLongitude;
+    cartographic[1] = mappedLatitude;
+    cartographic[2] = height;
+  }
+  return cartographic;
+}
+
 export function toCartographicFromDegrees<T extends Cartographic>(
   vector: Readonly<NumericArray>,
   cartographic: T