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

package/src/ellipsoid-geodesic.ts

@@ -0,0 +1,170 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original typed facade over the separately attributed GeographicLib geodesic solver. See ../GEOGRAPHICLIB-LICENSE.txt.
+import {geodesic} from './vendor/geographiclib-geodesic/runtime';
+
+/** Two-axis revolution geometry. For compatibility, semiMajorAxis means the
+ * equatorial radius a and semiMinorAxis the polar radius b, also when b > a.
+ */
+export type GeodesicParameters = {readonly semiMajorAxis: number; readonly semiMinorAxis: number};
+
+export type GeodesicOptions = {
+  /** Preserve longitude winding rather than normalizing to [-180, 180]. */
+  unrollLongitude?: boolean;
+  /** Include the signed geodesic edge area S12 in squared axis units. */
+  area?: boolean;
+};
+
+/** Angles and azimuths are degrees; distances and reduced lengths use the axes' units. */
+export type GeodesicResult = {
+  lat1: number;
+  lon1: number;
+  lat2: number;
+  lon2: number;
+  azi1: number;
+  azi2: number;
+  s12: number;
+  m12: number;
+  M12: number;
+  M21: number;
+  a12: number;
+  S12?: number;
+};
+
+interface EngineLine {
+  GenPosition(
+    arc: boolean,
+    distance: number,
+    mask: number,
+    output?: GeodesicResult
+  ): GeodesicResult;
+  Position(distance: number, mask: number): GeodesicResult;
+  ArcPosition(arc: number, mask: number): GeodesicResult;
+}
+interface Engine {
+  _c2: number;
+  Inverse(lat1: number, lon1: number, lat2: number, lon2: number, mask: number): GeodesicResult;
+  Line(latitude: number, longitude: number, azimuth: number, caps: number): EngineLine;
+}
+interface Namespace {
+  Geodesic: new (a: number, f: number) => Engine;
+  AREA: number;
+  ALL: number;
+  DISTANCE_IN: number;
+  LONG_UNROLL: number;
+}
+const library = geodesic.Geodesic as unknown as Namespace;
+
+/** A geodesic with a fixed starting point and initial azimuth. */
+export interface GeodesicLine {
+  position(distance: number): GeodesicResult;
+  arcPosition(arc: number): GeodesicResult;
+}
+
+/** Geodesics on an oblate or prolate ellipsoid of revolution, or sphere, using Karney's series solver.
+ * This class snapshots the axes. It does not accept triaxial ellipsoids or infer a CRS.
+ */
+export class EllipsoidGeodesic {
+  private readonly engine: Engine;
+
+  constructor({semiMajorAxis: a, semiMinorAxis: b}: GeodesicParameters) {
+    this.engine = createGeodesicEngine({semiMajorAxis: a, semiMinorAxis: b});
+  }
+
+  /** Total area in squared axis units, with the same normalization as S12. */
+  get surfaceArea(): number {
+    return 4 * Math.PI * this.engine._c2;
+  }
+
+  inverse(
+    lat1: number,
+    lon1: number,
+    lat2: number,
+    lon2: number,
+    options: GeodesicOptions = {}
+  ): GeodesicResult {
+    validatePoint(lat1, lon1);
+    validatePoint(lat2, lon2);
+    return this.engine.Inverse(lat1, lon1, lat2, lon2, outputMask(options));
+  }
+
+  direct(
+    latitude: number,
+    longitude: number,
+    azimuth: number,
+    distance: number,
+    options: GeodesicOptions = {}
+  ): GeodesicResult {
+    return this.line(latitude, longitude, azimuth, options).position(distance);
+  }
+
+  arcDirect(
+    latitude: number,
+    longitude: number,
+    azimuth: number,
+    arc: number,
+    options: GeodesicOptions = {}
+  ): GeodesicResult {
+    return this.line(latitude, longitude, azimuth, options).arcPosition(arc);
+  }
+
+  line(
+    latitude: number,
+    longitude: number,
+    azimuth: number,
+    options: GeodesicOptions = {}
+  ): GeodesicLine {
+    validatePoint(latitude, longitude);
+    validateFinite(azimuth);
+    const selectedMask = outputMask(options);
+    const line = this.engine.Line(latitude, longitude, azimuth, selectedMask | library.DISTANCE_IN);
+    return {
+      // Fourth argument is an internal result request; ordinary Array.map arguments remain ignored.
+      position(
+        distance: number,
+        _index?: unknown,
+        _array?: unknown,
+        output?: GeodesicResult
+      ): GeodesicResult {
+        validateFinite(distance);
+        return line.GenPosition(false, distance, selectedMask, output);
+      },
+      arcPosition(arc: number): GeodesicResult {
+        validateFinite(arc);
+        return line.ArcPosition(arc, selectedMask);
+      }
+    };
+  }
+}
+
+function validatePoint(latitude: number, longitude: number): void {
+  if (!(Number.isFinite(latitude) && Math.abs(latitude) <= 90 && Number.isFinite(longitude))) {
+    throw new Error('Invalid geodesic coordinates');
+  }
+}
+
+function outputMask(options: GeodesicOptions): number {
+  return (
+    (library.ALL & ~(options.area ? 0 : library.AREA)) |
+    (options.unrollLongitude ? library.LONG_UNROLL : 0)
+  );
+}
+
+function validateFinite(value: number): void {
+  if (!Number.isFinite(value)) throw new Error('Nonfinite axis, azimuth, distance or arc');
+}
+
+/** @internal Shared engine and non-area mask for projections. Keeping the raw
+ * kernel separate lets projection bundles discard the public optional facade.
+ */
+export const nonAreaGeodesicMask = library.ALL & ~library.AREA;
+export function createGeodesicEngine({
+  semiMajorAxis: a,
+  semiMinorAxis: b
+}: GeodesicParameters): Engine {
+  validateFinite(a);
+  validateFinite(b);
+  // The engine validates positivity of both derived axes.
+  return new library.Geodesic(a, (a - b) / a);
+}

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

