@woosh/meep-engine 3.39.0 → 3.41.0

package/src/engine/physics/inverse_kinematics/joint_hinge_mid_axis.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The hinge a mid joint (a knee, an elbow) has, from the physics {@link Joint} on it, as
+ * {@link two_joint_ik} takes it: an axis in the mid joint's own frame about which a positive turn
+ * straightens the joint, so it names the side the joint bends to as well as the axis
+ * (ozz-animation's `mid_axis`).
+ *
+ * The Joint sits on the mid bone: `entityA` is its parent, `entityB` the bone itself. A hinge
+ * ({@link Joint#asHinge}) leaves one angular frame axis unlocked, and turned by `localBasisB` that axis
+ * is the hinge in the bone's own frame. Physics measures the angle about it as B's turn relative to A,
+ * 0 at rest, so the bone bends to the side its limits reach further: positive for limits like
+ * `[0, 2.6]`, and the axis that straightens it is then the hinge reversed.
+ *
+ * A straight leg's pose says nothing about which way its knee bends, which is why the side is read
+ * off the limits and not the pose. So a hinge that does not say is no hinge here:
+ * - an unlocked axis that is not {@link DofMode.LIMITED} (FREE, or a SPRING or MOTOR, which IK
+ *   ignores) has no limits to read;
+ * - limits with `lower + upper == 0` reach equally far both ways.
+ *
+ * Anchors and the linear axes are ignored.
+ *
+ * @param {Vector3} out the hinge, of unit length, in the bone's own frame; written only on success
+ * @param {Joint} joint the physics joint on the mid bone
+ * @returns {boolean} false when the joint gives no bend side: more or fewer than one unlocked angular
+ * axis, an unlimited one, or symmetric limits
+ */
+export function joint_hinge_mid_axis(out: Vector3, joint: Joint): boolean;
+//# sourceMappingURL=joint_hinge_mid_axis.d.ts.map

package/src/engine/physics/inverse_kinematics/joint_hinge_mid_axis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"joint_hinge_mid_axis.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inverse_kinematics/joint_hinge_mid_axis.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,kEAHa,OAAO,CA6CnB"}

package/src/engine/physics/inverse_kinematics/joint_hinge_mid_axis.js

@@ -0,0 +1,77 @@
+import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
+import { DofMode } from "../constraint/DofMode.js";
+
+/**
+ * `[x, y, z]` scratch.
+ * @type {Float64Array}
+ */
+const axis = new Float64Array(3);
+
+/**
+ * The hinge a mid joint (a knee, an elbow) has, from the physics {@link Joint} on it, as
+ * {@link two_joint_ik} takes it: an axis in the mid joint's own frame about which a positive turn
+ * straightens the joint, so it names the side the joint bends to as well as the axis
+ * (ozz-animation's `mid_axis`).
+ *
+ * The Joint sits on the mid bone: `entityA` is its parent, `entityB` the bone itself. A hinge
+ * ({@link Joint#asHinge}) leaves one angular frame axis unlocked, and turned by `localBasisB` that axis
+ * is the hinge in the bone's own frame. Physics measures the angle about it as B's turn relative to A,
+ * 0 at rest, so the bone bends to the side its limits reach further: positive for limits like
+ * `[0, 2.6]`, and the axis that straightens it is then the hinge reversed.
+ *
+ * A straight leg's pose says nothing about which way its knee bends, which is why the side is read
+ * off the limits and not the pose. So a hinge that does not say is no hinge here:
+ * - an unlocked axis that is not {@link DofMode.LIMITED} (FREE, or a SPRING or MOTOR, which IK
+ *   ignores) has no limits to read;
+ * - limits with `lower + upper == 0` reach equally far both ways.
+ *
+ * Anchors and the linear axes are ignored.
+ *
+ * @param {Vector3} out the hinge, of unit length, in the bone's own frame; written only on success
+ * @param {Joint} joint the physics joint on the mid bone
+ * @returns {boolean} false when the joint gives no bend side: more or fewer than one unlocked angular
+ * axis, an unlimited one, or symmetric limits
+ */
+export function joint_hinge_mid_axis(out, joint) {
+    const mode = joint.dofMode;
+
+    let free = -1;
+
+    for (let k = 0; k < 3; k++) {
+        if (mode[3 + k] === DofMode.LOCKED) {
+            continue;
+        }
+
+        if (free !== -1) {
+            // two axes turn: a ball or a cone, not a hinge
+            return false;
+        }
+
+        free = k;
+    }
+
+    if (free === -1 || mode[3 + free] !== DofMode.LIMITED) {
+        return false;
+    }
+
+    const middle = joint.dofLowerLimit[3 + free] + joint.dofUpperLimit[3 + free];
+
+    if (middle === 0) {
+        return false;
+    }
+
+    const basis = joint.localBasisB;
+
+    v3_quaternion_apply(
+        axis, 0,
+        free === 0 ? 1 : 0, free === 1 ? 1 : 0, free === 2 ? 1 : 0,
+        basis[0], basis[1], basis[2], basis[3]
+    );
+
+    // bending is a turn toward the further limit, so straightening is a turn the other way
+    const sign = middle > 0 ? -1 : 1;
+
+    out.set(axis[0] * sign, axis[1] * sign, axis[2] * sign);
+
+    return true;
+}

package/src/engine/physics/inverse_kinematics/two_bone_path_solve.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pose a two-bone path (hip, knee, ankle) for a goal: the position by {@link two_joint_ik}, blended
+ * in by the goal's position weight, then the end's rotation slerped toward the goal's.
+ *
+ * Two-bone paths stay analytic: frame FABRIK needs more than 256 iterations to put a leg at 99.9 %
+ * of its reach where this is exact.
+ *
+ * - **Position.** The root and mid joints' local rotations are corrected to land the end on `t`, and
+ *   each is slerped from its animated rotation toward the correction by `position_weight`. Slerp,
+ *   not lerp: a componentwise blend of two unit quaternions is shorter than unit, and a hovering foot
+ *   blends by a fraction, so that is the ordinary case (a knee half-way through a 56 degree
+ *   correction came out at |q| = 0.970, its shin 3 cm short). The twist about each bone is the
+ *   animated one; the corrections turn the mid joint about its hinge and the root as little as
+ *   reaching the target takes.
+ * - **Rotation.** The end rides its chain, carried by the mid joint's corrected frame, and is then
+ *   turned toward `target_rotation` by slerp, `rotation_weight` of the way. At 0 its local rotation
+ *   is left exactly as animated.
+ *
+ * @param {Vector3} a root joint position, world
+ * @param {Vector3} b mid joint position, world
+ * @param {Vector3} c end position, world
+ * @param {Vector3} t target position, world
+ * @param {Vector3} mid_axis the mid joint's hinge in its own frame, of unit length, a positive turn
+ * straightening it; see {@link joint_hinge_mid_axis}
+ * @param {Quaternion} a_gr world rotation of the root joint
+ * @param {Quaternion} b_gr world rotation of the mid joint
+ * @param {Quaternion} a_lr local rotation of the root joint, corrected in place
+ * @param {Quaternion} b_lr local rotation of the mid joint, corrected in place
+ * @param {Quaternion} c_lr local rotation of the end, corrected in place
+ * @param {number} position_weight 0..1
+ * @param {Quaternion} target_rotation the rotation the goal wants the end to have, world
+ * @param {number} rotation_weight 0..1
+ */
+export function two_bone_path_solve(a: Vector3, b: Vector3, c: Vector3, t: Vector3, mid_axis: Vector3, a_gr: Quaternion, b_gr: Quaternion, a_lr: Quaternion, b_lr: Quaternion, c_lr: Quaternion, position_weight: number, target_rotation: Quaternion, rotation_weight: number): void;
+import Quaternion from "../../../core/geom/Quaternion.js";
+//# sourceMappingURL=two_bone_path_solve.d.ts.map

package/src/engine/physics/inverse_kinematics/two_bone_path_solve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"two_bone_path_solve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inverse_kinematics/two_bone_path_solve.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,6GATW,UAAU,QACV,UAAU,QACV,UAAU,QACV,UAAU,QACV,UAAU,mBACV,MAAM,mBACN,UAAU,mBACV,MAAM,QAqDhB;uBA/FsB,kCAAkC"}

package/src/engine/physics/inverse_kinematics/two_bone_path_solve.js

@@ -0,0 +1,97 @@
+import { assert } from "../../../core/assert.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import { two_joint_ik } from "./two_joint_ik.js";
+
+const solved_a = new Quaternion();
+const solved_b = new Quaternion();
+
+const above_a = new Quaternion();
+const mid_world = new Quaternion();
+const carried = new Quaternion();
+const turned = new Quaternion();
+
+/**
+ * Pose a two-bone path (hip, knee, ankle) for a goal: the position by {@link two_joint_ik}, blended
+ * in by the goal's position weight, then the end's rotation slerped toward the goal's.
+ *
+ * Two-bone paths stay analytic: frame FABRIK needs more than 256 iterations to put a leg at 99.9 %
+ * of its reach where this is exact.
+ *
+ * - **Position.** The root and mid joints' local rotations are corrected to land the end on `t`, and
+ *   each is slerped from its animated rotation toward the correction by `position_weight`. Slerp,
+ *   not lerp: a componentwise blend of two unit quaternions is shorter than unit, and a hovering foot
+ *   blends by a fraction, so that is the ordinary case (a knee half-way through a 56 degree
+ *   correction came out at |q| = 0.970, its shin 3 cm short). The twist about each bone is the
+ *   animated one; the corrections turn the mid joint about its hinge and the root as little as
+ *   reaching the target takes.
+ * - **Rotation.** The end rides its chain, carried by the mid joint's corrected frame, and is then
+ *   turned toward `target_rotation` by slerp, `rotation_weight` of the way. At 0 its local rotation
+ *   is left exactly as animated.
+ *
+ * @param {Vector3} a root joint position, world
+ * @param {Vector3} b mid joint position, world
+ * @param {Vector3} c end position, world
+ * @param {Vector3} t target position, world
+ * @param {Vector3} mid_axis the mid joint's hinge in its own frame, of unit length, a positive turn
+ * straightening it; see {@link joint_hinge_mid_axis}
+ * @param {Quaternion} a_gr world rotation of the root joint
+ * @param {Quaternion} b_gr world rotation of the mid joint
+ * @param {Quaternion} a_lr local rotation of the root joint, corrected in place
+ * @param {Quaternion} b_lr local rotation of the mid joint, corrected in place
+ * @param {Quaternion} c_lr local rotation of the end, corrected in place
+ * @param {number} position_weight 0..1
+ * @param {Quaternion} target_rotation the rotation the goal wants the end to have, world
+ * @param {number} rotation_weight 0..1
+ */
+export function two_bone_path_solve(
+    a, b, c, t,
+    mid_axis,
+    a_gr, b_gr,
+    a_lr, b_lr, c_lr,
+    position_weight,
+    target_rotation,
+    rotation_weight
+) {
+    assert.ok(position_weight >= 0 && position_weight <= 1, 'position_weight is within 0..1');
+    assert.ok(rotation_weight >= 0 && rotation_weight <= 1, 'rotation_weight is within 0..1');
+
+    // the frame above the root, which the corrections do not move: a_gr = above_a * a_lr
+    above_a.copyInverse(a_lr);
+    above_a.multiplyQuaternions(a_gr, above_a);
+
+    // slerp's endpoints are a ratio of sines, which rounds: weight 0 has to be the animated pose
+    // exactly, as no goal is
+    if (position_weight > 0) {
+        solved_a.copy(a_lr);
+        solved_b.copy(b_lr);
+
+        two_joint_ik(a, b, c, t, mid_axis, a_gr, b_gr, solved_a, solved_b);
+
+        if (position_weight === 1) {
+            a_lr.copy(solved_a);
+            b_lr.copy(solved_b);
+        } else {
+            a_lr.slerpQuaternions(a_lr, solved_a, position_weight);
+            b_lr.slerpQuaternions(b_lr, solved_b, position_weight);
+        }
+    }
+
+    if (rotation_weight === 0) {
+        return;
+    }
+
+    mid_world.multiplyQuaternions(above_a, a_lr);
+    mid_world.multiply(b_lr);
+
+    carried.multiplyQuaternions(mid_world, c_lr);
+
+    if (rotation_weight === 1) {
+        turned.copy(target_rotation);
+    } else {
+        turned.slerpQuaternions(carried, target_rotation, rotation_weight);
+    }
+
+    mid_world.conjugate();
+
+    c_lr.multiplyQuaternions(mid_world, turned);
+}

package/src/engine/physics/inverse_kinematics/two_joint_ik.d.ts

@@ -1,16 +1,38 @@
 /**
- * Based on http://theorangeduck.com/page/simple-two-joint
- * @param {Vector3} a Root bone position
- * @param {Vector3} b Second bone position
- * @param {Vector3} c Effector position
- * @param {Vector3} t Target position
- * @param {number} eps EPSILON value, small value for rounding error compensation
- * @param {Quaternion} a_gr Global rotation of root bone
- * @param {Quaternion} b_gr Global rotation of second bone
- * @param {Quaternion} a_lr local rotation for root bone, this will be updated as a result
- * @param {Quaternion} b_lr local rotation for second bone, this will be updated as a result
+ * Two-joint inverse kinematics: turn a root joint and a hinged mid joint so the end of the chain
+ * lands on a target, in one call.
+ *
+ * After http://theorangeduck.com/page/simple-two-joint, with the mid joint's hinge given rather than
+ * guessed. The reference bends about `normalize((c - a) x d)` for some `d` "close to" where the knee
+ * points; this file used to take `d` as the mid joint's local -Z, which is the hinge only for a rig
+ * whose -Z lies in the bend plane and on the knee's side of it - a knee bending toward +Z, or a frame
+ * yawed 30 degrees, bent about the wrong axis and missed by up to 119 mm. `mid_axis` is the convention
+ * ozz-animation ships (`IKTwoBoneJob::mid_axis`): an axis in the mid joint's own frame, about which a
+ * positive turn straightens the joint, so it names the side the joint bends to as well as the axis.
+ *
+ * - The mid joint turns about its hinge alone, by the angle that sets the end at the target's distance
+ *   from the root. That is solved exactly whether or not the bones are square to the hinge, and a joint
+ *   animated past straight, against its hinge, is brought round to the side the hinge bends it.
+ * - The root then turns twice, both turns in world: back onto the ray the end was animated along (the
+ *   reference's bend, a turn about the hinge when the bones are square to it), then along the shortest
+ *   arc from that ray onto the target (its swing).
+ * - A target the chain cannot reach is reached for: the chain straightens, or folds, and points at it.
+ *
+ * The corrections are right-multiplied onto the local rotations, so whatever is above the root may be
+ * rotated arbitrarily.
+ *
+ * @param {Vector3} a root joint position, world
+ * @param {Vector3} b mid joint position, world
+ * @param {Vector3} c end position, world
+ * @param {Vector3} t target position, world
+ * @param {Vector3} mid_axis the mid joint's hinge in its own frame, of unit length; a positive turn
+ * about it straightens the joint
+ * @param {Quaternion} a_gr world rotation of the root joint
+ * @param {Quaternion} b_gr world rotation of the mid joint
+ * @param {Quaternion} a_lr local rotation of the root joint, corrected in place
+ * @param {Quaternion} b_lr local rotation of the mid joint, corrected in place
  */
-export function two_joint_ik(a: Vector3, b: Vector3, c: Vector3, t: Vector3, eps: number, a_gr: Quaternion, b_gr: Quaternion, a_lr: Quaternion, b_lr: Quaternion): void;
+export function two_joint_ik(a: Vector3, b: Vector3, c: Vector3, t: Vector3, mid_axis: Vector3, a_gr: Quaternion, b_gr: Quaternion, a_lr: Quaternion, b_lr: Quaternion): void;
 import Vector3 from "../../../core/geom/Vector3.js";
 import Quaternion from "../../../core/geom/Quaternion.js";
 //# sourceMappingURL=two_joint_ik.d.ts.map

package/src/engine/physics/inverse_kinematics/two_joint_ik.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"two_joint_ik.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inverse_kinematics/two_joint_ik.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;GAWG;AACH,gCAVW,OAAO,KACP,OAAO,KACP,OAAO,KACP,OAAO,OACP,MAAM,QACN,UAAU,QACV,UAAU,QACV,UAAU,QACV,UAAU,QAoEpB;oBAtGmB,+BAA+B;uBAF5B,kCAAkC"}
+{"version":3,"file":"two_joint_ik.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inverse_kinematics/two_joint_ik.js"],"names":[],"mappings":"AAyEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,gCAXW,OAAO,KACP,OAAO,KACP,OAAO,KACP,OAAO,YACP,OAAO,QAEP,UAAU,QACV,UAAU,QACV,UAAU,QACV,UAAU,QA0FpB;oBAjMmB,+BAA+B;uBAD5B,kCAAkC"}

