@woosh/meep-engine 3.22.0 → 3.23.0

package/src/core/geom/3d/shape/PlaneShape3D.js

@@ -0,0 +1,251 @@
+import { assert } from "../../../assert.js";
+import { hash_mix2 } from "../../../math/hash/hash_mix2.js";
+import { hash_mix3 } from "../../../math/hash/hash_mix3.js";
+import { computeHashFloat } from "../../../primitives/numbers/computeHashFloat.js";
+import { AbstractShape3D } from "./AbstractShape3D.js";
+import { sdf3_plane, sdf3_plane_gradient } from "./sdf/sdf3_plane.js";
+
+/**
+ * # An infinite half-space
+ *
+ * The solid is `{ p : n·p − offset ≤ 0 }` — everything on the far side of the
+ * boundary plane from the direction {@link normal} points in. So `normal` is
+ * the **outward** surface normal, exactly as it is for every other shape's
+ * signed-distance gradient, and `offset` is how far along it the boundary sits
+ * from the body's local origin.
+ *
+ * A ground plane is `normal = (0, 1, 0), offset = 0`: solid below, open above.
+ *
+ * ## Why a shape rather than a very large box
+ *
+ * A box standing in for a ground plane has to be large enough that nothing ever
+ * reaches its edge and thin enough that nothing tunnels through it, and those
+ * two requirements pull against each other in `Float32`. It also costs a
+ * six-face field evaluation where the honest answer is one dot product, and its
+ * gradient has creases that the thing it is standing in for does not.
+ *
+ * ## What it deliberately does not implement, and why that is the honest answer
+ *
+ * A half-space is convex and **unbounded**, and three of
+ * {@link AbstractShape3D}'s methods are only meaningful on a bounded set:
+ *
+ * - {@link support} — GJK's operand. `argmax(p·d)` over a half-space is at
+ *   infinity for all but one direction, so a plane is not a GJK operand and
+ *   pretending otherwise with a large finite point would silently produce wrong
+ *   contact manifolds rather than a loud failure. Left unimplemented, which
+ *   makes the base class's `Not Implemented` the answer.
+ * - {@link sample_random_point_in_volume} — the base class's rejection sampler
+ *   needs a finite bounding box. There is no uniform distribution on an
+ *   infinite volume.
+ * - {@link volume} and {@link surface_area} — both `Infinity`, stated rather
+ *   than thrown, because a caller summing volumes gets an answer that is true.
+ *
+ * {@link compute_bounding_box} **does** answer, with `±Infinity` on the
+ * unbounded axes. That is what the set is. A consumer that cannot hold an
+ * infinite AABB — a BVH leaf, a broadphase grid — must not be handed a plane,
+ * and the cloth collider index that motivated this shape derives a plane's
+ * bounds from its normal rather than by projecting this box (`aabb3_matrix4_project`
+ * would multiply an infinity by a zero matrix element and get `NaN`).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PlaneShape3D extends AbstractShape3D {
+
+    /**
+     * Outward unit normal, x.
+     * @type {number}
+     */
+    normal_x = 0;
+
+    /**
+     * Outward unit normal, y.
+     * @type {number}
+     */
+    normal_y = 1;
+
+    /**
+     * Outward unit normal, z.
+     * @type {number}
+     */
+    normal_z = 0;
+
+    /**
+     * Distance from the local origin to the boundary plane, along
+     * {@link normal_x}/{@link normal_y}/{@link normal_z}.
+     * @type {number}
+     */
+    offset = 0;
+
+    /**
+     * @param {number} normal_x
+     * @param {number} normal_y
+     * @param {number} normal_z
+     * @param {number} [offset]
+     * @returns {PlaneShape3D}
+     */
+    static from(normal_x, normal_y, normal_z, offset = 0) {
+        assert.isNumber(normal_x, 'normal_x');
+        assert.isNumber(normal_y, 'normal_y');
+        assert.isNumber(normal_z, 'normal_z');
+        assert.isNumber(offset, 'offset');
+
+        const length = Math.sqrt(normal_x * normal_x + normal_y * normal_y + normal_z * normal_z);
+
+        assert.greaterThan(length, 0, 'plane normal length');
+
+        const r = new PlaneShape3D();
+
+        // Normalised on construction rather than trusted, because every method
+        // below reads the field as a *distance* field and an unnormalised
+        // normal makes all of them wrong by a scale rather than imprecise.
+        const inverse = 1 / length;
+
+        r.normal_x = normal_x * inverse;
+        r.normal_y = normal_y * inverse;
+        r.normal_z = normal_z * inverse;
+        r.offset = offset;
+
+        return r;
+    }
+
+    get volume() {
+        return Infinity;
+    }
+
+    get surface_area() {
+        return Infinity;
+    }
+
+    signed_distance_at_point(point) {
+        return sdf3_plane(
+            point[0], point[1], point[2],
+            this.normal_x, this.normal_y, this.normal_z, this.offset
+        );
+    }
+
+    signed_distance_gradient_at_point(result, point) {
+        return sdf3_plane_gradient(
+            result, 0,
+            point[0], point[1], point[2],
+            this.normal_x, this.normal_y, this.normal_z, this.offset
+        );
+    }
+
+    nearest_point_on_surface(result, reference) {
+        const distance = this.signed_distance_at_point(reference);
+
+        result[0] = reference[0] - this.normal_x * distance;
+        result[1] = reference[1] - this.normal_y * distance;
+        result[2] = reference[2] - this.normal_z * distance;
+    }
+
+    contains_point(point) {
+        return this.signed_distance_at_point(point) < 0;
+    }
+
+    /**
+     * The half-space's own bounds: finite on the one axis the normal is aligned
+     * with when it is axis-aligned, infinite everywhere else. See the class
+     * docblock for what a consumer is expected to do with that.
+     *
+     * @param {number[]|ArrayLike<number>|Float32Array|Float64Array} result
+     */
+    compute_bounding_box(result) {
+        result[0] = -Infinity;
+        result[1] = -Infinity;
+        result[2] = -Infinity;
+        result[3] = Infinity;
+        result[4] = Infinity;
+        result[5] = Infinity;
+
+        // A general normal makes every axis unbounded. An axis-aligned one — the
+        // overwhelmingly common case, and every ground plane — bounds exactly
+        // one of them, and saying so is what lets a caller cull against a floor.
+        if (this.normal_x === 1) { result[3] = this.offset; }
+        else if (this.normal_x === -1) { result[0] = -this.offset; }
+        else if (this.normal_y === 1) { result[4] = this.offset; }
+        else if (this.normal_y === -1) { result[1] = -this.offset; }
+        else if (this.normal_z === 1) { result[5] = this.offset; }
+        else if (this.normal_z === -1) { result[2] = -this.offset; }
+    }
+
+    /**
+     * Ray ↔ half-space, in the shape's local frame. A ray that starts inside
+     * the solid is already in contact and reports a hit at `t = 0` with the
+     * boundary normal, which is the convention every other shape here follows
+     * for an origin inside it.
+     *
+     * @param {Float32Array|number[]} hit
+     * @param {Ray3} ray
+     * @returns {boolean}
+     */
+    raycast(hit, ray) {
+        const nx = this.normal_x;
+        const ny = this.normal_y;
+        const nz = this.normal_z;
+
+        const distance = ray[0] * nx + ray[1] * ny + ray[2] * nz - this.offset;
+
+        const along = ray[3] * nx + ray[4] * ny + ray[5] * nz;
+
+        let t;
+
+        if (distance <= 0) {
+            t = 0;
+        } else if (along >= 0) {
+            // Outside and travelling away from — or exactly along — the plane.
+            return false;
+        } else {
+            t = -distance / along;
+
+            if (t > ray[6]) {
+                return false;
+            }
+        }
+
+        hit[0] = ray[0] + ray[3] * t;
+        hit[1] = ray[1] + ray[4] * t;
+        hit[2] = ray[2] + ray[5] * t;
+        hit[3] = nx;
+        hit[4] = ny;
+        hit[5] = nz;
+
+        return true;
+    }
+
+    equals(other) {
+        return super.equals(other)
+            && this.normal_x === other.normal_x
+            && this.normal_y === other.normal_y
+            && this.normal_z === other.normal_z
+            && this.offset === other.offset;
+    }
+
+    hash() {
+        return hash_mix2(
+            hash_mix3(
+                computeHashFloat(this.normal_x),
+                computeHashFloat(this.normal_y),
+                computeHashFloat(this.normal_z)
+            ),
+            computeHashFloat(this.offset)
+        );
+    }
+}
+
+/**
+ * Fast type-check marker, following {@link SphereShape3D#isSphereShape3D}. A
+ * consumer that cannot hold an unbounded shape tests this rather than reaching
+ * for `instanceof` across a module boundary.
+ * @readonly
+ * @type {boolean}
+ */
+PlaneShape3D.prototype.isPlaneShape3D = true;
+
+/**
+ * The ground: solid below `y = 0`, open above it. Shared and immutable, in the
+ * same spirit as {@link UnitSphereShape3D}`.INSTANCE`.
+ * @type {PlaneShape3D}
+ */
+PlaneShape3D.GROUND = PlaneShape3D.from(0, 1, 0, 0);

