@woosh/meep-engine 3.37.0 → 3.39.0

package/src/core/geom/3d/gjk/gjk_distance.js

@@ -0,0 +1,782 @@
+/**
+ * GJK distance between two convex shapes: the distance, the closest point on each, and the normal
+ * that separates them. The third GJK in this directory, and the only one that measures how far
+ * apart two shapes are rather than whether they overlap — `gjk.js` answers yes or no, and
+ * `gjk_epa_penetration.js` answers how deep.
+ *
+ * Ported from Box3D's `b3ShapeDistance` (distance.c, MIT, Erin Catto; portions by Dirk Gregorius):
+ * the same simplex solver — barycentric coordinates over the vertex, edge and face Voronoi regions,
+ * which never builds a search direction out of a near-zero closest point — and the same exits.
+ * Three things differ, all because a shape here is a support function rather than a vertex list:
+ *
+ * - A duplicate support point is recognised by its coordinates, not by a vertex index. A polytope's
+ *   support returns one vertex bit for bit every time it is chosen, so this terminates a box or a
+ *   hull exactly as Box3D does.
+ * - A curved support (a sphere, a capsule's caps) returns a new point for every direction, so the
+ *   duplicate test never fires on one. The search also stops once the support plane in the search
+ *   direction closes to within {@link GJK_DISTANCE_RELATIVE_GAP} of the closest point found — van
+ *   den Bergen's criterion; the closest point is then that close to the true distance — or within
+ *   the caller's own absolute tolerance, when it gives one.
+ * - It reports a LOWER bound on the distance besides the distance itself: the gap to that support
+ *   plane, along the reported normal. Every point of `B − A` lies beyond it, so it is a separating
+ *   plane in fact, not an estimate — what a conservative advancement needs to step by.
+ *
+ * Everything is in world space; the shapes are any support providers, e.g. {@link PosedShape3D}.
+ * Allocation-free: the simplex lives in a caller-owned {@link GJKSimplex}, the rest in module
+ * scratch (no callbacks run inside, so nothing can re-enter it).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+import { assert } from "../../../assert.js";
+
+/**
+ * Most iterations a query runs: Box3D's `B3_MAX_GJK_ITERATIONS`. A polytope pair terminates on a
+ * duplicate support long before it; the cap is for a curved pair whose gap closes slowly.
+ * @type {number}
+ */
+const MAX_ITERATIONS = 32;
+
+/**
+ * The search stops when the support plane lies within this fraction of the closest point's distance
+ * — the closest point is then within it of the true distance. A caller that needs less can stop it
+ * sooner with an absolute tolerance of its own (see {@link gjk_distance}).
+ * @type {number}
+ */
+export const GJK_DISTANCE_RELATIVE_GAP = 1e-10;
+
+/**
+ * A search direction shorter than this (squared) has collapsed: the origin lies on the simplex, and
+ * the shapes touch. Box3D's `1000 * FLT_MIN`, at double precision.
+ * @type {number}
+ */
+const COLLAPSED_SEARCH_SQR = 1000 * 2.2250738585072014e-308;
+
+/**
+ * Floats per simplex vertex: the support point on A, the one on B, and their difference `B − A`.
+ * @type {number}
+ */
+const VERTEX_STRIDE = 9;
+
+const OFFSET_A = 0;
+const OFFSET_B = 3;
+const OFFSET_W = 6;
+
+/**
+ * The simplex a {@link gjk_distance} query builds, and what it reports beyond the result array.
+ * Reusable: one per caller, re-filled by every query.
+ *
+ * A query starts from whatever vertices `count` says are live (zero for a cold start), so a caller
+ * repeating a query on the same pair can hand the last simplex back — Box3D's simplex cache. Those
+ * vertices must still be support points of the shapes as they are posed now:
+ * {@link gjk_simplex_translate_b} keeps them so across a translation of B.
+ */
+export class GJKSimplex {
+    /**
+     * Four vertices of {@link VERTEX_STRIDE} floats: the support point on A, the one on B, `B − A`.
+     * @type {Float64Array}
+     */
+    vertices = new Float64Array(4 * VERTEX_STRIDE);
+
+    /**
+     * Barycentric weight of each live vertex in the closest point.
+     * @type {Float64Array}
+     */
+    weights = new Float64Array(4);
+
+    /**
+     * Live vertices, 0 to 4.
+     * @type {number}
+     */
+    count = 0;
+
+    /**
+     * Whether the last query terminated on its own terms (a duplicate support, a closed gap, no
+     * further progress, an overlap) rather than on {@link MAX_ITERATIONS}. Its result is the best
+     * found either way, and its lower bound holds either way.
+     * @type {boolean}
+     */
+    converged = true;
+
+    /**
+     * Iterations the last query ran.
+     * @type {number}
+     */
+    iterations = 0;
+}
+
+/**
+ * Move every live vertex of `simplex` as shape B moves by `(dx, dy, dz)`, so it stays a valid warm
+ * start: a support point of a translated shape is the old one, translated.
+ *
+ * @param {GJKSimplex} simplex
+ * @param {number} dx
+ * @param {number} dy
+ * @param {number} dz
+ */
+export function gjk_simplex_translate_b(simplex, dx, dy, dz) {
+    const v = simplex.vertices;
+    for (let i = 0; i < simplex.count; i++) {
+        const o = i * VERTEX_STRIDE;
+        v[o + OFFSET_B] += dx; v[o + OFFSET_B + 1] += dy; v[o + OFFSET_B + 2] += dz;
+        v[o + OFFSET_W] += dx; v[o + OFFSET_W + 1] += dy; v[o + OFFSET_W + 2] += dz;
+    }
+}
+
+// ── module scratch ──────────────────────────────────────────────────────────
+
+/** The simplex as it was before a solve reordered it. */
+const solve_source = new Float64Array(4 * VERTEX_STRIDE);
+
+/** The simplex before the last vertex was added, restored when that vertex made no progress. */
+const backup_vertices = new Float64Array(4 * VERTEX_STRIDE);
+const backup_weights = new Float64Array(4);
+let backup_count = 0;
+
+/** A support point on each shape. */
+const support_a = new Float64Array(3);
+const support_b = new Float64Array(3);
+
+/** The unit direction handed to each shape's support, which takes it in an array. */
+const support_direction = new Float64Array(3);
+
+/** Barycentric coordinates, Box3D's layout: the weights, then the divisor last. */
+const w_ab = new Float64Array(3);
+const w_ac = new Float64Array(3);
+const w_ad = new Float64Array(3);
+const w_bc = new Float64Array(3);
+const w_cd = new Float64Array(3);
+const w_db = new Float64Array(3);
+const w_ca = new Float64Array(3);
+const w_abc = new Float64Array(4);
+const w_acb = new Float64Array(4);
+const w_abd = new Float64Array(4);
+const w_adc = new Float64Array(4);
+const w_bcd = new Float64Array(4);
+const w_abcd = new Float64Array(5);
+
+/**
+ * @param {Float64Array} out
+ * @param {Float64Array} v vertex data
+ * @param {number} a vertex index
+ * @param {number} b vertex index
+ */
+function barycentric_edge(out, v, a, b) {
+    const ao = a * VERTEX_STRIDE + OFFSET_W;
+    const bo = b * VERTEX_STRIDE + OFFSET_W;
+    const ax = v[ao], ay = v[ao + 1], az = v[ao + 2];
+    const bx = v[bo], by = v[bo + 1], bz = v[bo + 2];
+    const abx = bx - ax, aby = by - ay, abz = bz - az;
+
+    out[0] = bx * abx + by * aby + bz * abz;
+    out[1] = -(ax * abx + ay * aby + az * abz);
+    out[2] = abx * abx + aby * aby + abz * abz;
+}
+
+/**
+ * @param {Float64Array} out
+ * @param {Float64Array} v vertex data
+ * @param {number} a vertex index
+ * @param {number} b vertex index
+ * @param {number} c vertex index
+ */
+function barycentric_triangle(out, v, a, b, c) {
+    const ao = a * VERTEX_STRIDE + OFFSET_W;
+    const bo = b * VERTEX_STRIDE + OFFSET_W;
+    const co = c * VERTEX_STRIDE + OFFSET_W;
+    const ax = v[ao], ay = v[ao + 1], az = v[ao + 2];
+    const bx = v[bo], by = v[bo + 1], bz = v[bo + 2];
+    const cx = v[co], cy = v[co + 1], cz = v[co + 2];
+
+    const abx = bx - ax, aby = by - ay, abz = bz - az;
+    const acx = cx - ax, acy = cy - ay, acz = cz - az;
+
+    // ab × ac
+    const nx = aby * acz - abz * acy;
+    const ny = abz * acx - abx * acz;
+    const nz = abx * acy - aby * acx;
+
+    // b × c, c × a, a × b, each against the normal
+    out[0] = (by * cz - bz * cy) * nx + (bz * cx - bx * cz) * ny + (bx * cy - by * cx) * nz;
+    out[1] = (cy * az - cz * ay) * nx + (cz * ax - cx * az) * ny + (cx * ay - cy * ax) * nz;
+    out[2] = (ay * bz - az * by) * nx + (az * bx - ax * bz) * ny + (ax * by - ay * bx) * nz;
+    out[3] = nx * nx + ny * ny + nz * nz;
+}
+
+/**
+ * `p · (q × r)` over three vertices' `w`.
+ */
+function triple(v, p, q, r) {
+    const po = p * VERTEX_STRIDE + OFFSET_W;
+    const qo = q * VERTEX_STRIDE + OFFSET_W;
+    const ro = r * VERTEX_STRIDE + OFFSET_W;
+    const qx = v[qo], qy = v[qo + 1], qz = v[qo + 2];
+    const rx = v[ro], ry = v[ro + 1], rz = v[ro + 2];
+    return v[po] * (qy * rz - qz * ry) + v[po + 1] * (qz * rx - qx * rz) + v[po + 2] * (qx * ry - qy * rx);
+}
+
+/**
+ * @param {Float64Array} out
+ * @param {Float64Array} v vertex data
+ */
+function barycentric_tetrahedron(out, v) {
+    const o0 = OFFSET_W, o1 = VERTEX_STRIDE + OFFSET_W, o2 = 2 * VERTEX_STRIDE + OFFSET_W, o3 = 3 * VERTEX_STRIDE + OFFSET_W;
+    const ax = v[o0], ay = v[o0 + 1], az = v[o0 + 2];
+    const abx = v[o1] - ax, aby = v[o1 + 1] - ay, abz = v[o1 + 2] - az;
+    const acx = v[o2] - ax, acy = v[o2 + 1] - ay, acz = v[o2 + 2] - az;
+    const adx = v[o3] - ax, ady = v[o3 + 1] - ay, adz = v[o3 + 2] - az;
+
+    // ab · (ac × ad)
+    const divisor = abx * (acy * adz - acz * ady) + aby * (acz * adx - acx * adz) + abz * (acx * ady - acy * adx);
+    const sign = divisor < 0 ? -1 : 1;
+
+    out[0] = sign * triple(v, 1, 2, 3);
+    out[1] = sign * triple(v, 0, 3, 2);
+    out[2] = sign * triple(v, 0, 1, 3);
+    out[3] = sign * triple(v, 0, 2, 1);
+    out[4] = sign * divisor;
+}
+
+/**
+ * Keep vertices `i`, `j`, `k` of {@link solve_source} (as many as `count` says), in that order.
+ *
+ * @param {GJKSimplex} simplex
+ * @param {number} count
+ * @param {number} i
+ * @param {number} j
+ * @param {number} k
+ */
+function keep(simplex, count, i, j, k) {
+    const v = simplex.vertices;
+    const s = solve_source;
+    simplex.count = count;
+    for (let f = 0; f < VERTEX_STRIDE; f++) v[f] = s[i * VERTEX_STRIDE + f];
+    if (count < 2) return;
+    for (let f = 0; f < VERTEX_STRIDE; f++) v[VERTEX_STRIDE + f] = s[j * VERTEX_STRIDE + f];
+    if (count < 3) return;
+    for (let f = 0; f < VERTEX_STRIDE; f++) v[2 * VERTEX_STRIDE + f] = s[k * VERTEX_STRIDE + f];
+}
+
+/**
+ * Reduce a two-vertex simplex to the feature nearest the origin and weigh it. Box3D's
+ * `b3SolveSimplex2`.
+ *
+ * @param {GJKSimplex} simplex
+ * @returns {boolean} false when the edge is degenerate
+ */
+function solve2(simplex) {
+    const weights = simplex.weights;
+    barycentric_edge(w_ab, simplex.vertices, 0, 1);
+
+    // V(A)
+    if (w_ab[1] <= 0) {
+        simplex.count = 1;
+        weights[0] = 1;
+        return true;
+    }
+
+    // V(B)
+    if (w_ab[0] <= 0) {
+        solve_source.set(simplex.vertices);
+        keep(simplex, 1, 1, 0, 0);
+        weights[0] = 1;
+        return true;
+    }
+
+    const divisor = w_ab[2];
+    if (divisor <= 0) return false;
+
+    weights[0] = w_ab[0] / divisor;
+    weights[1] = w_ab[1] / divisor;
+    return true;
+}
+
+/**
+ * Keep the edge `(i, j)` of {@link solve_source} with its edge coordinates `w`.
+ *
+ * @returns {boolean} false when the edge is degenerate
+ */
+function keep_edge(simplex, i, j, w) {
+    keep(simplex, 2, i, j, 0);
+    const divisor = w[2];
+    if (divisor <= 0) return false;
+    simplex.weights[0] = w[0] / divisor;
+    simplex.weights[1] = w[1] / divisor;
+    return true;
+}
+
+/**
+ * Keep the face `(i, j, k)` of {@link solve_source} with its face coordinates `w`.
+ *
+ * @returns {boolean} false when the face is degenerate
+ */
+function keep_face(simplex, i, j, k, w) {
+    keep(simplex, 3, i, j, k);
+    const divisor = w[3];
+    if (divisor <= 0) return false;
+    simplex.weights[0] = w[0] / divisor;
+    simplex.weights[1] = w[1] / divisor;
+    simplex.weights[2] = w[2] / divisor;
+    return true;
+}
+
+/**
+ * Box3D's `b3SolveSimplex3`.
+ *
+ * @param {GJKSimplex} simplex
+ * @returns {boolean}
+ */
+function solve3(simplex) {
+    const v = simplex.vertices;
+    solve_source.set(v);
+
+    barycentric_edge(w_ab, v, 0, 1);
+    barycentric_edge(w_bc, v, 1, 2);
+    barycentric_edge(w_ca, v, 2, 0);
+
+    // VR(A)
+    if (w_ab[1] <= 0 && w_ca[0] <= 0) {
+        keep(simplex, 1, 0, 0, 0);
+        simplex.weights[0] = 1;
+        return true;
+    }
+
+    // VR(B)
+    if (w_bc[1] <= 0 && w_ab[0] <= 0) {
+        keep(simplex, 1, 1, 0, 0);
+        simplex.weights[0] = 1;
+        return true;
+    }
+
+    // VR(C)
+    if (w_ca[1] <= 0 && w_bc[0] <= 0) {
+        keep(simplex, 1, 2, 0, 0);
+        simplex.weights[0] = 1;
+        return true;
+    }
+
+    barycentric_triangle(w_abc, v, 0, 1, 2);
+
+    // VR(AB)
+    if (w_abc[2] <= 0 && w_ab[0] > 0 && w_ab[1] > 0) return keep_edge(simplex, 0, 1, w_ab);
+
+    // VR(BC)
+    if (w_abc[0] <= 0 && w_bc[0] > 0 && w_bc[1] > 0) return keep_edge(simplex, 1, 2, w_bc);
+
+    // VR(CA)
+    if (w_abc[1] <= 0 && w_ca[0] > 0 && w_ca[1] > 0) return keep_edge(simplex, 2, 0, w_ca);
+
+    // VR(ABC)
+    return keep_face(simplex, 0, 1, 2, w_abc);
+}
+
+/**
+ * Box3D's `b3SolveSimplex4`.
+ *
+ * @param {GJKSimplex} simplex
+ * @returns {boolean}
+ */
+function solve4(simplex) {
+    const v = simplex.vertices;
+    solve_source.set(v);
+
+    // vertex regions
+    barycentric_edge(w_ab, v, 0, 1);
+    barycentric_edge(w_ac, v, 0, 2);
+    barycentric_edge(w_ad, v, 0, 3);
+    barycentric_edge(w_bc, v, 1, 2);
+    barycentric_edge(w_cd, v, 2, 3);
+    barycentric_edge(w_db, v, 3, 1);
+
+    // VR(A)
+    if (w_ab[1] <= 0 && w_ac[1] <= 0 && w_ad[1] <= 0) {
+        keep(simplex, 1, 0, 0, 0);
+        simplex.weights[0] = 1;
+        return true;
+    }
+
+    // VR(B)
+    if (w_ab[0] <= 0 && w_db[0] <= 0 && w_bc[1] <= 0) {
+        keep(simplex, 1, 1, 0, 0);
+        simplex.weights[0] = 1;
+        return true;
+    }
+
+    // VR(C)
+    if (w_ac[0] <= 0 && w_bc[0] <= 0 && w_cd[1] <= 0) {
+        keep(simplex, 1, 2, 0, 0);
+        simplex.weights[0] = 1;
+        return true;
+    }
+
+    // VR(D)
+    if (w_ad[0] <= 0 && w_cd[0] <= 0 && w_db[1] <= 0) {
+        keep(simplex, 1, 3, 0, 0);
+        simplex.weights[0] = 1;
+        return true;
+    }
+
+    // edge regions
+    barycentric_triangle(w_acb, v, 0, 2, 1);
+    barycentric_triangle(w_abd, v, 0, 1, 3);
+    barycentric_triangle(w_adc, v, 0, 3, 2);
+    barycentric_triangle(w_bcd, v, 1, 2, 3);
+
+    // VR(AB)
+    if (w_abd[2] <= 0 && w_acb[1] <= 0 && w_ab[0] > 0 && w_ab[1] > 0) return keep_edge(simplex, 0, 1, w_ab);
+
+    // VR(AC)
+    if (w_acb[2] <= 0 && w_adc[1] <= 0 && w_ac[0] > 0 && w_ac[1] > 0) return keep_edge(simplex, 0, 2, w_ac);
+
+    // VR(AD)
+    if (w_adc[2] <= 0 && w_abd[1] <= 0 && w_ad[0] > 0 && w_ad[1] > 0) return keep_edge(simplex, 0, 3, w_ad);
+
+    // VR(BC)
+    if (w_acb[0] <= 0 && w_bcd[2] <= 0 && w_bc[0] > 0 && w_bc[1] > 0) return keep_edge(simplex, 1, 2, w_bc);
+
+    // VR(CD)
+    if (w_adc[0] <= 0 && w_bcd[0] <= 0 && w_cd[0] > 0 && w_cd[1] > 0) return keep_edge(simplex, 2, 3, w_cd);
+
+    // VR(DB)
+    if (w_abd[0] <= 0 && w_bcd[1] <= 0 && w_db[0] > 0 && w_db[1] > 0) return keep_edge(simplex, 3, 1, w_db);
+
+    // face regions
+    barycentric_tetrahedron(w_abcd, v);
+
+    // VR(ACB)
+    if (w_abcd[3] < 0 && w_acb[0] > 0 && w_acb[1] > 0 && w_acb[2] > 0) return keep_face(simplex, 0, 2, 1, w_acb);
+
+    // VR(ABD)
+    if (w_abcd[2] < 0 && w_abd[0] > 0 && w_abd[1] > 0 && w_abd[2] > 0) return keep_face(simplex, 0, 1, 3, w_abd);
+
+    // VR(ADC)
+    if (w_abcd[1] < 0 && w_adc[0] > 0 && w_adc[1] > 0 && w_adc[2] > 0) return keep_face(simplex, 0, 3, 2, w_adc);
+
+    // VR(BCD)
+    if (w_abcd[0] < 0 && w_bcd[0] > 0 && w_bcd[1] > 0 && w_bcd[2] > 0) return keep_face(simplex, 1, 2, 3, w_bcd);
+
+    // inside the tetrahedron
+    const divisor = w_abcd[4];
+    if (divisor <= 0) return false;
+
+    simplex.weights[0] = w_abcd[0] / divisor;
+    simplex.weights[1] = w_abcd[1] / divisor;
+    simplex.weights[2] = w_abcd[2] / divisor;
+    simplex.weights[3] = w_abcd[3] / divisor;
+    return true;
+}
+
+/**
+ * Write the weighted sum of the live vertices' field at `field` (A's, B's or `w`) into
+ * `out[out_offset..+2]`.
+ */
+function blend(out, out_offset, simplex, field) {
+    const v = simplex.vertices;
+    const weights = simplex.weights;
+    let x = 0, y = 0, z = 0;
+    for (let i = 0; i < simplex.count; i++) {
+        const o = i * VERTEX_STRIDE + field;
+        const a = weights[i];
+        x += a * v[o]; y += a * v[o + 1]; z += a * v[o + 2];
+    }
+    out[out_offset] = x;
+    out[out_offset + 1] = y;
+    out[out_offset + 2] = z;
+}
+
+/**
+ * Start `simplex` over from a single point of `B − A` — any point does.
+ *
+ * @param {GJKSimplex} simplex
+ * @param {{support:function}} shape_a
+ * @param {{support:function}} shape_b
+ */
+function seed(simplex, shape_a, shape_b) {
+    const v = simplex.vertices;
+    support_direction[0] = -1; support_direction[1] = 0; support_direction[2] = 0;
+    shape_a.support(support_a, 0, support_direction, 0);
+    support_direction[0] = 1; support_direction[1] = 0; support_direction[2] = 0;
+    shape_b.support(support_b, 0, support_direction, 0);
+    v[OFFSET_A] = support_a[0]; v[OFFSET_A + 1] = support_a[1]; v[OFFSET_A + 2] = support_a[2];
+    v[OFFSET_B] = support_b[0]; v[OFFSET_B + 1] = support_b[1]; v[OFFSET_B + 2] = support_b[2];
+    v[OFFSET_W] = support_b[0] - support_a[0];
+    v[OFFSET_W + 1] = support_b[1] - support_a[1];
+    v[OFFSET_W + 2] = support_b[2] - support_a[2];
+    simplex.count = 1;
+}
+
+/**
+ * Report an overlap: both witness points at the shapes' shared point, no normal, zero distance.
+ *
+ * @returns {number} 0
+ */
+function report_overlap(out, simplex) {
+    // Box3D forces the two points to coincide: blended from A's side, they are the same point.
+    blend(out, 0, simplex, OFFSET_A);
+    out[3] = out[0]; out[4] = out[1]; out[5] = out[2];
+    out[6] = 0; out[7] = 0; out[8] = 0;
+    out[9] = 0;
+    return 0;
+}
+
+/**
+ * Distance between convex shapes `shape_a` and `shape_b`, posed in world space.
+ *
+ * `out` receives:
+ * - `[0..2]` the closest point on A, `[3..5]` the closest point on B;
+ * - `[6..8]` the unit normal from A toward B — the direction B would move to separate further;
+ * - `[9]` a lower bound on the distance: every point of B lies at least this far beyond A along the
+ *   normal. Within {@link GJK_DISTANCE_RELATIVE_GAP} of the distance on convergence (or within
+ *   `gap_tolerance`), and a true bound regardless.
+ *
+ * When the shapes overlap or touch, the distance and the lower bound are 0, the normal is zero, and
+ * the two points coincide at a point the shapes share. A positive lower bound comes with a plane
+ * that separates the shapes. A search that runs out of {@link MAX_ITERATIONS} before finding any
+ * such plane establishes neither: it reports the closest it came — a distance no less than the
+ * true one, along the witness points' own direction — with a lower bound of 0, and
+ * `simplex.converged` false. Overlap is reported only by a search that ended on its own terms.
+ *
+ * @param {Float64Array} out at least 10 floats
+ * @param {GJKSimplex} simplex workspace, and warm start when its `count` is non-zero (see
+ *   {@link GJKSimplex}); holds the final simplex afterwards
+ * @param {{support:function(Float64Array, number, Float64Array, number):void}} shape_a support in
+ *   world space, unit direction ({@link AbstractShape3D#support}'s contract)
+ * @param {{support:function(Float64Array, number, Float64Array, number):void}} shape_b
+ * @param {number} gap_tolerance the search also stops once a support plane separates the shapes
+ *   and lies within this distance of the closest point, so the distance and its lower bound are
+ *   within it of the true distance. A curved pair's gap closes linearly, and chasing
+ *   {@link GJK_DISTANCE_RELATIVE_GAP} ran a sphere's queries to {@link MAX_ITERATIONS} a third of
+ *   the time; a caller that only steps by the bound needs no finer answer. The normal is no better
+ *   than the gap, though: off by up to `sqrt(2 · gap_tolerance / R)` for a pair whose surfaces
+ *   curve with a combined radius `R` (half a degree for a 5 cm sphere at 2.5e-6). 0 leaves
+ *   {@link GJK_DISTANCE_RELATIVE_GAP} as the only stop
+ * @returns {number} the distance, `|point on B − point on A|`
+ */
+export function gjk_distance(out, simplex, shape_a, shape_b, gap_tolerance) {
+    assert.isNumber(gap_tolerance, 'gap_tolerance');
+
+    const v = simplex.vertices;
+    const weights = simplex.weights;
+
+    if (simplex.count === 0) seed(simplex, shape_a, shape_b);
+
+    backup_count = 0;
+
+    let distance_sqr = Infinity;
+
+    // The best support plane found so far: its normal, and the gap behind it — van den Bergen's
+    // running maximum. Each plane is a true bound on its own; the last one taken need not be the
+    // best, and on a curved pair the search can end on one that no longer separates the two after
+    // an earlier one did.
+    let nx = 0, ny = 0, nz = 0;
+    let lower_bound = 0;
+
+    simplex.converged = false;
+
+    let iteration = 0;
+    for (; iteration < MAX_ITERATIONS; iteration++) {
+        let solved;
+        switch (simplex.count) {
+            case 1:
+                weights[0] = 1;
+                solved = true;
+                break;
+            case 2:
+                solved = solve2(simplex);
+                break;
+            case 3:
+                solved = solve3(simplex);
+                break;
+            default:
+                solved = solve4(simplex);
+                break;
+        }
+
+        if (!solved) {
+            if (backup_count === 0) {
+                // A warm start that no longer solves (it degenerated) has no earlier simplex to
+                // fall back on: start over from one point.
+                seed(simplex, shape_a, shape_b);
+                continue;
+            }
+            // no progress — reconstruct the last simplex
+            v.set(backup_vertices);
+            weights.set(backup_weights);
+            simplex.count = backup_count;
+            simplex.converged = true;
+            break;
+        }
+
+        if (simplex.count === 4) {
+            simplex.iterations = iteration;
+            simplex.converged = true;
+            return report_overlap(out, simplex);
+        }
+
+        // closest point of the simplex to the origin
+        const old_distance_sqr = distance_sqr;
+        let cx = 0, cy = 0, cz = 0;
+        for (let i = 0; i < simplex.count; i++) {
+            const o = i * VERTEX_STRIDE + OFFSET_W;
+            const a = weights[i];
+            cx += a * v[o]; cy += a * v[o + 1]; cz += a * v[o + 2];
+        }
+        distance_sqr = cx * cx + cy * cy + cz * cz;
+
+        if (distance_sqr >= old_distance_sqr) {
+            // no progress — reconstruct the last simplex
+            v.set(backup_vertices);
+            weights.set(backup_weights);
+            simplex.count = backup_count;
+            distance_sqr = old_distance_sqr;
+            simplex.converged = true;
+            break;
+        }
+
+        // search direction, toward the origin, built from the simplex's features rather than the
+        // closest point (Box3D: it keeps its precision when the origin is close)
+        let sx, sy, sz;
+        if (simplex.count === 1) {
+            sx = -v[OFFSET_W]; sy = -v[OFFSET_W + 1]; sz = -v[OFFSET_W + 2];
+        } else if (simplex.count === 2) {
+            // (ab × ao) × ab
+            const ax = v[OFFSET_W], ay = v[OFFSET_W + 1], az = v[OFFSET_W + 2];
+            const abx = v[VERTEX_STRIDE + OFFSET_W] - ax;
+            const aby = v[VERTEX_STRIDE + OFFSET_W + 1] - ay;
+            const abz = v[VERTEX_STRIDE + OFFSET_W + 2] - az;
+            const tx = aby * -az - abz * -ay;
+            const ty = abz * -ax - abx * -az;
+            const tz = abx * -ay - aby * -ax;
+            sx = ty * abz - tz * aby;
+            sy = tz * abx - tx * abz;
+            sz = tx * aby - ty * abx;
+        } else {
+            // the face normal, on the origin's side
+            const ax = v[OFFSET_W], ay = v[OFFSET_W + 1], az = v[OFFSET_W + 2];
+            const abx = v[VERTEX_STRIDE + OFFSET_W] - ax;
+            const aby = v[VERTEX_STRIDE + OFFSET_W + 1] - ay;
+            const abz = v[VERTEX_STRIDE + OFFSET_W + 2] - az;
+            const acx = v[2 * VERTEX_STRIDE + OFFSET_W] - ax;
+            const acy = v[2 * VERTEX_STRIDE + OFFSET_W + 1] - ay;
+            const acz = v[2 * VERTEX_STRIDE + OFFSET_W + 2] - az;
+            const fx = aby * acz - abz * acy;
+            const fy = abz * acx - abx * acz;
+            const fz = abx * acy - aby * acx;
+            if (fx * ax + fy * ay + fz * az < 0) {
+                sx = fx; sy = fy; sz = fz;
+            } else {
+                sx = -fx; sy = -fy; sz = -fz;
+            }
+        }
+
+        const search_sqr = sx * sx + sy * sy + sz * sz;
+        if (!(search_sqr >= COLLAPSED_SEARCH_SQR)) {
+            // The origin lies on the simplex: the shapes touch.
+            simplex.iterations = iteration;
+            simplex.converged = true;
+            return report_overlap(out, simplex);
+        }
+
+        const inv = 1 / Math.sqrt(search_sqr);
+        const ux = sx * inv, uy = sy * inv, uz = sz * inv;
+
+        // new support point of B − A, toward the origin
+        support_direction[0] = -ux; support_direction[1] = -uy; support_direction[2] = -uz;
+        shape_a.support(support_a, 0, support_direction, 0);
+        support_direction[0] = ux; support_direction[1] = uy; support_direction[2] = uz;
+        shape_b.support(support_b, 0, support_direction, 0);
+        const wx = support_b[0] - support_a[0];
+        const wy = support_b[1] - support_a[1];
+        const wz = support_b[2] - support_a[2];
+
+        // Every point of B − A lies on the far side of the plane through w normal to the search,
+        // so the origin is at least this far from it.
+        const plane_gap = -(wx * ux + wy * uy + wz * uz);
+        if (plane_gap > lower_bound) {
+            lower_bound = plane_gap;
+            nx = -ux; ny = -uy; nz = -uz;
+        }
+
+        // van den Bergen: the plane has closed on the closest point
+        const distance = Math.sqrt(distance_sqr);
+        // The caller's tolerance only once a plane separates the two: a pair it cannot yet tell
+        // apart from touching is searched to the end, so a gap under the tolerance is never
+        // reported as contact.
+        const gap = distance - lower_bound;
+        if (gap <= GJK_DISTANCE_RELATIVE_GAP * distance || (lower_bound > 0 && gap <= gap_tolerance)) {
+            simplex.converged = true;
+            break;
+        }
+
+        // save the simplex before adding the vertex
+        backup_vertices.set(v);
+        backup_weights.set(weights);
+        backup_count = simplex.count;
+
+        // a support point already in the simplex — the main termination for a polytope
+        let duplicate = false;
+        for (let i = 0; i < simplex.count; i++) {
+            const o = i * VERTEX_STRIDE;
+            if (v[o + OFFSET_A] === support_a[0] && v[o + OFFSET_A + 1] === support_a[1] && v[o + OFFSET_A + 2] === support_a[2]
+                && v[o + OFFSET_B] === support_b[0] && v[o + OFFSET_B + 1] === support_b[1] && v[o + OFFSET_B + 2] === support_b[2]) {
+                duplicate = true;
+                break;
+            }
+        }
+        if (duplicate) {
+            simplex.converged = true;
+            break;
+        }
+
+        const o = simplex.count * VERTEX_STRIDE;
+        v[o + OFFSET_A] = support_a[0]; v[o + OFFSET_A + 1] = support_a[1]; v[o + OFFSET_A + 2] = support_a[2];
+        v[o + OFFSET_B] = support_b[0]; v[o + OFFSET_B + 1] = support_b[1]; v[o + OFFSET_B + 2] = support_b[2];
+        v[o + OFFSET_W] = wx; v[o + OFFSET_W + 1] = wy; v[o + OFFSET_W + 2] = wz;
+        simplex.count++;
+    }
+
+    simplex.iterations = iteration;
+
+    if (!simplex.converged && backup_count > 0) {
+        // Out of iterations, with a vertex added that was never solved for: report the simplex
+        // before it.
+        v.set(backup_vertices);
+        weights.set(backup_weights);
+        simplex.count = backup_count;
+    }
+
+    if (!(lower_bound > 0) && simplex.converged) {
+        // The search ended on its own terms and no support plane separates the shapes: they touch
+        // or overlap. It can end here with the closest point a rounding error off the origin — the
+        // origin on a simplex face, the next support no further on — and a "distance" of 1e-17
+        // along a normal from nowhere. Over 4,000 sphere pairs overlapping 0.3 deep, 252 came back
+        // that way; a caller stepping by that distance along that normal walks straight through
+        // the overlap.
+        return report_overlap(out, simplex);
+    }
+
+    // witness points
+    blend(out, 0, simplex, OFFSET_A);
+    blend(out, 3, simplex, OFFSET_B);
+
+    const dx = out[3] - out[0];
+    const dy = out[4] - out[1];
+    const dz = out[5] - out[2];
+    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+    if (lower_bound > 0) {
+        out[6] = nx; out[7] = ny; out[8] = nz;
+        out[9] = lower_bound < distance ? lower_bound : distance;
+        return distance;
+    }
+
+    // Out of iterations before any plane separated the shapes, which is no evidence that they
+    // touch: a sphere and a box 1e-5 apart at a size ratio of 1,000 ran out this way 50 times in
+    // 400. Neither apart nor overlapping is known. Report how close the search came — the distance
+    // is no less than the true one — along its own direction, with no lower bound behind it.
+    if (!(distance > 0)) return report_overlap(out, simplex);
+    const inv_distance = 1 / distance;
+    out[6] = dx * inv_distance; out[7] = dy * inv_distance; out[8] = dz * inv_distance;
+    out[9] = 0;
+    return distance;
+}