package/src/engine/physics/inverse_kinematics/two_joint_ik.js

@@ -1,105 +1,196 @@
+import { assert } from "../../../core/assert.js";
 import Quaternion from "../../../core/geom/Quaternion.js";
-import { v3_interior_angle } from "../../../core/geom/vec3/v3_interior_angle.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { clamp } from "../../../core/math/clamp.js";
 
-const d = new Vector3();
+const hinge = new Vector3();
 
-const delta_ca = new Vector3();
-const delta_ta = new Vector3();
+const thigh = new Vector3();
+const shin = new Vector3();
 
-const axis0 = new Vector3();
-const axis1 = new Vector3();
+const thigh_across = new Vector3();
+const shin_across = new Vector3();
 
-const inv_a_gr = new Quaternion();
-const inv_b_gr = new Quaternion();
+const ankle_bent = new Vector3();
+const aim = new Vector3();
+const reach = new Vector3();
 
-const r0 = new Quaternion();
-const r1 = new Quaternion();
-const r2 = new Quaternion();
+const axis = new Vector3();
 
-const axis0_la = new Vector3();
-const axis0_lb = new Vector3();
-const axis1_la = new Vector3();
+const knee_turn = new Quaternion();
+const hip_turn = new Quaternion();
+const turn = new Quaternion();
+const inverse_a_gr = new Quaternion();
 