package/src/core/geom/3d/shape/SphereShape3D.js

@@ -3,7 +3,7 @@ import { random_point_in_sphere } from "../../random/random_point_in_sphere.js";
 import { sphere_raycast } from "../sphere/sphere_raycast.js";
 import { v3_length } from "../../vec3/v3_length.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
-import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
+import { sdf3_sphere, sdf3_sphere_gradient } from "./sdf/sdf3_sphere.js";
 
 /**
  * Sphere of arbitrary `radius`, centred at the body's local origin.
@@ -98,11 +98,11 @@ export class SphereShape3D extends AbstractShape3D {
     }
 
     signed_distance_gradient_at_point(result, point) {
-        return compute_signed_distance_gradient_by_sampling(result, this, point);
+        return sdf3_sphere_gradient(result, 0, point[0], point[1], point[2], this.radius);
     }
 
     signed_distance_at_point(point) {
-        return v3_length(point[0], point[1], point[2]) - this.radius;
+        return sdf3_sphere(point[0], point[1], point[2], this.radius);
     }
 
     contains_point(point) {

package/src/core/geom/3d/shape/json/shape_to_type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shape_to_type.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/shape_to_type.js"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,uDAFa,MAAM,CAoBlB"}
+{"version":3,"file":"shape_to_type.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/shape_to_type.js"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,uDAFa,MAAM,CAsBlB"}

package/src/core/geom/3d/shape/json/shape_to_type.js

@@ -1,5 +1,6 @@
 import { CapsuleShape3D } from "../CapsuleShape3D.js";
 import { CylinderShape3D } from "../CylinderShape3D.js";
+import { PlaneShape3D } from "../PlaneShape3D.js";
 import { SphereShape3D } from "../SphereShape3D.js";
 import { TransformedShape3D } from "../TransformedShape3D.js";
 import { UnionShape3D } from "../UnionShape3D.js";
@@ -25,6 +26,8 @@ export function shape_to_type(shape) {
         return 'capsule';
     } else if (shape instanceof CylinderShape3D) {
         return 'cylinder';
+    } else if (shape instanceof PlaneShape3D) {
+        return 'plane';
     } else {
         throw new Error('Unsupported shape');
     }

package/src/core/geom/3d/shape/json/type_adapters.d.ts

@@ -44,6 +44,19 @@ export namespace type_adapters {
             height: number;
         };
     }
+    namespace plane {
+        function read({ normal, offset }: {
+            normal: any;
+            offset: any;
+        }): PlaneShape3D;
+        /**
+         * @param {PlaneShape3D} object
+         */
+        function write(object: PlaneShape3D): {
+            normal: number[];
+            offset: number;
+        };
+    }
     namespace transform {
         function read({ transform, subject }: {
             transform: any;
@@ -75,6 +88,7 @@ import { UnitCubeShape3D } from "../UnitCubeShape3D.js";
 import { SphereShape3D } from "../SphereShape3D.js";
 import { CapsuleShape3D } from "../CapsuleShape3D.js";
 import { CylinderShape3D } from "../CylinderShape3D.js";
+import { PlaneShape3D } from "../PlaneShape3D.js";
 import { TransformedShape3D } from "../TransformedShape3D.js";
 import { UnionShape3D } from "../UnionShape3D.js";
 //# sourceMappingURL=type_adapters.d.ts.map

package/src/core/geom/3d/shape/json/type_adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type_adapters.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/type_adapters.js"],"names":[],"mappings":";;QAYQ,iCAEC;QACD,qBAEC;;;QAGD;;0BAQC;QACD;;WAEG;QACH;;;;UAIC;;;QAGD;;;2BAEC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;;4BAEC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;;+BAIC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;yBAIC;QACD;;;WAGG;QACH;;UAIC;;;gCA9FuB,uBAAuB;8BAHzB,qBAAqB;+BAFpB,sBAAsB;gCACrB,uBAAuB;mCAEpB,0BAA0B;6BAChC,oBAAoB"}
+{"version":3,"file":"type_adapters.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/type_adapters.js"],"names":[],"mappings":";;QAaQ,iCAEC;QACD,qBAEC;;;QAGD;;0BAQC;QACD;;WAEG;QACH;;;;UAIC;;;QAGD;;;2BAEC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;;4BAEC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;;yBAEC;QACD;;WAEG;QACH;;;UAKC;;;QAGD;;;+BAIC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;yBAIC;QACD;;;WAGG;QACH;;UAIC;;;gCA5GuB,uBAAuB;8BAHzB,qBAAqB;+BAHpB,sBAAsB;gCACrB,uBAAuB;6BAC1B,oBAAoB;mCAEd,0BAA0B;6BAChC,oBAAoB"}

package/src/core/geom/3d/shape/json/type_adapters.js

@@ -1,5 +1,6 @@
 import { CapsuleShape3D } from "../CapsuleShape3D.js";
 import { CylinderShape3D } from "../CylinderShape3D.js";
+import { PlaneShape3D } from "../PlaneShape3D.js";
 import { SphereShape3D } from "../SphereShape3D.js";
 import { TransformedShape3D } from "../TransformedShape3D.js";
 import { UnionShape3D } from "../UnionShape3D.js";
@@ -66,6 +67,20 @@ export const type_adapters = {
             };
         }
     },
