@woosh/meep-engine 3.14.4 → 3.14.5

package/src/shade/renderer/animation/skin_clip_scale_conflicts.js

@@ -0,0 +1,199 @@
+import { assert } from "../../../core/assert.js";
+import AABB2 from "../../../core/geom/2d/aabb/AABB2.js";
+import {
+    animation_curve_compute_aabb
+} from "../../../engine/animation/curve/animation_curve_compute_aabb.js";
+import { Node3DProperty } from "../object_property/Node3DProperty.js";
+
+/**
+ * How far from 1 a scale curve may run and still count as not scaling.
+ *
+ * The same order as the `IDENTITY_EPSILON` {@link ShadeAnimationChannel#optimize} drops an identity
+ * channel by, and for the same reason: a scale curve authored as the constant 1 arrives with f32
+ * round-trip noise on it and is not a scale. Anything a person authored is orders above this.
+ *
+ * @type {number}
+ */
+const UNIT_EPSILON = 1e-5;
+
+/**
+ * Scratch for one curve's value range. Nothing here re-enters.
+ *
+ * @type {AABB2}
+ */
+const _bounds = new AABB2();
+
+/**
+ * The channels of a clip that would scale this skin's joints out from under the frame it is
+ * deformed in.
+ *
+ * ## Why this is worth asking
+ *
+ * {@link skin_normalize_mesh_frame} makes `inverse(mesh.global) × joint.global × inverse_bind`
+ * rigid, and rigid is what a dual quaternion can carry. It does that with a **constant** correction,
+ * which is sound because the frame and the joints share their ancestors and a placement multiplies
+ * both on the left. A clip that scales a joint breaks that: the scale enters `joint.global` and not
+ * the frame, the fold stops being rigid, and no choice of frame fixes it —
+ * `SKINNING_FRAME_PLAN.md` §4 is the ladder out and neither of its rungs is built.
+ *
+ * The failure is per-frame and on the GPU, where nothing can see it. This is the same question asked
+ * **statically**, off the clip's own curves, at registration: exact, cheap, and it needs no device.
+ *
+ * ## What counts
+ *
+ * Not "the channel targets a joint" — that understates it. What matters is whether the scale is
+ * *shared* between the frame and the joints, and a scale is shared exactly when the node carrying it
+ * is an ancestor of the mesh **and** of every joint. So:
+ *
+ * - a scale on the character's own root reaches the mesh and all the joints, cancels out of the
+ *   fold, and is fine — this is how a model is made to grow;
+ * - a scale on a joint, or on any node above only *some* of them, reaches the joints and not the
+ *   mesh, and is a conflict;
+ * - a scale on a node that reaches neither is somebody else's business.
+ *
+ * A channel whose curves are all the constant 1 is not a scale at all, whatever it targets. The
+ * range is taken with {@link animation_curve_compute_aabb}, which follows the Hermite spline between
+ * keys rather than only reading the keys — a curve that leaves 1 and returns to it is a scale.
+ *
+ * @param {Skin} skin
+ * @param {ShadeAnimationClip} clip
+ * @returns {Array<{
+ *     channel: ShadeAnimationChannel,
+ *     node: Node3D,
+ *     uniform: boolean,
+ *     joints_reached: number,
+ *     reaches_mesh: boolean,
+ * }>} one entry per conflicting channel, empty when the clip and the skin can coexist. `uniform`
+ *     says which rung of §4's ladder would be needed: a uniform scale is one a dual quaternion could
+ *     be taught to carry alongside, a non-uniform one is not. It is `true` only when all three
+ *     components are animated by equal curves, so a channel that is uniform by coincidence of the
+ *     node's own scale reads as non-uniform — the safe direction for a report
+ */
+export function skin_clip_scale_conflicts(skin, clip) {
+    assert.defined(skin, 'skin');
+    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
+    assert.defined(clip, 'clip');
+
+    const scaling = clip_scale_channels(clip);
+
+    const conflicts = [];
+
+    if (scaling.length === 0) {
+        return conflicts;
+    }
+
+    const joints = new Set(skin.joints);
+    const meshes = new Set(skin.meshes);
+
+    for (const channel of scaling) {
+        let joints_reached = 0;
+        let meshes_reached = 0;
+
+        channel.target.traverse(node => {
+            if (joints.has(node)) {
+                joints_reached++;
+            }
+
+            if (meshes.has(node)) {
+                meshes_reached++;
+            }
+        });
+
+        const reaches_everything = joints_reached === joints.size && meshes_reached === meshes.size;
+        const reaches_nothing = joints_reached === 0 && meshes_reached === 0;
+
+        if (reaches_everything || reaches_nothing) {
+            continue;
+        }
+
+        conflicts.push({
+            channel,
+            node: channel.target,
+            uniform: is_uniform(channel),
+            joints_reached,
+            reaches_mesh: meshes_reached > 0,
+        });
+    }
+
+    return conflicts;
+}
+
+/**
+ * The channels of a clip that scale something, anywhere — before any question of *whose* joints.
+ *
+ * Separated out because it is the cheap half and almost always the whole answer. A character's clips
+ * rotate and translate; a clip with no scale channel at all can be dismissed in one pass over its
+ * channel list, which is what keeps the per-`(skin, clip)` pair check from costing anything at a
+ * few hundred dancers. {@link GPUAnimationManager} asks this first and only remembers a clip that
+ * says yes.
+ *
+ * @param {ShadeAnimationClip} clip
+ * @returns {ShadeAnimationChannel[]}
+ */
+export function clip_scale_channels(clip) {
+    assert.defined(clip, 'clip');
+
+    const scaling = [];
+
+    for (const channel of clip.channels) {
+        if (channel.property !== Node3DProperty.Scale) {
+            // translation and rotation keep the fold rigid, which is the whole of what it needs
+            continue;
+        }
+
+        if (channel.target === null || channel.target === undefined) {
+            continue;
+        }
+
+        if (scales(channel)) {
+            scaling.push(channel);
+        }
+    }
+
+    return scaling;
+}
+
+/**
+ * Whether a scale channel moves anything — false when every component it animates stays at 1.
+ *
+ * @param {ShadeAnimationChannel} channel
+ * @returns {boolean}
+ */
+function scales(channel) {
+    const curves = channel.curves;
+
+    for (const axis of ['x', 'y', 'z']) {
+        const curve = curves[axis];
+
+        if (curve === undefined || curve.length === 0) {
+            continue;
+        }
+
+        animation_curve_compute_aabb(_bounds, curve);
+
+        if (Math.abs(_bounds.y0 - 1) > UNIT_EPSILON || Math.abs(_bounds.y1 - 1) > UNIT_EPSILON) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Whether a scale channel drives all three axes by the same curve — the shape
+ * {@link Node3DProperty.Scale} names as how a uniform pulsate is authored.
+ *
+ * @param {ShadeAnimationChannel} channel
+ * @returns {boolean}
+ */
+function is_uniform(channel) {
+    const { x, y, z } = channel.curves;
+
+    if (x === undefined || y === undefined || z === undefined) {
+        // an axis left unanimated keeps whatever the node's own scale holds while the others move,
+        // which is a non-uniform scale however uniform the curves that are there
+        return false;
+    }
+
+    return (x === y || x.equals(y)) && (x === z || x.equals(z));
+}

package/src/shade/renderer/animation/skin_frame_defect.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Whether a frame is one this skin can be deformed in — and if not, by how much it is not.
+ *
+ * The skinning pass converts `frame⁻¹ × joint.global × inverse_bind` to a dual quaternion, and a
+ * dual quaternion carries a rotation and a translation and nothing else. So that product must be
+ * rigid for every joint. This is that condition as a number: zero when the frame works, and growing
+ * with whatever the conversion would have to throw away. `SKINNING_FRAME_PLAN.md` §1 is what
+ * happens when it does.
+ *
+ * **This, and not "do the joints agree", is the precondition.** A file whose rest pose is not its
+ * bind pose has joints whose skin matrices differ — by *rigid* motions, which cost nothing here.
+ * What cannot be absorbed is a scale or a shear, and this sees exactly that.
+ *
+ * Reads the joints' `transform_global`, so it answers for whatever pose the skeleton is standing in.
+ * At rest that is the registration-time question. Handed a posed skeleton it answers the runtime one
+ * — a clip that scales a joint, which no frame can fix (§4).
+ *
+ * @param {Skin} skin
+ * @param {ArrayLike<number>} frame 16 elements, column-major — the transform the renderer re-applies
+ * @returns {number} the largest {@link m4_rigidity_defect} over the skin's joints; `Infinity` if
+ *          `frame` has no inverse, or if any joint's fold comes out a reflection — which scores zero
+ *          on the defect and is unrepresentable all the same
+ */
+export function skin_frame_defect(skin: Skin, frame: ArrayLike<number>): number;
+/**
+ * The same question of one joint, freshly allocated — for a caller that wants to say *which* joint
+ * and by how much rather than only the worst of them.
+ *
+ * @param {Skin} skin
+ * @param {ArrayLike<number>} frame
+ * @returns {number[]} one defect per joint, in joint order
+ */
+export function skin_frame_defect_by_joint(skin: Skin, frame: ArrayLike<number>): number[];
+//# sourceMappingURL=skin_frame_defect.d.ts.map

package/src/shade/renderer/animation/skin_frame_defect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skin_frame_defect.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/skin_frame_defect.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qDALW,UAAU,MAAM,CAAC,GACf,MAAM,CA6ClB;AAiBD;;;;;;;GAOG;AACH,8DAHW,UAAU,MAAM,CAAC,GACf,MAAM,EAAE,CA8BpB"}

package/src/shade/renderer/animation/skin_frame_defect.js

@@ -0,0 +1,132 @@
+import { assert } from "../../../core/assert.js";
+import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+import { m4_rigidity_defect } from "../../../core/geom/3d/mat4/m4_rigidity_defect.js";
+import { skin_joint_matrix } from "./skin_joint_matrix.js";
+
+/**
+ * Scratch, so that walking a sixty-five-joint skeleton does not allocate per joint. Nothing here
+ * re-enters, and none of it outlives the call.
+ */
+const _inverse_frame = new Float64Array(16);
+const _joint_matrix = new Float64Array(16);
+const _folded = new Float64Array(16);
+
+/**
+ * Whether a frame is one this skin can be deformed in — and if not, by how much it is not.
+ *
+ * The skinning pass converts `frame⁻¹ × joint.global × inverse_bind` to a dual quaternion, and a
+ * dual quaternion carries a rotation and a translation and nothing else. So that product must be
+ * rigid for every joint. This is that condition as a number: zero when the frame works, and growing
+ * with whatever the conversion would have to throw away. `SKINNING_FRAME_PLAN.md` §1 is what
+ * happens when it does.
+ *
+ * **This, and not "do the joints agree", is the precondition.** A file whose rest pose is not its
+ * bind pose has joints whose skin matrices differ — by *rigid* motions, which cost nothing here.
+ * What cannot be absorbed is a scale or a shear, and this sees exactly that.
+ *
+ * Reads the joints' `transform_global`, so it answers for whatever pose the skeleton is standing in.
+ * At rest that is the registration-time question. Handed a posed skeleton it answers the runtime one
+ * — a clip that scales a joint, which no frame can fix (§4).
+ *
+ * @param {Skin} skin
+ * @param {ArrayLike<number>} frame 16 elements, column-major — the transform the renderer re-applies
+ * @returns {number} the largest {@link m4_rigidity_defect} over the skin's joints; `Infinity` if
+ *          `frame` has no inverse, or if any joint's fold comes out a reflection — which scores zero
+ *          on the defect and is unrepresentable all the same
+ */
+export function skin_frame_defect(skin, frame) {
+    assert.defined(skin, 'skin');
+    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
+    assert.isArrayLike(frame, 'frame');
+
+    if (!m4_invert(_inverse_frame, frame)) {
+        // a frame with no inverse is not a frame; the skinning pass would divide by that determinant
+        return Infinity;
+    }
+
+    const joint_count = skin.joints.length;
+
+    let worst = 0;
+
+    for (let j = 0; j < joint_count; j++) {
+        skin_joint_matrix(_joint_matrix, skin, j);
+
+        m4_multiply(_folded, _inverse_frame, _joint_matrix);
+
+        if (m4_linear_determinant(_folded) < 0) {
+            /*
+             A reflection. {@link m4_rigidity_defect} reads zero for one — it measures orthonormality,
+             and a reflection is orthonormal — so this is the one way a fold can be unrepresentable
+             and still score perfectly. `quat_from_m3` would answer with a *rotation*, silently, which
+             is precisely the class of failure this check exists to end.
+
+             Not fixable by a frame either: a reflection shared by the frame and every joint cancels
+             and never reaches here, so one that does reach here is a skeleton whose joints disagree
+             about handedness.
+            */
+            return Infinity;
+        }
+
+        const defect = m4_rigidity_defect(_folded);
+
+        if (defect > worst) {
+            worst = defect;
+        }
+    }
+
+    return worst;
+}
+
+/**
+ * The determinant of a matrix's upper 3×3 — negative exactly when the transform turns a
+ * right-handed basis left-handed.
+ *
+ * @param {ArrayLike<number>} mat4 column-major
+ * @returns {number}
+ */
+function m4_linear_determinant(mat4) {
+    const a = mat4[0], b = mat4[4], c = mat4[8];
+    const d = mat4[1], e = mat4[5], f = mat4[9];
+    const g = mat4[2], h = mat4[6], i = mat4[10];
+
+    return a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g);
+}
+
+/**
+ * The same question of one joint, freshly allocated — for a caller that wants to say *which* joint
+ * and by how much rather than only the worst of them.
+ *
+ * @param {Skin} skin
+ * @param {ArrayLike<number>} frame
+ * @returns {number[]} one defect per joint, in joint order
+ */
+export function skin_frame_defect_by_joint(skin, frame) {
+    assert.defined(skin, 'skin');
+    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
+
+    // f64 throughout: a 100× frame inverted in f32 reports a defect of its own rounding, and this
+    // number is read against a tolerance small enough to see one
+    const inverse_frame = new Float64Array(16);
+
+    if (!m4_invert(inverse_frame, frame)) {
+        return skin.joints.map(() => Infinity);
+    }
+
+    const joint_matrix = new Float64Array(16);
+    const folded = new Float64Array(16);
+
+    return skin.joints.map((_joint, j) => {
+        skin_joint_matrix(joint_matrix, skin, j);
+
+        m4_multiply(folded, inverse_frame, joint_matrix);
+
+        // the same refusal {@link skin_frame_defect} makes, so that the gate and the diagnostic
+        // that explains it cannot disagree about which joints are the problem
+        if (m4_linear_determinant(folded) < 0) {
+            return Infinity;
+        }
+
+        return m4_rigidity_defect(folded);
+    });
+}

package/src/shade/renderer/animation/skin_joint_matrix.d.ts

@@ -0,0 +1,24 @@
+/**
+ * One joint's skin matrix, in the pose its node currently holds: `joint.global × inverse_bind`.
+ *
+ * The same quantity `shader_skin_matrix_prep` writes to the GPU's `skin_matrices` buffer, and the
+ * same one `compute_skin_world_bounds` composes its box out of — kept here so the CPU-side callers
+ * that reason about a skin's geometry all read it from one place rather than three.
+ *
+ * It maps a vertex from the skin's mesh space into **world** space. The mesh node's own transform
+ * does not appear and must not: glTF says a skinned mesh's node transform is ignored, and this
+ * engine's arrangement is that the skinning pass folds its inverse in and the rasterizer re-applies
+ * it, so the two cancel. See `SKINNING_FRAME_PLAN.md` for what that fold requires of an asset.
+ *
+ * Not a per-frame path. Joints the pose accumulator drives are {@link TransformAuthority.GPU} and
+ * their `transform_global` holds the rest pose the CPU seeded, so what this answers for an animated
+ * character is the rest-pose matrix — which is exactly what the frame arithmetic wants, and is not
+ * what a renderer wants.
+ *
+ * @param {Float64Array|Float32Array|number[]} out 16 elements, column-major
+ * @param {Skin} skin
+ * @param {number} joint_index
+ * @returns {Float64Array|Float32Array|number[]} `out`
+ */
+export function skin_joint_matrix(out: Float64Array | Float32Array | number[], skin: Skin, joint_index: number): Float64Array | Float32Array | number[];
+//# sourceMappingURL=skin_joint_matrix.d.ts.map

package/src/shade/renderer/animation/skin_joint_matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skin_joint_matrix.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/skin_joint_matrix.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,uCALW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,2BAElC,MAAM,GACJ,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,CAsB9C"}

package/src/shade/renderer/animation/skin_joint_matrix.js

@@ -0,0 +1,46 @@
+import { assert } from "../../../core/assert.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+
+/**
+ * One joint's skin matrix, in the pose its node currently holds: `joint.global × inverse_bind`.
+ *
+ * The same quantity `shader_skin_matrix_prep` writes to the GPU's `skin_matrices` buffer, and the
+ * same one `compute_skin_world_bounds` composes its box out of — kept here so the CPU-side callers
+ * that reason about a skin's geometry all read it from one place rather than three.
+ *
+ * It maps a vertex from the skin's mesh space into **world** space. The mesh node's own transform
+ * does not appear and must not: glTF says a skinned mesh's node transform is ignored, and this
+ * engine's arrangement is that the skinning pass folds its inverse in and the rasterizer re-applies
+ * it, so the two cancel. See `SKINNING_FRAME_PLAN.md` for what that fold requires of an asset.
+ *
+ * Not a per-frame path. Joints the pose accumulator drives are {@link TransformAuthority.GPU} and
+ * their `transform_global` holds the rest pose the CPU seeded, so what this answers for an animated
+ * character is the rest-pose matrix — which is exactly what the frame arithmetic wants, and is not
+ * what a renderer wants.
+ *
+ * @param {Float64Array|Float32Array|number[]} out 16 elements, column-major
+ * @param {Skin} skin
+ * @param {number} joint_index
+ * @returns {Float64Array|Float32Array|number[]} `out`
+ */
+export function skin_joint_matrix(out, skin, joint_index) {
+    assert.isArrayLike(out, 'out');
+    assert.defined(skin, 'skin');
+    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
+    assert.isNonNegativeInteger(joint_index, 'joint_index');
+    assert.lessThan(joint_index, skin.joints.length, 'joint_index');
+
+    const offset = joint_index * 16;
+
+    assert.greaterThanOrEqual(
+        skin.inverse_bind_matrices.length, offset + 16,
+        'skin.inverse_bind_matrices.length'
+    );
+
+    // a Transform64's matrix starts at element 0, so the transform is its own mat4 argument
+    return m4_multiply(
+        out,
+        skin.joints[joint_index].transform_global,
+        skin.inverse_bind_matrices.subarray(offset, offset + 16)
+    );
+}

package/src/shade/renderer/animation/skin_normalize_mesh_frame.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Put a skin's meshes into the frame the skin actually deforms in.
+ *
+ * ## What it does and why
+ *
+ * The skinning pass writes each clone's vertices in `inverse(mesh.global)` space and the rasterizer
+ * re-applies `mesh.global`, so `mesh.global` is the *frame* a skinned mesh's vertices live in. The
+ * pass gets there by converting `inverse(mesh.global) × joint.global × inverse_bind` to a dual
+ * quaternion, which carries a rotation and a translation and **nothing else** — so that product has
+ * to be rigid, and whether it is depends entirely on `mesh.global`.
+ *
+ * glTF says a skinned mesh's node transform is ignored, so it is not the asset's to choose. This
+ * makes it the engine's, and sets it to the one frame that is guaranteed to work: the skin's own
+ * bind transform, `joint.global × inverse_bind` at rest — see {@link skin_bind_transform}. After
+ * this, `inverse(mesh.global) × joint.global × inverse_bind` is the joint's **displacement from
+ * bind**, which is rigid whenever the clip rotates and translates and does not scale. That is the
+ * honest precondition of dual-quaternion skinning, and it is a property of the animation rather than
+ * of the exporter's unit conventions.
+ *
+ * `SKINNING_FRAME_PLAN.md` is the whole argument, including what a violation looks like on screen.
+ *
+ * ## Properties worth knowing
+ *
+ * - **Idempotent.** Afterwards `mesh.global` *is* the bind transform, so a second call computes the
+ *   identity and changes nothing. Re-registering a skin is free.
+ * - **Placement-invariant.** The correction is `mesh.global⁻¹ × bind`, and anything applied above
+ *   both the mesh node and the joints — a placement, a walk cycle moving the character — multiplies
+ *   both on the left and cancels. Computed once, correct forever.
+ * - **A no-op for an asset that already agrees.** A file whose inverse-bind matrices are authored
+ *   before its root's unit conversion has `bind == mesh.global` already and is not touched. That is
+ *   the shape this engine's creature models are said to have, and it is what keeps this from being
+ *   a change to them.
+ *
+ * ## What it cannot fix
+ *
+ * A skin whose *own* bind frame does not work — a rest pose carrying a non-uniform scale or a shear,
+ * or joints that disagree about more than a rigid motion. No choice of frame fixes those; a dual
+ * quaternion cannot represent them at all. `frame_defect` in the report is that case, and when it
+ * fires nothing is written: the mesh is left as the asset had it rather than moved somewhere equally
+ * wrong. See `SKINNING_FRAME_PLAN.md` §4 for the ladder out.
+ *
+ * @param {Skin} skin its joints and meshes must have been walked — this reads `transform_global`,
+ *        which is derived. A skin that has never been walked at all is refused rather than
+ *        measured; one walked and then moved is the caller's to walk again, and the residual
+ *        below is what notices if the mesh half of that was missed
+ * @returns {{
+ *     frame_defect: number,
+ *     absorbed: number,
+ *     corrected: number,
+ *     unchanged: number,
+ *     residual: number,
+ *     obstructed: Node3D[],
+ *     unwalked: Node3D[],
+ * }} `frame_defect` — how far the skin is from being deformable in *any* frame, zero when it is
+ *    fine and `NaN` when `unwalked` stopped it being asked; `absorbed` — how far from rigid the largest correction was, which for a violation is the
+ *    number the soup was made of; `corrected` and `unchanged` — meshes moved and meshes already
+ *    right; `residual` — the worst `|mesh.global − bind|` left afterwards; `obstructed` — corrected
+ *    mesh nodes that had children, which have been scaled along with them; `unwalked` — joints or
+ *    meshes whose `transform_global` has never been derived, which stops everything else
+ */
+export function skin_normalize_mesh_frame(skin: Skin): {
+    frame_defect: number;
+    absorbed: number;
+    corrected: number;
+    unchanged: number;
+    residual: number;
+    obstructed: Node3D[];
+    unwalked: Node3D[];
+};
+//# sourceMappingURL=skin_normalize_mesh_frame.d.ts.map

package/src/shade/renderer/animation/skin_normalize_mesh_frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skin_normalize_mesh_frame.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/skin_normalize_mesh_frame.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH;kBAdqB,MAAM;cACV,MAAM;eACL,MAAM;eACN,MAAM;cACP,MAAM;gBACJ,QAAQ;cACV,QAAQ;EA4GxB"}