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

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

@@ -2,15 +2,15 @@
 // 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.
+// SPDX-FileComment: Derived from Cesium. See the repository LICENSE for upstream attribution and Apache-2.0 terms. Original math.gl follow-up replaces radial/Newton approximation with a safeguarded nearest-point solve; retained commit adapter derives from Cesium.
 
 /* eslint-disable */
-import {Vector3, _MathUtils, isArray} from '@math.gl/core';
+import {isArray} from '@math.gl/core';
 import type {Ellipsoid} from '../ellipsoid';
 
-const scratchVector = new Vector3();
-const scaleToGeodeticSurfaceIntersection = new Vector3();
-const scaleToGeodeticSurfaceGradient = new Vector3();
+import {nearestSurface} from './nearest-surface';
+
+const surface = {x: 0, y: 0, z: 0};
 
 // Scales the provided Cartesian position along the geodetic surface normal
 // so that it is on the surface of this ellipsoid.  If the position is
@@ -20,109 +20,16 @@ export function scaleToGeodeticSurface(
   ellipsoid: Ellipsoid,
   result: number[] = []
 ): number[] {
-  const {oneOverRadii, oneOverRadiiSquared, centerToleranceSquared} = ellipsoid;
-
-  // 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;
-  const oneOverRadiiZ = oneOverRadii.z;
-
-  const x2 = positionX * positionX * oneOverRadiiX * oneOverRadiiX;
-  const y2 = positionY * positionY * oneOverRadiiY * oneOverRadiiY;
-  const z2 = positionZ * positionZ * oneOverRadiiZ * oneOverRadiiZ;
-
-  // Compute the squared ellipsoid norm.
-  const squaredNorm = x2 + y2 + z2;
-  const ratio = Math.sqrt(1.0 / squaredNorm);
-
-  // When very close to center or at center
-  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.set(positionX, positionY, positionZ).scale(ratio);
-
-  // If the position is near the center, the iteration will not converge.
-  if (squaredNorm < centerToleranceSquared) {
-    return writeResult(result, intersection.x, intersection.y, intersection.z);
-  }
-
-  const oneOverRadiiSquaredX = oneOverRadiiSquared.x;
-  const oneOverRadiiSquaredY = oneOverRadiiSquared.y;
-  const oneOverRadiiSquaredZ = oneOverRadiiSquared.z;
-
-  // Use the gradient at the intersection point in place of the true unit normal.
-  // The difference in magnitude will be absorbed in the multiplier.
-  const gradient = scaleToGeodeticSurfaceGradient;
-  gradient.set(
-    intersection.x * oneOverRadiiSquaredX * 2.0,
-    intersection.y * oneOverRadiiSquaredY * 2.0,
-    intersection.z * oneOverRadiiSquaredZ * 2.0
-  );
-
-  // Compute the initial guess at the normal vector multiplier, lambda.
-  let lambda = ((1.0 - ratio) * scratchVector.len()) / (0.5 * gradient.len());
-  let correction = 0.0;
-
-  let xMultiplier;
-  let yMultiplier;
-  let zMultiplier;
-  let func;
-
-  // 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);
-    yMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredY);
-    zMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredZ);
-
-    const xMultiplier2 = xMultiplier * xMultiplier;
-    const yMultiplier2 = yMultiplier * yMultiplier;
-    const zMultiplier2 = zMultiplier * zMultiplier;
-
-    const xMultiplier3 = xMultiplier2 * xMultiplier;
-    const yMultiplier3 = yMultiplier2 * yMultiplier;
-    const zMultiplier3 = zMultiplier2 * zMultiplier;
-
-    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 =
-      x2 * xMultiplier3 * oneOverRadiiSquaredX +
-      y2 * yMultiplier3 * oneOverRadiiSquaredY +
-      z2 * zMultiplier3 * oneOverRadiiSquaredZ;
-
-    const derivative = -2.0 * denominator;
-
-    if (!Number.isFinite(derivative) || derivative === 0) return undefined;
-    correction = func / derivative;
-    if (!Number.isFinite(correction)) return undefined;
-  }
-  return undefined;
+  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;
+  // Keep the public adapter's established finite squared-coordinate domain.
+  if (!Number.isFinite(x * x + y * y + z * z)) return undefined;
+  const {radii} = ellipsoid;
+  if (!nearestSurface(x, y, z, radii.x, radii.y, radii.z, surface)) return undefined;
+  return writeResult(result, surface.x, surface.y, surface.z);
 }
 
 /** Original numeric commit: application setters cannot overwrite remaining scratch ordinates. */