+    'plane': {
+        read({ normal, offset }) {
+            return PlaneShape3D.from(normal[0], normal[1], normal[2], offset);
+        },
+        /**
+         * @param {PlaneShape3D} object
+         */
+        write(object) {
+            return {
+                normal: [object.normal_x, object.normal_y, object.normal_z],
+                offset: object.offset
+            };
+        }
+    },
     'transform': {
         read({ transform, subject }) {
             const subject_shape = shape_from_json(subject);

package/src/core/geom/3d/shape/sdf/sdf3_box.d.ts

@@ -0,0 +1,51 @@
+/**
+ * # Axis-aligned box — signed distance and its analytic gradient
+ *
+ * A box centred at the origin of its own frame, spanning `±half_extent` on each
+ * axis. Inigo Quilez's exact box field, with `q = |x| − h`:
+ *
+ *     d(x) = ‖max(q, 0)‖ + min(max(qx, qy, qz), 0)
+ *
+ * The gradient has two regimes and that is the whole of the derivation:
+ *
+ * - **Outside** (some component of `q` is positive) the field is the distance
+ *   to the nearest point on the box, so the gradient is the unit vector from
+ *   that point — `sign(x) · max(q, 0)` normalised.
+ * - **Inside** (every component of `q` is negative) the field is
+ *   `max(qx, qy, qz)`, a plain maximum, so the gradient is the signed unit axis
+ *   of whichever component attains it — the nearest face.
+ *
+ * Inside a box the field is not differentiable on the medial surface, where two
+ * faces are equidistant. The maximum picks one, which is the standard answer
+ * and is what a caller wants: a consistent nearest face, not an average of two.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Signed distance from a point to a box's surface: negative inside.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} half_x
+ * @param {number} half_y
+ * @param {number} half_z
+ * @returns {number}
+ */
+export function sdf3_box(x: number, y: number, z: number, half_x: number, half_y: number, half_z: number): number;
+/**
+ * Signed distance and the unit outward gradient, written to `out`.
+ *
+ * @param {Float32Array|Float64Array|number[]} out gradient destination
+ * @param {number} out_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} half_x
+ * @param {number} half_y
+ * @param {number} half_z
+ * @returns {number} the signed distance
+ */
+export function sdf3_box_gradient(out: Float32Array | Float64Array | number[], out_offset: number, x: number, y: number, z: number, half_x: number, half_y: number, half_z: number): number;
+//# sourceMappingURL=sdf3_box.d.ts.map

package/src/core/geom/3d/shape/sdf/sdf3_box.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdf3_box.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/sdf/sdf3_box.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;GAUG;AACH,4BARW,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAkBlB;AAED;;;;;;;;;;;;GAYG;AACH,uCAVW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CA6ClB"}

package/src/core/geom/3d/shape/sdf/sdf3_box.js

@@ -0,0 +1,113 @@
+import { SDF3_EPSILON } from "./sdf3_degenerate_normal.js";
+
+/**
+ * # Axis-aligned box — signed distance and its analytic gradient
+ *
+ * A box centred at the origin of its own frame, spanning `±half_extent` on each
+ * axis. Inigo Quilez's exact box field, with `q = |x| − h`:
+ *
+ *     d(x) = ‖max(q, 0)‖ + min(max(qx, qy, qz), 0)
+ *
+ * The gradient has two regimes and that is the whole of the derivation:
+ *
+ * - **Outside** (some component of `q` is positive) the field is the distance
+ *   to the nearest point on the box, so the gradient is the unit vector from
+ *   that point — `sign(x) · max(q, 0)` normalised.
+ * - **Inside** (every component of `q` is negative) the field is
+ *   `max(qx, qy, qz)`, a plain maximum, so the gradient is the signed unit axis
+ *   of whichever component attains it — the nearest face.
+ *
+ * Inside a box the field is not differentiable on the medial surface, where two
+ * faces are equidistant. The maximum picks one, which is the standard answer
+ * and is what a caller wants: a consistent nearest face, not an average of two.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Signed distance from a point to a box's surface: negative inside.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} half_x
+ * @param {number} half_y
+ * @param {number} half_z
+ * @returns {number}
+ */
+export function sdf3_box(x, y, z, half_x, half_y, half_z) {
+    const qx = Math.abs(x) - half_x;
+    const qy = Math.abs(y) - half_y;
+    const qz = Math.abs(z) - half_z;
+
+    const ex = qx > 0 ? qx : 0;
+    const ey = qy > 0 ? qy : 0;
+    const ez = qz > 0 ? qz : 0;
+
+    let inner = qx > qy ? qx : qy;
+
+    if (qz > inner) {
+        inner = qz;
+    }
+
+    return Math.sqrt(ex * ex + ey * ey + ez * ez) + (inner < 0 ? inner : 0);
+}
+
+/**
+ * Signed distance and the unit outward gradient, written to `out`.
+ *
+ * @param {Float32Array|Float64Array|number[]} out gradient destination
+ * @param {number} out_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} half_x
+ * @param {number} half_y
+ * @param {number} half_z
+ * @returns {number} the signed distance
+ */
+export function sdf3_box_gradient(out, out_offset, x, y, z, half_x, half_y, half_z) {
+    const qx = Math.abs(x) - half_x;
+    const qy = Math.abs(y) - half_y;
+    const qz = Math.abs(z) - half_z;
+
+    const ex = qx > 0 ? qx : 0;
+    const ey = qy > 0 ? qy : 0;
+    const ez = qz > 0 ? qz : 0;
+
+    const outside = Math.sqrt(ex * ex + ey * ey + ez * ez);
+
+    if (outside > SDF3_EPSILON) {
+        const inverse = 1 / outside;
+
+        out[out_offset] = (x < 0 ? -ex : ex) * inverse;
+        out[out_offset + 1] = (y < 0 ? -ey : ey) * inverse;
+        out[out_offset + 2] = (z < 0 ? -ez : ez) * inverse;
+
+        return outside;
+    }
+
+    // Inside, or exactly on the surface. The field is `max(q)` and its gradient
+    // is the signed unit axis of the component that attains it — the nearest
+    // face, and the direction that leaves the box soonest.
+    out[out_offset] = 0;
+    out[out_offset + 1] = 0;
+    out[out_offset + 2] = 0;
+
+    if (qx >= qy && qx >= qz) {
+        out[out_offset] = x < 0 ? -1 : 1;
+
+        return qx;
+    }
+
+    if (qy >= qz) {
+        out[out_offset + 1] = y < 0 ? -1 : 1;
+
+        return qy;
+    }
+
+    out[out_offset + 2] = z < 0 ? -1 : 1;
+
+    return qz;
+}

package/src/core/geom/3d/shape/sdf/sdf3_capsule.d.ts

@@ -0,0 +1,46 @@
+/**
+ * # Capsule — signed distance and its analytic gradient
+ *
+ * A capsule about the **Y axis** of its own frame: a segment of length
+ * `height` — so `±height/2` — swept by a sphere of `radius`. This is
+ * {@link CapsuleShape3D}'s parameterisation, and the total extent along Y is
+ * `height + 2·radius`.
+ *
+ *     d(x) = ‖x − c(x)‖ − r,   c(x) = (0, clamp(y, −h/2, +h/2), 0)
+ *     ∇d(x) = (x − c(x))/‖x − c(x)‖
+ *
+ * The gradient is a sphere's gradient about the nearest point on the segment,
+ * which is the whole reason a capsule is cheap: collapsing Y onto the segment
+ * turns it into the sphere case, exactly once, with no branch on which cap.
+ *
+ * Degenerate on the segment itself, where the distance is zero and no direction
+ * is nearer than any other. See `sdf3_degenerate_normal.js`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Signed distance from a point to a capsule's surface: negative inside.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @param {number} height length of the central segment — total extent is `height + 2·radius`
+ * @returns {number}
+ */
+export function sdf3_capsule(x: number, y: number, z: number, radius: number, height: number): number;
+/**
+ * Signed distance and the unit outward gradient, written to `out`.
+ *
+ * @param {Float32Array|Float64Array|number[]} out gradient destination
+ * @param {number} out_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @param {number} height
+ * @returns {number} the signed distance
+ */
+export function sdf3_capsule_gradient(out: Float32Array | Float64Array | number[], out_offset: number, x: number, y: number, z: number, radius: number, height: number): number;
+//# sourceMappingURL=sdf3_capsule.d.ts.map

package/src/core/geom/3d/shape/sdf/sdf3_capsule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdf3_capsule.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/sdf/sdf3_capsule.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;GASG;AACH,gCAPW,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAQlB;AAED;;;;;;;;;;;GAWG;AACH,2CATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAwBlB"}

package/src/core/geom/3d/shape/sdf/sdf3_capsule.js

@@ -0,0 +1,82 @@
+import {
+    SDF3_DEGENERATE_NORMAL_X,
+    SDF3_DEGENERATE_NORMAL_Y,
+    SDF3_DEGENERATE_NORMAL_Z,
+    SDF3_EPSILON
+} from "./sdf3_degenerate_normal.js";
+
+/**
+ * # Capsule — signed distance and its analytic gradient
+ *
+ * A capsule about the **Y axis** of its own frame: a segment of length
+ * `height` — so `±height/2` — swept by a sphere of `radius`. This is
+ * {@link CapsuleShape3D}'s parameterisation, and the total extent along Y is
+ * `height + 2·radius`.
+ *
+ *     d(x) = ‖x − c(x)‖ − r,   c(x) = (0, clamp(y, −h/2, +h/2), 0)
+ *     ∇d(x) = (x − c(x))/‖x − c(x)‖
+ *
+ * The gradient is a sphere's gradient about the nearest point on the segment,
+ * which is the whole reason a capsule is cheap: collapsing Y onto the segment
+ * turns it into the sphere case, exactly once, with no branch on which cap.
+ *
+ * Degenerate on the segment itself, where the distance is zero and no direction
+ * is nearer than any other. See `sdf3_degenerate_normal.js`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Signed distance from a point to a capsule's surface: negative inside.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @param {number} height length of the central segment — total extent is `height + 2·radius`
+ * @returns {number}
+ */
+export function sdf3_capsule(x, y, z, radius, height) {
+    const half = height * 0.5;
+
+    const dy = y < -half ? y + half : (y > half ? y - half : 0);
+
+    return Math.sqrt(x * x + dy * dy + z * z) - radius;
+}
+
+/**
+ * Signed distance and the unit outward gradient, written to `out`.
+ *
+ * @param {Float32Array|Float64Array|number[]} out gradient destination
+ * @param {number} out_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @param {number} height
+ * @returns {number} the signed distance
+ */
+export function sdf3_capsule_gradient(out, out_offset, x, y, z, radius, height) {
+    const half = height * 0.5;
+
+    const dy = y < -half ? y + half : (y > half ? y - half : 0);
+
+    const length = Math.sqrt(x * x + dy * dy + z * z);
+
+    if (length < SDF3_EPSILON) {
+        out[out_offset] = SDF3_DEGENERATE_NORMAL_X;
+        out[out_offset + 1] = SDF3_DEGENERATE_NORMAL_Y;
+        out[out_offset + 2] = SDF3_DEGENERATE_NORMAL_Z;
+
+        return -radius;
+    }
+
+    const inverse = 1 / length;
+
+    out[out_offset] = x * inverse;
+    out[out_offset + 1] = dy * inverse;
+    out[out_offset + 2] = z * inverse;
+
+    return length - radius;
+}