@woosh/meep-engine 3.25.0 → 3.27.0

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

@@ -8,6 +8,7 @@ import { aabb3_matrix4_project } from "../aabb/aabb3_matrix4_project.js";
 import { m4_extract_scale } from "../mat4/m4_extract_scale.js";
 import { m4_invert } from "../mat4/m4_invert.js";
 import { m4_make_scale } from "../mat4/m4_make_scale.js";
+import { Ray3 } from "../ray/Ray3.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 
 /**
@@ -278,6 +279,107 @@ export class TransformedShape3D extends AbstractShape3D {
         v3_matrix4_multiply(result, result_offset, scratch_v3_0, 0, this.__matrix);
     }
 
+    /**
+     * Ray ↔ transformed shape, with the ray given in the WRAPPER's frame. The cached inverse matrix
+     * carries the ray into the subject's frame, the subject answers there, and the answer comes back
+     * by two different maps: the point through the forward matrix, the normal through the inverse
+     * TRANSPOSE.
+     *
+     * Three things an affine transform does to a ray that a rigid pose ({@link PosedShape3D#raycast})
+     * does not:
+     *
+     *  - DISTANCE. The mapped direction is no longer unit — a scaled shape stretches travel along the
+     *    ray — so it is renormalised and the stretch factor is carried on `tMax` INTO the subject.
+     *    Nothing carries it back out, because the hit point is mapped by the matrix rather than
+     *    rebuilt from a distance, and an affine map takes the subject's point on its ray to this
+     *    ray's point at the matching parameter. So a caller recovering `t` as `(p − origin)·direction`
+     *    still gets the distance in THIS frame, which is what the family contract promises.
+     *  - NORMAL. It maps by (M⁻¹)ᵀ rather than by M — that is what keeps a normal perpendicular to
+     *    its surface under non-uniform scale — and is renormalised afterwards, because that map does
+     *    not preserve length. Done inline against the cached {@link inverse_transform}, not through
+     *    `v3_matrix4_rotate_normal`, which would invert the matrix again on every ray.
+     *  - ORIENTATION. Nothing to fix, as it happens: `n_here · d_here = scale · (n_subject ·
+     *    d_subject)` with `scale > 0`, so a normal the subject turned to meet its ray meets this one
+     *    too. True even of a mirroring matrix — its determinant is negative, but that scale, a vector
+     *    length, is not.
+     *
+     * A transform that was never successfully inverted — a singular matrix, or a shape whose
+     * `transform` was never set — leaves the cached inverse zeroed, and the mapped direction with it;
+     * that is reported as a miss rather than propagated onward as NaN. Note the narrower case this
+     * does NOT rescue: {@link m4_invert} leaves a PREVIOUS inverse in place when it refuses, so a
+     * shape handed a singular transform after a good one goes on casting against the older one. That
+     * hazard belongs to every method here that reads the cached inverse, not to this one.
+     *
+     * The physics ray query does not come through here; it uses `refine_ray_transformed`, which does
+     * the same mapping on loose scalars and, reporting a distance rather than a point, divides that
+     * distance by the stretch factor instead of pushing a point through the matrix.
+     *
+     * @param {Float32Array|number[]} hit out: [px, py, pz, nx, ny, nz]
+     * @param {Ray3} ray wrapper-frame ray (origin in [0..2], unit direction in [3..5], tMax in [6])
+     * @returns {boolean} whether anything was hit
+     */
+    raycast(hit, ray) {
+        const subject = this.__subject;
+
+        if (subject === null) {
+            return false;
+        }
+
+        const inverse = this.__inverse_matrix;
+
+        // Direction takes the linear part only, so it is written out rather than run through
+        // v3_matrix4_multiply — and its length is needed anyway.
+        const dx = ray[3], dy = ray[4], dz = ray[5];
+
+        const sdx = inverse[0] * dx + inverse[4] * dy + inverse[8] * dz;
+        const sdy = inverse[1] * dx + inverse[5] * dy + inverse[9] * dz;
+        const sdz = inverse[2] * dx + inverse[6] * dy + inverse[10] * dz;
+
+        // How much longer one unit of travel here is in the subject's frame.
+        const scale = Math.sqrt(sdx * sdx + sdy * sdy + sdz * sdz);
+
+        if (!(scale > 0)) {
+            // Singular (or never-inverted) transform: the direction has no image to cast along.
+            return false;
+        }
+
+        const inv_scale = 1 / scale;
+
+        // Allocated per call rather than kept as a module scratch: a transformed shape may wrap another
+        // wrapper, and every level of that recursion needs its own sub-ray alive across the call below.
+        const subject_ray = new Ray3();
+
+        v3_matrix4_multiply(subject_ray, 0, ray, 0, inverse);
+
+        subject_ray[3] = sdx * inv_scale;
+        subject_ray[4] = sdy * inv_scale;
+        subject_ray[5] = sdz * inv_scale;
+        subject_ray[6] = ray[6] * scale;
+
+        if (!subject.raycast(hit, subject_ray)) {
+            return false;
+        }
+
+        // Point: the full forward transform, in place. v3_matrix4_multiply reads all three components
+        // before writing any, so `hit` may be both its source and its destination.
+        v3_matrix4_multiply(hit, 0, hit, 0, this.__matrix);
+
+        // Normal: (M⁻¹)ᵀ · n, then renormalised.
+        const nx = hit[3], ny = hit[4], nz = hit[5];
+
+        const wx = inverse[0] * nx + inverse[1] * ny + inverse[2] * nz;
+        const wy = inverse[4] * nx + inverse[5] * ny + inverse[6] * nz;
+        const wz = inverse[8] * nx + inverse[9] * ny + inverse[10] * nz;
+
+        const inv_length = 1 / Math.sqrt(wx * wx + wy * wy + wz * wz);
+
+        hit[3] = wx * inv_length;
+        hit[4] = wy * inv_length;
+        hit[5] = wz * inv_length;
+
+        return true;
+    }
+
     /**
      *
      * @param {TransformedShape3D} other

package/src/core/geom/3d/shape/UnionShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UnionShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnionShape3D.js"],"names":[],"mappings":"AA2BA;IAkII;;;;OAIG;IACH,sBAHW,eAAe,EAAE,GACf,YAAY,CAYxB;IAhJD;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,kCAA+B;IAE/B,qBAAkB;IAClB,qBAAmB;IACnB,uBAAqB;IAErB,wCAgCC;IAED;;;OAGG;IACH,mCAkBC;IAED;;;OAGG;IACH,2CA+CC;IA2DD,mEAEC;IAED,6CAaC;IAED,oCAYC;IAED,kFAoDC;IAED,qGAyBC;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;IA6BL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;CApBpC;gCArV+B,sBAAsB"}
+{"version":3,"file":"UnionShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnionShape3D.js"],"names":[],"mappings":"AA4BA;IAkII;;;;OAIG;IACH,sBAHW,eAAe,EAAE,GACf,YAAY,CAYxB;IAhJD;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,kCAA+B;IAE/B,qBAAkB;IAClB,qBAAmB;IACnB,uBAAqB;IAErB,wCAgCC;IAED;;;OAGG;IACH,mCAkBC;IAED;;;OAGG;IACH,2CA+CC;IA2DD,mEAEC;IAED,6CAaC;IAED,oCAYC;IAED,kFAoDC;IAED,qGAyBC;IAiED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;IA6BL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;CApBpC;gCApZ+B,sBAAsB"}

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

@@ -7,6 +7,7 @@ import { min2 } from "../../../math/min2.js";
 import { seededRandom } from "../../../math/random/seededRandom.js";
 import { number_compare_ascending } from "../../../primitives/numbers/number_compare_ascending.js";
 import { v3_dot } from "../../vec3/v3_dot.js";
+import { Ray3 } from "../ray/Ray3.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
 
@@ -326,6 +327,69 @@ export class UnionShape3D extends AbstractShape3D {
 
     }
 
+    /**
+     * Nearest hit across the children, which all share the union's own frame — so, unlike the other
+     * two wrappers, there is no ray to re-frame and no answer to map back.
+     *
+     * Each child is handed the best distance so far as its `tMax`, so a child can only report a hit by
+     * beating every child before it. That is what makes it safe to let the children write straight into
+     * `hit`: a child that writes is a child that won, and a child that misses leaves `hit` untouched by
+     * the family convention, so the standing answer survives it.
+     *
+     * The distance to narrow on is recovered from the point the child wrote, as
+     * `(p − origin)·direction` — the shape-level API hands back a point where the narrowphase's
+     * `refine_ray_union` has the distance already. Two children closer together than a float32 ulp
+     * of the coordinates involved are therefore a tie, settled by whichever is listed last.
+     *
+     * That ulp is the API's, not this method's: a child writes `origin + direction · t` into a float32
+     * `hit` before anything here reads it, so the resolution is already spent by the time a LONE shape
+     * answers. Measured against the narrowphase over 4,000 rays per scale, this union's error tracks a
+     * lone sphere's within a factor of two everywhere — 3e-6 near the origin, 1e-3 at 1e4 out, 0.1 at
+     * 1e6, where one float32 ulp IS 0.06 world units. A compound collider that far out wants a float64
+     * ray, which is what the narrowphase path already gives it; it does not want a different union.
+     *
+     * DIVERGENCE from `refine_ray_union`: that one carries a sentinel for a shape it cannot answer and
+     * poisons the entire union with it, because reporting the nearest of the children it COULD answer
+     * would be a hit confidently too far. There is no sentinel in this API — a child that does not
+     * implement `raycast` throws from {@link AbstractShape3D#raycast} — but the effect is the one that
+     * matters: every child is visited unconditionally, so such a child is never quietly skipped, and
+     * the throw leaves the union with no answer rather than a partial one.
+     *
+     * @param {Float32Array|number[]} hit out: [px, py, pz, nx, ny, nz]
+     * @param {Ray3} ray union-frame ray (origin in [0..2], unit direction in [3..5], tMax in [6])
+     * @returns {boolean} whether anything was hit
+     */
+    raycast(hit, ray) {
+        const children = this.children;
+        const child_count = children.length;
+
+        const ox = ray[0], oy = ray[1], oz = ray[2];
+        const dx = ray[3], dy = ray[4], dz = ray[5];
+
+        // Allocated per call rather than kept as a module scratch: a union may hold another wrapper,
+        // and every level of that recursion needs its own narrowing ray alive across the loop below.
+        const child_ray = new Ray3();
+
+        child_ray[0] = ox; child_ray[1] = oy; child_ray[2] = oz;
+        child_ray[3] = dx; child_ray[4] = dy; child_ray[5] = dz;
+        child_ray[6] = ray[6];
+
+        let found = false;
+
+        for (let i = 0; i < child_count; i++) {
+            if (!children[i].raycast(hit, child_ray)) {
+                continue;
+            }
+
+            // The direction is unit, so the hit's projection onto it IS the distance travelled.
+            child_ray[6] = (hit[0] - ox) * dx + (hit[1] - oy) * dy + (hit[2] - oz) * dz;
+
+            found = true;
+        }
+
+        return found;
+    }
+
     /**
      *
      * @param {UnionShape3D} other