-// TODO: investigate https://github.com/guillaumeblanc/ozz-animation/blob/master/src/animation/runtime/ik_two_bone_job.cc
+/**
+ * The shortest turn taking the direction of `from` onto the direction of `to`; neither has to be of
+ * unit length. Either being zero leaves nothing to turn.
+ *
+ * Directions within 1e-12 rad of opposite turn half a circle about `fallback`, less its part along
+ * `from`. Their cross product is no axis there - it is zero, or rounding noise, and noise need not
+ * even be square to `from` (measured: an exact-zero test missed targets opposite the effector by up
+ * to 995 mm on 1,911 of 2,000 random leg orientations).
+ *
+ * @param {Quaternion} out
+ * @param {Vector3} from
+ * @param {Vector3} to
+ * @param {Vector3} fallback unit length
+ */
+function turn_between(out, from, to, fallback) {
+    const scale = Math.sqrt(from.lengthSqr() * to.lengthSqr());
+
+    axis.crossVectors(from, to);
+
+    // both scaled by |from| |to|
+    const sine = Math.sqrt(axis.lengthSqr());
+    const cosine = from.dot(to);
+
+    if (sine > 1e-12 * scale) {
+        axis.multiplyScalar(1 / sine);
+
+        out.fromAxisAngle(axis, Math.atan2(sine, cosine));
+
+        return;
+    }
+
+    if (scale === 0 || cosine > 0) {
+        out.set(0, 0, 0, 1);
+
+        return;
+    }
+
+    axis.copy(from).multiplyScalar(-fallback.dot(from) / from.lengthSqr()).add(fallback);
+
+    if (axis.lengthSqr() < 1e-24) {
+        // the fallback lies along `from` as well: any axis square to it will do
+        axis.crossVectors(from, Math.abs(from.x) < Math.abs(from.y) ? Vector3.right : Vector3.up);
+    }
+
+    axis.normalize();
+
+    out.fromAxisAngle(axis, Math.PI);
+}
 
 /**
- * Based on http://theorangeduck.com/page/simple-two-joint
- * @param {Vector3} a Root bone position
- * @param {Vector3} b Second bone position
- * @param {Vector3} c Effector position
- * @param {Vector3} t Target position
- * @param {number} eps EPSILON value, small value for rounding error compensation
- * @param {Quaternion} a_gr Global rotation of root bone
- * @param {Quaternion} b_gr Global rotation of second bone
- * @param {Quaternion} a_lr local rotation for root bone, this will be updated as a result
- * @param {Quaternion} b_lr local rotation for second bone, this will be updated as a result
+ * Two-joint inverse kinematics: turn a root joint and a hinged mid joint so the end of the chain
+ * lands on a target, in one call.
+ *
+ * After http://theorangeduck.com/page/simple-two-joint, with the mid joint's hinge given rather than
+ * guessed. The reference bends about `normalize((c - a) x d)` for some `d` "close to" where the knee
+ * points; this file used to take `d` as the mid joint's local -Z, which is the hinge only for a rig
+ * whose -Z lies in the bend plane and on the knee's side of it - a knee bending toward +Z, or a frame
+ * yawed 30 degrees, bent about the wrong axis and missed by up to 119 mm. `mid_axis` is the convention
+ * ozz-animation ships (`IKTwoBoneJob::mid_axis`): an axis in the mid joint's own frame, about which a
+ * positive turn straightens the joint, so it names the side the joint bends to as well as the axis.
+ *
+ * - The mid joint turns about its hinge alone, by the angle that sets the end at the target's distance
+ *   from the root. That is solved exactly whether or not the bones are square to the hinge, and a joint
+ *   animated past straight, against its hinge, is brought round to the side the hinge bends it.
+ * - The root then turns twice, both turns in world: back onto the ray the end was animated along (the
+ *   reference's bend, a turn about the hinge when the bones are square to it), then along the shortest
+ *   arc from that ray onto the target (its swing).
+ * - A target the chain cannot reach is reached for: the chain straightens, or folds, and points at it.
+ *
+ * The corrections are right-multiplied onto the local rotations, so whatever is above the root may be
+ * rotated arbitrarily.
+ *
+ * @param {Vector3} a root joint position, world
+ * @param {Vector3} b mid joint position, world
+ * @param {Vector3} c end position, world
+ * @param {Vector3} t target position, world
+ * @param {Vector3} mid_axis the mid joint's hinge in its own frame, of unit length; a positive turn
+ * about it straightens the joint
+ * @param {Quaternion} a_gr world rotation of the root joint
+ * @param {Quaternion} b_gr world rotation of the mid joint
+ * @param {Quaternion} a_lr local rotation of the root joint, corrected in place
+ * @param {Quaternion} b_lr local rotation of the mid joint, corrected in place
  */
 export function two_joint_ik(
-    a, b, c, t, eps,
+    a, b, c, t,
+    mid_axis,
     a_gr, b_gr,
     a_lr, b_lr
 ) {
+    assert.ok(mid_axis.isNormalized(), 'mid_axis must be of unit length');
+
+    hinge.copy(mid_axis).applyQuaternion(b_gr);
+
+    thigh.subVectors(b, a);
+    shin.subVectors(c, b);
+
+    // turning the knee leaves each bone's part along the hinge where it is, and turns the part across
+    const thigh_along = thigh.dot(hinge);
+    const shin_along = shin.dot(hinge);
+
+    thigh_across.copy(hinge).multiplyScalar(-thigh_along).add(thigh);
+    shin_across.copy(hinge).multiplyScalar(-shin_along).add(shin);
+
+    /*
+     With the shin's across part at angle g from the thigh's, about the hinge,
 
-    //Compute lengths of bones
-    const lab = b.distanceTo(a);
-    const lcb = b.distanceTo(c);
+         |end - root|^2 = base + span * cos(g)
 
-    const maximum_extension = lab + lcb - eps;
+     so the chain reaches from sqrt(base - span), folded, to sqrt(base + span), straight: for bones
+     square to the hinge, |lab - lcb| to lab + lcb. That is the whole of the clamp. The reference
+     trims the far end by an absolute `eps` so a leg "never appears fully extended"; a length in world
+     units is no ratio of a leg, and the 0.01 the ECS solver passed left every foot short of a target
+     within a centimetre of full reach. Easing into full extension is a separate choice
+     (ozz-animation's `soften`) and nothing asks for it.
+    */
+    const base = thigh.lengthSqr() + shin.lengthSqr() + 2 * thigh_along * shin_along;
+    const span = 2 * Math.sqrt(thigh_across.lengthSqr() * shin_across.lengthSqr());
 
-    //clamp length to the target to maximum extension of the joint
-    const lat = clamp(t.distanceTo(a), eps, maximum_extension);
+    reach.subVectors(t, a);
 
-    //compute current interior angles
-    const ac_ab_0 = v3_interior_angle(c, a, b);
-    const ba_bc_0 = v3_interior_angle(a, b, c);
-    const ac_at_0 = v3_interior_angle(c, a, t);
+    let knee_angle = 0;
 
-    // Using the cosine rule to compute desired interior angles
-    const length_at_sqr = lat * lat;
-    const length_cb_sqr = lcb * lcb;
-    const length_ab_sqr = lab * lab;
+    // a bone along the hinge has nothing across it to turn, and the reach is what it is
+    if (span > 0) {
+        axis.crossVectors(thigh_across, shin_across);
 
-    const ac_ab_1 = Math.acos(clamp((length_cb_sqr - length_ab_sqr - length_at_sqr) / (-2 * lab * lat), -1, 1));
-    const ba_bc_1 = Math.acos(clamp((length_at_sqr - length_ab_sqr - length_cb_sqr) / (-2 * lab * lcb), -1, 1));
+        const bend_animated = Math.atan2(axis.dot(hinge), thigh_across.dot(shin_across));
 
-    d.copy(Vector3.back);
-    d.applyQuaternion(b_gr);
+        const reach_sqr = clamp(reach.lengthSqr(), base - span, base + span);
 
-    delta_ca.subVectors(c, a);
-    delta_ta.subVectors(t, a);
+        // a positive turn straightens, so a joint bent the way its hinge bends it sits at g <= 0
+        const bend_solved = -Math.acos(clamp((reach_sqr - base) / span, -1, 1));
 
-    axis0.crossVectors(delta_ca, d);
-    axis0.normalize();
+        knee_angle = bend_solved - bend_animated;
+    }
 
-    axis1.crossVectors(delta_ca, delta_ta);
-    axis1.normalize();
+    turn.fromAxisAngle(mid_axis, knee_angle);
 
-    inv_a_gr.copyInverse(a_gr);
-    inv_b_gr.copyInverse(b_gr);
+    b_lr.multiply(turn);
 
-    axis0_la.copy(axis0);
-    axis0_la.applyQuaternion(inv_a_gr);
+    // the end, relative to the root, with the knee turned and the hip not yet
+    knee_turn.fromAxisAngle(hinge, knee_angle);
 
-    const angle0 = ac_ab_1 - ac_ab_0;
+    ankle_bent.copy(shin).applyQuaternion(knee_turn).add(thigh);
 
-    r0.fromAxisAngle(axis0_la, angle0);
+    aim.subVectors(c, a);
 
-    const angle1 = ba_bc_1 - ba_bc_0;
+    if (aim.lengthSqr() === 0) {
+        // animated with the end on the root, there is no ray to keep; the bent end's own serves
+        aim.copy(ankle_bent);
+    }
 
-    axis0_lb.copy(axis0);
-    axis0_lb.applyQuaternion(inv_b_gr);
+    /*
+     The bend first, then the swing, both turns in world, so the swing is the left factor. The
+     reference's listing composes them the other way about - bend after swing, about an axis the swing
+     has already carried away - and misses every target off the bend plane (14 mm for one 23 cm off on
+     a 0.92 m leg); its prose has them in this order.
+    */
+    turn_between(hip_turn, ankle_bent, aim, hinge);
 
-    r1.fromAxisAngle(axis0_lb, angle1);
+    turn_between(turn, aim, reach, hinge);
 
-    axis1_la.copy(axis1);
-    axis1_la.applyQuaternion(inv_a_gr);
+    hip_turn.multiplyQuaternions(turn, hip_turn);
 
-    r2.fromAxisAngle(axis1_la, ac_at_0);
+    // into the root's frame: a_lr * (a_gr^-1 * hip_turn * a_gr)
+    inverse_a_gr.copyInverse(a_gr);
 
-    r0.multiply(r2);
+    turn.multiplyQuaternions(inverse_a_gr, hip_turn);
+    turn.multiply(a_gr);
 
-    a_lr.multiply(r0);
-    b_lr.multiply(r1);
-}
+    a_lr.multiply(turn);
+}

