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
/**
* Runtime animation retargeting — unit tests.
*
* Builds synthetic skeletons and clips in-memory (no GLB fixtures), so the
* suite is fast and deterministic. Covers the contract that lets a canonical
* preset clip drive an arbitrarily-named, arbitrarily-proportioned rig:
* - track bone names rewritten to the target's actual node names,
* - vendor-prefixed rigs (mixamorig:, DEF-, snake_case) still map,
* - tracks for bones the rig lacks are dropped + reported,
* - coverage gating returns a null clip below MIN_COVERAGE,
* - hip translation scaling and speed resampling are applied.
*/
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { describe, it, expect } from 'vitest';
import {
Bone,
SkinnedMesh,
Skeleton,
BufferGeometry,
QuaternionKeyframeTrack,
NumberKeyframeTrack,
VectorKeyframeTrack,
AnimationClip,
Object3D,
Quaternion,
Vector3,
Euler,
Uint16BufferAttribute,
Float32BufferAttribute,
} from 'three';
import {
canonicalNodeMapFromObject,
canonicalRestMapFromObject,
hipGroundLocalY,
hipRestLocalHeight,
hipsParentWorldQuat,
retargetClip,
retargetClipToObject,
scaleClipSpeed,
trimClip,
blendClipLoop,
MIN_COVERAGE,
} from '../src/animation-retarget.js';
import { CANONICAL_REST, CANONICAL_REST_WORLD } from '../src/animation-canonical-rest.js';
import { canonicalizeBoneName } from '../src/glb-canonicalize.js';
import { loadBoneGraph } from './_helpers/glb-bone-graph.js';
// Build a SkinnedMesh-rooted skeleton from a list of bone names so
// canonicalNodeMapFromObject finds it the way it would in a real GLB.
function makeRig(boneNames) {
const root = new Object3D();
const bones = boneNames.map((name) => {
const b = new Bone();
b.name = name;
return b;
});
// Parent them all under root (flat is fine for name-mapping tests).
for (const b of bones) root.add(b);
const mesh = new SkinnedMesh(new BufferGeometry());
mesh.add(bones[0]);
mesh.bind(new Skeleton(bones));
root.add(mesh);
return root;
}
// Build a SkinnedMesh-rooted skeleton with a REAL parent/child hierarchy, so
// tests can exercise the structural (ancestor) reasoning the flat `makeRig`
// can't express. Each bone gets a distinct rest rotation and offset, so a test
// that reads the wrong node's rest pose fails instead of matching by accident.
// `rows` is parent-before-child, each `{ name, parent }` naming a previous row.
function makeHierarchicalRig(rows) {
const byName = new Map();
const root = new Object3D();
rows.forEach((row, i) => {
const bone = new Bone();
bone.name = row.name;
bone.position.set(0, 0.1 + i * 0.01, 0);
bone.quaternion.setFromEuler(new Euler(0, 0, (i + 1) * 0.05));
byName.set(row.name, bone);
(row.parent ? byName.get(row.parent) : root).add(bone);
});
const mesh = new SkinnedMesh(new BufferGeometry());
mesh.bind(new Skeleton([...byName.values()]));
root.add(mesh);
root.updateMatrixWorld(true);
return root;
}
// A canonical clip: quaternion tracks on a few bones + a Hips position track.
function makeCanonicalClip() {
const q = new QuaternionKeyframeTrack('Hips.quaternion', [0, 1], [0, 0, 0, 1, 0, 0, 0, 1]);
const spine = new QuaternionKeyframeTrack('Spine.quaternion', [0, 1], [0, 0, 0, 1, 0, 0, 0, 1]);
const arm = new QuaternionKeyframeTrack('LeftArm.quaternion', [0, 1], [0, 0, 0, 1, 0, 0, 0, 1]);
// Hips at world Y = 1.0 (authoring rig height).
const pos = new VectorKeyframeTrack('Hips.position', [0, 1], [0, 1, 0, 0, 1.1, 0]);
return new AnimationClip('test', 1, [q, spine, arm, pos]);
}
// A 3-keyframe clip with distinct values at every sample (makeCanonicalClip's
// identity-at-both-ends shape can't tell slerp/lerp apart), for trim/blend math.
function makeMovingClip() {
const q = new QuaternionKeyframeTrack(
'Hips.quaternion',
[0, 1, 2],
[0, 0, 0, 1, 0, 0.7071067811865476, 0, 0.7071067811865476, 0, 1, 0, 0],
);
const pos = new VectorKeyframeTrack('Hips.position', [0, 1, 2], [0, 1, 0, 0, 1, 1, 0, 1, 2]);
return new AnimationClip('moving', 2, [q, pos]);
}
const CANONICAL_RIG = ['Hips', 'Spine', 'LeftArm', 'RightArm', 'Head'];
describe('canonicalNodeMapFromObject', () => {
it('maps canonical bone names to themselves', () => {
const map = canonicalNodeMapFromObject(makeRig(CANONICAL_RIG));
expect(map.get('Hips')).toBe('Hips');
expect(map.get('LeftArm')).toBe('LeftArm');
});
it('maps vendor-prefixed and separator variants to canonical → real node name', () => {
const map = canonicalNodeMapFromObject(
makeRig(['mixamorig:Hips', 'DEF-spine', 'left_arm', 'Armature_Head']),
);
expect(map.get('Hips')).toBe('mixamorig:Hips');
expect(map.get('Spine')).toBe('DEF-spine');
expect(map.get('LeftArm')).toBe('left_arm');
expect(map.get('Head')).toBe('Armature_Head');
});
it('returns an empty map for a rig with no recognizable humanoid bones', () => {
const map = canonicalNodeMapFromObject(makeRig(['root', 'wheel_fl', 'wheel_fr']));
expect(map.size).toBe(0);
});
});
// A rig where the clavicle and the upper arm both normalize onto ONE canonical
// name is the hardest naming case there is, because the same spelling means a
// different bone on a different rig: Rigify's `shoulder.L` is the clavicle,
// while a hand-built rig's `shoulderL` IS the upper arm. Getting it wrong binds
// the arm clip to the shoulder blade (the arm swings from the wrong pivot) or
// leaves LeftArm vacant so the arm never moves at all. The ingest canonicalizer
// resolved this by contention; these cover the same resolver on the runtime lane
// (canonicalNodeMapFromObject), which a third-party GLB loaded straight into the
// viewer goes through without ever being renamed.
describe('canonicalNodeMapFromObject: clavicle vs upper-arm collision', () => {
// Rigify: chest → shoulder.L (clavicle) → upper_arm.L → forearm.L → hand.L.
// Both `shoulder.L` and `upper_arm.L` normalize onto LeftArm.
const rigifyChain = (side) => [
{ name: `shoulder.${side}`, parent: 'chest' },
{ name: `upper_arm.${side}`, parent: `shoulder.${side}` },
{ name: `forearm.${side}`, parent: `upper_arm.${side}` },
{ name: `hand.${side}`, parent: `forearm.${side}` },
];
function makeRigifyRig() {
return makeHierarchicalRig([
{ name: 'hips', parent: null },
{ name: 'spine', parent: 'hips' },
{ name: 'chest', parent: 'spine' },
...rigifyChain('L'),
...rigifyChain('R'),
]);
}
it('binds LeftArm/RightArm to the upper arm and the clavicle to the Shoulder bone', () => {
const map = canonicalNodeMapFromObject(makeRigifyRig());
expect(map.get('LeftArm')).toBe('upper_arm.L');
expect(map.get('RightArm')).toBe('upper_arm.R');
expect(map.get('LeftShoulder')).toBe('shoulder.L');
expect(map.get('RightShoulder')).toBe('shoulder.R');
expect(map.get('LeftForeArm')).toBe('forearm.L');
});
it('keeps the rest maps on the same nodes the node map chose', () => {
const root = makeRigifyRig();
const nodes = canonicalNodeMapFromObject(root);
const rest = canonicalRestMapFromObject(root);
// The rest quaternion for a canonical bone must belong to the very node the
// track gets renamed onto, or the bind correction is computed against a
// different bone than the one it is applied to.
for (const key of ['LeftArm', 'LeftShoulder', 'RightArm', 'RightShoulder']) {
const node = root.getObjectByName(nodes.get(key));
expect(rest.get(key).equals(node.quaternion)).toBe(true);
}
});
it('leaves a hobby rig whose upper arm IS spelled shoulderL alone', () => {
// No clavicle in this skeleton: chest → shoulderL → elbowL. Demoting the
// only contender would vacate LeftArm and freeze the arm.
const map = canonicalNodeMapFromObject(
makeHierarchicalRig([
{ name: 'hips', parent: null },
{ name: 'chest', parent: 'hips' },
{ name: 'shoulderL', parent: 'chest' },
{ name: 'elbowL', parent: 'shoulderL' },
{ name: 'wristL', parent: 'elbowL' },
]),
);
expect(map.get('LeftArm')).toBe('shoulderL');
expect(map.has('LeftShoulder')).toBe(false);
});
it('promotes the upper arm on the mirror-image (SMPL) collision', () => {
// SMPL names the clavicle `left_collar` and the upper arm `left_shoulder`;
// both normalize onto LeftShoulder, so without resolution LeftArm is vacant
// and the arm track binds to nothing.
const map = canonicalNodeMapFromObject(
makeHierarchicalRig([
{ name: 'pelvis', parent: null },
{ name: 'spine3', parent: 'pelvis' },
{ name: 'left_collar', parent: 'spine3' },
{ name: 'left_shoulder', parent: 'left_collar' },
{ name: 'left_elbow', parent: 'left_shoulder' },
{ name: 'left_wrist', parent: 'left_elbow' },
]),
);
expect(map.get('LeftShoulder')).toBe('left_collar');
expect(map.get('LeftArm')).toBe('left_shoulder');
expect(map.get('LeftForeArm')).toBe('left_elbow');
});
it('actually drives the upper arm: the retargeted LeftArm track lands on it', () => {
const root = makeRigifyRig();
const clip = makeCanonicalClip();
const r = retargetClipToObject(clip, root, { minCoverage: 0 });
const names = r.clip.tracks.map((t) => t.name);
expect(names).toContain('upper_arm.L.quaternion');
expect(names).not.toContain('shoulder.L.quaternion');
});
});
describe('retargetClip', () => {
it('rewrites track bone names onto an identically-named rig (100% coverage)', () => {
const clip = makeCanonicalClip();
const map = canonicalNodeMapFromObject(makeRig(CANONICAL_RIG));
const r = retargetClip(clip, map, { hipScale: 1 });
expect(r.coverage).toBe(1);
expect(r.matched).toBe(4);
expect(r.clip.tracks.map((t) => t.name).sort()).toEqual(
['Hips.position', 'Hips.quaternion', 'LeftArm.quaternion', 'Spine.quaternion'].sort(),
);
});
it('rewrites onto a differently-named (Mixamo) rig', () => {
const clip = makeCanonicalClip();
const map = canonicalNodeMapFromObject(
makeRig([
'mixamorig:Hips',
'mixamorig:Spine',
'mixamorig:LeftArm',
'mixamorig:RightArm',
]),
);
const r = retargetClip(clip, map, { hipScale: 1 });
const names = r.clip.tracks.map((t) => t.name);
expect(names).toContain('mixamorig:Hips.quaternion');
expect(names).toContain('mixamorig:LeftArm.quaternion');
expect(names).toContain('mixamorig:Hips.position');
});
it('drops tracks for bones the rig lacks and reports them', () => {
const clip = makeCanonicalClip(); // addresses Hips, Spine, LeftArm
const map = canonicalNodeMapFromObject(makeRig(['Hips', 'Spine'])); // no LeftArm
const r = retargetClip(clip, map, { hipScale: 1, minCoverage: 0.1 });
expect(r.dropped).toContain('LeftArm');
expect(r.clip.tracks.find((t) => t.name.includes('LeftArm'))).toBeUndefined();
});
it('returns a null clip when coverage is below the threshold', () => {
const clip = makeCanonicalClip(); // 4 tracks (Hips ×2, Spine, LeftArm)
const map = canonicalNodeMapFromObject(makeRig(['Spine'])); // only 1 of 4 maps
const r = retargetClip(clip, map);
expect(r.coverage).toBeLessThan(MIN_COVERAGE);
expect(r.clip).toBeNull();
});
it('scales the hip position track by hipScale', () => {
const clip = makeCanonicalClip();
const map = canonicalNodeMapFromObject(makeRig(CANONICAL_RIG));
const r = retargetClip(clip, map, { hipScale: 2 });
const pos = r.clip.tracks.find((t) => t.name === 'Hips.position');
// Original Y values were 1 and 1.1 → doubled.
expect(pos.values[1]).toBeCloseTo(2, 5);
expect(pos.values[4]).toBeCloseTo(2.2, 5);
});
it('does not mutate the source clip', () => {
const clip = makeCanonicalClip();
const before = clip.tracks.map((t) => t.name);
const map = canonicalNodeMapFromObject(
makeRig(['mixamorig:Hips', 'mixamorig:Spine', 'mixamorig:LeftArm']),
);
retargetClip(clip, map, { hipScale: 3 });
expect(clip.tracks.map((t) => t.name)).toEqual(before);
expect(clip.tracks.find((t) => t.name === 'Hips.position').values[1]).toBe(1);
});
// The baked library carries a position + quaternion + scale channel per bone.
// A limb bone's local position (its offset from its parent) and its scale are
// the *authoring* rig's structure, not motion — replaying them verbatim on a
// differently-proportioned avatar overwrites its bone lengths and collapses it
// into a heap while every bone still "matches" (coverage lies at 100%). The
// retargeter must drop those structural channels and keep only rotations + the
// root (Hips) translation, and coverage must be computed over just those.
it('drops non-Hips position and all scale channels (keeps rotations + root)', () => {
const q = new QuaternionKeyframeTrack('LeftArm.quaternion', [0], [0, 0, 0, 1]);
const hipsQ = new QuaternionKeyframeTrack('Hips.quaternion', [0], [0, 0, 0, 1]);
const hipsPos = new VectorKeyframeTrack('Hips.position', [0], [0, 1, 0]);
// Structural channels that must NOT survive: a limb bone offset + scales.
const armPos = new VectorKeyframeTrack('LeftArm.position', [0], [0.09, -0.015, 0]);
const armScale = new VectorKeyframeTrack('LeftArm.scale', [0], [1, 1, 1]);
const hipsScale = new VectorKeyframeTrack('Hips.scale', [0], [1, 1, 1]);
const clip = new AnimationClip('struct', 1, [
hipsQ,
hipsPos,
q,
armPos,
armScale,
hipsScale,
]);
const map = canonicalNodeMapFromObject(makeRig(CANONICAL_RIG));
const r = retargetClip(clip, map, { hipScale: 1 });
const names = r.clip.tracks.map((t) => t.name).sort();
expect(names).toEqual(['Hips.position', 'Hips.quaternion', 'LeftArm.quaternion'].sort());
expect(r.clip.tracks.some((t) => t.name === 'LeftArm.position')).toBe(false);
expect(r.clip.tracks.some((t) => t.name.endsWith('.scale'))).toBe(false);
// Coverage is over the 3 retargetable channels, not all 6 → honest 100%.
expect(r.total).toBe(3);
expect(r.matched).toBe(3);
expect(r.coverage).toBe(1);
});
});
describe('bind-rotation correction', () => {
// A −90°X rest, the up-axis convention Mixamo/FBX bakes onto Hips.
const MINUS_90X = new Quaternion().setFromAxisAngle({ x: 1, y: 0, z: 0 }, -Math.PI / 2);
// Pose a synthetic rig in the canonical authoring rest (cz's rest pose), so it
// matches the convention the clip library was baked against.
function applyAuthoringRest(rig, names) {
for (const n of names) {
const b = rig.getObjectByName(n);
if (b && CANONICAL_REST[n]) b.quaternion.fromArray(CANONICAL_REST[n]);
}
}
it('round-trips byte-for-byte when the rig matches the canonical authoring rest', () => {
const clip = makeCanonicalClip();
const rig = makeRig(CANONICAL_RIG);
applyAuthoringRest(rig, CANONICAL_RIG);
const map = canonicalNodeMapFromObject(rig);
const targetRest = canonicalRestMapFromObject(rig);
const corrected = retargetClip(clip, map, { hipScale: 1, targetRest }).clip;
const verbatim = retargetClip(clip, map, { hipScale: 1 }).clip; // no targetRest → no correction
// Every correction is identity (target rest == authoring rest) → skipped.
corrected.tracks.forEach((t, i) => {
expect(Array.from(t.values)).toEqual(Array.from(verbatim.tracks[i].values));
});
});
it('re-applies a Hips up-axis rest the clip would otherwise overwrite (stays upright)', () => {
const clip = makeCanonicalClip(); // Hips.quaternion identity at every key
const rig = makeRig(CANONICAL_RIG);
applyAuthoringRest(rig, CANONICAL_RIG);
// Bake a Mixamo-style −90°X onto Hips: Tr = (−90X)·Sr ⇒ C = Tr·Sr⁻¹ = −90X.
const sr = new Quaternion().fromArray(CANONICAL_REST.Hips);
rig.getObjectByName('Hips').quaternion.copy(MINUS_90X.clone().multiply(sr));
const map = canonicalNodeMapFromObject(rig);
const targetRest = canonicalRestMapFromObject(rig);
const r = retargetClip(clip, map, { hipScale: 1, targetRest }).clip;
// C · identity = C = −90X exactly, restoring the rig's upright convention.
const hipsQ = r.tracks.find((t) => t.name === 'Hips.quaternion');
expect(hipsQ.values[0]).toBeCloseTo(MINUS_90X.x, 5);
expect(hipsQ.values[3]).toBeCloseTo(MINUS_90X.w, 5);
// Root-motion keyframes rotate by the same correction: (0,1,0) → (0,0,−1).
const hipsP = r.tracks.find((t) => t.name === 'Hips.position');
expect(hipsP.values[2]).toBeCloseTo(-1, 5);
});
it('corrects limb bones too — a T-pose (identity) arm rest is not copied verbatim', () => {
const clip = makeCanonicalClip();
const rig = makeRig(CANONICAL_RIG); // identity rests ≠ cz's A-pose authoring rest
const map = canonicalNodeMapFromObject(rig);
const targetRest = canonicalRestMapFromObject(rig);
const corrected = retargetClip(clip, map, { hipScale: 1, targetRest }).clip;
const verbatim = retargetClip(clip, map, { hipScale: 1 }).clip;
const armC = corrected.tracks.find((t) => t.name === 'LeftArm.quaternion');
const armV = verbatim.tracks.find((t) => t.name === 'LeftArm.quaternion');
// cz rests its arms in an A-pose, so an identity-rest arm gets a real correction.
expect(Array.from(armC.values)).not.toEqual(Array.from(armV.values));
});
it('hip scaling and rotation compose on the position track', () => {
const clip = makeCanonicalClip();
const rig = makeRig(CANONICAL_RIG);
applyAuthoringRest(rig, CANONICAL_RIG);
const sr = new Quaternion().fromArray(CANONICAL_REST.Hips);
rig.getObjectByName('Hips').quaternion.copy(MINUS_90X.clone().multiply(sr));
const map = canonicalNodeMapFromObject(rig);
const targetRest = canonicalRestMapFromObject(rig);
const r = retargetClip(clip, map, { hipScale: 2, targetRest }).clip;
const hipsP = r.tracks.find((t) => t.name === 'Hips.position');
// (0,1,0) rotated → (0,0,−1), then ×2 → (0,0,−2).
expect(hipsP.values[2]).toBeCloseTo(-2, 5);
});
});
describe('root-motion correction', () => {
// A rig whose Hips sit under a tilted armature (the Mixamo +90°X pattern, or
// any non-standard up-axis). Root motion authored in world-Y-up must be
// re-expressed in this frame so the body still travels the right way.
function makeRigWithTiltedArmature(tilt) {
const root = new Object3D();
const armature = new Object3D();
armature.name = 'Armature';
armature.quaternion.copy(tilt);
root.add(armature);
const bones = ['Hips', 'Spine', 'LeftArm', 'RightArm', 'Head'].map((n) => {
const b = new Bone();
b.name = n;
return b;
});
armature.add(bones[0]);
for (let i = 1; i < bones.length; i++) bones[0].add(bones[i]);
const mesh = new SkinnedMesh(new BufferGeometry());
mesh.bind(new Skeleton(bones));
root.add(mesh);
return root;
}
it('rotates the hip-position track by the inverse of the hips-parent world frame', () => {
const clip = makeCanonicalClip(); // Hips.position keyframe (0,1,0)
const tilt = new Quaternion().setFromAxisAngle({ x: 1, y: 0, z: 0 }, Math.PI / 2); // +90°X
const rig = makeRigWithTiltedArmature(tilt);
const map = canonicalNodeMapFromObject(rig);
const targetRest = canonicalRestMapFromObject(rig);
const hpq = hipsParentWorldQuat(rig);
expect(hpq).not.toBeNull();
const r = retargetClip(clip, map, { hipScale: 1, targetRest, hipsParentWorldQuat: hpq }).clip;
const pos = r.tracks.find((t) => t.name.endsWith('.position'));
// Parent is +90°X → position rotated by −90°X: (0,1,0) → (0,0,−1).
expect(pos.values[0]).toBeCloseTo(0, 5);
expect(pos.values[1]).toBeCloseTo(0, 5);
expect(pos.values[2]).toBeCloseTo(-1, 5);
});
it('leaves the hip-position track untouched when the hips-parent frame is identity', () => {
const clip = makeCanonicalClip();
const rig = makeRigWithTiltedArmature(new Quaternion()); // identity armature
const map = canonicalNodeMapFromObject(rig);
const targetRest = canonicalRestMapFromObject(rig);
const hpq = hipsParentWorldQuat(rig);
const r = retargetClip(clip, map, { hipScale: 1, targetRest, hipsParentWorldQuat: hpq }).clip;
const verbatim = retargetClip(clip, map, { hipScale: 1 }).clip; // no correction baseline
const pos = r.tracks.find((t) => t.name.endsWith('.position'));
const posV = verbatim.tracks.find((t) => t.name.endsWith('.position'));
expect(Array.from(pos.values)).toEqual(Array.from(posV.values));
});
});
describe('retargetClipToObject', () => {
it('retargets straight onto an Object3D graph', () => {
const clip = makeCanonicalClip();
const rig = makeRig([
'mixamorig:Hips',
'mixamorig:Spine',
'mixamorig:LeftArm',
'mixamorig:RightArm',
]);
const r = retargetClipToObject(clip, rig, { minCoverage: 0.5 });
expect(r.clip).not.toBeNull();
expect(r.clip.tracks.some((t) => t.name === 'mixamorig:LeftArm.quaternion')).toBe(true);
});
});
describe('scaleClipSpeed', () => {
it('1.8× shortens duration and times proportionally', () => {
const clip = makeCanonicalClip(); // duration 1
const fast = scaleClipSpeed(clip, 1.8);
expect(fast.duration).toBeCloseTo(1 / 1.8, 5);
const t = fast.tracks[0].times;
expect(t[t.length - 1]).toBeCloseTo(1 / 1.8, 5);
});
it('factor of 1 returns the clip unchanged', () => {
const clip = makeCanonicalClip();
expect(scaleClipSpeed(clip, 1)).toBe(clip);
});
it('does not mutate the source clip', () => {
const clip = makeCanonicalClip();
const origDur = clip.duration;
scaleClipSpeed(clip, 2);
expect(clip.duration).toBe(origDur);
});
});
describe('trimClip', () => {
it('returns a clone, unchanged, when the range covers the whole clip', () => {
const clip = makeMovingClip();
const out = trimClip(clip, 0, clip.duration);
expect(out).not.toBe(clip);
expect(out.duration).toBeCloseTo(clip.duration, 5);
expect(Array.from(out.tracks[0].values)).toEqual(Array.from(clip.tracks[0].values));
});
it('shortens duration and shifts kept keyframes to start at 0', () => {
const clip = makeMovingClip(); // duration 2, keyframes at 0/1/2
const out = trimClip(clip, 1, 2);
expect(out.duration).toBeCloseTo(1, 5);
const posTrack = out.tracks.find((t) => t.name === 'Hips.position');
expect(Array.from(posTrack.times)).toEqual([0, 1]);
// Original values at t=1 and t=2 were [0,1,1] and [0,1,2].
expect(Array.from(posTrack.values)).toEqual([0, 1, 1, 0, 1, 2]);
});
it('interpolates a boundary that falls between keyframes', () => {
const clip = makeMovingClip();
const out = trimClip(clip, 0.5, 1.5);
const posTrack = out.tracks.find((t) => t.name === 'Hips.position');
// Lerp of [0,1,0]→[0,1,1] at 0.5 is [0,1,0.5]; the start boundary sample.
expect(posTrack.values[0]).toBeCloseTo(0, 5);
expect(posTrack.values[1]).toBeCloseTo(1, 5);
expect(posTrack.values[2]).toBeCloseTo(0.5, 5);
});
it('does not mutate the source clip', () => {
const clip = makeMovingClip();
const beforeDur = clip.duration;
const beforeValues = Array.from(clip.tracks[0].values);
trimClip(clip, 1, 2);
expect(clip.duration).toBe(beforeDur);
expect(Array.from(clip.tracks[0].values)).toEqual(beforeValues);
});
});
describe('blendClipLoop', () => {
it('returns a clone, unchanged, when blendSeconds is 0', () => {
const clip = makeMovingClip();
const out = blendClipLoop(clip, 0);
expect(out).not.toBe(clip);
expect(Array.from(out.tracks[0].values)).toEqual(Array.from(clip.tracks[0].values));
});
it('slerps the quaternion tail toward the clip start as the seam approaches', () => {
const clip = makeMovingClip(); // duration 2, blend of 1s starts at t=1
const out = blendClipLoop(clip, 1);
const quatTrack = out.tracks.find((t) => t.name === 'Hips.quaternion');
// At the blend start (t=1, weight 0) the value is untouched.
expect(quatTrack.values[4]).toBeCloseTo(0, 5);
expect(quatTrack.values[5]).toBeCloseTo(0.7071067811865476, 5);
// At the seam (t=2, weight 1) it fully matches the clip's own start pose.
expect(quatTrack.values[8]).toBeCloseTo(0, 5);
expect(quatTrack.values[9]).toBeCloseTo(0, 5);
expect(quatTrack.values[10]).toBeCloseTo(0, 5);
expect(quatTrack.values[11]).toBeCloseTo(1, 5);
});
it('lerps a vector track toward its start value at the seam', () => {
const clip = makeMovingClip();
const out = blendClipLoop(clip, 1);
const posTrack = out.tracks.find((t) => t.name === 'Hips.position');
expect(Array.from(posTrack.values.slice(6, 9))).toEqual([0, 1, 0]); // t=2 → start value
});
it('clamps the blend window to half the clip length', () => {
const clip = makeMovingClip(); // duration 2 → max blend 1s
const out = blendClipLoop(clip, 10);
const posTrack = out.tracks.find((t) => t.name === 'Hips.position');
expect(Array.from(posTrack.values.slice(6, 9))).toEqual([0, 1, 0]);
});
it('does not mutate the source clip', () => {
const clip = makeMovingClip();
const beforeValues = Array.from(clip.tracks[0].values);
blendClipLoop(clip, 1);
expect(Array.from(clip.tracks[0].values)).toEqual(beforeValues);
});
});
// ---------------------------------------------------------------------------
// Cross-rig locomotion invariants, validated against the real shipped GLB rigs
// (cz.glb, michelle.glb) plus two synthetic conventions, using a raw GLB parse
// and world-matrix composition — no GLTFLoader, no browser, fully deterministic.
//
// What this guards: root motion lives in the Hips' *parent* local frame, so to
// preserve world-space travel the retargeter rotates the hip-position track by
// the inverse of the target Hips-parent rest rotation (animation-retarget.js →
// hipPositionCorrection). The earlier, narrower fix rotated by the Hips *bone*
// correction, which is exact only on the standard Mixamo +90°X/−90°X split. The
// `tilted` rig below carries a compound, non-±90° armature rotation while its
// Hips sit at the authoring rest (so the Hips bone correction is identity): only
// the parent-frame correction can recover the right world direction, so a
// regression to the bone-correction approach makes the direction/verticality
// assertions fail there.
// ---------------------------------------------------------------------------
describe('cross-rig locomotion invariants (real GLB)', () => {
const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const clipPath = (n) => path.join(REPO, 'public/animations/clips', `${n}.json`);
const glbPath = (n) => path.join(REPO, 'public/avatars', `${n}.glb`);
// Real GLB rigs are reconstructed with the shared bone-graph helper
// (tests/_helpers/glb-bone-graph.js) — the same raw-JSON-chunk parse +
// SkinnedMesh/Skeleton reconstruction the upright-invariant corpus uses, so
// production's canonical readers see these rigs exactly as a GLTFLoader scene.
const realRig = (name) => loadBoneGraph(glbPath(name)).root;
// A synthetic rig: every canonical bone at the authoring rest (so per-bone
// limb corrections are identity), parented under an armature carrying an
// arbitrary rest rotation. This isolates the hip-position correction — the
// armature rotation is the *only* thing the root motion must compensate for.
function buildSyntheticRig(armatureQuat) {
const root = new Object3D();
const armature = new Object3D();
armature.name = 'Armature';
armature.quaternion.copy(armatureQuat);
root.add(armature);
const names = Object.keys(CANONICAL_REST);
const byName = {};
for (const nm of names) {
const b = new Bone();
b.name = nm;
b.quaternion.fromArray(CANONICAL_REST[nm]);
byName[nm] = b;
}
byName.Hips.position.set(0, 1, 0); // a plausible rest hip height
armature.add(byName.Hips);
for (const nm of names) if (nm !== 'Hips') byName.Hips.add(byName[nm]);
const mesh = new SkinnedMesh(new BufferGeometry());
mesh.bind(new Skeleton(names.map((n) => byName[n])));
root.add(mesh);
root.updateMatrixWorld(true);
return root;
}
function loadClip(name) {
const clip = AnimationClip.parse(JSON.parse(fs.readFileSync(clipPath(name), 'utf8')));
clip.name = name;
return clip;
}
function findHips(root) {
let hips = null;
root.traverse((n) => {
if (!hips && n.isBone && canonicalizeBoneName(n.name || '') === 'Hips') hips = n;
});
return hips;
}
// Net world-space hip displacement over a retargeted clip, expressed in
// hip-heights (dividing out the rig's overall scale so rigs authored in metres
// and in centimetres are directly comparable). Composes the real world matrix
// of the Hips' parent — the frame the position track binds into — so this is
// what the avatar actually does on screen, not a re-derivation of the maths.
function worldHipNet(root, clip) {
const hips = findHips(root);
root.updateMatrixWorld(true);
const restHeight = Math.abs(new Vector3().setFromMatrixPosition(hips.matrixWorld).y) || 1;
const parentWorld = hips.parent.matrixWorld.clone();
const { clip: out, coverage } = retargetClipToObject(clip, root, { minCoverage: 0 });
expect(coverage).toBeGreaterThan(MIN_COVERAGE); // the rig really animates
const track = out.tracks.find((t) => t.name === `${hips.name}.position`);
const v = track.values;
const last = v.length - 3;
const p0 = new Vector3(v[0], v[1], v[2]).applyMatrix4(parentWorld);
const pN = new Vector3(v[last], v[last + 1], v[last + 2]).applyMatrix4(parentWorld);
return pN.sub(p0).divideScalar(restHeight);
}
// Authored net displacement straight from the clip (the authoring rig is
// world-Y-up, so this *is* the intended world direction every rig must match).
function authoredNet(clip) {
const t = clip.tracks.find(
(tr) => tr.name.endsWith('.position') && canonicalizeBoneName(tr.name.split('.')[0]) === 'Hips',
);
const v = t.values;
const last = v.length - 3;
return new Vector3(v[last] - v[0], v[last + 1] - v[1], v[last + 2] - v[2]);
}
// Four conventions: cz (authoring rig, identity armature), michelle (Mixamo
// +90°X armature / −90°X Hips), and two synthetics — a compound non-±90°
// armature and a pure 30° yaw (an upright RPM-style placement rotation).
const rigs = {
cz: realRig('cz'),
michelle: realRig('michelle'),
tilted: buildSyntheticRig(
new Quaternion().setFromEuler(
new Euler((25 * Math.PI) / 180, (40 * Math.PI) / 180, (15 * Math.PI) / 180, 'XYZ'),
),
),
yawed: buildSyntheticRig(new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), Math.PI / 6)),
};
const rigNames = Object.keys(rigs);
// Clips that actually travel (the in-place featured walk/jump have ~zero net
// translation, so a non-trivial library clip is used to test direction).
const WALK = 'av-walk-crouching'; // pure forward (+Z), flat ground
const JUMP = 'jumpdown2'; // forward + downward arc
describe.each([WALK, JUMP])('%s travels the authored world direction on every rig', (name) => {
const clip = loadClip(name);
const authored = authoredNet(clip);
const authoredDir = authored.clone().normalize();
it.each(rigNames)('direction matches on %s (no sideways drift)', (rigName) => {
const world = worldHipNet(rigs[rigName], clip);
// World travel must point the same way as the authored travel: a unit-dot
// near 1 means the heading is preserved and nothing leaked sideways.
expect(world.clone().normalize().dot(authoredDir)).toBeGreaterThan(0.999);
});
it.each(rigNames)('verticality matches on %s (no sinking / floating)', (rigName) => {
const world = worldHipNet(rigs[rigName], clip);
const worldVertFrac = world.y / world.length();
const authoredVertFrac = authored.y / authored.length();
// The share of travel that is vertical is preserved, so a forward walk
// stays on the ground and a jump arcs by exactly its authored amount —
// horizontal motion never bleeds into the up axis (or vice-versa).
expect(Math.abs(worldVertFrac - authoredVertFrac)).toBeLessThan(0.02);
});
});
// In-place performances must not acquire net horizontal travel on any rig.
describe.each(['idle', 'celebrate', 'walk', 'jump'])('%s stays in place on every rig', (name) => {
const clip = loadClip(name);
it.each(rigNames)('net XZ travel is ~zero on %s', (rigName) => {
const world = worldHipNet(rigs[rigName], clip);
expect(Math.hypot(world.x, world.z)).toBeLessThan(0.01);
});
});
it('cz.glb output is byte-for-byte identical to the verbatim (uncorrected) clip', () => {
// cz is the authoring rig: identity armature, identity Hips rest. Every
// correction collapses to identity, so the retarget must be a no-op — the
// absolute no-regression bar for the whole initiative.
const clip = loadClip(WALK);
const corrected = retargetClipToObject(clip, rigs.cz, { minCoverage: 0 }).clip;
const map = canonicalNodeMapFromObject(rigs.cz);
const verbatim = retargetClip(clip, map, { hipScale: 1, minCoverage: 0 }).clip;
const byName = new Map(verbatim.tracks.map((t) => [t.name, t]));
for (const t of corrected.tracks) {
expect(Array.from(t.values)).toEqual(Array.from(byName.get(t.name).values));
}
});
});
describe('world-delta correctness — limb retarget preserves world motion', () => {
// The bug this guards: a local-only premultiply correction (Rt·Rs⁻¹·q) replays a
// clip bone's deviation in the wrong frame, skewing limbs by ~30° on a rig whose
// rest pose differs from the cz authoring rig. The world-aware correction
// (q ← L·q·R) must instead reproduce the SAME world-space rotation delta on any
// rest pose. Oracle is three's getWorldQuaternion — independent of the module's
// own world-rest math, so the test can't pass by sharing the bug.
const Rs = new Quaternion().fromArray(CANONICAL_REST.LeftArm); // cz LeftArm local rest
const WS = new Quaternion().fromArray(CANONICAL_REST_WORLD.LeftArm); // …world rest
// A target rig whose LeftArm rests deep down-and-in, under rotated Hips/Spine —
// a rest pose far from cz, so a local-only correction would visibly skew it.
function buildTarget() {
const root = new Object3D();
const hips = Object.assign(new Bone(), { name: 'Hips' });
hips.quaternion.setFromEuler(new Euler(0.12, 0.25, -0.08));
const spine = Object.assign(new Bone(), { name: 'Spine' });
spine.quaternion.setFromEuler(new Euler(0.05, 0, 0.18));
const arm = Object.assign(new Bone(), { name: 'LeftArm' });
arm.quaternion.setFromEuler(new Euler(0.2, -0.3, -1.1));
spine.add(arm);
hips.add(spine);
root.add(hips);
root.updateMatrixWorld(true);
return { root, arm, restLocal: arm.quaternion.clone() };
}
// A clip keyframe: cz's LeftArm rotated by world delta D, as its absolute local
// rotation (sourceParentWorld = WS·Rs⁻¹ ⇒ local = parent⁻¹·D·WS).
function clipForWorldDelta(D) {
const parentWorld = WS.clone().multiply(Rs.clone().invert());
const S = parentWorld.clone().invert().multiply(D).multiply(WS);
return new AnimationClip('m', 1, [
new QuaternionKeyframeTrack(
'LeftArm.quaternion',
[0, 1],
[S.x, S.y, S.z, S.w, S.x, S.y, S.z, S.w],
),
]);
}
const worldDirErr = (a, b) => {
const probe = new Vector3(0, 1, 0);
return (
(probe.clone().applyQuaternion(a).angleTo(probe.clone().applyQuaternion(b)) * 180) / Math.PI
);
};
it('reproduces a known world-space arm motion on a foreign rest pose (≈0° error)', () => {
const D = new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), (40 * Math.PI) / 180);
const clip = clipForWorldDelta(D);
const { root, arm } = buildTarget();
const restWorld = arm.getWorldQuaternion(new Quaternion()); // bind world (oracle)
const expected = D.clone().multiply(restWorld); // same world delta on target rest
const out = retargetClipToObject(clip, root, { minCoverage: 0 }).clip;
const t = out.tracks.find((x) => x.name === 'LeftArm.quaternion');
arm.quaternion.set(t.values[0], t.values[1], t.values[2], t.values[3]);
root.updateMatrixWorld(true);
const actual = arm.getWorldQuaternion(new Quaternion());
expect(worldDirErr(actual, expected)).toBeLessThan(0.5);
});
it('the old local-only premultiply (Rt·Rs⁻¹·q) would skew this badly (>5°) — test is discriminating', () => {
const D = new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), (40 * Math.PI) / 180);
const clip = clipForWorldDelta(D);
const { root, arm, restLocal } = buildTarget();
const restWorld = arm.getWorldQuaternion(new Quaternion());
const expected = D.clone().multiply(restWorld);
// Reconstruct the prior behaviour: C·q with C = Rt·Rs⁻¹ (no world term).
const S = new Quaternion(clip.tracks[0].values[0], clip.tracks[0].values[1], clip.tracks[0].values[2], clip.tracks[0].values[3]);
const buggy = restLocal.clone().multiply(Rs.clone().invert()).multiply(S);
arm.quaternion.copy(buggy);
root.updateMatrixWorld(true);
const actual = arm.getWorldQuaternion(new Quaternion());
expect(worldDirErr(actual, expected)).toBeGreaterThan(5);
});
});
// ---------------------------------------------------------------------------
// The dignity floor: a rig from any supported naming convention must clear
// MIN_COVERAGE against the REAL shipped clips, with both arms and both legs
// bound. This is the invariant scripts/animation-dignity-sweep.mjs measures in
// full (it also checks that the bones actually rotate and that the hands and
// feet travel through world space); the case below is the cheap CI half of it.
//
// Why coverage is the sharp edge: 30 of a clip's 53 tracks address finger bones.
// A convention whose hands don't name-map scores about 40%, falls under the gate,
// and `retargetClip` returns a NULL clip: production then builds no action at
// all and the avatar stands frozen in its bind pose. Every convention here was
// measured doing exactly that before the finger aliases landed in
// src/glb-canonicalize.js, and nothing in the suite noticed, because every other
// test either passes `minCoverage: 0` or uses a synthetic 5-bone rig.
// ---------------------------------------------------------------------------
describe('rig-convention coverage floor (real clips)', () => {
const REPO2 = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const realClip = (name) => {
const clip = AnimationClip.parse(
JSON.parse(fs.readFileSync(path.join(REPO2, 'public/animations/clips', `${name}.json`), 'utf8')),
);
clip.name = name;
return clip;
};
const FINGER_STEMS = ['Thumb', 'Index', 'Middle', 'Ring', 'Pinky'];
// Each entry spells the same humanoid skeleton the way that tool exports it.
// `body` is given left-side-first; right twins are derived by the swap fn.
const CONVENTIONS = {
'Unreal mannequin': {
centre: ['pelvis', 'spine_01', 'spine_02', 'spine_03', 'neck_01', 'head'],
limb: (s) => [
`clavicle_${s}`, `upperarm_${s}`, `lowerarm_${s}`, `hand_${s}`,
`thigh_${s}`, `calf_${s}`, `foot_${s}`, `ball_${s}`,
],
finger: (s, f, n) => `${f.toLowerCase()}_0${n}_${s}`,
sides: ['l', 'r'],
},
'VRM 1.0': {
centre: ['hips', 'spine', 'chest', 'upperChest', 'neck', 'head'],
limb: (s) => [
`${s}Shoulder`, `${s}UpperArm`, `${s}LowerArm`, `${s}Hand`,
`${s}UpperLeg`, `${s}LowerLeg`, `${s}Foot`, `${s}Toes`,
],
finger: (s, f, n) => {
const vf = f === 'Pinky' ? 'Little' : f;
const phalanx =
f === 'Thumb'
? ['Metacarpal', 'Proximal', 'Distal'][n - 1]
: ['Proximal', 'Intermediate', 'Distal'][n - 1];
return `${s}${vf}${phalanx}`;
},
sides: ['left', 'right'],
},
'Daz / Genesis 8': {
centre: ['hip', 'abdomenLower', 'abdomenUpper', 'chestUpper', 'neckLower', 'head'],
limb: (s) => [
`${s}Collar`, `${s}ShldrBend`, `${s}ForearmBend`, `${s}Hand`,
`${s}ThighBend`, `${s}Shin`, `${s}Foot`, `${s}Toe`,
],
finger: (s, f, n) => `${s}${f === 'Middle' ? 'Mid' : f}${n}`,
sides: ['l', 'r'],
},
MakeHuman: {
centre: ['pelvis', 'spine', 'chest', 'neck', 'head'],
limb: (s) => [
`clavicle.${s}`, `upperarm.${s}`, `forearm.${s}`, `hand.${s}`,
`thigh.${s}`, `shin.${s}`, `foot.${s}`, `toe.${s}`,
],
finger: (s, f, n) => `finger${FINGER_STEMS.indexOf(f) + 1}-${n}.${s}`,
sides: ['L', 'R'],
},
'Blender Rigify': {
centre: ['hips', 'spine', 'chest', 'neck', 'head'],
limb: (s) => [
`shoulder.${s}`, `upper_arm.${s}`, `forearm.${s}`, `hand.${s}`,
`thigh.${s}`, `shin.${s}`, `foot.${s}`, `toe.${s}`,
],
finger: (s, f, n) =>
f === 'Thumb' ? `thumb.0${n}.${s}` : `f_${f.toLowerCase()}.0${n}.${s}`,
sides: ['L', 'R'],
},
'anatomical Latin': {
centre: ['pelvis', 'lumbar', 'thoracic', 'sternum', 'cervical', 'cranium'],
limb: (s) => [
`scapula.${s}`, `humerus.${s}`, `ulna.${s}`, `carpus.${s}`,
`femur.${s}`, `tibia.${s}`, `talus.${s}`, `metatarsus.${s}`,
],
finger: (s, f, n) => {
const af = f === 'Pinky' ? 'little' : f.toLowerCase();
const phalanx =
f === 'Thumb'
? ['metacarpal', 'proximal', 'distal'][n - 1]
: ['proximal', 'intermediate', 'distal'][n - 1];
return `${af}_${phalanx}.${s}`;
},
sides: ['L', 'R'],
},
};
function boneNames(spec) {
const names = [...spec.centre];
for (const side of spec.sides) {
names.push(...spec.limb(side));
for (const f of FINGER_STEMS) {
for (let n = 1; n <= 3; n++) names.push(spec.finger(side, f, n));
}
}
return names;
}
describe.each(Object.entries(CONVENTIONS))('%s', (label, spec) => {
const rig = makeRig(boneNames(spec));
const map = canonicalNodeMapFromObject(rig);
it.each(['idle', 'walk'])('clears the MIN_COVERAGE gate on %s', (clipName) => {
// Default minCoverage on purpose: this asserts what PRODUCTION does, not
// what a permissive test harness would allow.
const r = retargetClipToObject(realClip(clipName), rig);
expect(r.clip, `${label} produced no clip on ${clipName}`).not.toBeNull();
expect(r.coverage).toBeGreaterThanOrEqual(MIN_COVERAGE);
});
it('binds both arms and both legs', () => {
for (const bone of [
'LeftArm', 'LeftForeArm', 'RightArm', 'RightForeArm',
'LeftUpLeg', 'LeftLeg', 'RightUpLeg', 'RightLeg',
]) {
expect(map.get(bone), `${label} lost ${bone}`).toBeTruthy();
}
});
it('maps all 30 finger joints', () => {
const fingers = [...map.keys()].filter((k) => /Hand(Thumb|Index|Middle|Ring|Pinky)[123]$/.test(k));
expect(fingers.length, `${label} mapped only ${fingers.length} finger joints`).toBe(30);
});
});
});
describe('face (morph target) lanes', () => {
/** A rig with two meshes that share some blendshapes and differ on others. */
function faceRig() {
const root = new Object3D();
root.name = 'Armature';
const hips = new Bone();
hips.name = 'Hips';
root.add(hips);
const head = new Object3D();
head.name = 'Wolf3D_Head';
head.morphTargetDictionary = { browInnerUp: 0, mouthSmileLeft: 1 };
head.morphTargetInfluences = [0, 0];
const teeth = new Object3D();
teeth.name = 'Wolf3D_Teeth';
teeth.morphTargetDictionary = { mouthSmileLeft: 0 };
teeth.morphTargetInfluences = [0];
root.add(head, teeth);
return root;
}
const faceClip = () =>
new AnimationClip('sign', 1, [
new QuaternionKeyframeTrack('Hips.quaternion', [0, 1], [0, 0, 0, 1, 0, 0, 0, 1]),
new NumberKeyframeTrack('Face.morphTargetInfluences[browInnerUp]', [0, 1], [0, 0.8]),
new NumberKeyframeTrack('Face.morphTargetInfluences[mouthSmileLeft]', [0, 1], [0, 0.5]),
new NumberKeyframeTrack('Face.morphTargetInfluences[tongueOut]', [0, 1], [0, 1]),
]);
it('re-points each face lane at every mesh that owns the shape', () => {
const root = faceRig();
const { clip, face } = retargetClipToObject(faceClip(), root);
const names = clip.tracks.map((t) => t.name);
// browInnerUp lives on one mesh, mouthSmileLeft on two, tongueOut on none.
expect(names).toContain('Wolf3D_Head.morphTargetInfluences[browInnerUp]');
expect(names).toContain('Wolf3D_Head.morphTargetInfluences[mouthSmileLeft]');
expect(names).toContain('Wolf3D_Teeth.morphTargetInfluences[mouthSmileLeft]');
expect(names.some((n) => n.includes('tongueOut'))).toBe(false);
expect(face).toBe(3);
});
it('drops the whole face lane on a rig with no blendshapes, keeping the motion', () => {
const root = new Object3D();
const hips = new Bone();
hips.name = 'Hips';
root.add(hips);
const { clip, coverage, face } = retargetClipToObject(faceClip(), root);
expect(face).toBe(0);
expect(clip.tracks.map((t) => t.name)).toEqual(['Hips.quaternion']);
// Face lanes must not drag bone coverage down and fail the retarget.
expect(coverage).toBe(1);
});
it('leaves a clip with no face lanes untouched', () => {
const root = faceRig();
const plain = new AnimationClip('walk', 1, [
new QuaternionKeyframeTrack('Hips.quaternion', [0, 1], [0, 0, 0, 1, 0, 0, 0, 1]),
]);
const { clip, face } = retargetClipToObject(plain, root);
expect(face).toBe(0);
expect(clip.tracks).toHaveLength(1);
});
});
describe('hipRestLocalHeight', () => {
// A half-metre chibi rig with real geometry bounds: body spans floor..top,
// hips partway up. Built like a GLB import: bones + a skinned mesh whose
// geometry carries the body's vertical extent.
function makeMeasuredRig({ floorY, topY, hipsY }) {
const root = new Object3D();
const hips = new Bone();
hips.name = 'Hips';
hips.position.y = hipsY;
root.add(hips);
const geo = new BufferGeometry();
geo.setFromPoints([new Vector3(0, floorY, 0), new Vector3(0, topY, 0)]);
// Real skin attributes: SkinnedMesh.computeBoundingBox (used by
// Box3.setFromObject) walks them per vertex.
geo.setAttribute(
'skinIndex',
new Uint16BufferAttribute(new Uint16Array([0, 0, 0, 0, 0, 0, 0, 0]), 4),
);
geo.setAttribute(
'skinWeight',
new Float32BufferAttribute(new Float32Array([1, 0, 0, 0, 1, 0, 0, 0]), 4),
);
const mesh = new SkinnedMesh(geo);
root.add(mesh);
// Update world matrices BEFORE bind so the inverse bind matrices capture
// the true bind pose (as a GLB's authored IBMs would); binding at
// identity would re-shift every vertex by the hips offset.
root.updateMatrixWorld(true);
mesh.bind(new Skeleton([hips]));
return root;
}
it('measures a ground-native rig unchanged (floor at 0)', () => {
const root = makeMeasuredRig({ floorY: 0, topY: 1, hipsY: 0.24 });
expect(hipRestLocalHeight(root)).toBeCloseTo(0.24, 5);
});
it('measures above the model floor for an origin-centered rig', () => {
// Same body exported origin-centered: floor at -0.5, hips world at -0.26.
// Measured from world zero this reads negative and used to skip hip
// scaling entirely, flinging the rig to the clip's metre-scale height.
const root = makeMeasuredRig({ floorY: -0.5, topY: 0.5, hipsY: -0.26 });
expect(hipRestLocalHeight(root)).toBeCloseTo(0.24, 5);
});
it('measures above the floor after a viewer recenters the content', () => {
// Viewer.setContent subtracts the bbox center from the content root; the
// hips height above the feet must survive that shift.
const root = makeMeasuredRig({ floorY: 0, topY: 1, hipsY: 0.24 });
root.position.y -= 0.5;
root.updateMatrixWorld(true);
expect(hipRestLocalHeight(root)).toBeCloseTo(0.24, 5);
});
});
describe('hipGroundLocalY + hip track offset', () => {
function measuredRig({ floorY, topY, hipsY }) {
const root = new Object3D();
const hips = new Bone();
hips.name = 'Hips';
hips.position.y = hipsY;
root.add(hips);
const geo = new BufferGeometry();
geo.setFromPoints([new Vector3(0, floorY, 0), new Vector3(0, topY, 0)]);
geo.setAttribute(
'skinIndex',
new Uint16BufferAttribute(new Uint16Array([0, 0, 0, 0, 0, 0, 0, 0]), 4),
);
geo.setAttribute(
'skinWeight',
new Float32BufferAttribute(new Float32Array([1, 0, 0, 0, 1, 0, 0, 0]), 4),
);
const mesh = new SkinnedMesh(geo);
root.add(mesh);
root.updateMatrixWorld(true);
mesh.bind(new Skeleton([hips]));
return root;
}
it('is 0 for a ground-native rig', () => {
const root = measuredRig({ floorY: 0, topY: 1, hipsY: 0.24 });
expect(hipGroundLocalY(root)).toBeCloseTo(0, 5);
});
it('reports the local floor of an origin-centered rig', () => {
const root = measuredRig({ floorY: -0.5, topY: 0.5, hipsY: -0.26 });
expect(hipGroundLocalY(root)).toBeCloseTo(-0.5, 5);
});
it('offsets the hip position track Y so the clip ground lands on the rig floor', () => {
const clip = makeCanonicalClip(); // Hips.position Y keys: 1.0, 1.1
const map = canonicalNodeMapFromObject(makeRig(CANONICAL_RIG));
const r = retargetClip(clip, map, { hipScale: 0.24, hipOffsetY: -0.5 });
const pos = r.clip.tracks.find((t) => t.name === 'Hips.position');
// scaled then offset: 1.0 * 0.24 - 0.5, 1.1 * 0.24 - 0.5
expect(pos.values[1]).toBeCloseTo(-0.26, 5);
expect(pos.values[4]).toBeCloseTo(-0.236, 5);
// X/Z stay un-offset.
expect(pos.values[0]).toBeCloseTo(0, 5);
expect(pos.values[2]).toBeCloseTo(0, 5);
});
});