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
/**
* GLB bone-name canonicalizer — unit tests.
*
* Covers both the name-mapping helper and the full GLB rewrite. The GLB tests
* build synthetic v2 GLB ArrayBuffers in-memory (no fixtures on disk), which
* keeps the suite fast and lets us assert exact byte-level behaviour: header
* checks, chunk-length update, BIN-chunk preservation, 4-byte padding.
*
* A separate section ("real-fixture tests") loads the actual cz.glb and
* michelle.glb from disk to verify idempotency on a canonical rig and full
* normalization on a Mixamo rig.
*/
import { readFileSync } from 'node:fs';
import { describe, it, expect, beforeAll } from 'vitest';
import { Matrix4, Quaternion, Vector3 } from 'three';
import {
canonicalizeBoneName,
canonicalizeJointNodes,
canonicalizeArmatureOrientation,
canonicalizeGLBBones,
resolveArmShoulderCollisions,
CANONICAL_BONES,
} from '../src/glb-canonicalize.js';
const GLB_MAGIC = 0x46546c67;
const CHUNK_TYPE_JSON = 0x4e4f534a;
const CHUNK_TYPE_BIN = 0x004e4942;
// Build a synthetic GLB v2 from a JS object (JSON chunk) and an optional
// Uint8Array (BIN chunk).
function buildGLB(jsonObj, bin = null) {
let jsonBytes = new TextEncoder().encode(JSON.stringify(jsonObj));
const jPad = (4 - (jsonBytes.length % 4)) % 4;
if (jPad) {
const padded = new Uint8Array(jsonBytes.length + jPad);
padded.set(jsonBytes);
for (let i = 0; i < jPad; i++) padded[jsonBytes.length + i] = 0x20;
jsonBytes = padded;
}
let binBytes = null;
if (bin) {
const bPad = (4 - (bin.length % 4)) % 4;
if (bPad) {
binBytes = new Uint8Array(bin.length + bPad);
binBytes.set(bin);
} else {
binBytes = bin;
}
}
const total = 12 + 8 + jsonBytes.length + (binBytes ? 8 + binBytes.length : 0);
const ab = new ArrayBuffer(total);
const dv = new DataView(ab);
const u8 = new Uint8Array(ab);
dv.setUint32(0, GLB_MAGIC, true);
dv.setUint32(4, 2, true);
dv.setUint32(8, total, true);
dv.setUint32(12, jsonBytes.length, true);
dv.setUint32(16, CHUNK_TYPE_JSON, true);
u8.set(jsonBytes, 20);
if (binBytes) {
const binOff = 20 + jsonBytes.length;
dv.setUint32(binOff, binBytes.length, true);
dv.setUint32(binOff + 4, CHUNK_TYPE_BIN, true);
u8.set(binBytes, binOff + 8);
}
return ab;
}
// Re-parse the JSON chunk out of a GLB ArrayBuffer.
function readGLBJson(ab) {
const dv = new DataView(ab);
const jLen = dv.getUint32(12, true);
const jsonBytes = new Uint8Array(ab, 20, jLen);
return JSON.parse(new TextDecoder().decode(jsonBytes).replace(/\s+$/, ''));
}
// Mixamo-style skinned humanoid skeleton for round-trip tests.
const MIXAMO_NODES = [
{ name: 'mixamorig:Hips', children: [1, 30, 38] },
{ name: 'mixamorig:Spine' },
{ name: 'mixamorig:LeftArm' },
{ name: 'mixamorig:LeftForeArm' },
{ name: 'mixamorig:LeftHand' },
{ name: 'mixamorig:RightArm' },
// A non-joint mesh node intentionally has a bone-shaped name to confirm
// it is NOT renamed (we only touch skins[].joints[]).
{ name: 'mixamorig:LeftLeg_collision_mesh', mesh: 0 },
];
const MIXAMO_SKINS = [{ joints: [0, 1, 2, 3, 4, 5] }];
describe('canonicalizeBoneName', () => {
it('returns null for non-strings, empties, and unknown names', () => {
expect(canonicalizeBoneName(null)).toBeNull();
expect(canonicalizeBoneName(undefined)).toBeNull();
expect(canonicalizeBoneName('')).toBeNull();
expect(canonicalizeBoneName(42)).toBeNull();
expect(canonicalizeBoneName('Tail_01')).toBeNull();
expect(canonicalizeBoneName('J_Sec_Hair1_01')).toBeNull(); // VRM secondary (hair) — not a body bone
expect(canonicalizeBoneName('mannequin-root')).toBeNull(); // armature root, not a bone
});
it('returns canonical exact-match names unchanged', () => {
for (const name of CANONICAL_BONES) {
expect(canonicalizeBoneName(name)).toBe(name);
}
});
it.each([
['mixamorig:LeftArm', 'LeftArm'],
['mixamorig1:LeftForeArm', 'LeftForeArm'],
['mixamorigHead', 'Head'],
['mixamorig_LeftHandThumb3', 'LeftHandThumb3'],
['MIXAMORIG:LeftHand', 'LeftHand'],
])('strips Mixamo prefix: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
['Armature_Hips', 'Hips'],
['Armature/LeftLeg', 'LeftLeg'],
['armature_RightArm', 'RightArm'],
])('strips Armature prefix: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
['DEF-LeftArm', 'LeftArm'],
['ORG-Hips', 'Hips'],
['MCH-RightLeg', 'RightLeg'],
['DEF_Spine1', 'Spine1'],
])('strips Rigify prefix: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
['left_arm', 'LeftArm'],
['Left_Arm', 'LeftArm'],
['left-arm', 'LeftArm'],
['LEFT_ARM', 'LeftArm'],
['right hand', 'RightHand'],
['lefttoebase', 'LeftToeBase'],
['left_hand_index1', 'LeftHandIndex1'],
])('canonicalizes separator / case variants: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it('combines vendor prefix + separator variant: mixamorig:left_arm → LeftArm', () => {
expect(canonicalizeBoneName('mixamorig:left_arm')).toBe('LeftArm');
expect(canonicalizeBoneName('DEF-left_fore_arm')).toBe('LeftForeArm');
});
// CharacterStudio prefixes every joint `CH_`; the stems are otherwise
// canonical, so stripping the prefix makes the whole rig drivable.
it.each([
['CH_Hips', 'Hips'],
['CH_LeftUpLeg', 'LeftUpLeg'],
['CH_RightFoot', 'RightFoot'],
['CH_Hips_01', 'Hips'], // CH_ prefix + glTF de-dup suffix
['CH_LeftLeg_03', 'LeftLeg'],
])('strips the CharacterStudio CH_ prefix: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Unreal Engine mannequin joint names map onto canonical bones via the
// alias table. The `_l`/`_r` side suffix is preserved through the collapse.
it.each([
['pelvis', 'Hips'],
['pelvis_09', 'Hips'], // UE name + de-dup suffix
['clavicle_l', 'LeftShoulder'],
['upperarm_l', 'LeftArm'],
['lowerarm_r', 'RightForeArm'],
['hand_r', 'RightHand'],
['thigh_l', 'LeftUpLeg'],
['calf_l', 'LeftLeg'],
['foot_r', 'RightFoot'],
['ball_l', 'LeftToeBase'],
['thigh_l_010', 'LeftUpLeg'], // UE name + de-dup suffix
])('maps Unreal mannequin bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// The Unreal spine chain is intentionally NOT aliased — `spine_02`'s
// stripped form collides with Mixamo's `Spine` + `_02` de-dup, which must
// keep resolving to `Spine` (asserted in the de-dup suite above). Guard it
// here so a future alias addition can't silently break that.
it('does not alias the Unreal spine chain (avoids Mixamo de-dup collision)', () => {
expect(canonicalizeBoneName('mixamorig:Spine_02')).toBe('Spine');
expect(canonicalizeBoneName('mixamorig:Spine_03')).toBe('Spine');
});
// glTF/FBX exporters (CharacterStudio, Blender, FBX2glTF) append a `_NN`
// node-de-dup index to keep names unique. These are the bone names that ship
// in real uploaded avatars — without stripping the suffix the whole animation
// library silently fails to bind to them.
it.each([
['mixamorig:Hips_01', 'Hips'],
['mixamorig:Spine_02', 'Spine'],
['mixamorig:Spine1_03', 'Spine1'], // base name itself ends in a digit
['mixamorig:Spine2_04', 'Spine2'],
['mixamorig:Neck_05', 'Neck'],
['mixamorig:LeftForeArm_010','LeftForeArm'],
['mixamorig:LeftToeBase_058','LeftToeBase'],
['mixamorig:RightUpLeg_060', 'RightUpLeg'],
['Hips_01', 'Hips'],
['LeftHandIndex1_016', 'LeftHandIndex1'], // digit base + dedup suffix
])('strips the glTF node-de-dup suffix: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// VRM 0.x / VRoid skeletons (`J_Bip_<C|L|R>_<bone>`). The side is in the
// prefix; the alias table maps each explicitly, including the "Little" → pinky
// finger rename, so a VRoid avatar drives the canonical clip library.
it.each([
['J_Bip_C_Hips', 'Hips'],
['J_Bip_C_Spine', 'Spine'],
['J_Bip_C_Chest', 'Spine1'],
['J_Bip_C_UpperChest', 'Spine2'],
['J_Bip_C_Neck', 'Neck'],
['J_Bip_C_Head', 'Head'],
['J_Bip_L_Shoulder', 'LeftShoulder'],
['J_Bip_L_UpperArm', 'LeftArm'],
['J_Bip_R_LowerArm', 'RightForeArm'],
['J_Bip_L_Hand', 'LeftHand'],
['J_Bip_L_UpperLeg', 'LeftUpLeg'],
['J_Bip_R_LowerLeg', 'RightLeg'],
['J_Bip_L_Foot', 'LeftFoot'],
['J_Bip_L_ToeBase', 'LeftToeBase'],
['J_Bip_R_Toes', 'RightToeBase'],
['J_Bip_L_Little1', 'LeftHandPinky1'],
['J_Bip_R_Index3', 'RightHandIndex3'],
['J_Bip_L_Thumb2', 'LeftHandThumb2'],
])('maps VRM/VRoid bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Reallusion Character Creator 3/4 — every joint carries a `CC_Base_` prefix
// and the limb stems use one-word spellings (`Upperarm`, `Calf`, `ToeBase`,
// `NeckTwist01`) behind an `L_`/`R_` side token. Without the prefix strip +
// sided aliases an entire CC export maps zero bones and ships a T-pose.
it.each([
['CC_Base_Hip', 'Hips'],
['CC_Base_Pelvis', 'Hips'],
['CC_Base_Spine01', 'Spine'],
['CC_Base_Spine02', 'Spine1'],
['CC_Base_Head', 'Head'],
['CC_Base_NeckTwist01', 'Neck'],
['CC_Base_L_Clavicle', 'LeftShoulder'],
['CC_Base_L_Upperarm', 'LeftArm'],
['CC_Base_R_Upperarm', 'RightArm'],
['CC_Base_L_Forearm', 'LeftForeArm'],
['CC_Base_L_Hand', 'LeftHand'],
['CC_Base_L_Thigh', 'LeftUpLeg'],
['CC_Base_R_Thigh', 'RightUpLeg'],
['CC_Base_L_Calf', 'LeftLeg'],
['CC_Base_L_Foot', 'LeftFoot'],
['CC_Base_L_ToeBase', 'LeftToeBase'],
])('maps Character Creator 3/4 bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// 3ds Max Biped — `Bip01 <bone>` / `Bip001 <bone>` with a space-separated side
// token. Stripping the `Bip<NN>` prefix lets the residual canonical/sided
// spellings resolve so the whole biped rig animates instead of T-posing.
it.each([
['Bip01 Pelvis', 'Hips'],
['Bip01 Spine', 'Spine'],
['Bip01 Spine1', 'Spine1'],
['Bip01 Neck', 'Neck'],
['Bip01 Head', 'Head'],
['Bip01 L UpperArm', 'LeftArm'],
['Bip01 L Forearm', 'LeftForeArm'],
['Bip01 L Hand', 'LeftHand'],
['Bip01 L Thigh', 'LeftUpLeg'],
['Bip01 L Calf', 'LeftLeg'],
['Bip01 L Foot', 'LeftFoot'],
['Bip001 R UpperArm','RightArm'],
['Bip001 R Thigh', 'RightUpLeg'],
])('maps 3ds Max Biped bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// 3ds Max Biped numbers its fingers: one digit is the finger at segment 1, two
// digits are the finger then the segment minus one. Both the space spelling
// and the underscore spelling three.js produces at runtime must resolve.
describe('3ds Max Biped fingers and toes', () => {
const FINGERS = [
['Finger0', 'Thumb1'], ['Finger01', 'Thumb2'], ['Finger02', 'Thumb3'],
['Finger1', 'Index1'], ['Finger11', 'Index2'], ['Finger12', 'Index3'],
['Finger2', 'Middle1'], ['Finger21', 'Middle2'], ['Finger22', 'Middle3'],
['Finger3', 'Ring1'], ['Finger31', 'Ring2'], ['Finger32', 'Ring3'],
['Finger4', 'Pinky1'], ['Finger41', 'Pinky2'], ['Finger42', 'Pinky3'],
];
const cases = [];
for (const prefix of ['Bip01', 'Bip001']) {
for (const sep of [' ', '_']) {
for (const [side, long] of [['L', 'Left'], ['R', 'Right']]) {
for (const [raw, canon] of FINGERS) {
cases.push([`${prefix}${sep}${side}${sep}${raw}`, `${long}Hand${canon}`]);
}
cases.push([`${prefix}${sep}${side}${sep}Toe0`, `${long}ToeBase`]);
}
}
}
it.each(cases)('maps %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it('never crosses sides', () => {
for (const [input, expected] of cases) {
const side = /[\s_]([LR])[\s_]/.exec(input)[1];
expect(expected.startsWith(side === 'L' ? 'Left' : 'Right')).toBe(true);
expect(canonicalizeBoneName(input)).toBe(expected);
}
});
});
// Source engine (Valve) skeletons: `ValveBiped.Bip01_*` in a raw glTF,
// `ValveBipedBip01_*` after three.js sanitizes the node name at runtime.
describe('Source engine ValveBiped bones', () => {
const BONES = [
['Pelvis', 'Hips'], ['Spine', 'Spine'], ['Spine1', 'Spine1'], ['Spine2', 'Spine2'],
['Spine4', 'Spine2'], ['Neck1', 'Neck'], ['Head1', 'Head'],
['L_Clavicle', 'LeftShoulder'], ['L_UpperArm', 'LeftArm'], ['L_Forearm', 'LeftForeArm'], ['L_Hand', 'LeftHand'],
['L_Thigh', 'LeftUpLeg'], ['L_Calf', 'LeftLeg'], ['L_Foot', 'LeftFoot'],
['R_Clavicle', 'RightShoulder'], ['R_UpperArm', 'RightArm'], ['R_Forearm', 'RightForeArm'], ['R_Hand', 'RightHand'],
['R_Thigh', 'RightUpLeg'], ['R_Calf', 'RightLeg'], ['R_Foot', 'RightFoot'],
['L_Finger01', 'LeftHandThumb2'], ['R_Finger42', 'RightHandPinky3'],
];
const cases = [];
for (const prefix of ['ValveBiped.', 'ValveBiped']) {
for (const [raw, canon] of BONES) cases.push([`${prefix}Bip01_${raw}`, canon]);
}
it.each(cases)('maps %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
});
// Autodesk HumanIK / MotionBuilder / Maya — every joint sits behind a
// character or subject namespace (`Character1:Hips`, `subject:LeftArm`),
// optionally nested (`char:ns:Hips`). The stems are already canonical, so
// stripping the namespace makes the whole HumanIK rig (the standard mocap
// retarget skeleton) drive the clip library — legs included.
it.each([
['Character1:Hips', 'Hips'],
['Character1:Spine', 'Spine'],
['Character1:Spine1', 'Spine1'],
['Character1:Spine2', 'Spine2'],
['Character1:Neck', 'Neck'],
['Character1:Head', 'Head'],
['Character1:LeftShoulder','LeftShoulder'],
['Character1:LeftArm', 'LeftArm'],
['Character1:LeftForeArm', 'LeftForeArm'],
['Character1:RightHand', 'RightHand'],
['Character1:LeftUpLeg', 'LeftUpLeg'],
['Character1:RightLeg', 'RightLeg'],
['Character1:LeftFoot', 'LeftFoot'],
['Character1:LeftToeBase', 'LeftToeBase'],
['Character2:RightUpLeg', 'RightUpLeg'], // multi-character scene
['subject:LeftArm', 'LeftArm'], // OptiTrack / mocap subject namespace
['char:ns:Hips', 'Hips'], // nested Maya namespaces
['Character1:LeftHandThumb1', 'LeftHandThumb1'],
])('strips the HumanIK / Maya namespace prefix: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// A namespaced node that isn't a real bone must still resolve to null (the
// strip only ever helps a name that was already a humanoid bone).
it('returns null for a namespaced non-bone node', () => {
expect(canonicalizeBoneName('Character1:Reference')).toBeNull();
expect(canonicalizeBoneName('prop:Sword')).toBeNull();
expect(canonicalizeBoneName('Character1:IKLeftFootEffector')).toBeNull();
});
// Generic bare side-prefix auto-riggers (some Meshy/Tripo + simple rigs) emit
// the canonical short bone name behind an `L_`/`R_` token.
it.each([
['L_Arm', 'LeftArm'],
['R_Arm', 'RightArm'],
['L_Shoulder', 'LeftShoulder'],
['L_Leg', 'LeftLeg'],
['R_Leg', 'RightLeg'],
['L_UpLeg', 'LeftUpLeg'],
])('maps generic L_/R_ side-prefix bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// VRM 1.0 normalized humanoid names (camelCase, no vendor prefix).
it.each([
['leftUpperArm', 'LeftArm'],
['rightLowerArm', 'RightForeArm'],
['leftUpperLeg', 'LeftUpLeg'],
['rightLowerLeg', 'RightLeg'],
['upperChest', 'Spine2'],
['chest', 'Spine1'],
['leftToes', 'LeftToeBase'],
])('maps VRM 1.0 camelCase bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Daz3D / Genesis skeletons (`hip`, `abdomen`, `lShldr`, `lThigh`, …),
// including the Genesis 3+ `…Bend` joints.
it.each([
['hip', 'Hips'],
['abdomen', 'Spine'],
['lCollar', 'LeftShoulder'],
['lShldr', 'LeftArm'],
['lShldrBend', 'LeftArm'],
['rForeArm', 'RightForeArm'],
['lThigh', 'LeftUpLeg'],
['lThighBend', 'LeftUpLeg'],
['rShin', 'RightLeg'],
])('maps Daz/Genesis bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// MakeHuman / Blender `.L`/`.R` side suffix (the `.` is a separator), sharing
// stems with the Unreal alias table. Blender's `.001` de-dup is stripped too.
it.each([
['upperarm.L', 'LeftArm'],
['lowerarm.R', 'RightForeArm'],
['clavicle.L', 'LeftShoulder'],
['thigh.L', 'LeftUpLeg'],
['shin.R', 'RightLeg'],
['foot.L', 'LeftFoot'],
['upperarm.L.001', 'LeftArm'], // .L side + Blender .001 de-dup suffix
])('maps MakeHuman/Blender .L/.R bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Simple / generic 3-joint-limb rigs that put the side as a trailing L/R and
// name the upper arm "shoulder", forearm "elbow", hand "wrist", etc.
it.each([
['shoulderL', 'LeftArm'],
['elbowR', 'RightForeArm'],
['wristL', 'LeftHand'],
['hipL', 'LeftUpLeg'],
['kneeR', 'RightLeg'],
['ankleL', 'LeftFoot'],
['toeL', 'LeftToeBase'],
['chest', 'Spine1'],
['pelvis', 'Hips'],
])('maps simple/generic side-suffix rigs: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// SMPL / SMPL-X research-pipeline skeletons (text-to-avatar generators, mocap
// tooling) spell every limb joint as a side word + anatomical joint. The same
// spellings show up in hand-built `leftKnee`-style rigs.
it.each([
['left_hip', 'LeftUpLeg'],
['right_hip', 'RightUpLeg'],
['left_knee', 'LeftLeg'],
['right_knee', 'RightLeg'],
['left_ankle', 'LeftFoot'],
['right_ankle', 'RightFoot'],
['left_elbow', 'LeftForeArm'],
['right_elbow', 'RightForeArm'],
['left_wrist', 'LeftHand'],
['right_wrist', 'RightHand'],
['left_collar', 'LeftShoulder'],
['right_collar', 'RightShoulder'],
['left_clavicle', 'LeftShoulder'],
['left_thigh', 'LeftUpLeg'],
['left_toe', 'LeftToeBase'],
['leftKnee', 'LeftLeg'],
['rightAnkle', 'RightFoot'],
])('maps SMPL / spelled-out side-word bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Alias-table entries that predate this block but had no coverage: the
// centre-torso chest/abdomen/neck spellings, the CC neck twist, and the
// remaining Daz / simple-rig side variants (including derived right twins).
it.each([
['lowerChest', 'Spine1'],
['chestLower', 'Spine1'],
['chestUpper', 'Spine2'],
['abdomenLower', 'Spine'],
['abdomenUpper', 'Spine1'],
['lowerNeck', 'Neck'],
['upperNeck', 'Neck'],
['neckLower', 'Neck'],
['neckUpper', 'Neck'],
['NeckTwist02', 'Neck'],
['lHand', 'LeftHand'],
['rHand', 'RightHand'],
['lFoot', 'LeftFoot'],
['rFoot', 'RightFoot'],
['lToe', 'LeftToeBase'],
['collarR', 'RightShoulder'],
['lClavicle', 'LeftShoulder'],
['rCalf', 'RightLeg'],
['J_Bip_L_Toes', 'LeftToeBase'],
['J_Bip_L_Middle2', 'LeftHandMiddle2'],
['J_Bip_R_Ring1', 'RightHandRing1'],
])('maps remaining alias-table variants: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Roblox R15 (`LowerTorso`/`UpperTorso`, camelCase limbs) and R6 (`Torso`,
// space-separated limbs), plus the generic single-torso spellings.
it.each([
['LowerTorso', 'Hips'],
['UpperTorso', 'Spine1'],
['Torso', 'Spine'],
['Waist', 'Spine'],
['Ribcage', 'Spine1'],
['LeftUpperArm', 'LeftArm'],
['RightLowerArm', 'RightForeArm'],
['LeftUpperLeg', 'LeftUpLeg'],
['RightLowerLeg', 'RightLeg'],
['Left Arm', 'LeftArm'],
['Right Leg', 'RightLeg'],
])('maps Roblox R15/R6 and generic torso bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Second Life / OpenSim skeletons: `m`-prefixed bones with a trailing side
// word. `mShoulder` is the upper arm (the clavicle is `mCollar`); the ankle
// is the articulating foot joint and `mFoot` (the ball) drives the toe.
it.each([
['mPelvis', 'Hips'],
['mTorso', 'Spine'],
['mChest', 'Spine1'],
['mNeck', 'Neck'],
['mHead', 'Head'],
['mCollarLeft', 'LeftShoulder'],
['mCollarRight', 'RightShoulder'],
['mShoulderLeft', 'LeftArm'],
['mShoulderRight', 'RightArm'],
['mElbowLeft', 'LeftForeArm'],
['mWristRight', 'RightHand'],
['mHipLeft', 'LeftUpLeg'],
['mHipRight', 'RightUpLeg'],
['mKneeLeft', 'LeftLeg'],
['mAnkleRight', 'RightFoot'],
['mFootLeft', 'LeftToeBase'],
['mToeRight', 'RightToeBase'],
])('maps Second Life / OpenSim bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
['hips_joint', 'Hips'],
['left_arm_joint', 'LeftArm'],
['right_arm_joint', 'RightArm'],
['left_forearm_joint', 'LeftForeArm'],
['right_hand_joint', 'RightHand'],
['left_upLeg_joint', 'LeftUpLeg'],
['right_leg_joint', 'RightLeg'],
['left_foot_joint', 'LeftFoot'],
])('maps Apple / ARKit _joint skeleton bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it('does not map Apple transform roots as body joints', () => {
expect(canonicalizeBoneName('root_joint')).toBeNull();
});
it.each([
['SpineBase', 'Hips'],
['SpineMid', 'Spine'],
['SpineShoulder', 'Spine2'],
['ShoulderLeft', 'LeftArm'],
['ShoulderRight', 'RightArm'],
['ElbowLeft', 'LeftForeArm'],
['WristRight', 'RightHand'],
['HipLeft', 'LeftUpLeg'],
['KneeRight', 'RightLeg'],
['AnkleLeft', 'LeftFoot'],
['FootRight', 'RightToeBase'],
])('maps Kinect body-tracking bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
['left_heel', 'LeftFoot'],
['right_heel', 'RightFoot'],
['left_foot_index', 'LeftToeBase'],
['right_foot_index', 'RightToeBase'],
])('maps MediaPipe Pose foot landmarks: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it('never crosses sides for Apple, Kinect, or MediaPipe names', () => {
for (const name of ['left_arm_joint', 'ShoulderLeft', 'left_heel', 'left_foot_index']) {
expect(canonicalizeBoneName(name)?.startsWith('Right'), name).toBe(false);
}
for (const name of ['right_arm_joint', 'ShoulderRight', 'right_heel', 'right_foot_index']) {
expect(canonicalizeBoneName(name)?.startsWith('Left'), name).toBe(false);
}
});
// Side-SUFFIX leg spellings. The arm twins (`forearm.L`, `upper_arm.L`) were
// covered by the Rigify fix; the LEG twins were not, and no side-PREFIX entry
// reaches `upperlegl`. Found in production by scripts/audit-rig-coverage.mjs:
// a Blender-exported rig lost both leg joints per side and glided on frozen legs.
it.each([
['UpperLeg.L', 'LeftUpLeg'],
['UpperLeg.R', 'RightUpLeg'],
['LowerLeg.L', 'LeftLeg'],
['LowerLeg.R', 'RightLeg'],
['upper_leg.L', 'LeftUpLeg'],
['lower_leg.R', 'RightLeg'],
['LowerArm.L', 'LeftForeArm'],
['Scapula_R', 'RightShoulder'],
['Scapula_L', 'LeftShoulder'],
])('maps side-suffix leg/arm spellings: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Side-suffix finger chains, both conventions seen in real uploaded avatars.
// The un-numbered spelling is the first phalanx; metacarpals (`Palm1.L`) stay
// unmapped because the canonical set has no metacarpal to drive.
it.each([
['Index.L', 'LeftHandIndex1'],
['Index2.L', 'LeftHandIndex2'],
['Middle1.L', 'LeftHandMiddle1'],
['Middle2.R', 'RightHandMiddle2'],
['Thumb.L', 'LeftHandThumb1'],
['Thumb2.L', 'LeftHandThumb2'],
['Ring1.R', 'RightHandRing1'],
['Pinky3.L', 'LeftHandPinky3'],
['Little1.L', 'LeftHandPinky1'],
['IndexFinger1_R', 'RightHandIndex1'],
['MiddleFinger2_L', 'LeftHandMiddle2'],
['ThumbFinger3_R', 'RightHandThumb3'],
['RingFinger1_R', 'RightHandRing1'],
['LittleFinger2_L', 'LeftHandPinky2'],
['IndexFinger1_R_018', 'RightHandIndex1'], // + glTF de-dup suffix
])('maps side-suffix finger chains: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Advanced Skeleton (Maya) tags centre bones `_M` and limbs `_L`/`_R`. The limbs
// already resolved through the sided table, so these rigs arrived with working
// arms and legs but NO Hips — and with no root to anchor, nothing animated.
it.each([
['Root_M', 'Hips'],
['Root_M_03', 'Hips'], // + glTF de-dup suffix
['Spine1_M_04', 'Spine'], // AS numbers its spine one deeper than canonical
['Spine2_M_05', 'Spine1'],
['Spine3_M', 'Spine2'],
['Neck_M', 'Neck'],
['Head_M', 'Head'],
['Hip_M', 'Hips'],
])('maps Advanced Skeleton centre bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Sketchfab / Maya `j_`-prefixed joint exports. These previously mapped ZERO
// bones and shipped a bind-pose T-pose.
it.each([
['j_pelvis_05', 'Hips'],
['j_hips_00', 'Hips'],
['j_L_hip_06', 'LeftUpLeg'],
['j_L_knee_07', 'LeftLeg'],
['j_L_ankle_08', 'LeftFoot'],
['j_L_toe_010', 'LeftToeBase'],
['j_R_hip_011', 'RightUpLeg'],
['j_R_knee_012', 'RightLeg'],
['j_spine_0_016', 'Spine'],
['j_spine_1_017', 'Spine1'],
['j_spine_2_018', 'Spine2'],
])('maps Sketchfab j_-prefixed bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// The `j_` strip must never touch VRM/VRoid, whose `J_Bip_*` names are matched
// WHOLE by the alias table — stripping `J_` there corrupts the key and drops the
// entire rig. This guards the negative lookahead.
it('does not let the j_ strip corrupt VRM J_Bip_ names', () => {
expect(canonicalizeBoneName('J_Bip_L_UpperArm')).toBe('LeftArm');
expect(canonicalizeBoneName('J_Bip_C_Hips')).toBe('Hips');
expect(canonicalizeBoneName('J_Bip_R_LowerLeg')).toBe('RightLeg');
expect(canonicalizeBoneName('J_Sec_Hair1_01')).toBeNull();
});
// UniGLTF / VRM-converter numbers every node and may flag it with `!`.
it.each([
['5.joint_HipMaster', 'Hips'],
['7.joint_LeftHip', 'LeftUpLeg'],
['8.joint_LeftKnee', 'LeftLeg'],
['9.joint_LeftFoot', 'LeftFoot'],
['10.!joint_LeftToe', 'LeftToeBase'],
])('maps UniGLTF numbered joint names: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Constraint-driven Blender control rigs (Auto-Rig-Pro / "cwf_ + def_ +
// tracker") MUST stay unmapped. Their deform bones are leaves hanging off
// tracker nodes — `def_arm_1.R` is not a child of `def_arm_0.R` — and glTF
// drops the constraints that made that work. Rotating a mapped def_ bone would
// move its own skin while the next segment stayed put, tearing the arm apart.
// The default-rig fallback is the correct outcome; re-rigging is the remedy.
it('leaves constraint-driven control-rig bones unmapped (mesh-tearing guard)', () => {
for (const name of [
'def_arm_0.R', 'def_arm_1.R', 'def_leg_0.L', 'def_leg_1.L',
'def_foot_0.L', 'def_toe_0.L', 'def_hand_0.R', 'def_shoulder_0.R',
'cwf_leg_0.L', 'cwf_arm_1.R', 'fk_leg_0.L', 'c_arm_0_tracker.R',
'cwh_leg_softik_0.L', 'cwf_arm_1_emulator.R',
]) {
expect(canonicalizeBoneName(name), name).toBeNull();
}
});
it('leaves metacarpals and rig scaffolding unmapped', () => {
// Real unmapped names from the production audit that must STAY unmapped —
// mapping them would bind a clip track to the wrong joint.
for (const name of ['Palm1.L', 'Palm2.R', '_rootJoint', 'Bone', 'Body', 'Weapon_R', 'Hat_M']) {
expect(canonicalizeBoneName(name), name).toBeNull();
}
});
// Rigify / Blender anatomical arm chain: side is a `.L`/`.R` suffix and the
// forearm is spelled `forearm` (not `lowerarm`/`elbow`). The suffix normalises
// to `forearml`, which the side-prefix spellings never reach — so before the
// alias was added the elbow dropped and Rigify characters (Quaternius, many
// Blender exports) animated with a rigid forearm.
it.each([
['forearm.L', 'LeftForeArm'],
['forearm.R', 'RightForeArm'],
['DEF-forearm.L', 'LeftForeArm'],
['DEF-upper_arm.L','LeftArm'],
['upper_arm.R', 'RightArm'],
])('maps Rigify/Blender anatomical arm bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it('only strips the suffix when the plain form does not already resolve', () => {
// A genuinely numbered finger bone must keep its index — the un-stripped
// form resolves first, so we never reach the suffix strip.
expect(canonicalizeBoneName('left_hand_index_1')).toBe('LeftHandIndex1');
expect(canonicalizeBoneName('LeftHandIndex1')).toBe('LeftHandIndex1');
// End-effector / non-bone nodes still fall through to null after stripping.
expect(canonicalizeBoneName('mixamorig:HeadTop_End_07')).toBeNull();
expect(canonicalizeBoneName('mixamorig:LeftToe_End_059')).toBeNull();
expect(canonicalizeBoneName('Tail_01')).toBeNull();
});
// Daz/Genesis chains that had no direct coverage: the Genesis 3+ forearm
// Bend joint, the lShin/lCalf lower-leg spellings, and the derived right
// twins of the Shldr/Thigh/Bend family. A miss on any of these drops the
// joint and a Daz export animates with a rigid elbow or frozen legs.
it.each([
['lForearmBend', 'LeftForeArm'],
['rForearmBend', 'RightForeArm'],
['lShin', 'LeftLeg'],
['lCalf', 'LeftLeg'],
['rShldr', 'RightArm'],
['rShldrBend', 'RightArm'],
['rThigh', 'RightUpLeg'],
['rThighBend', 'RightUpLeg'],
['lUpperArm', 'LeftArm'],
['rUpperArm', 'RightArm'],
['lLowerArm', 'LeftForeArm'],
['rLowerLeg', 'RightLeg'],
])('maps remaining Daz/Genesis chain bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Reallusion CC3/CC4 neck twists WITHOUT the CC_Base_ prefix (some export
// paths ship the bare joint names); either twist drives the head chain.
it.each([
['neckTwist01', 'Neck'],
['neckTwist02', 'Neck'],
['neck_twist_01', 'Neck'], // separator variant collapses to the same key
])('maps bare Reallusion neck twists: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Generic Meshy/Tripo side-prefix twins derived by the l→r rule, plus the
// separator/case variants the normaliser must collapse onto the same keys.
it.each([
['R_UpLeg', 'RightUpLeg'],
['R_Shoulder', 'RightShoulder'],
['r_arm', 'RightArm'],
['R_Leg', 'RightLeg'],
])('maps derived R_ side-prefix twins: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// MakeHuman / VRM 1.0 centre-torso spellings in separator form (the
// camelCase forms are asserted in the VRM 1.0 and alias-variant tables
// above; these pin that snake_case reaches the same keys).
it.each([
['upper_chest', 'Spine2'],
['chest_lower', 'Spine1'],
['lower_neck', 'Neck'],
])('maps separator variants of centre-torso bones: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// The SIDED right-twin derivation has four branches. Each is pinned with
// spellings only that branch can produce, so a regression in one regex
// cannot hide behind another.
// Branch 1: a leading "left" word swaps to "right" (leftUpperArm → rightUpperArm).
it.each([
['rightUpperArm', 'RightArm'],
['rightUpperLeg', 'RightUpLeg'],
['rightToes', 'RightToeBase'],
['rightHip', 'RightUpLeg'],
['rightThigh', 'RightUpLeg'],
['rightShin', 'RightLeg'],
['rightCalf', 'RightLeg'],
['rightWrist', 'RightHand'],
['rightClavicle', 'RightShoulder'],
['rightCollar', 'RightShoulder'],
])('derives right twins from the left- word branch: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Branch 2: a leading lowercase "l" before an uppercase letter becomes "r"
// (lShldr → rShldr, lToeBase → rToeBase).
it.each([
['rLowerArm', 'RightForeArm'],
['rUpperLeg', 'RightUpLeg'],
['rToeBase', 'RightToeBase'],
['rClavicle', 'RightShoulder'],
['rCollar', 'RightShoulder'],
])('derives right twins from the l-prefix branch: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Branch 3: a trailing "L" becomes "R" (shoulderL → shoulderR).
it.each([
['shoulderR', 'RightArm'],
['forearmR', 'RightForeArm'],
['upperArmR', 'RightArm'],
['wristR', 'RightHand'],
['ankleR', 'RightFoot'],
['shinR', 'RightLeg'],
['toeR', 'RightToeBase'],
['hipR', 'RightUpLeg'],
])('derives right twins from the trailing-L branch: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
// Branch 4 (identity fallthrough): a SIDED entry with no recognisable side
// token derives rv === lv, and the first-spelling-wins put() means the
// derived Right canonical can never overwrite the left entry. The observable
// invariant: no left-side spelling ever resolves to a Right bone, and no
// derived right-side spelling ever resolves to a Left bone.
it('side derivation never crosses sides', () => {
const leftSpellings = [
'leftUpperArm', 'lUpperArm', 'shoulderL', 'lShldr', 'lShldrBend',
'leftLowerArm', 'elbowL', 'lForeArm', 'lForearmBend', 'forearmL',
'upperArmL', 'wristL', 'lHand', 'lCollar', 'collarL', 'lClavicle',
'leftUpperLeg', 'hipL', 'lThigh', 'lThighBend',
'leftLowerLeg', 'kneeL', 'shinL', 'lShin', 'lCalf',
'ankleL', 'lFoot', 'leftToes', 'toeL', 'lToe', 'lToeBase',
'lArm', 'lShoulder', 'lLeg', 'lUpLeg',
'leftHip', 'leftKnee', 'leftAnkle', 'leftElbow', 'leftWrist',
'leftCollar', 'leftClavicle', 'leftToe',
];
const rightSpellings = [
'rightUpperArm', 'rUpperArm', 'shoulderR', 'rShldr', 'rShldrBend',
'rightLowerArm', 'elbowR', 'rForeArm', 'rForearmBend', 'forearmR',
'upperArmR', 'wristR', 'rHand', 'rCollar', 'collarR', 'rClavicle',
'rightUpperLeg', 'hipR', 'rThigh', 'rThighBend',
'rightLowerLeg', 'kneeR', 'shinR', 'rShin', 'rCalf',
'ankleR', 'rFoot', 'rightToes', 'toeR', 'rToe', 'rToeBase',
'rArm', 'rShoulder', 'rLeg', 'rUpLeg',
'rightHip', 'rightKnee', 'rightAnkle', 'rightElbow', 'rightWrist',
'rightCollar', 'rightClavicle', 'rightToe',
];
for (const name of leftSpellings) {
const canonical = canonicalizeBoneName(name);
expect(canonical, name).not.toBeNull();
expect(canonical.startsWith('Right'), `${name} must not map to a Right bone`).toBe(false);
}
for (const name of rightSpellings) {
const canonical = canonicalizeBoneName(name);
expect(canonical, name).not.toBeNull();
expect(canonical.startsWith('Left'), `${name} must not map to a Left bone`).toBe(false);
}
});
});
// ---------------------------------------------------------------------------
// Finger conventions, and why they are load-bearing.
//
// 30 of the 53 tracks in every clip in public/animations/clips address finger
// bones. A rig whose hands do not name-map therefore scores about 40% retarget
// coverage, which is UNDER the MIN_COVERAGE gate in src/animation-retarget.js,
// so production builds no action for it at all and the avatar stands frozen in
// its bind pose, arms and legs included. That is how an Unreal mannequin, a VRM
// 1.0 avatar, a Genesis figure, a MakeHuman export and a Rigify character were
// all failing before these aliases landed, each measured doing exactly that by
// scripts/animation-dignity-sweep.mjs. Every case below is a real export
// spelling from that convention's own tooling.
// ---------------------------------------------------------------------------
describe('finger chains across rig conventions', () => {
it.each([
// Unreal mannequin: zero-padded joint index, side last.
['index_01_l', 'LeftHandIndex1'],
['index_03_r', 'RightHandIndex3'],
['middle_02_l', 'LeftHandMiddle2'],
['ring_01_r', 'RightHandRing1'],
['pinky_03_l', 'LeftHandPinky3'],
['thumb_01_r', 'RightHandThumb1'],
])('Unreal mannequin: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
// VRM 1.0 names the phalanges instead of numbering them, side first, and
// starts the thumb at its metacarpal. "Little" is the pinky.
['leftIndexProximal', 'LeftHandIndex1'],
['leftIndexIntermediate', 'LeftHandIndex2'],
['leftIndexDistal', 'LeftHandIndex3'],
['rightMiddleProximal', 'RightHandMiddle1'],
['leftLittleDistal', 'LeftHandPinky3'],
['rightRingIntermediate', 'RightHandRing2'],
['leftThumbMetacarpal', 'LeftHandThumb1'],
['leftThumbProximal', 'LeftHandThumb2'],
['rightThumbDistal', 'RightHandThumb3'],
])('VRM 1.0: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
// Daz / Genesis numbers each digit behind a bare side letter, and
// abbreviates the middle finger to `Mid`.
['lIndex1', 'LeftHandIndex1'],
['rIndex3', 'RightHandIndex3'],
['lMid2', 'LeftHandMiddle2'],
['rMid1', 'RightHandMiddle1'],
['lRing3', 'LeftHandRing3'],
['rPinky1', 'RightHandPinky1'],
['lThumb2', 'LeftHandThumb2'],
])('Daz / Genesis: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
// Blender Rigify prefixes the four fingers `f_` and leaves the thumb bare.
['f_index.01.L', 'LeftHandIndex1'],
['f_index.03.R', 'RightHandIndex3'],
['f_middle.02.L', 'LeftHandMiddle2'],
['f_ring.01.R', 'RightHandRing1'],
['f_pinky.03.L', 'LeftHandPinky3'],
['thumb.01.L', 'LeftHandThumb1'],
['thumb.03.R', 'RightHandThumb3'],
// Rigify's deform layer carries the same names behind a DEF- prefix.
['DEF-f_index.01.L', 'LeftHandIndex1'],
])('Blender Rigify: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
// MakeHuman numbers the digits 1..5 starting at the thumb.
['finger1-1.L', 'LeftHandThumb1'],
['finger1-3.R', 'RightHandThumb3'],
['finger2-1.L', 'LeftHandIndex1'],
['finger3-2.R', 'RightHandMiddle2'],
['finger4-3.L', 'LeftHandRing3'],
['finger5-1.R', 'RightHandPinky1'],
])('MakeHuman: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
// Anatomy-kit / scan rigs name the phalanges with the side as a suffix.
['index_proximal.L', 'LeftHandIndex1'],
['index_distal.R', 'RightHandIndex3'],
['middle_intermediate.L', 'LeftHandMiddle2'],
['little_proximal.R', 'RightHandPinky1'],
['thumb_metacarpal.L', 'LeftHandThumb1'],
])('anatomical phalanx naming: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it('a full Unreal mannequin hand maps all 15 joints per side', () => {
const mapped = new Set();
for (const side of ['l', 'r']) {
for (const finger of ['thumb', 'index', 'middle', 'ring', 'pinky']) {
for (let n = 1; n <= 3; n++) {
const canonical = canonicalizeBoneName(`${finger}_0${n}_${side}`);
expect(canonical, `${finger}_0${n}_${side}`).not.toBeNull();
mapped.add(canonical);
}
}
}
// 30 distinct canonical finger bones, no two spellings collapsed onto one,
// which would leave a joint undriven while coverage still looked healthy.
expect(mapped.size).toBe(30);
});
it('metacarpal scaffolding that has no canonical home stays unmapped', () => {
// The canonical set has no palm/metacarpal bone for the four fingers, so
// these must keep falling through rather than stealing a phalanx track.
// (The THUMB metacarpal is the exception: it IS the canonical Thumb1.)
for (const name of ['Palm1.L', 'lCarpal1', 'index_metacarpal.L', 'leftIndexMetacarpal']) {
expect(canonicalizeBoneName(name), name).toBeNull();
}
});
});
// ---------------------------------------------------------------------------
// Anatomical-Latin rigs: the convention the canonicalizer had never seen. Scan
// pipelines and anatomy kits name every joint for the bone itself. Before these
// aliases the whole skeleton mapped 3 of 52 joints (pelvis, scapula.L/R) and
// animated nothing at all.
// ---------------------------------------------------------------------------
describe('anatomical-Latin skeleton', () => {
it.each([
['lumbar', 'Spine'],
['thoracic', 'Spine1'],
['sternum', 'Spine2'],
['cervical', 'Neck'],
['cranium', 'Head'],
['skull', 'Head'],
])('centre chain: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
['humerus.L', 'LeftArm'],
['humerus.R', 'RightArm'],
['l_humerus', 'LeftArm'],
['ulna.L', 'LeftForeArm'],
['radius.R', 'RightForeArm'],
['carpus.L', 'LeftHand'],
['femur.R', 'RightUpLeg'],
['l_femur', 'LeftUpLeg'],
['tibia.L', 'LeftLeg'],
['fibula.R', 'RightLeg'],
['talus.L', 'LeftFoot'],
['tarsus.R', 'RightFoot'],
['calcaneus.L', 'LeftFoot'],
['metatarsus.R', 'RightToeBase'],
])('limbs, both side spellings: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it('never crosses sides', () => {
const left = [
'humerus.L', 'ulna.L', 'radius.L', 'carpus.L', 'femur.L', 'tibia.L',
'fibula.L', 'talus.L', 'tarsus.L', 'calcaneus.L', 'metatarsus.L',
'l_humerus', 'l_femur', 'index_proximal.L', 'thumb_metacarpal.L',
];
const right = left.map((n) => (n.endsWith('.L') ? n.replace(/\.L$/, '.R') : n.replace(/^l_/, 'r_')));
for (const name of left) {
expect(canonicalizeBoneName(name)?.startsWith('Right'), name).toBe(false);
}
for (const name of right) {
expect(canonicalizeBoneName(name)?.startsWith('Left'), name).toBe(false);
}
});
});
describe('MMD (MikuMikuDance) Japanese skeleton', () => {
it.each([
['センター', 'Hips'],
['下半身', 'Hips'],
['上半身', 'Spine'],
['上半身2', 'Spine1'],
['首', 'Neck'],
['頭', 'Head'],
])('centre chain: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
['左肩', 'LeftShoulder'],
['左腕', 'LeftArm'],
['左ひじ', 'LeftForeArm'],
['左手首', 'LeftHand'],
['左足', 'LeftUpLeg'],
['左ひざ', 'LeftLeg'],
['左足首', 'LeftFoot'],
['左つま先', 'LeftToeBase'],
['右肩', 'RightShoulder'],
['右腕', 'RightArm'],
['右ひじ', 'RightForeArm'],
['右手首', 'RightHand'],
['右足', 'RightUpLeg'],
['右ひざ', 'RightLeg'],
['右足首', 'RightFoot'],
['右つま先', 'RightToeBase'],
])('limbs: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it.each([
['左人指1', 'LeftHandIndex1'],
['左人差指2', 'LeftHandIndex2'],
['左中指3', 'LeftHandMiddle3'],
['左薬指1', 'LeftHandRing1'],
['左小指2', 'LeftHandPinky2'],
['右人指3', 'RightHandIndex3'],
['右小指1', 'RightHandPinky1'],
])('finger chains: %s → %s', (input, expected) => {
expect(canonicalizeBoneName(input)).toBe(expected);
});
it('shifts the 0-indexed thumb onto the 1-indexed canonical chain', () => {
expect(canonicalizeBoneName('左親指0')).toBe('LeftHandThumb1');
expect(canonicalizeBoneName('左親指1')).toBe('LeftHandThumb2');
expect(canonicalizeBoneName('左親指2')).toBe('LeftHandThumb3');
expect(canonicalizeBoneName('右親指0')).toBe('RightHandThumb1');
});
it('leaves IK targets, twist bones, and non-joint control bones unmapped', () => {
for (const name of ['左足IK', '左つま先IK', '右足IK', '左腕捩', '左手捩', '全ての親', 'グルーブ', '両目']) {
expect(canonicalizeBoneName(name), name).toBeNull();
}
});
it('never crosses sides', () => {
const left = ['左肩', '左腕', '左ひじ', '左手首', '左足', '左ひざ', '左足首', '左つま先', '左人指1', '左親指0'];
for (const name of left) {
expect(canonicalizeBoneName(name)?.startsWith('Left'), name).toBe(true);
}
for (const name of left.map((n) => n.replace(/^左/, '右'))) {
expect(canonicalizeBoneName(name)?.startsWith('Right'), name).toBe(true);
}
});
});
describe('canonicalizeJointNodes (in-place rewrite)', () => {
it('only touches nodes referenced by skins[].joints', () => {
const json = {
nodes: [
{ name: 'mixamorig:Hips' },
{ name: 'mixamorig:Spine' },
{ name: 'mixamorig:left_arm' },
{ name: 'mixamorig:Decoration_NotABone' }, // not a joint — left alone
],
skins: [{ joints: [0, 1, 2] }],
};
const { renamed, samples } = canonicalizeJointNodes(json);
expect(renamed).toBe(3);
expect(json.nodes[0].name).toBe('Hips');
expect(json.nodes[1].name).toBe('Spine');
expect(json.nodes[2].name).toBe('LeftArm');
expect(json.nodes[3].name).toBe('mixamorig:Decoration_NotABone');
expect(samples).toHaveLength(3);
expect(samples[0]).toEqual({ from: 'mixamorig:Hips', to: 'Hips' });
});
it('splits a Rigify shoulder/upper-arm collision (clavicle → Shoulder, upper arm → Arm)', () => {
// Both `shoulder.L` (clavicle) and `upper_arm.L` normalise onto LeftArm.
// Without collision resolution two joints take the name LeftArm and the arm
// clip binds to the clavicle. The resolver demotes the clavicle to Shoulder.
const json = {
nodes: [
{ name: 'DEF-hips' },
{ name: 'DEF-shoulder.L' }, { name: 'DEF-upper_arm.L' }, { name: 'DEF-forearm.L' }, { name: 'DEF-hand.L' },
{ name: 'DEF-shoulder.R' }, { name: 'DEF-upper_arm.R' }, { name: 'DEF-forearm.R' }, { name: 'DEF-hand.R' },
],
skins: [{ joints: [0, 1, 2, 3, 4, 5, 6, 7, 8] }],
};
canonicalizeJointNodes(json);
const names = json.nodes.map((n) => n.name);
expect(names.filter((n) => n === 'LeftArm')).toHaveLength(1);
expect(names.filter((n) => n === 'LeftShoulder')).toHaveLength(1);
expect(names.filter((n) => n === 'LeftForeArm')).toHaveLength(1);
expect(names.filter((n) => n === 'RightArm')).toHaveLength(1);
expect(names.filter((n) => n === 'RightShoulder')).toHaveLength(1);
});
it('does NOT invent a Shoulder when there is no collision (simple rig: shoulder = the arm)', () => {
// A simple 3-joint rig names its upper arm `shoulderL` and has no separate
// upper-arm bone — so shoulder must stay LeftArm, never demote to Shoulder.
const json = {
nodes: [{ name: 'Hips' }, { name: 'shoulderL' }, { name: 'elbowL' }, { name: 'wristL' }],
skins: [{ joints: [0, 1, 2, 3] }],
};
canonicalizeJointNodes(json);
const names = json.nodes.map((n) => n.name);
expect(names).toContain('LeftArm');
expect(names).not.toContain('LeftShoulder');
});
it('splits an SMPL collar/shoulder collision (collar → Shoulder, shoulder → Arm)', () => {
// SMPL names the clavicle `left_collar` and the upper arm `left_shoulder`;
// both normalise onto LeftShoulder, which would leave LeftArm vacant and
// the arm clip unbound. The resolver promotes the shoulder-spelled joint
// (the upper arm) to Arm.
const json = {
nodes: [
{ name: 'pelvis' },
{ name: 'left_collar' }, { name: 'left_shoulder' }, { name: 'left_elbow' }, { name: 'left_wrist' },
{ name: 'right_collar' }, { name: 'right_shoulder' }, { name: 'right_elbow' }, { name: 'right_wrist' },
],
skins: [{ joints: [0, 1, 2, 3, 4, 5, 6, 7, 8] }],
};
canonicalizeJointNodes(json);
expect(json.nodes[1].name).toBe('LeftShoulder');
expect(json.nodes[2].name).toBe('LeftArm');
expect(json.nodes[3].name).toBe('LeftForeArm');
expect(json.nodes[4].name).toBe('LeftHand');
expect(json.nodes[6].name).toBe('RightArm');
});
it('does NOT promote shoulder to Arm when there is no collar collision', () => {
// A rig whose only arm-root joint is `left_shoulder` must keep it on
// LeftShoulder — nothing contests the name.
const json = {
nodes: [{ name: 'pelvis' }, { name: 'left_shoulder' }, { name: 'left_elbow' }],
skins: [{ joints: [0, 1, 2] }],
};
canonicalizeJointNodes(json);
expect(json.nodes[1].name).toBe('LeftShoulder');
});
it('uses skeleton hierarchy to pick the clavicle when two contenders are eligible', () => {
// `scapula.L` and `shoulder.L` are both clavicle-spelled, so spelling alone
// cannot say which one to demote, and document order would pick the wrong
// one. Hierarchy can: only `shoulder.L` sits above the upper arm.
// spine → scapula.L (a leaf deform bone)
// → shoulder.L → upper_arm.L
const plan = [
{ raw: 'scapula.L', canonical: 'LeftArm', id: 'scapula' },
{ raw: 'shoulder.L', canonical: 'LeftArm', id: 'clavicle' },
{ raw: 'upper_arm.L', canonical: 'LeftArm', id: 'arm' },
];
const parent = { scapula: 'spine', clavicle: 'spine', arm: 'clavicle' };
const changed = resolveArmShoulderCollisions(plan, {
isAncestor: (x, y) => {
for (let cur = parent[y.id]; cur; cur = parent[cur]) if (cur === x.id) return true;
return false;
},
});
expect(changed).toBe(1);
expect(plan.find((p) => p.id === 'clavicle').canonical).toBe('LeftShoulder');
expect(plan.find((p) => p.id === 'scapula').canonical).toBe('LeftArm');
});
it('resolves nothing on a plan with no contention', () => {
const plan = [
{ raw: 'clavicle.L', canonical: 'LeftShoulder' },
{ raw: 'upperarm.L', canonical: 'LeftArm' },
];
expect(resolveArmShoulderCollisions(plan)).toBe(0);
expect(plan.map((p) => p.canonical)).toEqual(['LeftShoulder', 'LeftArm']);
});
it('resolves the collision identically whichever order the joints are listed in', () => {
// glTF lists joints parent-first, but nothing in the spec requires it, and
// exporters that write the skin's joint array in skin-weight order do not.
// The result must not depend on that ordering.
const build = (order) => ({
nodes: order.map((name) => ({ name })),
skins: [{ joints: order.map((_, i) => i) }],
});
const parentFirst = build(['hips', 'shoulder.L', 'upper_arm.L', 'forearm.L']);
const childFirst = build(['hips', 'upper_arm.L', 'shoulder.L', 'forearm.L']);
canonicalizeJointNodes(parentFirst);
canonicalizeJointNodes(childFirst);
expect(parentFirst.nodes[1].name).toBe('LeftShoulder');
expect(parentFirst.nodes[2].name).toBe('LeftArm');
expect(childFirst.nodes[1].name).toBe('LeftArm');
expect(childFirst.nodes[2].name).toBe('LeftShoulder');
});
it('never assigns the same canonical name to two joints (SMPL ankle + foot chain)', () => {
// `left_ankle` (the articulating joint) and `left_foot` (its child) both
// resolve to LeftFoot. Parent-first order means the ankle takes the name;
// the child keeps its original name instead of creating an ambiguous twin.
const json = {
nodes: [
{ name: 'pelvis', children: [1] },
{ name: 'left_hip', children: [2] },
{ name: 'left_knee', children: [3] },
{ name: 'left_ankle', children: [4] },
{ name: 'left_foot' },
],
skins: [{ joints: [0, 1, 2, 3, 4] }],
};
canonicalizeJointNodes(json);
expect(json.nodes[3].name).toBe('LeftFoot');
expect(json.nodes[4].name).toBe('left_foot');
const names = json.nodes.map((n) => n.name);
expect(names.filter((n) => n === 'LeftFoot')).toHaveLength(1);
expect(names).toContain('Hips');
expect(names).toContain('LeftUpLeg');
expect(names).toContain('LeftLeg');
});
it('skips a rename whose target already exists on a joint that is not renamed', () => {
// A rig with a literal canonical `Neck` plus a CC neck twist that would
// also map to Neck: the existing bone keeps the name, the twist is left
// untouched rather than duplicated.
const json = {
nodes: [
{ name: 'CC_Base_Hip' },
{ name: 'Neck' },
{ name: 'CC_Base_NeckTwist02' },
],
skins: [{ joints: [0, 1, 2] }],
};
const { renamed } = canonicalizeJointNodes(json);
expect(renamed).toBe(1);
expect(json.nodes[0].name).toBe('Hips');
expect(json.nodes[1].name).toBe('Neck');
expect(json.nodes[2].name).toBe('CC_Base_NeckTwist02');
});
it('returns 0 when the rig is already canonical', () => {
const json = {
nodes: [{ name: 'Hips' }, { name: 'Spine' }, { name: 'LeftArm' }],
skins: [{ joints: [0, 1, 2] }],
};
const { renamed } = canonicalizeJointNodes(json);
expect(renamed).toBe(0);
expect(json.nodes[0].name).toBe('Hips');
});
it('returns 0 and never throws on a buffer-less GLB JSON (no skins / no nodes)', () => {
expect(canonicalizeJointNodes({}).renamed).toBe(0);
expect(canonicalizeJointNodes({ nodes: [] }).renamed).toBe(0);
expect(canonicalizeJointNodes({ nodes: [{ name: 'mixamorig:Hips' }] }).renamed).toBe(0);
});
it('skips joints whose names are not recognised humanoid bones', () => {
const json = {
nodes: [{ name: 'mixamorig:Hips' }, { name: 'mixamorig:Tail_01' }, { name: 'J_Bip_L_UpperArm' }],
skins: [{ joints: [0, 1, 2] }],
};
const { renamed } = canonicalizeJointNodes(json);
// Hips (Mixamo) and the VRM upper-arm both canonicalize; the non-humanoid
// Tail bone has no mapping and is left untouched.
expect(renamed).toBe(2);
expect(json.nodes[0].name).toBe('Hips');
expect(json.nodes[1].name).toBe('mixamorig:Tail_01');
expect(json.nodes[2].name).toBe('LeftArm');
});
});
describe('canonicalizeGLBBones (full GLB rewrite)', () => {
it('throws clearly on a non-ArrayBuffer or truncated buffer', () => {
expect(() => canonicalizeGLBBones(null)).toThrow(/ArrayBuffer required/);
expect(() => canonicalizeGLBBones(new ArrayBuffer(8))).toThrow(/too small/);
});
it('throws on a bad magic number', () => {
const ab = new ArrayBuffer(40);
new DataView(ab).setUint32(0, 0xdeadbeef, true);
expect(() => canonicalizeGLBBones(ab)).toThrow(/bad magic/);
});
it('throws on GLB version != 2', () => {
const ab = new ArrayBuffer(40);
const dv = new DataView(ab);
dv.setUint32(0, GLB_MAGIC, true);
dv.setUint32(4, 1, true);
expect(() => canonicalizeGLBBones(ab)).toThrow(/v2 is supported/);
});
it('returns the original buffer by reference when no renames were needed', () => {
const ab = buildGLB({
nodes: [{ name: 'Hips' }, { name: 'LeftArm' }],
skins: [{ joints: [0, 1] }],
});
const out = canonicalizeGLBBones(ab);
expect(out.renamed).toBe(0);
expect(out.buffer).toBe(ab); // same reference — caller can skip re-upload
});
it('rewrites Mixamo-prefixed joint names and produces a valid GLB', () => {
const bin = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
const ab = buildGLB({ nodes: MIXAMO_NODES, skins: MIXAMO_SKINS }, bin);
const { buffer, renamed, samples } = canonicalizeGLBBones(ab);
expect(renamed).toBe(6);
expect(buffer).not.toBe(ab);
const dv = new DataView(buffer);
expect(dv.getUint32(0, true)).toBe(GLB_MAGIC);
expect(dv.getUint32(4, true)).toBe(2);
expect(dv.getUint32(8, true)).toBe(buffer.byteLength);
const json = readGLBJson(buffer);
expect(json.nodes[0].name).toBe('Hips');
expect(json.nodes[1].name).toBe('Spine');
expect(json.nodes[2].name).toBe('LeftArm');
expect(json.nodes[3].name).toBe('LeftForeArm');
expect(json.nodes[4].name).toBe('LeftHand');
expect(json.nodes[5].name).toBe('RightArm');
// Non-joint preserved verbatim.
expect(json.nodes[6].name).toBe('mixamorig:LeftLeg_collision_mesh');
// Samples are stable, used by the dashboard to surface "X bones retargeted".
expect(samples.length).toBeGreaterThan(0);
expect(samples[0].from).toMatch(/^mixamorig:/);
});
it('preserves the BIN chunk byte-for-byte', () => {
const bin = new Uint8Array(64);
for (let i = 0; i < bin.length; i++) bin[i] = (i * 7 + 13) & 0xff;
const ab = buildGLB({ nodes: MIXAMO_NODES, skins: MIXAMO_SKINS }, bin);
const { buffer } = canonicalizeGLBBones(ab);
// Find BIN chunk in the rewritten buffer.
const dv = new DataView(buffer);
const jLen = dv.getUint32(12, true);
const binOffset = 20 + jLen;
expect(dv.getUint32(binOffset + 4, true)).toBe(CHUNK_TYPE_BIN);
const binLen = dv.getUint32(binOffset, true);
expect(binLen).toBe(bin.length);
const recoveredBin = new Uint8Array(buffer, binOffset + 8, binLen);
expect(Array.from(recoveredBin)).toEqual(Array.from(bin));
});
it('JSON chunk in the output is 4-byte aligned', () => {
const ab = buildGLB({ nodes: MIXAMO_NODES, skins: MIXAMO_SKINS });
const { buffer } = canonicalizeGLBBones(ab);
const jLen = new DataView(buffer).getUint32(12, true);
expect(jLen % 4).toBe(0);
});
it('round-trips a buffer-less GLB (no BIN chunk)', () => {
const ab = buildGLB({ nodes: MIXAMO_NODES, skins: MIXAMO_SKINS });
const { buffer, renamed } = canonicalizeGLBBones(ab);
expect(renamed).toBe(6);
// Header `total` matches actual byte length and there's no chunk 1.
const dv = new DataView(buffer);
expect(dv.getUint32(8, true)).toBe(buffer.byteLength);
const jLen = dv.getUint32(12, true);
expect(20 + jLen).toBe(buffer.byteLength);
});
// best3d order 075 task 4: the import landing accepts a .vrm export and
// repairs its rig through this same function before upload. VRM files are
// ordinary GLB containers with a VRoid-style skeleton plus VRM-specific
// extension JSON (VRMC_vrm's humanBones point at node *indices*, not
// names). canonicalizeGLBBones must rename the joints the Mixamo clip
// library needs without touching node order or any extension block, since
// a shifted index would break @pixiv/three-vrm's humanoid resolution.
it('renames VRoid joints in a VRM 1.0 GLB without disturbing the VRMC_vrm/VRMC_springBone extension blocks', () => {
const nodes = [
{ name: 'J_Bip_C_Hips', children: [1] },
{ name: 'J_Bip_C_Spine', children: [2] },
{ name: 'J_Bip_L_UpperArm' },
{ name: 'J_Sec_Hair1_01' }, // VRM spring-bone joint, not a humanoid bone
];
const vrmExtension = {
specVersion: '1.0',
humanoid: {
humanBones: {
hips: { node: 0 },
spine: { node: 1 },
leftUpperArm: { node: 2 },
},
},
};
const springBoneExtension = {
specVersion: '1.0',
colliderGroups: [],
springs: [{ name: 'hair', joints: [{ node: 3, stiffness: 0.5, gravityPower: 0.5, gravityDir: [0, -1, 0], dragForce: 0.3, hitRadius: 0.02 }] }],
};
const ab = buildGLB({
nodes,
skins: [{ joints: [0, 1, 2, 3] }],
extensionsUsed: ['VRMC_vrm', 'VRMC_springBone'],
extensions: { VRMC_vrm: vrmExtension, VRMC_springBone: springBoneExtension },
});
const { buffer, renamed } = canonicalizeGLBBones(ab);
expect(renamed).toBe(3); // the three humanoid joints; the spring-bone-only node is untouched
const json = readGLBJson(buffer);
expect(json.nodes[0].name).toBe('Hips');
expect(json.nodes[1].name).toBe('Spine');
expect(json.nodes[2].name).toBe('LeftArm');
expect(json.nodes[3].name).toBe('J_Sec_Hair1_01');
// The VRM extensions reference nodes by index, never by name, so the
// rename must leave both blocks byte-for-byte identical.
expect(json.extensionsUsed).toEqual(['VRMC_vrm', 'VRMC_springBone']);
expect(json.extensions.VRMC_vrm).toEqual(vrmExtension);
expect(json.extensions.VRMC_springBone).toEqual(springBoneExtension);
});
});
describe('canonicalizeArmatureOrientation', () => {
const P90 = [Math.sin(Math.PI / 4), 0, 0, Math.cos(Math.PI / 4)]; // +90°X
const M90 = [-Math.sin(Math.PI / 4), 0, 0, Math.cos(Math.PI / 4)]; // −90°X
// Mixamo-shaped rig: armature(+90°X, uniform scale) → Hips(−90°X) → Spine → Head,
// plus a sibling mesh node under the armature. Net bind pose is upright.
function tiltedRigJson(armRot, hipsRot) {
return {
asset: { version: '2.0' },
nodes: [
{ name: 'Armature', rotation: armRot, scale: [0.01, 0.01, 0.01], children: [1, 4] },
{ name: 'mixamorig:Hips', rotation: hipsRot, translation: [0, 100, 0], children: [2] },
{ name: 'mixamorig:Spine', translation: [0, 10, 0], children: [3] },
{ name: 'mixamorig:Head', translation: [0, 20, 0] },
{ name: 'Ch03' },
],
skins: [{ joints: [1, 2, 3] }],
scenes: [{ nodes: [0] }],
scene: 0,
};
}
function jointWorld(json, idx) {
const parentOf = new Map();
json.nodes.forEach((n, i) => {
if (Array.isArray(n.children)) for (const c of n.children) parentOf.set(c, i);
});
const local = (n) => {
const t = new Vector3();
const r = new Quaternion();
const s = new Vector3(1, 1, 1);
if (n.translation) t.fromArray(n.translation);
if (n.rotation) r.fromArray(n.rotation);
if (n.scale) s.fromArray(n.scale);
return new Matrix4().compose(t, r, s);
};
const w = (i) => {
const p = parentOf.get(i);
const m = local(json.nodes[i]);
return p == null ? m : w(p).clone().multiply(m);
};
return w(idx);
}
it('folds a Mixamo +90/−90 split to an axis-aligned rig, losslessly', () => {
const json = tiltedRigJson(P90.slice(), M90.slice());
const hipsBefore = jointWorld(json, 1).elements.slice();
const headBefore = jointWorld(json, 3).elements.slice();
const res = canonicalizeArmatureOrientation(json);
expect(res.corrected).toBe(true);
expect(res.hipsIdentity).toBe(true);
// Both the armature and the (counter-rotated) Hips are now identity.
expect(json.nodes[0].rotation).toEqual([0, 0, 0, 1]);
json.nodes[1].rotation.forEach((v, i) => expect(v).toBeCloseTo([0, 0, 0, 1][i], 6));
// World matrices of the bones are preserved → the skinned mesh is unchanged.
jointWorld(json, 1).elements.forEach((v, i) => expect(v).toBeCloseTo(hipsBefore[i], 4));
jointWorld(json, 3).elements.forEach((v, i) => expect(v).toBeCloseTo(headBefore[i], 4));
});
it('is a no-op when the armature is already axis-aligned', () => {
const json = tiltedRigJson([0, 0, 0, 1], [0, 0, 0, 1]);
const res = canonicalizeArmatureOrientation(json);
expect(res.corrected).toBe(false);
});
it('refuses to fold a non-uniform-scale armature (rotation would not commute)', () => {
const json = tiltedRigJson(P90.slice(), M90.slice());
json.nodes[0].scale = [0.01, 0.02, 0.01];
const res = canonicalizeArmatureOrientation(json);
expect(res.corrected).toBe(false);
expect(json.nodes[0].rotation).toEqual(P90); // untouched
});
it('canonicalizeGLBBones reports orientationCorrected and produces a valid GLB', () => {
const glb = buildGLB(tiltedRigJson(P90.slice(), M90.slice()), new Uint8Array([1, 2, 3, 4]));
const res = canonicalizeGLBBones(glb);
expect(res.orientationCorrected).toBe(true);
expect(res.renamed).toBeGreaterThan(0); // mixamorig: names also canonicalized
const dv = new DataView(res.buffer);
expect(dv.getUint32(0, true)).toBe(GLB_MAGIC);
expect(dv.getUint32(8, true)).toBe(res.buffer.byteLength);
});
});
// ── Real-fixture tests ────────────────────────────────────────────────────────
// These load the actual cz.glb (reference canonical rig) and michelle.glb
// (Mixamo rig with +90°X armature / −90°X Hips) from disk so we can verify
// idempotency and appearance-invariant normalization on real production assets.
//
// Helper: collect joint-world matrices from a parsed glTF JSON.
function jointWorldMatrices(json) {
const parentOf = new Map();
json.nodes.forEach((n, i) => {
if (Array.isArray(n.children)) for (const c of n.children) parentOf.set(c, i);
});
const local = (n) => {
const t = new Vector3(), r = new Quaternion(), s = new Vector3(1, 1, 1);
if (n.translation) t.fromArray(n.translation);
if (n.rotation) r.fromArray(n.rotation);
if (n.scale) s.fromArray(n.scale);
return new Matrix4().compose(t, r, s);
};
const cache = new Map();
const world = (i) => {
if (cache.has(i)) return cache.get(i);
const p = parentOf.get(i);
const m = p == null ? local(json.nodes[i]) : world(p).clone().multiply(local(json.nodes[i]));
cache.set(i, m);
return m;
};
const joints = new Set();
for (const sk of json.skins || []) for (const j of sk.joints || []) joints.add(j);
const out = new Map();
for (const j of joints) out.set(j, world(j).elements.slice());
return out;
}
function glbToAB(buf) {
// Node Buffer may be a view into a shared pool; .slice() always returns a
// fresh backing ArrayBuffer at offset 0.
return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
}
describe('real-fixture: cz.glb (reference canonical rig)', () => {
it('is a no-op — buffer returned by reference (idempotent)', () => {
const buf = readFileSync('public/avatars/cz.glb');
const ab = glbToAB(buf);
const res = canonicalizeGLBBones(ab);
expect(res.renamed).toBe(0);
expect(res.orientationCorrected).toBe(false);
// Original buffer reference returned — no unnecessary repack.
expect(res.buffer).toBe(ab);
});
});
describe('real-fixture: michelle.glb (Mixamo rig normalization)', () => {
// Shared fixture computed once in beforeAll; each it() reads from these.
let ab, res, beforeW, afterJson;
beforeAll(() => {
const buf = readFileSync('public/avatars/michelle.glb');
ab = glbToAB(buf);
beforeW = jointWorldMatrices(readGLBJson(ab));
res = canonicalizeGLBBones(ab);
afterJson = readGLBJson(res.buffer);
});
it('bones renamed and orientation corrected', () => {
expect(res.renamed).toBeGreaterThan(0); // mixamorig: prefix stripped
expect(res.orientationCorrected).toBe(true); // +90/−90 fold applied
expect(res.buffer).not.toBe(ab); // new buffer produced
});
it('Hips rest is near identity after normalization', () => {
const hipsIdx = afterJson.nodes.findIndex((n) => n.name === 'Hips');
expect(hipsIdx).toBeGreaterThanOrEqual(0);
const hipsRot = afterJson.nodes[hipsIdx].rotation || [0, 0, 0, 1];
// |w| ≈ 1 means identity quaternion (axis ≈ zero, angle ≈ 0).
expect(Math.abs(hipsRot[3])).toBeCloseTo(1, 5);
});
it('joint world matrices are preserved — appearance is lossless', () => {
const afterW = jointWorldMatrices(afterJson);
const EPS = 1e-3; // 1 mm in typical avatar units
for (const [idx, bEls] of beforeW) {
const aEls = afterW.get(idx);
if (!aEls) continue;
for (let k = 0; k < 16; k++) {
expect(Math.abs(bEls[k] - aEls[k])).toBeLessThan(EPS);
}
}
});
it('all joint names are canonical after normalization', () => {
const joints = new Set();
for (const sk of afterJson.skins || []) for (const j of sk.joints || []) joints.add(j);
const nonCanon = [...joints].map((j) => afterJson.nodes[j].name)
.filter((n) => canonicalizeBoneName(n) !== n && canonicalizeBoneName(n) !== null);
expect(nonCanon).toHaveLength(0);
});
});
describe('SMPL / SMPL-X skeleton (research text-to-avatar output)', () => {
// The 24-joint SMPL body skeleton, in its standard parent-first order. This
// is what research generators (TADA, HumanGaussian, mocap exporters) emit,
// so it hits the avatar upload path with no vendor prefix to strip.
const SMPL_JOINTS = [
'pelvis',
'left_hip', 'right_hip', 'spine1',
'left_knee', 'right_knee', 'spine2',
'left_ankle', 'right_ankle', 'spine3',
'left_foot', 'right_foot',
'neck', 'left_collar', 'right_collar', 'head',
'left_shoulder', 'right_shoulder',
'left_elbow', 'right_elbow',
'left_wrist', 'right_wrist',
'left_hand', 'right_hand',
];
it('maps the full body chain, legs and arms included, with no duplicate names', () => {
const json = {
nodes: SMPL_JOINTS.map((name) => ({ name })),
skins: [{ joints: SMPL_JOINTS.map((_, i) => i) }],
};
canonicalizeJointNodes(json);
const names = json.nodes.map((n) => n.name);
for (const bone of [
'Hips', 'Neck', 'Head',
'LeftShoulder', 'LeftArm', 'LeftForeArm', 'LeftHand',
'RightShoulder', 'RightArm', 'RightForeArm', 'RightHand',
'LeftUpLeg', 'LeftLeg', 'LeftFoot',
'RightUpLeg', 'RightLeg', 'RightFoot',
]) {
expect(names, bone).toContain(bone);
}
// The wrist (articulating joint) takes the Hand name; its child keeps its
// original name — no canonical name is ever assigned twice.
const canon = names.filter((n) => CANONICAL_BONES.includes(n));
expect(new Set(canon).size).toBe(canon.length);
});
});
describe('rig worker skeleton (workers/rig, Make-It-Animatable output)', () => {
// The exact 52-bone skeleton the auto-rig worker emits (Mixamo names, see
// workers/rig/engine_mia.py). Every bone must map onto the canonical set so
// a freshly rigged avatar can drive the full clip library with 100%
// coverage; a rename miss here silently breaks retargeting in production.
const MIA_JOINTS = [
'Hips', 'Spine', 'Spine1', 'Spine2', 'Neck', 'Head',
'LeftShoulder', 'LeftArm', 'LeftForeArm', 'LeftHand',
'LeftHandThumb1', 'LeftHandThumb2', 'LeftHandThumb3',
'LeftHandIndex1', 'LeftHandIndex2', 'LeftHandIndex3',
'LeftHandMiddle1', 'LeftHandMiddle2', 'LeftHandMiddle3',
'LeftHandRing1', 'LeftHandRing2', 'LeftHandRing3',
'LeftHandPinky1', 'LeftHandPinky2', 'LeftHandPinky3',
'RightShoulder', 'RightArm', 'RightForeArm', 'RightHand',
'RightHandThumb1', 'RightHandThumb2', 'RightHandThumb3',
'RightHandIndex1', 'RightHandIndex2', 'RightHandIndex3',
'RightHandMiddle1', 'RightHandMiddle2', 'RightHandMiddle3',
'RightHandRing1', 'RightHandRing2', 'RightHandRing3',
'RightHandPinky1', 'RightHandPinky2', 'RightHandPinky3',
'LeftUpLeg', 'LeftLeg', 'LeftFoot', 'LeftToeBase',
'RightUpLeg', 'RightLeg', 'RightFoot', 'RightToeBase',
].map((n) => `mixamorig:${n}`);
it('every worker bone name canonicalizes', () => {
for (const name of MIA_JOINTS) {
expect(canonicalizeBoneName(name), name).not.toBeNull();
}
});
it('the worker skeleton covers the canonical bone set completely', () => {
const mapped = new Set(MIA_JOINTS.map((n) => canonicalizeBoneName(n)));
for (const bone of CANONICAL_BONES) {
expect(mapped.has(bone), bone).toBe(true);
}
expect(mapped.size).toBe(CANONICAL_BONES.length);
});
it('a worker-shaped GLB rewrites to canonical names in place', () => {
const nodes = MIA_JOINTS.map((name, i) => ({
name,
translation: [0, i * 0.01, 0],
}));
// Chain children linearly; the canonicalizer only needs skins[].joints.
const json = {
asset: { version: '2.0' },
scenes: [{ nodes: [0] }],
scene: 0,
nodes,
skins: [{ joints: nodes.map((_, i) => i) }],
};
const out = canonicalizeGLBBones(buildGLB(json));
expect(out.renamed).toBe(MIA_JOINTS.length);
const after = readGLBJson(out.buffer);
const names = after.nodes.map((n) => n.name);
for (const bone of CANONICAL_BONES) {
expect(names).toContain(bone);
}
});
});
describe('non-humanoid rig (UniRig / SkinTokens / AniGen output)', () => {
// workers/rig-nonhuman (UniRig skeleton prediction + SkinTokens skinning)
// and workers/model-anigen both predict a skeleton for arbitrary topology
// (a quadruped, a prop, a creature), so their joints carry opaque,
// autogenerated names with no anatomical meaning (`bone_0`, `bone_1`, ...)
// rather than Mixamo-style spellings. canonicalizeBoneName correctly
// returns null for every one of them (there is no canonical target for a
// name that means nothing), so the full-GLB rewrite must leave the names
// untouched rather than corrupt them into a false match, and the mesh
// must still be a valid, drivable-by-its-own-skeleton GLB afterward: the
// non-humanoid fallback exists precisely because the canonical Mixamo set
// cannot describe a six-legged creature, so unmapped bones here are the
// correct outcome, not a bug.
const NONHUMANOID_JOINTS = Array.from({ length: 12 }, (_, i) => `bone_${i}`);
it('opaque autogenerated joint names do not canonicalize to anything', () => {
for (const name of NONHUMANOID_JOINTS) {
expect(canonicalizeBoneName(name), name).toBeNull();
}
});
it('a non-humanoid GLB round-trips unchanged (renamed: 0, same buffer)', () => {
const nodes = NONHUMANOID_JOINTS.map((name, i) => ({
name,
translation: [0, i * 0.01, 0],
}));
const json = {
asset: { version: '2.0' },
scenes: [{ nodes: [0] }],
scene: 0,
nodes,
skins: [{ joints: nodes.map((_, i) => i) }],
};
const bin = new Uint8Array(32);
for (let i = 0; i < bin.length; i++) bin[i] = (i * 5 + 1) & 0xff;
const ab = buildGLB(json, bin);
const out = canonicalizeGLBBones(ab);
expect(out.renamed).toBe(0);
expect(out.samples).toEqual([]);
// No rename and no orientation fix means the original buffer comes back
// by reference, so a caller correctly skips a redundant re-upload.
expect(out.buffer).toBe(ab);
const after = readGLBJson(out.buffer);
expect(after.nodes.map((n) => n.name)).toEqual(NONHUMANOID_JOINTS);
});
it('mixed real limb names alongside opaque ones only rename the real ones', () => {
// A hybrid skeleton (e.g. a predicted skeleton that happens to label a
// root/spine chain conventionally but leaves auxiliary limbs opaque)
// must canonicalize the recognizable joints and leave the rest intact.
const nodes = [
{ name: 'Hips', children: [1] },
{ name: 'Spine' },
{ name: 'bone_0' },
{ name: 'bone_1' },
{ name: 'bone_2' },
];
const json = {
asset: { version: '2.0' },
scenes: [{ nodes: [0] }],
scene: 0,
nodes,
skins: [{ joints: [0, 1, 2, 3, 4] }],
};
const out = canonicalizeGLBBones(buildGLB(json));
expect(out.renamed).toBe(0);
const after = readGLBJson(out.buffer);
expect(after.nodes.map((n) => n.name)).toEqual(['Hips', 'Spine', 'bone_0', 'bone_1', 'bone_2']);
});
});