@@ -1,15 +1,23 @@
 // math.gl
-// SPDX-License-Identifier: MIT and Apache-2.0
-// Copyright (c) vis.gl contributors
-
-import {NumericArray} from '@math.gl/types';
-import {Vector3, assert, equals as equalsEpsilon} from '@math.gl/core';
+// 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. Scaled east normalization and the small-unit pole neighborhood are original math.gl fixes.
+
+import {NumericArray} from '@math.gl/core';
+import {Vector3, assert} from '@math.gl/core';
+import {
+  createLocalFrameBasis,
+  eastNorthUpBasisFromDirections,
+  localFrameToMatrix
+} from '@math.gl/core';
 
 import type {Ellipsoid} from '../ellipsoid';
 
 const EPSILON14 = 1e-14;
 
 const scratchOrigin = new Vector3();
+const scratchBasis = createLocalFrameBasis();
 
 export type AxisDirection = 'up' | 'down' | 'north' | 'east' | 'south' | 'west';
 
@@ -101,7 +109,44 @@ export function localFrameToFixedFrame(
   const origin = scratchOrigin.copy(cartesianOrigin);
 
   // If x and y are zero, assume origin is at a pole, which is a special case.
-  const atPole = equalsEpsilon(origin.x, 0.0, EPSILON14) && equalsEpsilon(origin.y, 0.0, EPSILON14);
+  if (
+    !Number.isFinite(origin.x) ||
+    !Number.isFinite(origin.y) ||
+    !Number.isFinite(origin.z) ||
+    (!Array.isArray(result) && (result as NumericArray).length < 16)
+  )
+    throw new Error('Unsupported local frame');
+  // Retain the legacy orientation neighborhood for ordinary units, but never
+  // classify an entire tiny ellipsoid as a pole merely because of its unit.
+  const poleTolerance = EPSILON14 * Math.min(1, ellipsoid.maximumRadius);
+  const atPole = Math.abs(origin.x) <= poleTolerance && Math.abs(origin.y) <= poleTolerance;
+
+  // Only the qualified sphere/oblate basis is shared. Three-radius and center
+  // conventions keep the retained Cesium path, without changing its normal choice.
+  const radii = ellipsoid.radii;
+  if (
+    radii.x === radii.y &&
+    radii.x > 0 &&
+    radii.z > 0 &&
+    radii.z <= radii.x &&
+    (!atPole || origin.z !== 0)
+  ) {
+    const {east, up} = scratchAxisVectors;
+    if (atPole) {
+      east.set(0, 1, 0);
+      up.set(0, 0, Math.sign(origin.z));
+    } else {
+      const scale = Math.max(Math.abs(origin.x), Math.abs(origin.y));
+      east.set(-origin.y / scale, origin.x / scale, 0).normalize();
+      ellipsoid.geodeticSurfaceNormal(origin, up);
+    }
+    if (
+      !eastNorthUpBasisFromDirections(east, up, scratchBasis) ||
+      !localFrameToMatrix(scratchBasis, origin, firstAxis, secondAxis, thirdAxis, result)
+    )
+      throw new Error('Unsupported local frame');
+    return result;
+  }
 
   if (atPole) {
     // Look up axis value and adjust
@@ -125,7 +170,8 @@ export function localFrameToFixedFrame(
     // Calculate all axis
     const {up, east, north} = scratchAxisVectors;
 
-    east.set(-origin.y, origin.x, 0.0).normalize();
+    const scale = Math.max(Math.abs(origin.x), Math.abs(origin.y));
+    east.set(-origin.y / scale, origin.x / scale, 0).normalize();
     ellipsoid.geodeticSurfaceNormal(origin, up);
     north.copy(up).cross(east);
 
@@ -141,22 +187,35 @@ export function localFrameToFixedFrame(
     thirdAxisVector = scratchAxisVectors[thirdAxis];
   }
 
-  // TODO - assuming the result is column-major
-  result[0] = firstAxisVector.x;
-  result[1] = firstAxisVector.y;
-  result[2] = firstAxisVector.z;
+  // Snapshot the retained three-radius/center path too: application result setters
+  // can recursively invoke either path and overwrite all module scratch vectors.
+  const ax = firstAxisVector.x,
+    ay = firstAxisVector.y,
+    az = firstAxisVector.z;
+  const bx = secondAxisVector.x,
+    by = secondAxisVector.y,
+    bz = secondAxisVector.z;
+  const cx = thirdAxisVector.x,
+    cy = thirdAxisVector.y,
+    cz = thirdAxisVector.z;
+  const x = origin.x,
+    y = origin.y,
+    z = origin.z;
+  result[0] = ax;
+  result[1] = ay;
+  result[2] = az;
   result[3] = 0.0;
-  result[4] = secondAxisVector.x;
-  result[5] = secondAxisVector.y;
-  result[6] = secondAxisVector.z;
+  result[4] = bx;
+  result[5] = by;
+  result[6] = bz;
   result[7] = 0.0;
-  result[8] = thirdAxisVector.x;
-  result[9] = thirdAxisVector.y;
-  result[10] = thirdAxisVector.z;
+  result[8] = cx;
+  result[9] = cy;
+  result[10] = cz;
   result[11] = 0.0;
-  result[12] = origin.x;
-  result[13] = origin.y;
-  result[14] = origin.z;
+  result[12] = x;
+  result[13] = y;
+  result[14] = z;
   result[15] = 1.0;
   return result;
 }

package/src/ellipsoid-helpers/exact-nearest-surface.ts

@@ -0,0 +1,118 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original exact-dyadic fallback for ill-conditioned nearest-point geometry; no upstream code.
+
+/** Rare fallback: exact signs of the multiplier equation, not arbitrary precision
+ * transcendental arithmetic. BigInt/string allocations are confined to this path.
+ * Input dyadics share a unit; t uses at least 64 fraction bits. For a nonzero
+ * shortest-axis coordinate the root is at least one squared input unit, so this
+ * resolves its relative bracket to substantially better than binary64 precision.
+ */
+export function exactNearestSurface(
+  x: number,
+  y: number,
+  z: number,
+  a: number,
+  b: number,
+  c: number,
+  result: {x: number; y: number; z: number}
+): boolean {
+  const values = [a, b, c, Math.abs(x), Math.abs(y), Math.abs(z)];
+  const parts = values.map(value => {
+    const bits = value.toString(2);
+    const dot = bits.indexOf('.');
+    return {
+      integer: BigInt('0b' + bits.replace('.', '')),
+      exponent: dot < 0 ? 0 : dot + 1 - bits.length
+    };
+  });
+  const exponent = Math.min(...parts.filter(p => p.integer !== 0n).map(p => p.exponent));
+  const integers = parts.map(p => p.integer << BigInt(p.exponent - exponent));
+  const squares = integers.slice(0, 3).map(v => v * v);
+  const minimum = squares.reduce((p, v) => (p < v ? p : v));
+  const offsets = squares.map(v => v - minimum);
+  const products = squares.map((_, i) => integers[i] * integers[i + 3]);
+  let precision = 64;
+  if (!products.some((u, i) => offsets[i] === 0n && u !== 0n)) {
+    // Exact boundary classification. Negative means multiple minima; equality
+    // means the unique cusp point has zero shortest-axis coordinates.
+    let numerator = -1n,
+      denominator = 1n;
+    for (let i = 0; i < 3; i++) {
+      if (offsets[i] === 0n) continue;
+      const d2 = offsets[i] * offsets[i];
+      numerator = numerator * d2 + products[i] * products[i] * denominator;
+      denominator *= d2;
+    }
+    if (numerator < 0n) return false;
+    if (numerator === 0n) {
+      return commit(0n, 1n);
+    }
+    // Convexity bounds the positive root below by F(0)/abs(F'(0)).
+    // abs(F'(0)) <= 2*(1+F(0))/minPositiveOffset. Use this exact
+    // rational bound when a zero shortest-axis coordinate admits a tiny root.
+    const positive = offsets.filter(d => d > 0n);
+    const least = positive.reduce((p, v) => (p < v ? p : v));
+    precision = Math.max(
+      64,
+      (2n * (denominator + numerator)).toString(2).length -
+        (numerator * least).toString(2).length +
+        128
+    );
+  }
+  const unit = 1n << BigInt(precision);
+  const d = offsets.map(v => v * unit);
+  const u = products.map(v => v * unit);
+  const u2 = u.map(v => v * v);
+  let lower = 0n,
+    upper = u.reduce((sum, v) => sum + v, 0n);
+  if (upper === 0n) return false;
+  for (let iteration = 0; iteration < 4096; iteration++) {
+    const t = (lower + upper) >> 1n;
+    if (t === lower) return false;
+    const dx = d[0] + t,
+      dy = d[1] + t,
+      dz = d[2] + t;
+    const xx = dx * dx,
+      yy = dy * dy,
+      zz = dz * dz;
+    const sign = u2[0] * yy * zz + u2[1] * xx * zz + u2[2] * xx * yy - xx * yy * zz;
+    if (sign === 0n) return commit(t, unit);
+    if (sign > 0n) lower = t;
+    else upper = t;
+    if (lower > 0n && upper - lower <= lower >> 60n) return commit((lower + upper) >> 1n, unit);
+  }
+  return false;
+
+  function commit(t: bigint, unit: bigint): boolean {
+    const output = squares.map((r2, i) => {
+      const denominator = offsets[i] * unit + t;
+      return denominator === 0n ? 0 : ratio(r2 * integers[i + 3] * unit, denominator, exponent);
+    });
+    if (!output.every(Number.isFinite)) return false;
+    const qx = Math.sign(x) * output[0],
+      qy = Math.sign(y) * output[1],
+      qz = Math.sign(z) * output[2];
+    result.x = qx;
+    result.y = qy;
+    result.z = qz;
+    return true;
+  }
+}
+
+/** Round a positive rational dyadic to a binary64 significand without converting
+ * unbounded integers to Number first. Split the exponent for subnormal outputs.
+ */
+export function ratio(n: bigint, d: bigint, exponent: number): number {
+  if (n === 0n) return 0;
+  const shift = 52 - (n.toString(2).length - d.toString(2).length);
+  const numerator = shift >= 0 ? n << BigInt(shift) : n;
+  const denominator = shift >= 0 ? d : d << BigInt(-shift);
+  let quotient = numerator / denominator;
+  const remainder = numerator % denominator;
+  if (2n * remainder > denominator || (2n * remainder === denominator && quotient & 1n)) quotient++;
+  const power = exponent - shift;
+  const first = Math.max(-1022, Math.min(1023, power));
+  return Number(quotient) * 2 ** first * 2 ** (power - first);
+}

package/src/ellipsoid-helpers/intersection-bounds.ts

@@ -0,0 +1,85 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) Charles Karney (2023)
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Capture-distance and conjugate calculations adapted from GeographicLib 2.7 Intersect.cpp (MIT). See ../../GEOGRAPHICLIB-LICENSE.txt.
+import type {EllipsoidGeodesic, GeodesicLine} from '../ellipsoid-geodesic';
+
+/** @internal Native characteristic distances, in normalized axis units. */
+export class IntersectionBounds {
+  readonly margin: number;
+  readonly capture: number;
+  readonly spacing: number;
+  readonly halfCircumference: number;
+  constructor(
+    private readonly solver: EllipsoidGeodesic,
+    ratio: number,
+    radius: number
+  ) {
+    this.halfCircumference = Math.PI * radius;
+    this.margin = this.halfCircumference * Number.EPSILON ** (1 / 5);
+    this.capture = ratio <= 1 ? Math.PI * ratio : this.polarMinimum(ratio);
+    this.spacing = this.capture - this.margin;
+    if (!(Number.isFinite(this.spacing) && this.spacing > 0))
+      throw new Error('Unresolved geodesic capture bound');
+  }
+
+  conjugate(
+    line: GeodesicLine,
+    guess: number,
+    semi = false,
+    reference = {m12: 0, M12: 1, M21: 1}
+  ): number {
+    const {m12, M12, M21} = reference;
+    let s = guess;
+    for (let i = 0; i < 100; i++) {
+      const p = line.position(s);
+      const m = p.m12 * M12 - m12 * p.M12;
+      const forward = p.M12 * M21 + (m12 === 0 ? 0 : ((1 - M12 * M21) * p.m12) / m12);
+      const reverse = p.M21 * M12 + (p.m12 === 0 ? 0 : ((1 - p.M12 * p.M21) * m12) / p.m12);
+      const step = semi ? (m * forward) / (1 - forward * reverse) : -m / reverse;
+      if (!Number.isFinite(step)) throw new Error('Unresolved conjugate distance');
+      const next = s + step;
+      if (next === s || Math.abs(step) <= 5e-14) return next;
+      s = next;
+    }
+    throw new Error('Conjugate distance did not converge');
+  }
+
+  private polarDistance(latitude: number, ratio: number): number {
+    return this.conjugate(
+      this.solver.line(latitude, 0, 0),
+      ((1 + (1 - ratio) / 2) * Math.PI) / 2,
+      true
+    );
+  }
+  private polarMinimum(ratio: number): number {
+    let lat0 = 63,
+      lat1 = 65,
+      lat2 = 64;
+    let s0 = this.polarDistance(lat0, ratio),
+      s1 = this.polarDistance(lat1, ratio),
+      s2 = this.polarDistance(lat2, ratio);
+    let best = s2;
+    for (let i = 0; i < 10; i++) {
+      const denominator = (lat1 - lat0) * s2 + (lat0 - lat2) * s1 + (lat2 - lat1) * s0;
+      if (denominator === 0) break;
+      const next =
+        ((lat1 - lat0) * (lat1 + lat0) * s2 +
+          (lat0 - lat2) * (lat0 + lat2) * s1 +
+          (lat2 - lat1) * (lat2 + lat1) * s0) /
+        (2 * denominator);
+      // Near a sphere the quadratic becomes numerically flat. The capture
+      // safety margin is much larger than the roundoff in these distances.
+      if (!(Number.isFinite(next) && next >= 0 && next <= 90)) break;
+      lat0 = lat1;
+      s0 = s1;
+      lat1 = lat2;
+      s1 = s2;
+      lat2 = next;
+      s2 = this.polarDistance(lat2, ratio);
+      best = Math.min(best, s2);
+    }
+    return 2 * best;
+  }
+}

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

@@ -0,0 +1,157 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original safeguarded constrained-distance solver and compensated residual; no upstream code.
+
+import {exactNearestSurface} from './exact-nearest-surface';
+
+/** Unique nearest point on a positive three-axis ellipsoid. No output on failure.
+ * With t = lambda + min(radii)^2 > 0 the constrained Hessian is positive
+ * definite, certifying a global minimum in exact arithmetic. Unique boundary
+ * roots and ill-conditioned residuals use exact dyadic classification/solving. Numerical qualification
+ * is sampled; unrepresentable products and exhausted convergence reject.
+ */
+export function nearestSurface(
+  x: number,
+  y: number,
+  z: number,
+  a: number,
+  b: number,
+  c: number,
+  result: {x: number; y: number; z: number}
+): boolean {
+  const minimum = Math.min(a, b, c);
+  const minimumSquared = minimum * minimum;
+  const aa = a * a,
+    bb = b * b,
+    cc = c * c;
+  if (!(minimum > 0) || !(minimumSquared > 0) || !Number.isFinite(Math.max(aa, bb, cc)))
+    return false;
+  const minimumError = productError(minimum, minimum, minimumSquared);
+  const dx = aa - minimumSquared,
+    dy = bb - minimumSquared,
+    dz = cc - minimumSquared;
+  const ex = sumError(aa, -minimumSquared, dx) + productError(a, a, aa) - minimumError;
+  const ey = sumError(bb, -minimumSquared, dy) + productError(b, b, bb) - minimumError;
+  const ez = sumError(cc, -minimumSquared, dz) + productError(c, c, cc) - minimumError;
+  const ux = a * Math.abs(x),
+    uy = b * Math.abs(y),
+    uz = c * Math.abs(z);
+  // Error-free products cannot retain their low bits below the normal range.
+  if (
+    minimumSquared < 2 ** -1022 ||
+    (x !== 0 && ux < 2 ** -1022) ||
+    (y !== 0 && uy < 2 ** -1022) ||
+    (z !== 0 && uz < 2 ** -1022)
+  )
+    return exactNearestSurface(x, y, z, a, b, c, result);
+  const fx = productError(a, Math.abs(x), ux);
+  const fy = productError(b, Math.abs(y), uy);
+  const fz = productError(c, Math.abs(z), uz);
+  const limit = Math.hypot(
+    dx === 0 ? (ux === 0 ? 0 : Infinity) : ux / (dx + ex),
+    dy === 0 ? (uy === 0 ? 0 : Infinity) : uy / (dy + ey),
+    dz === 0 ? (uz === 0 ? 0 : Infinity) : uz / (dz + ez)
+  );
+  if (limit <= 1 + 64 * Number.EPSILON) return exactNearestSurface(x, y, z, a, b, c, result);
+  if ((x !== 0 ? 1 : 0) + (y !== 0 ? 1 : 0) + (z !== 0 ? 1 : 0) === 1) {
+    result.x = x === 0 ? x : Math.sign(x) * a;
+    result.y = y === 0 ? y : Math.sign(y) * b;
+    result.z = z === 0 ? z : Math.sign(z) * c;
+    return true;
+  }
+  let lower = Math.hypot(dx === 0 ? ux : 0, dy === 0 ? uy : 0, dz === 0 ? uz : 0);
+  let upper = Math.hypot(ux, uy, uz);
+  if (!(upper > 0) || !Number.isFinite(upper)) return exactNearestSurface(x, y, z, a, b, c, result);
+  let t = lower > 0 ? lower : upper;
+  for (let iteration = 0; iteration < 512; iteration++) {
+    const hx = dx + t,
+      hy = dy + t,
+      hz = dz + t;
+    const lx = sumError(dx, t, hx) + ex;
+    const ly = sumError(dy, t, hy) + ey;
+    const lz = sumError(dz, t, hz) + ez;
+    const vx = ux / hx,
+      vy = uy / hy,
+      vz = uz / hz;
+    // Subtract one from the dominant squared component using a compensated
+    // (numerator - denominator), not hypot(v)-1. At a cusp the residual may
+    // be 1e-80 even though the ordinary norm rounds exactly to one.
+    let term: number, rest: number;
+    if (vx >= vy && vx >= vz) {
+      term = offset(ux, fx, dx, ex, t, hx) * (vx + 1);
+      rest = (vy * (1 - ly / hy)) ** 2 + (vz * (1 - lz / hz)) ** 2;
+    } else if (vy >= vz) {
+      term = offset(uy, fy, dy, ey, t, hy) * (vy + 1);
+      rest = (vx * (1 - lx / hx)) ** 2 + (vz * (1 - lz / hz)) ** 2;
+    } else {
+      term = offset(uz, fz, dz, ez, t, hz) * (vz + 1);
+      rest = (vx * (1 - lx / hx)) ** 2 + (vy * (1 - ly / hy)) ** 2;
+    }
+    const derivative = -2 * ((vx * vx) / hx + (vy * vy) / hy + (vz * vz) / hz);
+    const roundoff = 4 * Number.EPSILON * (Math.abs(term) + rest);
+    const residual = term + rest;
+    if (!Number.isFinite(residual)) return exactNearestSurface(x, y, z, a, b, c, result);
+    if (
+      Math.abs(residual) <= 4 * Number.EPSILON * (Math.abs(term) + rest) ||
+      upper - lower <= 4 * Number.EPSILON * t
+    ) {
+      // With several large components, a rounded residual may lose a tiny
+      // multiplier. Bound displacement using its sensitivity, and reject when
+      // the local error estimate is too large to certify the qualified budget.
+      const uncertainty = roundoff / Math.abs(derivative);
+      if (!Number.isFinite(derivative) || !(Math.abs(derivative) > 0) || uncertainty > 2e-13 * t)
+        return exactNearestSurface(x, y, z, a, b, c, result);
+      const qx = Math.sign(x) * a * (vx * (1 - lx / hx));
+      const qy = Math.sign(y) * b * (vy * (1 - ly / hy));
+      const qz = Math.sign(z) * c * (vz * (1 - lz / hz));
+      const displacement =
+        2 * uncertainty * Math.max(Math.abs(qx / hx), Math.abs(qy / hy), Math.abs(qz / hz));
+      if (!Number.isFinite(displacement) || displacement > 2e-13 * Math.max(a, b, c))
+        return exactNearestSurface(x, y, z, a, b, c, result);
+      if (!Number.isFinite(qx) || !Number.isFinite(qy) || !Number.isFinite(qz))
+        return exactNearestSurface(x, y, z, a, b, c, result);
+      result.x = qx;
+      result.y = qy;
+      result.z = qz;
+      return true;
+    }
+    if (residual > 0) lower = t;
+    else upper = t;
+    const candidate = t - residual / derivative;
+    const next = candidate > lower && candidate < upper ? candidate : lower + (upper - lower) / 2;
+    if (next === t) return exactNearestSurface(x, y, z, a, b, c, result);
+    t = next;
+  }
+  return exactNearestSurface(x, y, z, a, b, c, result);
+}
+
+function offset(
+  u: number,
+  error: number,
+  d: number,
+  dError: number,
+  t: number,
+  denominator: number
+): number {
+  const difference = u - d;
+  const correction = sumError(u, -d, difference) + error - dError;
+  const base = difference + correction;
+  const low = sumError(difference, correction, base);
+  const shifted = base - t;
+  return (shifted + (sumError(base, -t, shifted) + low)) / denominator;
+}
+function sumError(x: number, y: number, sum: number): number {
+  const part = sum - x;
+  return x - (sum - part) + (y - part);
+}
+function productError(x: number, y: number, product: number): number {
+  const sx = 134217729 * x,
+    sy = 134217729 * y;
+  if (!Number.isFinite(sx) || !Number.isFinite(sy)) return 0;
+  const hx = sx - (sx - x),
+    hy = sy - (sy - y);
+  const lx = x - hx,
+    ly = y - hy;
+  return hx * hy - product + hx * ly + lx * hy + lx * ly;
+}