package/src/format/image/avif/api/convert_to_rgba.d.ts

@@ -14,7 +14,7 @@
  *   for, in nits; defaults to {@link LINEAR_REFERENCE_NITS}. Only read for `COLOUR_SPACE_LINEAR`,
  *   and the exact counterpart of {@link encode_avif}'s option of the same name
  * @param {number} [options.chroma_upsampling] one of the `CHROMA_UPSAMPLING_*` constants
- * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ * @returns {{data: (Uint8ClampedArray|Uint16Array|Float16Array), width: number, height: number}}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -26,7 +26,7 @@ export function convert_to_rgba(decoder: AvifDecoder, image: YuvImage, options?:
     linear_reference_nits?: number;
     chroma_upsampling?: number;
 }): {
-    data: (Uint8ClampedArray | Uint16Array);
+    data: (Uint8ClampedArray | Uint16Array | Float16Array);
     width: number;
     height: number;
 };

package/src/format/image/avif/api/convert_to_rgba.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert_to_rgba.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/api/convert_to_rgba.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAZ4B,SAAS,GAA1B,MAAM;IACY,cAAc,GAAhC,OAAO;IACU,mBAAmB,GAApC,MAAM;IACW,qBAAqB,GAAtC,MAAM;IAGW,iBAAiB,GAAlC,MAAM;IACJ;IAAC,IAAI,EAAE,CAAC,iBAAiB,GAAC,WAAW,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAkJlF;AA5LD;;;GAGG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;GAGG;AACH,0CAFU,MAAM,CAE6B;AAE7C,uCAAuC;AACvC,wCADW,MAAM,CAC0B;AAE3C,8BAA8B;AAC9B,qCADW,MAAM,CACuB"}
+{"version":3,"file":"convert_to_rgba.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/api/convert_to_rgba.js"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAZ4B,SAAS,GAA1B,MAAM;IACY,cAAc,GAAhC,OAAO;IACU,mBAAmB,GAApC,MAAM;IACW,qBAAqB,GAAtC,MAAM;IAGW,iBAAiB,GAAlC,MAAM;IACJ;IAAC,IAAI,EAAE,CAAC,iBAAiB,GAAC,WAAW,eAAa,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAoJ/F;AA9LD;;;GAGG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;GAGG;AACH,0CAFU,MAAM,CAE6B;AAE7C,uCAAuC;AACvC,wCADW,MAAM,CAC0B;AAE3C,8BAA8B;AAC9B,qCADW,MAAM,CACuB"}

package/src/format/image/avif/api/convert_to_rgba.js

@@ -3,7 +3,6 @@ import { clamp_sample } from "../color/clamp_sample.js";
 import { colour_transform_init } from "../color/ColourTransform.js";
 import { LINEAR_REFERENCE_NITS } from "../color/transfer_to_linear.js";
 import { MC_BT_601 } from "../av1/tables/av1_symbols.js";
-import { to_half_float_uint16 } from "../../../../core/binary/to_half_float_uint16.js";
 import { transfer_row_to_linear } from "../color/transfer_to_linear.js";
 import { UPSAMPLE_BILINEAR, UPSAMPLE_NEAREST, upsample_chroma_row } from "../color/upsample_chroma_row.js";
 import { ycbcr_row_to_rgb } from "../color/ycbcr_row_to_rgb.js";
@@ -50,7 +49,7 @@ export const CHROMA_UPSAMPLING_BEST = 2;
  *   for, in nits; defaults to {@link LINEAR_REFERENCE_NITS}. Only read for `COLOUR_SPACE_LINEAR`,
  *   and the exact counterpart of {@link encode_avif}'s option of the same name
  * @param {number} [options.chroma_upsampling] one of the `CHROMA_UPSAMPLING_*` constants
- * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ * @returns {{data: (Uint8ClampedArray|Uint16Array|Float16Array), width: number, height: number}}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -98,9 +97,9 @@ export function convert_to_rgba(decoder, image, options = {}) {
 
     const samples = width * height * 4;
 
-    const data = output_float16 || output_bit_depth > 8
-        ? new Uint16Array(samples)
-        : new Uint8ClampedArray(samples);
+    const data = output_float16
+        ? new Float16Array(samples)
+        : output_bit_depth > 8 ? new Uint16Array(samples) : new Uint8ClampedArray(samples);
 
     const maximum = (1 << output_bit_depth) - 1;
 
@@ -180,10 +179,12 @@ export function convert_to_rgba(decoder, image, options = {}) {
                 : clamp01((image.alpha[alpha_row + x] - alpha_offset) * alpha_scale);
 
             if (output_float16) {
-                data[out] = to_half_float_uint16(rgb_row[i]);
-                data[out + 1] = to_half_float_uint16(rgb_row[i + 1]);
-                data[out + 2] = to_half_float_uint16(rgb_row[i + 2]);
-                data[out + 3] = to_half_float_uint16(alpha);
+                for (let c = 0; c < 3; c++) {
+                    const value = rgb_row[i + c];
+                    // Preserve finite HDR saturation, even with a very small reference white.
+                    data[out + c] = Number.isFinite(value) ? Math.min(Math.max(value, -65504), 65504) : value;
+                }
+                data[out + 3] = alpha;
             } else {
                 data[out] = quantise(rgb_row[i], maximum);
                 data[out + 1] = quantise(rgb_row[i + 1], maximum);