package/src/ellipsoid-helpers/surface-polygon.ts

@@ -0,0 +1,210 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) Charles Karney (2010-2023)
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Area reduction and meridian transit rules adapted from GeographicLib 2.7 PolygonArea.cpp (MIT). Typed accumulation/preview facade uses the existing attributed GeographicLib accumulator. See ../../GEOGRAPHICLIB-LICENSE.txt.
+import {geodesic} from '../vendor/geographiclib-geodesic/runtime';
+
+export type SurfacePolygonOptions = {
+  /** Clockwise positive instead of counterclockwise positive. */
+  reverse?: boolean;
+  /** Return [0, surfaceArea) instead of (-surfaceArea/2, surfaceArea/2]. */
+  unsigned?: boolean;
+};
+export type SurfacePolygonResult = {number: number; perimeter: number; area?: number};
+export type SurfacePointOptions = {longitudeTurns?: number};
+export interface SurfacePolygonSolver {
+  readonly surfaceArea: number;
+  inverse(
+    a: number,
+    b: number,
+    c: number,
+    d: number,
+    options?: {area?: boolean; unrollLongitude?: boolean; longitudeTurns?: number}
+  ): {s12: number; S12?: number; lon2: number};
+  direct(
+    a: number,
+    b: number,
+    c: number,
+    d: number,
+    options?: {area?: boolean; unrollLongitude?: boolean}
+  ): {lat2: number; lon2: number; S12?: number};
+}
+interface Sum {
+  Add(value: number): void;
+  Sum(value?: number): number;
+  Negate(): void;
+  Remainder(value: number): void;
+}
+const Accumulator = geodesic.Accumulator.Accumulator as unknown as new (
+  value?: number | Sum
+) => Sum;
+const math = geodesic.Math as unknown as {
+  AngNormalize(value: number): number;
+  AngDiff(a: number, b: number): {d: number; e: number};
+};
+
+/** Streaming geodesic polygon or open polyline. Point arguments are latitude,
+ * longitude in degrees. Edge lengths use axis units and may be negative.
+ * Self-intersections contribute algebraic area; no vertex list is retained.
+ */
+export class SurfacePolygon {
+  private readonly geodesic: SurfacePolygonSolver;
+  readonly polyline: boolean;
+  private readonly area0: number;
+  private count = 0;
+  private firstLat = 0;
+  private firstLon = 0;
+  private lastLat = 0;
+  private lastLon = 0;
+  private crossings = 0;
+  private perimeter = new Accumulator();
+  private area = new Accumulator();
+
+  constructor(solver: SurfacePolygonSolver, options: {polyline?: boolean} = {}) {
+    this.geodesic = solver;
+    this.polyline = Boolean(options.polyline);
+    this.area0 = this.geodesic.surfaceArea;
+    if (!(Number.isFinite(this.area0) && this.area0 > 0)) {
+      throw new Error('Polygon area exceeds representable range');
+    }
+  }
+
+  get number(): number {
+    return this.count;
+  }
+
+  clear(): this {
+    this.count = this.crossings = 0;
+    this.firstLat = this.firstLon = this.lastLat = this.lastLon = 0;
+    this.perimeter = new Accumulator();
+    this.area = new Accumulator();
+    return this;
+  }
+
+  addPoint(latitude: number, longitude: number, options: SurfacePointOptions = {}): this {
+    if (!(Number.isFinite(latitude) && Math.abs(latitude) <= 90 && Number.isFinite(longitude))) {
+      throw new Error('Polygon point requires finite longitude and latitude in [-90, 90]');
+    }
+    if (this.count) {
+      const edge = this.geodesic.inverse(this.lastLat, this.lastLon, latitude, longitude, {
+        area: !this.polyline,
+        longitudeTurns: options.longitudeTurns,
+        unrollLongitude: Boolean(options.longitudeTurns)
+      });
+      this.accumulate(edge.s12, this.polyline ? 0 : edge.S12!);
+      if (!this.polyline) {
+        this.crossings =
+          (this.crossings +
+            (options.longitudeTurns
+              ? transitDirect(this.lastLon, edge.lon2)
+              : transit(this.lastLon, longitude))) %
+          2;
+      }
+    } else {
+      this.firstLat = latitude;
+      this.firstLon = longitude;
+    }
+    this.lastLat = latitude;
+    this.lastLon = longitude;
+    ++this.count;
+    return this;
+  }
+
+  addEdge(azimuth: number, distance: number): this {
+    if (!this.count) throw new Error('Add a starting point before adding an edge');
+    const edge = this.geodesic.direct(this.lastLat, this.lastLon, azimuth, distance, {
+      area: !this.polyline,
+      unrollLongitude: true
+    });
+    if (!(Number.isFinite(edge.lat2) && Number.isFinite(edge.lon2)))
+      throw new Error('Unrepresentable geodesic edge');
+    this.accumulate(distance, this.polyline ? 0 : edge.S12!);
+    if (!this.polyline) {
+      this.crossings = (this.crossings + transitDirect(this.lastLon, edge.lon2)) % 2;
+    }
+    this.lastLat = edge.lat2;
+    this.lastLon = edge.lon2;
+    ++this.count;
+    return this;
+  }
+
+  compute(options: SurfacePolygonOptions = {}): SurfacePolygonResult {
+    if (this.count < 2)
+      return this.polyline
+        ? {number: this.count, perimeter: 0}
+        : {number: this.count, perimeter: 0, area: 0};
+    if (this.polyline) return {number: this.count, perimeter: this.perimeter.Sum()};
+    const edge = this.geodesic.inverse(this.lastLat, this.lastLon, this.firstLat, this.firstLon, {
+      area: true
+    });
+    const total = new Accumulator(this.area);
+    total.Add(edge.S12!);
+    const area0 = this.area0;
+    total.Remainder(area0);
+    if ((this.crossings + transit(this.lastLon, this.firstLon)) % 2 !== 0) {
+      total.Add(((total.Sum() < 0 ? 1 : -1) * area0) / 2);
+    }
+    if (!options.reverse) total.Negate();
+    if (options.unsigned) {
+      if (total.Sum() >= area0) total.Add(-area0);
+      else if (total.Sum() < 0) total.Add(area0);
+    } else {
+      if (total.Sum() > area0 / 2) total.Add(-area0);
+      else if (total.Sum() <= -area0 / 2) total.Add(area0);
+    }
+    return {number: this.count, perimeter: this.perimeter.Sum(edge.s12), area: 0 + total.Sum()};
+  }
+
+  /** Nonmutating preview, with the same compensated arithmetic as insertion. */
+  testPoint(
+    latitude: number,
+    longitude: number,
+    options: SurfacePolygonOptions & SurfacePointOptions = {}
+  ): SurfacePolygonResult {
+    return this.copy().addPoint(latitude, longitude, options).compute(options);
+  }
+
+  testEdge(
+    azimuth: number,
+    distance: number,
+    options: SurfacePolygonOptions = {}
+  ): SurfacePolygonResult {
+    return this.copy().addEdge(azimuth, distance).compute(options);
+  }
+
+  private accumulate(distance: number, area: number): void {
+    if (
+      ![distance, area, this.perimeter.Sum(distance), this.area.Sum(area)].every(Number.isFinite)
+    ) {
+      throw new Error('Unrepresentable geodesic sum');
+    }
+    this.perimeter.Add(distance);
+    if (!this.polyline) this.area.Add(area);
+  }
+
+  private copy(): SurfacePolygon {
+    // No engine setup or vertex replay for previews.
+    const copy = Object.create(Object.getPrototypeOf(this)) as SurfacePolygon;
+    Object.assign(copy, this);
+    copy.perimeter = new Accumulator(this.perimeter);
+    copy.area = new Accumulator(this.area);
+    return copy;
+  }
+}
+
+function transit(a: number, b: number): number {
+  const delta = math.AngDiff(a, b).d;
+  a = math.AngNormalize(a);
+  b = math.AngNormalize(b);
+  return delta > 0 && ((a < 0 && b >= 0) || (a > 0 && b === 0))
+    ? 1
+    : delta < 0 && a >= 0 && b < 0
+      ? -1
+      : 0;
+}
+function transitDirect(a: number, b: number): number {
+  a %= 720;
+  b %= 720;
+  return ((b >= 0 && b < 360) || b < -360 ? 0 : 1) - ((a >= 0 && a < 360) || a < -360 ? 0 : 1);
+}

