@woosh/meep-engine 3.21.0 → 3.23.0

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;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * # Capped cylinder — signed distance and its analytic gradient
+ *
+ * A cylinder about the **Y axis** of its own frame: `radius` across, `height`
+ * tall, so the flat caps sit at `±height/2`. Inigo Quilez's capped-cylinder
+ * field, written with the radial and axial distances named:
+ *
+ *     s  = ‖(x, z)‖
+ *     dr = s − r                     distance outside the infinite cylinder
+ *     da = |y| − h/2                 distance outside the slab
+ *     d  = ‖max(dr, 0), max(da, 0)‖ + min(max(dr, da), 0)
+ *
+ * The gradient is the two directions the field is built from, blended by how
+ * much of each the point is outside by:
+ *
+ *     û = (x, 0, z)/s                the radial direction
+ *     â = (0, sign(y), 0)            the axial direction
+ *     ∇d = (max(dr,0)·û + max(da,0)·â) / d      outside
+ *     ∇d = û or â, whichever of dr, da is larger        inside
+ *
+ * — which is exactly right on the rim, where both terms are live and the
+ * normalised sum sweeps continuously from the side to the cap.
+ *
+ * ## The axis is degenerate, and not in the way the others are
+ *
+ * On the axis, `û` does not exist. Unlike the sphere and the capsule this is
+ * *not* covered by `sdf3_degenerate_normal.js`'s `+Y`: a long thin cylinder's
+ * nearest exit from a point on its axis is sideways, and `+Y` is the one
+ * direction that is certainly not it. The fallback here is therefore `+X` — an
+ * arbitrary radial direction, which is what the configuration actually is:
+ * every radial direction is equally near and one has to be chosen.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Signed distance from a point to a capped cylinder's surface: negative inside.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @param {number} height total extent along Y
+ * @returns {number}
+ */
+export function sdf3_cylinder(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_cylinder_gradient(out: Float32Array | Float64Array | number[], out_offset: number, x: number, y: number, z: number, radius: number, height: number): number;
+//# sourceMappingURL=sdf3_cylinder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sdf3_cylinder.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/sdf/sdf3_cylinder.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;;;;GASG;AACH,iCAPW,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;;;;;GAWG;AACH,4CATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAuDlB"}

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

@@ -0,0 +1,126 @@
+import { SDF3_EPSILON } from "./sdf3_degenerate_normal.js";
+
+/**
+ * # Capped cylinder — signed distance and its analytic gradient
+ *
+ * A cylinder about the **Y axis** of its own frame: `radius` across, `height`
+ * tall, so the flat caps sit at `±height/2`. Inigo Quilez's capped-cylinder
+ * field, written with the radial and axial distances named:
+ *
+ *     s  = ‖(x, z)‖
+ *     dr = s − r                     distance outside the infinite cylinder
+ *     da = |y| − h/2                 distance outside the slab
+ *     d  = ‖max(dr, 0), max(da, 0)‖ + min(max(dr, da), 0)
+ *
+ * The gradient is the two directions the field is built from, blended by how
+ * much of each the point is outside by:
+ *
+ *     û = (x, 0, z)/s                the radial direction
+ *     â = (0, sign(y), 0)            the axial direction
+ *     ∇d = (max(dr,0)·û + max(da,0)·â) / d      outside
+ *     ∇d = û or â, whichever of dr, da is larger        inside
+ *
+ * — which is exactly right on the rim, where both terms are live and the
+ * normalised sum sweeps continuously from the side to the cap.
+ *
+ * ## The axis is degenerate, and not in the way the others are
+ *
+ * On the axis, `û` does not exist. Unlike the sphere and the capsule this is
+ * *not* covered by `sdf3_degenerate_normal.js`'s `+Y`: a long thin cylinder's
+ * nearest exit from a point on its axis is sideways, and `+Y` is the one
+ * direction that is certainly not it. The fallback here is therefore `+X` — an
+ * arbitrary radial direction, which is what the configuration actually is:
+ * every radial direction is equally near and one has to be chosen.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Signed distance from a point to a capped cylinder's surface: negative inside.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @param {number} height total extent along Y
+ * @returns {number}
+ */
+export function sdf3_cylinder(x, y, z, radius, height) {
+    const radial = Math.sqrt(x * x + z * z) - radius;
+    const axial = Math.abs(y) - height * 0.5;
+
+    const ext_r = radial > 0 ? radial : 0;
+    const ext_a = axial > 0 ? axial : 0;
+
+    const inner = radial > axial ? radial : axial;
+
+    return Math.sqrt(ext_r * ext_r + ext_a * ext_a) + (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} radius
+ * @param {number} height
+ * @returns {number} the signed distance
+ */
+export function sdf3_cylinder_gradient(out, out_offset, x, y, z, radius, height) {
+    const s = Math.sqrt(x * x + z * z);
+
+    const radial = s - radius;
+    const axial = Math.abs(y) - height * 0.5;
+
+    // The radial direction, with an arbitrary one chosen on the axis.
+    let ux;
+    let uz;
+
+    if (s < SDF3_EPSILON) {
+        ux = 1;
+        uz = 0;
+    } else {
+        const inverse = 1 / s;
+
+        ux = x * inverse;
+        uz = z * inverse;
+    }
+
+    const axis_sign = y < 0 ? -1 : 1;
+
+    const ext_r = radial > 0 ? radial : 0;
+    const ext_a = axial > 0 ? axial : 0;
+
+    const outside = Math.sqrt(ext_r * ext_r + ext_a * ext_a);
+
+    if (outside > SDF3_EPSILON) {
+        const inverse = 1 / outside;
+
+        const wr = ext_r * inverse;
+        const wa = ext_a * inverse;
+
+        out[out_offset] = ux * wr;
+        out[out_offset + 1] = axis_sign * wa;
+        out[out_offset + 2] = uz * wr;
+
+        return outside;
+    }
+
+    if (radial >= axial) {
+        out[out_offset] = ux;
+        out[out_offset + 1] = 0;
+        out[out_offset + 2] = uz;
+
+        return radial;
+    }
+
+    out[out_offset] = 0;
+    out[out_offset + 1] = axis_sign;
+    out[out_offset + 2] = 0;
+
+    return axial;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * # The direction to leave a shape by when there is no direction
+ *
+ * Every analytic gradient in this directory has one configuration where the
+ * true gradient does not exist: the centre of a sphere, the axis of a capsule,
+ * the axis of a cylinder, the centre of a cube. `‖x‖` is not differentiable at
+ * zero, and no continuous choice fixes that — it is a property of the distance
+ * field, not of the arithmetic.
+ *
+ * A gradient of `(0, 0, 0)` is the mathematically honest answer and it is the
+ * wrong one for every caller. The consumers of these functions are pushing
+ * something *out* of the shape: a zero gradient carries no force, so a particle
+ * that reaches the exact centre of a sphere stays there for ever. "It does not
+ * get stuck" is the second design commitment of the cloth system and the first
+ * thing a zero would break, so the answer is an arbitrary unit vector rather
+ * than no vector.
+ *
+ * `+Y`, because a degenerate case wants a deterministic answer more than a
+ * clever one, and because it agrees with the axis every axis-aligned primitive
+ * in this family is already built around.
+ *
+ * {@link compute_signed_distance_gradient_by_sampling} answers these
+ * configurations differently and worse: at a sphere's centre it returns
+ * `(1,1,1)/√3`, which is unit-length, plausible-looking, and a pure artefact of
+ * sampling three positive offsets from one point. That it is *an* answer rather
+ * than obviously nothing is the reason it went unnoticed.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_X: number;
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_Y: number;
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_Z: number;
+/**
+ * Below this a length is treated as zero. It is well above `Float32`'s own
+ * resolution over a garment-sized coordinate and well below any distance a
+ * caller can act on, which is the whole of what an epsilon here has to be.
+ * @type {number}
+ */
+export const SDF3_EPSILON: number;
+//# sourceMappingURL=sdf3_degenerate_normal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sdf3_degenerate_normal.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/sdf/sdf3_degenerate_normal.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;GAEG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;GAEG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;GAEG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;;;GAKG;AACH,2BAFU,MAAM,CAEiB"}

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

@@ -0,0 +1,53 @@
+/**
+ * # The direction to leave a shape by when there is no direction
+ *
+ * Every analytic gradient in this directory has one configuration where the
+ * true gradient does not exist: the centre of a sphere, the axis of a capsule,
+ * the axis of a cylinder, the centre of a cube. `‖x‖` is not differentiable at
+ * zero, and no continuous choice fixes that — it is a property of the distance
+ * field, not of the arithmetic.
+ *
+ * A gradient of `(0, 0, 0)` is the mathematically honest answer and it is the
+ * wrong one for every caller. The consumers of these functions are pushing
+ * something *out* of the shape: a zero gradient carries no force, so a particle
+ * that reaches the exact centre of a sphere stays there for ever. "It does not
+ * get stuck" is the second design commitment of the cloth system and the first
+ * thing a zero would break, so the answer is an arbitrary unit vector rather
+ * than no vector.
+ *
+ * `+Y`, because a degenerate case wants a deterministic answer more than a
+ * clever one, and because it agrees with the axis every axis-aligned primitive
+ * in this family is already built around.
+ *
+ * {@link compute_signed_distance_gradient_by_sampling} answers these
+ * configurations differently and worse: at a sphere's centre it returns
+ * `(1,1,1)/√3`, which is unit-length, plausible-looking, and a pure artefact of
+ * sampling three positive offsets from one point. That it is *an* answer rather
+ * than obviously nothing is the reason it went unnoticed.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_X = 0;
+
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_Y = 1;
+
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_Z = 0;
+
+/**
+ * Below this a length is treated as zero. It is well above `Float32`'s own
+ * resolution over a garment-sized coordinate and well below any distance a
+ * caller can act on, which is the whole of what an epsilon here has to be.
+ * @type {number}
+ */
+export const SDF3_EPSILON = 1e-9;

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

@@ -0,0 +1,52 @@
+/**
+ * # Half-space — signed distance and its analytic gradient
+ *
+ * The solid is `{ p : n·p − offset ≤ 0 }`, so `n` points **out** of the
+ * material and `offset` is how far along `n` the boundary plane sits from the
+ * origin.
+ *
+ *     d(x) = n·x − offset
+ *     ∇d(x) = n
+ *
+ * The only field in this family with no degenerate configuration anywhere and a
+ * gradient that is constant, which is why it is also the cheapest thing a
+ * simulation can collide against and the reason it is worth having as a shape
+ * rather than approximating with a very large box.
+ *
+ * PRECONDITION: `n` is unit length. A caller with an unnormalised normal has a
+ * scaled field rather than a distance field, and every consumer of a signed
+ * *distance* would then be wrong by that scale rather than merely imprecise.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Signed distance from a point to the boundary plane: negative inside the
+ * solid half-space.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} normal_x unit
+ * @param {number} normal_y unit
+ * @param {number} normal_z unit
+ * @param {number} offset
+ * @returns {number}
+ */
+export function sdf3_plane(x: number, y: number, z: number, normal_x: number, normal_y: number, normal_z: number, offset: 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} normal_x unit
+ * @param {number} normal_y unit
+ * @param {number} normal_z unit
+ * @param {number} offset
+ * @returns {number} the signed distance
+ */
+export function sdf3_plane_gradient(out: Float32Array | Float64Array | number[], out_offset: number, x: number, y: number, z: number, normal_x: number, normal_y: number, normal_z: number, offset: number): number;
+//# sourceMappingURL=sdf3_plane.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sdf3_plane.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/sdf/sdf3_plane.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;;;GAYG;AACH,8BATW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;GAaG;AACH,yCAXW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,UACN,MAAM,GACJ,MAAM,CAQlB"}