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
/**
* Bind-pose neutralisation before export: unit tests.
*
* Builds a skinned humanoid whose bind pose is a symmetric A-pose, poses it away
* from that bind the way a playing idle clip would, and asserts:
* - posing to bind restores the exact bind transforms (this is the regression
* guard: exported rest pose must equal the pose the mesh was skinned against);
* - the restored pose is symmetric, which a frozen animation frame is not;
* - a skeleton shared by several primitives is posed once, not once per mesh;
* - capture/restore round-trips so the live scene survives an export;
* - malformed and skeleton-free graphs are safe no-ops.
*/
import { describe, it, expect } from 'vitest';
import { Bone, Object3D, Skeleton, SkinnedMesh, BufferGeometry, Matrix4 } from 'three';
import {
poseSkeletonsToBind,
captureBoneTransforms,
restoreBoneTransforms,
} from '../src/glb-bind-pose.js';
// Symmetric A-pose humanoid: hips → (spine → each arm) + each leg. Mirrors the
// shape of the real parametric base, where left/right offsets are exact mirrors.
function makeRig() {
const root = new Object3D();
const hips = Object.assign(new Bone(), { name: 'Hips' });
hips.position.set(0, 0.92, 0);
root.add(hips);
const spine = Object.assign(new Bone(), { name: 'Spine' });
spine.position.set(0, 0.11, 0);
hips.add(spine);
const bones = [hips, spine];
for (const side of ['Left', 'Right']) {
const dir = side === 'Left' ? 1 : -1;
const arm = Object.assign(new Bone(), { name: `${side}Arm` });
arm.position.set(dir * 0.17, 0.29, 0);
spine.add(arm);
const hand = Object.assign(new Bone(), { name: `${side}Hand` });
// Down-and-out: the A-pose the base body is authored in.
hand.position.set(dir * 0.21, -0.35, 0);
arm.add(hand);
const leg = Object.assign(new Bone(), { name: `${side}UpLeg` });
leg.position.set(dir * 0.11, -0.05, 0);
hips.add(leg);
const foot = Object.assign(new Bone(), { name: `${side}Foot` });
foot.position.set(dir * 0.09, -0.8, 0);
leg.add(foot);
bones.push(arm, hand, leg, foot);
}
root.updateMatrixWorld(true);
// Bind the skeleton while the rig sits in that A-pose, so the inverse bind
// matrices describe exactly this stance.
const boneInverses = bones.map((b) => new Matrix4().copy(b.matrixWorld).invert());
const skeleton = new Skeleton(bones, boneInverses);
return { root, hips, skeleton, bones };
}
function skinnedMesh(skeleton, root) {
const mesh = new SkinnedMesh(new BufferGeometry());
root.add(mesh);
mesh.bind(skeleton, new Matrix4());
return mesh;
}
// World-space distance between two bones, which is what the pose actually looks
// like and is invariant to where the rig sits in the scene.
function dist(root, a, b) {
root.updateMatrixWorld(true);
return a.getWorldPosition(new (a.position.constructor)()).distanceTo(
b.getWorldPosition(new (b.position.constructor)()),
);
}
const byName = (bones, name) => bones.find((b) => b.name === name);
describe('poseSkeletonsToBind', () => {
it('restores the exact bind pose after an animation-style pose', () => {
const { root, skeleton, bones } = makeRig();
skinnedMesh(skeleton, root);
const bindLocals = bones.map((b) => b.position.toArray().concat(b.quaternion.toArray()));
// Pose it away from bind the way a mid-idle frame does: arms swung in,
// asymmetrically, plus a hip weight shift.
byName(bones, 'LeftArm').rotation.z = 0.7;
byName(bones, 'RightArm').rotation.z = -0.45;
byName(bones, 'Hips').position.x = 0.04;
root.updateMatrixWorld(true);
expect(poseSkeletonsToBind(root)).toBe(1);
bones.forEach((b, i) => {
const now = b.position.toArray().concat(b.quaternion.toArray());
now.forEach((v, k) => expect(v).toBeCloseTo(bindLocals[i][k], 6));
});
});
it('leaves the rig symmetric, unlike the frozen frame it replaces', () => {
const { root, skeleton, bones } = makeRig();
skinnedMesh(skeleton, root);
const hips = byName(bones, 'Hips');
const lh = byName(bones, 'LeftHand');
const rh = byName(bones, 'RightHand');
byName(bones, 'LeftArm').rotation.z = 0.7;
byName(bones, 'RightArm').rotation.z = -0.45;
root.updateMatrixWorld(true);
const posedAsymmetry = Math.abs(dist(root, hips, lh) - dist(root, hips, rh));
expect(posedAsymmetry).toBeGreaterThan(0.01);
poseSkeletonsToBind(root);
expect(Math.abs(dist(root, hips, lh) - dist(root, hips, rh))).toBeCloseTo(0, 6);
});
it('poses a shared skeleton once, not once per primitive', () => {
const { root, skeleton } = makeRig();
// The real base body carries body + eyes + teeth + tongue on one skeleton.
skinnedMesh(skeleton, root);
skinnedMesh(skeleton, root);
skinnedMesh(skeleton, root);
expect(poseSkeletonsToBind(root)).toBe(1);
});
it('is a no-op on a graph with no skinned meshes', () => {
const root = new Object3D();
root.add(new Object3D());
expect(poseSkeletonsToBind(root)).toBe(0);
});
it('skips a skeleton whose inverse-bind count does not match its bones', () => {
const { root, skeleton, bones } = makeRig();
skinnedMesh(skeleton, root);
skeleton.boneInverses.pop();
const before = bones.map((b) => b.position.toArray());
expect(poseSkeletonsToBind(root)).toBe(0);
bones.forEach((b, i) => expect(b.position.toArray()).toEqual(before[i]));
});
it('tolerates a null root', () => {
expect(poseSkeletonsToBind(null)).toBe(0);
});
});
describe('captureBoneTransforms / restoreBoneTransforms', () => {
it('round-trips the live pose so the scene survives an export', () => {
const { root, skeleton, bones } = makeRig();
skinnedMesh(skeleton, root);
byName(bones, 'LeftArm').rotation.z = 0.7;
byName(bones, 'Hips').position.x = 0.04;
root.updateMatrixWorld(true);
const posed = bones.map((b) => b.position.toArray().concat(b.quaternion.toArray()));
const saved = captureBoneTransforms(root);
expect(saved).toHaveLength(bones.length);
poseSkeletonsToBind(root);
expect(restoreBoneTransforms(saved, root)).toBe(bones.length);
bones.forEach((b, i) => {
const now = b.position.toArray().concat(b.quaternion.toArray());
now.forEach((v, k) => expect(v).toBeCloseTo(posed[i][k], 6));
});
});
it('tolerates empty and malformed input', () => {
expect(captureBoneTransforms(null)).toEqual([]);
expect(restoreBoneTransforms(null)).toBe(0);
expect(restoreBoneTransforms([null])).toBe(1);
});
});