package/src/ellipsoid-helpers/tangent-plane-numerics.ts

@@ -0,0 +1,124 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original compensated binary64 products for tangent contacts; no upstream code copied.
+import type {NumericArray} from '@math.gl/core/types';
+import {ratio} from './exact-nearest-surface';
+const SPLITTER = 134217729;
+function productError(a: number, b: number, product: number): number {
+  const ca = SPLITTER * a,
+    cb = SPLITTER * b;
+  const ah = ca - (ca - a),
+    al = a - ah;
+  const bh = cb - (cb - b),
+    bl = b - bh;
+  return ah * bh - product + ah * bl + al * bh + al * bl;
+}
+function sumError(a: number, b: number, sum: number): number {
+  const v = sum - a;
+  return a - (sum - v) + (b - v);
+}
+/** Exact power-of-two scaling keeps products finite without rounding ratios. */
+function binaryScale(value: number): number {
+  return 2 ** Math.min(1023, Math.floor(Math.log2(value)));
+}
+export function compensatedDot3(
+  x: number,
+  y: number,
+  z: number,
+  a: number,
+  b: number,
+  c: number
+): number {
+  const magnitude = Math.max(Math.abs(x), Math.abs(y), Math.abs(z));
+  if (magnitude === 0) return 0;
+  const scale = binaryScale(magnitude);
+  const sx = x / scale,
+    sy = y / scale,
+    sz = z / scale;
+  const p = sx * a,
+    q = sy * b,
+    r = sz * c;
+  const s = p + q,
+    t = s + r;
+  return (
+    (t +
+      (sumError(p, q, s) +
+        sumError(s, r, t) +
+        productError(sx, a, p) +
+        productError(sy, b, q) +
+        productError(sz, c, r))) *
+    scale
+  );
+}
+/** Rare exact-sign fallback for a normal line near an ellipsoid silhouette.
+ * The stored binary64 origin/basis and local coordinates define the affine line.
+ */
+export function exactNormalIntersection(
+  radii: readonly number[],
+  origin: readonly number[],
+  east: readonly number[],
+  north: readonly number[],
+  normal: readonly number[],
+  point: Readonly<NumericArray>,
+  sphereRadius?: number
+): number[] | undefined {
+  const values = sphereRadius
+    ? [
+        sphereRadius,
+        sphereRadius,
+        sphereRadius,
+        sphereRadius,
+        0,
+        0,
+        0,
+        1,
+        0,
+        0,
+        0,
+        1,
+        1,
+        0,
+        0,
+        point[0],
+        point[1]
+      ]
+    : [...radii, ...origin, ...east, ...north, ...normal, ...point];
+  const v = values.map(value => {
+    const [whole, fraction = ''] = Math.abs(value).toString(2).split('.');
+    return (
+      ((value < 0 ? -1n : 1n) * BigInt('0b' + whole + fraction)) << BigInt(1074 - fraction.length)
+    );
+  });
+  const unit = 1n << 1074n,
+    q = 1n << 64n;
+  const factors = [v[1] * v[2], v[0] * v[2], v[0] * v[1]];
+  const p = [0, 1, 2].map(
+    i => (v[3 + i] * unit + v[6 + i] * v[15] + v[9 + i] * v[16]) * factors[i]
+  );
+  const n = v.slice(12, 15).map((x, i) => x * factors[i]);
+  const dot = (x: bigint[], y: bigint[]) => x.reduce((s, v, i) => s + v * y[i], 0n);
+  const a = dot(n, n),
+    b = dot(n, p),
+    c = dot(p, p) - (v[0] * v[1] * v[2] * unit) ** 2n;
+  const discriminant = b * b - a * c;
+  if (a === 0n || discriminant < 0n) return undefined;
+  const value = discriminant << 128n;
+  let root = value === 0n ? 0n : 1n << BigInt(Math.ceil(value.toString(2).length / 2));
+  if (root)
+    for (;;) {
+      const next = (root + value / root) >> 1n;
+      if (next >= root) break;
+      root = next;
+    }
+  const output = p.map((x, i) =>
+    signedRatio(x * a * q + n[i] * (root - b * q), a * q * factors[i])
+  );
+  return sphereRadius
+    ? output.map((_, i) => east[i] * output[1] + north[i] * output[2] + normal[i] * output[0])
+    : output;
+}
+
+function signedRatio(n: bigint, d: bigint): number {
+  return Math.sign(Number(n)) * ratio(n < 0n ? -n : n, d, -2148);
+}

