Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Sign-rig: forward/inverse kinematics for the canonical skeleton, in plain JS.
//
// Signing is a spatial language: a sign is "flat hand, palm out, at the chin,
// moving down-forward": a LOCATION and an ORIENTATION, never a list of joint
// angles. Authoring it as raw quaternions per bone is how the first pass of this
// feature ended up with the signing arm pointing behind the avatar: it assumed
// the reference rig aimed its bones down local +X from a T-pose, when cz.glb
// (like every Mixamo/Avaturn/VRM humanoid) aims them down local +Y through a
// shoulder whose own rest rotation is ~120° off identity.
//
// So this module reads the reference skeleton instead of assuming it. Everything
// below is derived at load time from the generated bind-pose data
// (src/animation-canonical-rest.js: rotations, positions, and parent chain of
// public/avatars/cz.glb):
//
// • each bone's axis (the local direction that points at its child),
// • each hand's palm normal and radial (thumb-side) direction,
// • bone lengths, so a two-bone IK solver can put the wrist at a POINT.
//
// A `Pose` is a mutable FK container: set a bone's world orientation and it
// stores the local rotation that produces it, given whatever its parents are
// currently doing. `solveArm` places a wrist at a world-space target with a
// natural elbow, then orients the hand by (fingers direction, palm direction).
// The output is the same absolute-local-rotation form the clip library stores,
// so it retargets onto any rigged avatar through src/animation-retarget.js.
//
// Pure module: no three.js, no DOM: it runs in the browser, in Node, and in
// vitest identically.
import {
CANONICAL_PARENT,
CANONICAL_REST,
CANONICAL_REST_POSITION,
CANONICAL_REST_WORLD,
} from './animation-canonical-rest.js';
// ── vector + quaternion helpers ([x, y, z, w], matching three.js) ───────────
export const IDENTITY = Object.freeze([0, 0, 0, 1]);
export const v3 = (x, y, z) => [x, y, z];
export function vAdd(a, b) {
return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
}
export function vSub(a, b) {
return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
}
export function vScale(a, k) {
return [a[0] * k, a[1] * k, a[2] * k];
}
export function vDot(a, b) {
return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
}
export function vCross(a, b) {
return [
a[1] * b[2] - a[2] * b[1],
a[2] * b[0] - a[0] * b[2],
a[0] * b[1] - a[1] * b[0],
];
}
export function vLen(a) {
return Math.hypot(a[0], a[1], a[2]);
}
export function vNorm(a) {
const n = vLen(a);
return n < 1e-9 ? [0, 0, 0] : [a[0] / n, a[1] / n, a[2] / n];
}
export function vLerp(a, b, t) {
return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
}
/** Component of `a` perpendicular to unit vector `axis`. */
export function vReject(a, axis) {
const d = vDot(a, axis);
return [a[0] - axis[0] * d, a[1] - axis[1] * d, a[2] - axis[2] * d];
}
export function qMul(a, b) {
const [ax, ay, az, aw] = a;
const [bx, by, bz, bw] = b;
return [
aw * bx + ax * bw + ay * bz - az * by,
aw * by - ax * bz + ay * bw + az * bx,
aw * bz + ax * by - ay * bx + az * bw,
aw * bw - ax * bx - ay * by - az * bz,
];
}
export function qConj(q) {
return [-q[0], -q[1], -q[2], q[3]];
}
export function qNorm(q) {
const n = Math.hypot(q[0], q[1], q[2], q[3]);
return n < 1e-9 ? [...IDENTITY] : [q[0] / n, q[1] / n, q[2] / n, q[3] / n];
}
export function qAxisAngle(axis, deg) {
const [x, y, z] = vNorm(axis);
const half = (deg * Math.PI) / 360;
const s = Math.sin(half);
return [x * s, y * s, z * s, Math.cos(half)];
}
/** Rotate vector `v` by quaternion `q`. */
export function qRotate(q, v) {
const [x, y, z, w] = q;
// t = 2 * (q.xyz × v); v' = v + w*t + q.xyz × t
const tx = 2 * (y * v[2] - z * v[1]);
const ty = 2 * (z * v[0] - x * v[2]);
const tz = 2 * (x * v[1] - y * v[0]);
return [
v[0] + w * tx + y * tz - z * ty,
v[1] + w * ty + z * tx - x * tz,
v[2] + w * tz + x * ty - y * tx,
];
}
/** Shortest rotation carrying unit vector `from` onto unit vector `to`. */
export function qBetween(from, to) {
const f = vNorm(from);
const t = vNorm(to);
const d = vDot(f, t);
if (d > 1 - 1e-9) return [...IDENTITY];
if (d < -1 + 1e-9) {
let axis = vCross(f, [1, 0, 0]);
if (vLen(axis) < 1e-6) axis = vCross(f, [0, 1, 0]);
const [x, y, z] = vNorm(axis);
return [x, y, z, 0];
}
const axis = vCross(f, t);
return qNorm([axis[0], axis[1], axis[2], 1 + d]);
}
export function qSlerp(a, b, t) {
let [bx, by, bz, bw] = b;
let cos = a[0] * bx + a[1] * by + a[2] * bz + a[3] * bw;
if (cos < 0) {
cos = -cos;
bx = -bx;
by = -by;
bz = -bz;
bw = -bw;
}
if (cos > 0.9995) return qNorm([
a[0] + (bx - a[0]) * t,
a[1] + (by - a[1]) * t,
a[2] + (bz - a[2]) * t,
a[3] + (bw - a[3]) * t,
]);
const theta = Math.acos(cos);
const sin = Math.sin(theta);
const wa = Math.sin((1 - t) * theta) / sin;
const wb = Math.sin(t * theta) / sin;
return qNorm([a[0] * wa + bx * wb, a[1] * wa + by * wb, a[2] * wa + bz * wb, a[3] * wa + bw * wb]);
}
// Quaternion from an orthonormal 3×3 basis given as its column vectors.
function qFromBasis(x, y, z) {
const m00 = x[0], m10 = x[1], m20 = x[2];
const m01 = y[0], m11 = y[1], m21 = y[2];
const m02 = z[0], m12 = z[1], m22 = z[2];
const trace = m00 + m11 + m22;
if (trace > 0) {
const s = 0.5 / Math.sqrt(trace + 1);
return qNorm([(m21 - m12) * s, (m02 - m20) * s, (m10 - m01) * s, 0.25 / s]);
}
if (m00 > m11 && m00 > m22) {
const s = 2 * Math.sqrt(1 + m00 - m11 - m22);
return qNorm([0.25 * s, (m01 + m10) / s, (m02 + m20) / s, (m21 - m12) / s]);
}
if (m11 > m22) {
const s = 2 * Math.sqrt(1 + m11 - m00 - m22);
return qNorm([(m01 + m10) / s, 0.25 * s, (m12 + m21) / s, (m02 - m20) / s]);
}
const s = 2 * Math.sqrt(1 + m22 - m00 - m11);
return qNorm([(m02 + m20) / s, (m12 + m21) / s, 0.25 * s, (m10 - m01) / s]);
}
// Orthonormal basis from a primary direction and a secondary reference. The
// primary is preserved exactly; the reference only resolves the roll.
function basisFrom(primary, reference) {
const a = vNorm(primary);
let b = vReject(reference, a);
if (vLen(b) < 1e-6) {
// Reference parallel to the primary: pick any perpendicular so the frame
// stays well-defined (the caller's roll is undefined anyway).
b = vReject(Math.abs(a[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0], a);
}
b = vNorm(b);
return [a, b, vCross(a, b)];
}
/**
* The rotation that carries the local frame (`axisLocal`, `refLocal`) onto the
* world frame (`axisWorld`, `refWorld`). `axisLocal → axisWorld` is exact; the
* reference pair only fixes the twist about it.
*/
export function orientQuat(axisLocal, refLocal, axisWorld, refWorld) {
const [la, lb, lc] = basisFrom(axisLocal, refLocal);
const [wa, wb, wc] = basisFrom(axisWorld, refWorld);
// Q = W · Lᵀ, expressed as two basis quaternions: Q = qW · qL⁻¹.
const qL = qFromBasis(la, lb, lc);
const qW = qFromBasis(wa, wb, wc);
return qNorm(qMul(qW, qConj(qL)));
}
// ── the reference skeleton, read from the generated bind pose ───────────────
/** Nearest canonical ancestor of `bone`, or null at the root. */
export const parentOf = (bone) => CANONICAL_PARENT[bone] ?? null;
/** Local rest (bind) rotation of `bone` on the reference rig. */
export const restLocal = (bone) => CANONICAL_REST[bone] ?? [...IDENTITY];
/** World (model-space) rest rotation of `bone` on the reference rig. */
export const restWorld = (bone) => CANONICAL_REST_WORLD[bone] ?? [...IDENTITY];
/** World (model-space) rest position of `bone`, in metres. */
export const restPos = (bone) => CANONICAL_REST_POSITION[bone] ?? [0, 0, 0];
/** True when the reference rig carries this canonical bone. */
export const hasBone = (bone) => Object.hasOwn(CANONICAL_REST, bone);
const CHILDREN = (() => {
const map = new Map();
for (const [bone, parent] of Object.entries(CANONICAL_PARENT)) {
if (!parent) continue;
if (!map.has(parent)) map.set(parent, []);
map.get(parent).push(bone);
}
return map;
})();
// Bones with several canonical children need the one that defines the segment's
// direction: the hand points down the middle finger, the hips up the spine.
const PREFERRED_CHILD = {
Hips: 'Spine',
LeftHand: 'LeftHandMiddle1',
RightHand: 'RightHandMiddle1',
};
function segmentChild(bone) {
if (PREFERRED_CHILD[bone] && hasBone(PREFERRED_CHILD[bone])) return PREFERRED_CHILD[bone];
return (CHILDREN.get(bone) || [])[0] ?? null;
}
/** World direction `bone` points at rest (toward its child, or along its own segment for a tip). */
export function restDirWorld(bone) {
const child = segmentChild(bone);
if (child) return vNorm(vSub(restPos(child), restPos(bone)));
const parent = parentOf(bone);
if (parent) return vNorm(vSub(restPos(bone), restPos(parent)));
return [0, 1, 0];
}
const _axisCache = new Map();
/**
* The bone's own axis: the LOCAL direction that points at its child. ~[0,1,0]
* on most canonical humanoid rigs, but measured rather than assumed.
* @param {string} bone
* @returns {number[]}
*/
export function boneAxis(bone) {
if (!_axisCache.has(bone)) {
_axisCache.set(bone, vNorm(qRotate(qConj(restWorld(bone)), restDirWorld(bone))));
}
return _axisCache.get(bone);
}
/** Length of the segment from `bone` to its next canonical joint, in metres. */
export function boneLength(bone) {
const child = segmentChild(bone);
return child ? vLen(vSub(restPos(child), restPos(bone))) : 0;
}
// Per-hand anatomy, measured from the bind pose rather than assumed:
// radial: from the pinky knuckle toward the index knuckle, i.e. the thumb
// side of the hand (forward, +Z, on this palms-down T-pose rig),
// palm: normal to the hand plane, flipped to the side the thumb tip sits
// on, which is the palm side for any relaxed humanoid hand.
// Both are stored in WORLD terms; per-bone locals come from each bone's own
// rest rotation, so the finger joints inherit the frame without mirror hacks.
function handFrame(side) {
const hand = `${side}Hand`;
const axis = restDirWorld(hand);
let radial = vNorm(vReject(vSub(restPos(`${side}HandIndex1`), restPos(`${side}HandPinky1`)), axis));
if (vLen(radial) < 1e-6) radial = vNorm(vReject([0, 0, 1], axis));
let palm = vNorm(vCross(radial, axis));
const thumbTip = vSub(restPos(`${side}HandThumb3`), restPos(hand));
if (vDot(palm, thumbTip) < 0) palm = vScale(palm, -1);
return { axis, radial, palm };
}
const HAND_FRAME = { Left: handFrame('Left'), Right: handFrame('Right') };
/** World direction the `side` palm faces at rest (down, on this rig). */
export const restPalmWorld = (side) => HAND_FRAME[side].palm;
/** World direction from the pinky toward the thumb side of the `side` hand at rest. */
export const restRadialWorld = (side) => HAND_FRAME[side].radial;
const sideOf = (bone) => (bone.startsWith('Left') ? 'Left' : 'Right');
/** LOCAL direction in which `bone`'s palm side faces (hand + finger bones). */
export function palmAxis(bone) {
return vNorm(qRotate(qConj(restWorld(bone)), HAND_FRAME[sideOf(bone)].palm));
}
/** LOCAL direction toward the thumb side of the hand (hand + finger bones). */
export function radialAxis(bone) {
return vNorm(qRotate(qConj(restWorld(bone)), HAND_FRAME[sideOf(bone)].radial));
}
/**
* LOCAL flexion axis of a finger/thumb joint: rotating about it by a POSITIVE
* angle curls the bone toward the palm. Derived per bone, so it is correct on
* both hands with no mirroring by hand.
*/
export function curlAxis(bone) {
return vNorm(vCross(boneAxis(bone), palmAxis(bone)));
}
/**
* LOCAL abduction axis of a finger joint: a POSITIVE angle splays the finger
* toward the thumb side, a negative one toward the pinky.
*/
export function splayAxis(bone) {
return vNorm(vCross(boneAxis(bone), radialAxis(bone)));
}
/**
* LOCAL adduction axis of a thumb joint: a POSITIVE angle swings the thumb in
* toward the fingers (across the palm), a negative one out away from them.
*/
export function adductAxis(bone) {
const handDir = restDirWorld(`${sideOf(bone)}Hand`);
return vNorm(vCross(boneAxis(bone), qRotate(qConj(restWorld(bone)), handDir)));
}
/** The five digits, and every finger bone of one hand in track order. */
export const FINGERS = Object.freeze(['Index', 'Middle', 'Ring', 'Pinky']);
export const FINGER_JOINTS = Object.freeze([1, 2, 3]);
export function fingerBones(side) {
return [...FINGERS, 'Thumb'].flatMap((f) => FINGER_JOINTS.map((j) => `${side}Hand${f}${j}`));
}
// ── touchable parts of a hand ──────────────────────────────────────────────
//
// Signs are described by CONTACT ("two fingers stand on the flat palm", "the
// fingertips touch the forehead"), not by where the wrist happens to be. Solving
// that needs the geometry of the posed hand: where its fingertips are, where its
// palm faces. Reading it off the skeleton is what makes contact survive a
// different avatar: hand size and finger length change, and the contact still
// lands, where a hardcoded wrist position would drift off the palm.
// Skin sits outside the bone: contact points on a surface are offset off the
// bone plane by roughly half a hand's thickness so two hands meet instead of
// interpenetrating. Scaled from the rig's own hand length, not a magic number.
const SURFACE = 0.14; // fraction of hand length
/** Length past the last knuckle to the fingertip, estimated from the rig. */
function tipExtension(side, finger) {
return boneLength(`${side}Hand${finger}2`) * 0.85;
}
/** World position of a fingertip under `pose` (past the final joint). */
export function fingerTip(pose, side, finger) {
const distal = `${side}Hand${finger}3`;
return vAdd(pose.worldPos(distal), vScale(pose.worldDir(distal), tipExtension(side, finger)));
}
const mean = (points) => vScale(points.reduce(vAdd, [0, 0, 0]), 1 / points.length);
/**
* World position of a named part of a posed hand.
*
* `palm`/`back` are surface points, offset off the bone plane so a hand resting
* on the palm sits ON it. `fingertips` is the pad of the index and middle
* fingers, which is what most contacting signs actually use.
*
* @param {Pose} pose
* @param {'Left'|'Right'} side
* @param {'wrist'|'palm'|'back'|'fingertips'|'indextip'|'middletip'|'thumbtip'|'knuckles'|'fingers'|'edge'} part
* @returns {number[]}
*/
export function handPoint(pose, side, part = 'fingertips') {
const hand = `${side}Hand`;
const q = pose.worldQuat(hand);
const normal = vNorm(qRotate(q, palmAxis(hand)));
const radial = vNorm(qRotate(q, radialAxis(hand)));
const thickness = boneLength(hand) * SURFACE;
const knuckles = () => FINGERS.map((f) => pose.worldPos(`${side}Hand${f}1`));
switch (part) {
case 'wrist':
return pose.worldPos(hand);
case 'palm':
return vAdd(mean([pose.worldPos(hand), ...knuckles()]), vScale(normal, thickness));
case 'back':
return vAdd(mean([pose.worldPos(hand), ...knuckles()]), vScale(normal, -thickness));
case 'knuckles':
return vAdd(mean(knuckles()), vScale(normal, thickness));
case 'fingers':
return vAdd(
mean([pose.worldPos(`${side}HandIndex2`), pose.worldPos(`${side}HandMiddle2`)]),
vScale(normal, thickness),
);
case 'edge':
return vAdd(pose.worldPos(`${side}HandPinky1`), vScale(radial, -thickness));
case 'indextip':
return fingerTip(pose, side, 'Index');
case 'middletip':
return fingerTip(pose, side, 'Middle');
case 'thumbtip':
return fingerTip(pose, side, 'Thumb');
case 'fingertips':
return mean([fingerTip(pose, side, 'Index'), fingerTip(pose, side, 'Middle')]);
default:
throw new Error(`unknown hand part "${part}"`);
}
}
/**
* The offset from the wrist to one of its own parts, expressed in the HAND's
* local frame: so it depends only on the handshape, not on where the arm is.
* That is what lets the solver work backwards: given where a fingertip must
* END UP and which way the hand faces, this says where the wrist has to go.
*
* @param {Pose} pose supplies this hand's finger rotations
* @param {'Left'|'Right'} side
* @param {string} part
* @returns {number[]}
*/
export function handPartOffset(pose, side, part = 'fingertips') {
// Measure on a scratch pose whose arm is at rest, so the answer is purely the
// hand's own shape.
const scratch = new Pose();
for (const bone of fingerBones(side)) scratch.setLocal(bone, pose.getLocal(bone));
const hand = `${side}Hand`;
const point = handPoint(scratch, side, part);
return qRotate(qConj(scratch.worldQuat(hand)), vSub(point, scratch.worldPos(hand)));
}
// Anchors ride a bone, so a turned head carries the chin with it. Anything not
// listed is fixed in model space.
const ANCHOR_BONE = {
forehead: 'Head',
nose: 'Head',
chin: 'Head',
mouth: 'Head',
head: 'Head',
neck: 'Neck',
sternum: 'Spine2',
chest: 'Spine2',
belly: 'Spine1',
shoulder: 'Spine2',
hip: 'Hips',
};
/**
* An anchor's position under a POSE rather than at rest: the rest point is
* carried by whichever bone owns it, so a sign that touches the chin still
* touches the chin when the head has turned.
*
* @param {Pose} pose
* @param {string} name ANCHORS key
* @param {{ out?: number, up?: number, forward?: number, side?: 'Left'|'Right' }} [offset]
* @returns {number[]}
*/
export function anchorPoint(pose, name, offset = {}) {
const rest = signPoint(name, offset);
const bone = ANCHOR_BONE[name];
if (!bone || !hasBone(bone)) return rest;
const local = qRotate(qConj(restWorld(bone)), vSub(rest, restPos(bone)));
return vAdd(pose.worldPos(bone), qRotate(pose.worldQuat(bone), local));
}
// ── the signing body: anchors and workspace ────────────────────────────────
/**
* Anatomical anchor points in model space, measured off the reference rig, so a
* sign can be authored as "at the chin" or "centre chest" instead of as an
* arbitrary XYZ. Signs are written against these and stay anatomically placed.
*/
export const ANCHORS = (() => {
const head = restPos('Head');
const neck = restPos('Neck');
const chest = restPos('Spine2');
const hips = restPos('Hips');
const shoulderR = restPos('RightArm');
const shoulderL = restPos('LeftArm');
// At a palms-down rest the hand's radial (thumb) side points where the body
// faces, so the rig gives us "forward" without a hardcoded axis.
const forward = restRadialWorld('Right');
const up = [0, 1, 0];
const chinY = neck[1] + (head[1] - neck[1]) * 0.55;
return Object.freeze({
forward,
up,
/** Model-space width between the shoulders: the unit signs scale by. */
shoulderSpan: vLen(vSub(shoulderL, shoulderR)),
head,
neck,
chest,
hips,
/** Side-aware anchors: `signPoint('shoulder', { side })` picks the right one. */
shoulder: { Left: shoulderL, Right: shoulderR },
hip: {
Left: [Math.abs(shoulderL[0]) * 0.55, hips[1], hips[2]],
Right: [-Math.abs(shoulderR[0]) * 0.55, hips[1], hips[2]],
},
forehead: [0, head[1] + 0.07, head[2]],
chin: [0, chinY, head[2] + 0.03],
mouth: [0, chinY + 0.04, head[2] + 0.04],
nose: [0, head[1] + 0.02, head[2] + 0.05],
/**
* Upper chest, where most two-handed signs live. Measured up from the
* chest bone toward the neck rather than from the bone itself, which sits
* at mid-torso: anchoring signs there hangs them at belly height.
*/
sternum: [0, chest[1] + (neck[1] - chest[1]) * 0.6, chest[2] + 0.02],
/** Mid torso: the low end of neutral signing space. */
belly: [0, (chest[1] + hips[1]) / 2, chest[2]],
});
})();
/**
* A point in signing space: an anchor (or explicit point) plus an offset in
* body-relative axes: out (toward the signer's dominant side), up, and forward
* (toward the receiver). Offsets are in metres on the reference rig.
*
* @param {number[]|string} anchor ANCHORS key or an explicit [x,y,z]
* @param {{ out?: number, up?: number, forward?: number, side?: 'Left'|'Right' }} [offset]
* @returns {number[]} model-space point
*/
export function signPoint(anchor, offset = {}) {
const side = offset.side ?? 'Right';
let base = Array.isArray(anchor) ? anchor : ANCHORS[anchor];
// Side-aware anchors (shoulder, hip) resolve against the acting hand.
if (base && !Array.isArray(base)) base = base[side];
if (!base) throw new Error(`unknown sign anchor "${anchor}"`);
const outSign = side === 'Right' ? -1 : 1; // the right hand's "out" is −X
return [
base[0] + outSign * (offset.out ?? 0),
base[1] + (offset.up ?? 0),
base[2] + (offset.forward ?? 0),
];
}
// ── the pose container ─────────────────────────────────────────────────────
/**
* A skeleton pose: per-bone LOCAL rotations (absolute, replacing the rest
* rotation exactly like an AnimationClip track does), with forward kinematics
* so a caller can ask where a bone ENDED UP and aim bones at world targets.
*/
export class Pose {
/** @param {Pose|null} [from] copy-construct from another pose */
constructor(from = null) {
/** @type {Map<string, number[]>} */
this.local = new Map(from ? from.local : []);
/**
* Blendshape weights, 0-1 by name. ASL carries grammar on the face, so a
* pose is not complete without it: raised brows make a yes/no question,
* furrowed brows a wh-question, and neither is optional decoration.
* @type {Map<string, number>}
*/
this.face = new Map(from ? from.face : []);
this._worldQ = new Map();
this._worldP = new Map();
}
clone() {
return new Pose(this);
}
_invalidate() {
this._worldQ.clear();
this._worldP.clear();
}
/** Local rotation of `bone`: posed if set, otherwise the rig's rest. */
getLocal(bone) {
return this.local.get(bone) ?? restLocal(bone);
}
/** Set `bone`'s local rotation directly. */
setLocal(bone, q) {
this.local.set(bone, qNorm(q));
this._invalidate();
return this;
}
/** Rotate `bone` by `deg` about a LOCAL axis, on top of its current rotation. */
rotateLocal(bone, axis, deg) {
return this.setLocal(bone, qMul(this.getLocal(bone), qAxisAngle(axis, deg)));
}
/** World (model-space) rotation of `bone` under this pose. */
worldQuat(bone) {
let q = this._worldQ.get(bone);
if (q) return q;
const parent = parentOf(bone);
q = parent ? qMul(this.worldQuat(parent), this.getLocal(bone)) : this.getLocal(bone);
this._worldQ.set(bone, q);
return q;
}
/** World (model-space) position of `bone` under this pose. */
worldPos(bone) {
let p = this._worldP.get(bone);
if (p) return p;
const parent = parentOf(bone);
if (!parent) {
p = restPos(bone);
} else {
// The bone's fixed offset from its parent, carried by the parent's
// posed rotation: the rig's own bone lengths, never rescaled.
const offsetLocal = qRotate(qConj(restWorld(parent)), vSub(restPos(bone), restPos(parent)));
p = vAdd(this.worldPos(parent), qRotate(this.worldQuat(parent), offsetLocal));
}
this._worldP.set(bone, p);
return p;
}
/** World direction `bone` points under this pose (toward its child). */
worldDir(bone) {
return vNorm(qRotate(this.worldQuat(bone), boneAxis(bone)));
}
/** Set `bone`'s WORLD rotation, storing the local that produces it here. */
setWorldQuat(bone, qWorld) {
const parent = parentOf(bone);
const local = parent ? qMul(qConj(this.worldQuat(parent)), qWorld) : qWorld;
return this.setLocal(bone, local);
}
/**
* Aim `bone` down `dirWorld`, using `refWorld` to resolve the twist about it.
* `refLocal` defaults to the bone's palm axis (hands/fingers) so callers can
* say "point the fingers here, face the palm there".
*/
aim(bone, dirWorld, refWorld = null, refLocal = null) {
const axisLocal = boneAxis(bone);
if (!refWorld) {
// No roll requested: rotate the bone's current orientation the short way.
const current = this.worldDir(bone);
return this.setWorldQuat(bone, qMul(qBetween(current, dirWorld), this.worldQuat(bone)));
}
const rl = refLocal ?? palmAxis(bone);
return this.setWorldQuat(bone, orientQuat(axisLocal, rl, dirWorld, refWorld));
}
/** Set blendshape weights by name, merging with whatever is already set. */
setFace(weights) {
for (const [shape, value] of Object.entries(weights ?? {})) {
this.face.set(shape, Math.max(0, Math.min(1, value)));
}
return this;
}
/** Weight of one blendshape under this pose (0 when unset). */
getFace(shape) {
return this.face.get(shape) ?? 0;
}
/** Plain `{bone: [x,y,z,w]}` of every posed bone: the clip track payload. */
locals() {
return Object.fromEntries(this.local);
}
}
// ── two-bone arm IK ────────────────────────────────────────────────────────
/**
* Place a `side` wrist at a world-space point with a natural elbow, then orient
* the hand.
*
* The elbow lands on the circle of valid solutions, pushed toward `pole`: a
* world direction meaning "the elbow points that way". The default drops it
* down, back, and slightly out, which is where a signer's elbow actually sits;
* signs never lift the elbow to shoulder height unless the sign says so.
*
* Roll is anatomical, not arbitrary: the upper arm twists so the elbow flexes in
* the plane the pole defines, and the forearm carries the pronation the palm
* direction implies: so the wrist itself only ever holds the small residual,
* which is what stops the "broken wrist" look.
*
* @param {Pose} pose mutated in place
* @param {'Left'|'Right'} side
* @param {{
* wrist: number[],
* fingers?: number[],
* palm?: number[],
* pole?: number[],
* reach?: number,
* }} spec `wrist` is the world target for the wrist joint; `fingers`/`palm` are
* world directions for the hand; `reach` (0-1) caps how straight the arm may
* lock (0.98 default leaves a soft elbow).
* @returns {Pose} the same pose
*/
export function solveArm(pose, side, spec) {
const upper = `${side}Arm`;
const lower = `${side}ForeArm`;
const hand = `${side}Hand`;
const shoulder = pose.worldPos(upper);
const lu = boneLength(upper);
const ll = boneLength(lower);
const reach = spec.reach ?? 0.985;
let toTarget = vSub(spec.wrist, shoulder);
let dist = vLen(toTarget);
const maxReach = (lu + ll) * reach;
const minReach = Math.abs(lu - ll) + 1e-3;
if (dist < 1e-6) {
toTarget = [0, -1, 0];
dist = minReach;
}
dist = Math.min(maxReach, Math.max(minReach, dist));
const toDir = vNorm(toTarget);
// Elbow direction: default down/back/outward from the shoulder.
const outSign = side === 'Right' ? -1 : 1;
const pole = spec.pole ?? [outSign * 0.42, -1, -0.30];
let polePerp = vReject(pole, toDir);
if (vLen(polePerp) < 1e-6) polePerp = vReject([0, -1, 0], toDir);
polePerp = vNorm(polePerp);
// Law of cosines: how far along the shoulder→target line the elbow sits.
const cosShoulder = Math.min(1, Math.max(-1, (lu * lu + dist * dist - ll * ll) / (2 * lu * dist)));
const sinShoulder = Math.sqrt(Math.max(0, 1 - cosShoulder * cosShoulder));
const elbow = vAdd(shoulder, vAdd(vScale(toDir, lu * cosShoulder), vScale(polePerp, lu * sinShoulder)));
const upperDir = vNorm(vSub(elbow, shoulder));
const wristPoint = vAdd(shoulder, vScale(toDir, dist));
const lowerDir = vNorm(vSub(wristPoint, elbow));
// The direction the forearm swings toward as the elbow closes: the anterior
// side of the arm. Falls back to the pole when the arm is nearly straight.
let flexDir = vReject(lowerDir, upperDir);
if (vLen(flexDir) < 1e-4) flexDir = vScale(polePerp, -1);
flexDir = vNorm(flexDir);
// On this rest pose (T-pose, palms down) elbow flexion carries the hand
// toward the hand's radial side, so that rest direction is the upper arm's
// flexion reference. Measured, not assumed.
const radialWorld = restRadialWorld(side);
const upperRefLocal = vNorm(qRotate(qConj(restWorld(upper)), radialWorld));
pose.setWorldQuat(upper, orientQuat(boneAxis(upper), upperRefLocal, upperDir, flexDir));
// The forearm carries pronation: aim its palm side where the hand's palm is
// going, so the wrist holds only the residual.
const palmTarget = spec.palm ? vNorm(spec.palm) : null;
const lowerRefLocal = vNorm(qRotate(qConj(restWorld(lower)), restPalmWorld(side)));
const lowerRefWorld = palmTarget ?? flexDir;
pose.setWorldQuat(lower, orientQuat(boneAxis(lower), lowerRefLocal, lowerDir, lowerRefWorld));
// Hand: fingers down `fingers`, palm facing `palm`. Default carries the
// forearm's own direction through, i.e. a straight wrist.
const fingersDir = spec.fingers ? vNorm(spec.fingers) : lowerDir;
if (palmTarget) {
pose.setWorldQuat(hand, orientQuat(boneAxis(hand), palmAxis(hand), fingersDir, palmTarget));
} else {
pose.aim(hand, fingersDir);
}
return pose;
}
/**
* Where the wrist actually landed for a solved arm: the reachability check the
* tests assert against, since IK clamps targets outside the arm's range.
* @param {Pose} pose
* @param {'Left'|'Right'} side
* @returns {number[]}
*/
export function wristPosition(pose, side) {
return pose.worldPos(`${side}Hand`);
}