package/src/ellipsoid-metrics.ts

@@ -0,0 +1,225 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original quadrature-based implementation of revolution-ellipsoid integrals; independently compared with GeographicLib 2.7 (Charles Karney, MIT). See ../GEOGRAPHICLIB-LICENSE.txt.
+import type {GeodesicParameters} from './ellipsoid-geodesic';
+
+/** All latitude values are degrees, including isometric latitude (radians * 180/pi). */
+export type AuxiliaryLatitude =
+  | 'geocentric'
+  | 'parametric'
+  | 'rectifying'
+  | 'authalic'
+  | 'conformal'
+  | 'isometric';
+
+const DEG = Math.PI / 180;
+// Positive half of the 16-point Gauss-Legendre rule.
+const NODES = [
+  0.09501250983763744, 0.2816035507792589, 0.4580167776572274, 0.6178762444026438,
+  0.755404408355003, 0.8656312023878318, 0.9445750230732326, 0.9894009349916499
+];
+const WEIGHTS = [
+  0.1894506104550685, 0.1826034150449236, 0.16915651939500254, 0.14959598881657673,
+  0.12462897125553388, 0.09515851168249279, 0.06225352393864789, 0.027152459411754095
+];
+const KINDS: readonly string[] = [
+  'geocentric',
+  'parametric',
+  'rectifying',
+  'authalic',
+  'conformal',
+  'isometric'
+];
+
+/** Metrics on a revolution ellipsoid. Qualified for 0.5 <= b/a <= 2.
+ * Axes use caller length units; areas/volumes use their square/cube.
+ * Separate from Ellipsoid so Cartesian and projection users pay no bundle cost.
+ */
+export class EllipsoidMetrics {
+  readonly semiMajorAxis: number;
+  readonly semiMinorAxis: number;
+  readonly surfaceArea: number;
+  readonly volume: number;
+  readonly quarterMeridian: number;
+  private readonly ratio: number;
+  private readonly e2: number;
+  private readonly qPole: number;
+  private readonly quarter: number;
+
+  constructor({semiMajorAxis: a, semiMinorAxis: b}: GeodesicParameters) {
+    const r = b / a;
+    if (!(Number.isFinite(a) && Number.isFinite(b) && a > 0 && b > 0 && r >= 0.5 && r <= 2)) {
+      throw new Error('Ellipsoid metrics require finite positive axes with 0.5 <= b/a <= 2');
+    }
+    this.semiMajorAxis = a;
+    this.semiMinorAxis = b;
+    this.ratio = r;
+    this.e2 = (1 - r) * (1 + r);
+    this.qPole = 1 + r * r * this.eccentricIntegral(1);
+    this.quarter = integrate(t => this.meridianIntegrand(t), 0, Math.PI / 2);
+    this.quarterMeridian = a * this.quarter;
+    this.surfaceArea = 2 * Math.PI * a * a * this.qPole;
+    this.volume = ((4 * Math.PI) / 3) * a * b * a;
+    if (
+      ![this.quarterMeridian, this.surfaceArea, this.volume].every(v => Number.isFinite(v) && v > 0)
+    ) {
+      throw new Error('Ellipsoid metrics exceed representable length/area/volume range');
+    }
+    Object.freeze(this);
+  }
+
+  meridianDistance(latitude: number): number {
+    validateLatitude(latitude);
+    return Math.sign(latitude) * this.semiMajorAxis * this.meridian(Math.abs(latitude));
+  }
+
+  meridionalCurvatureRadius(latitude: number): number {
+    validateLatitude(latitude);
+    return this.semiMajorAxis * this.meridianIntegrand(latitude * DEG);
+  }
+
+  transverseCurvatureRadius(latitude: number): number {
+    validateLatitude(latitude);
+    const [s, c] = sincos(latitude);
+    return this.semiMajorAxis / Math.hypot(c, this.ratio * s);
+  }
+
+  normalCurvatureRadius(latitude: number, azimuth: number): number {
+    if (!Number.isFinite(azimuth)) throw new Error('Azimuth must be finite');
+    const [s, c] = sincos(azimuth % 180);
+    return (
+      1 /
+      ((c * c) / this.meridionalCurvatureRadius(latitude) +
+        (s * s) / this.transverseCurvatureRadius(latitude))
+    );
+  }
+
+  latitudeToAuxiliary(latitude: number, kind: AuxiliaryLatitude): number {
+    validateKind(kind);
+    validateLatitude(latitude);
+    if (latitude === 0) return latitude;
+    if (Math.abs(latitude) === 90)
+      return kind === 'isometric' ? Math.sign(latitude) * Infinity : latitude;
+    if (this.ratio === 1 && kind !== 'isometric') return latitude;
+    const sign = Math.sign(latitude);
+    const phi = Math.abs(latitude);
+    const [s, c] = sincos(phi);
+    switch (kind) {
+      case 'geocentric':
+        return sign * angle(this.ratio * this.ratio * s, c);
+      case 'parametric':
+        return sign * angle(this.ratio * s, c);
+      case 'rectifying':
+        return (
+          sign *
+          (phi <= 45
+            ? (this.meridian(phi) / this.quarter) * 90
+            : 90 -
+              (integrate(t => this.meridianIntegrand(Math.PI / 2 - t), 0, (90 - phi) * DEG) /
+                this.quarter) *
+                90)
+        );
+      case 'authalic': {
+        if (phi <= 45) {
+          const q =
+            this.ratio ** 2 * (s / (c * c + (this.ratio * s) ** 2) + this.eccentricIntegral(s));
+          return (sign * Math.asin(q / this.qPole)) / DEG;
+        }
+        const cap = integrate(
+          t => {
+            const st = Math.sin(t),
+              ct = Math.cos(t);
+            const d = st * st + (this.ratio * ct) ** 2;
+            return (2 * this.ratio ** 2 * st) / (d * d);
+          },
+          0,
+          (90 - phi) * DEG
+        );
+        return sign * (90 - (2 * Math.asin(Math.sqrt(cap / (2 * this.qPole)))) / DEG);
+      }
+      default: {
+        const psi = Math.asinh(s / c) - this.e2 * this.eccentricIntegral(s);
+        return (
+          sign *
+          (kind === 'isometric'
+            ? psi / DEG
+            : psi < 1
+              ? Math.atan(Math.sinh(psi)) / DEG
+              : 90 - (2 * Math.atan(Math.exp(-psi))) / DEG)
+        );
+      }
+    }
+  }
+
+  latitudeFromAuxiliary(latitude: number, kind: AuxiliaryLatitude): number {
+    validateKind(kind);
+    if (kind === 'isometric' && Math.abs(latitude) === Infinity) return Math.sign(latitude) * 90;
+    if (kind !== 'isometric') validateLatitude(latitude);
+    else if (!Number.isFinite(latitude))
+      throw new Error('Isometric latitude must be finite or a pole infinity');
+    if (latitude === 0) return latitude;
+    if (kind !== 'isometric' && Math.abs(latitude) === 90) return latitude;
+    if (this.ratio === 1 && kind !== 'isometric') return latitude;
+    const sign = Math.sign(latitude),
+      target = Math.abs(latitude);
+    if (kind === 'geocentric' || kind === 'parametric') {
+      const [s, c] = sincos(target);
+      return sign * angle(s, c * (kind === 'geocentric' ? this.ratio ** 2 : this.ratio));
+    }
+    // Monotonic, bounded solve in degrees; preserves input complements near poles.
+    let lo = 0,
+      hi = 90;
+    for (let i = 0; i < 64; ++i) {
+      const mid = (lo + hi) / 2;
+      if (mid === lo || mid === hi) break;
+      if (this.latitudeToAuxiliary(mid, kind) < target) lo = mid;
+      else hi = mid;
+    }
+    return sign * ((lo + hi) / 2);
+  }
+
+  private eccentricIntegral(s: number): number {
+    const e = Math.sqrt(Math.abs(this.e2));
+    return e === 0 ? s : (this.e2 > 0 ? Math.atanh(e * s) : Math.atan(e * s)) / e;
+  }
+
+  private meridianIntegrand(t: number): number {
+    return this.ratio ** 2 / Math.hypot(Math.cos(t), this.ratio * Math.sin(t)) ** 3;
+  }
+
+  private meridian(phi: number): number {
+    return phi <= 45
+      ? integrate(t => this.meridianIntegrand(t), 0, phi * DEG)
+      : this.quarter - integrate(t => this.meridianIntegrand(Math.PI / 2 - t), 0, (90 - phi) * DEG);
+  }
+}
+
+function validateLatitude(value: number): void {
+  if (!(Number.isFinite(value) && Math.abs(value) <= 90))
+    throw new Error('Latitude must be in [-90, 90] degrees');
+}
+function validateKind(kind: AuxiliaryLatitude): void {
+  if (!KINDS.includes(kind)) throw new Error('Unknown auxiliary latitude');
+}
+function sincos(degrees: number): [number, number] {
+  const a = Math.abs(degrees);
+  if (a <= 45) return [Math.sin(degrees * DEG), Math.cos(degrees * DEG)];
+  return [Math.sign(degrees) * Math.cos((90 - a) * DEG), Math.sin((90 - a) * DEG)];
+}
+function angle(s: number, c: number): number {
+  return s > c ? 90 - Math.atan2(c, s) / DEG : Math.atan2(s, c) / DEG;
+}
+/** @internal Shared bounded quadrature for original revolution integrals. */
+export function integrate(f: (t: number) => number, lo: number, hi: number): number {
+  let sum = 0;
+  for (let j = 0; j < 8; ++j) {
+    const h = (hi - lo) / 16,
+      mid = lo + (2 * j + 1) * h;
+    let part = 0;
+    for (let i = 0; i < 8; ++i)
+      part += WEIGHTS[i] * (f(mid - h * NODES[i]) + f(mid + h * NODES[i]));
+    sum += h * part;
+  }
+  return sum;
+}