Skip to content

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.

fix(animation): re-aim limb rest direction so A-pose rigs stop clipping through the torso

nirholas8561d5c5dc93
diff --git a/src/animation-manager.js b/src/animation-manager.js
index 36ccbfc92..0941eac36 100644
--- a/src/animation-manager.js
+++ b/src/animation-manager.js
@@ -11,6 +11,7 @@ import {
import { canonicalizeBoneName } from './glb-canonicalize.js';
import {
canonicalNodeMapFromObject,
+ canonicalRestDirectionMapFromObject,
canonicalRestMapFromObject,
canonicalWorldRestMapFromObject,
clipHipBaselineY,
@@ -212,6 +213,11 @@ export class AnimationManager {
// skews an A-pose clip's limbs ~30° on a T-pose rig. Matches the server
// (retargetClipToObject) and rig (retargetClipToRig) paths.
this._canonicalWorldRest = canonicalWorldRestMapFromObject(model);
+ // Rest direction of each upper arm, forearm, thigh and shin. A rig that
+ // rests in an A-pose (or with splayed legs) is re-aimed onto the clips'
+ // T-pose stance before the motion replays, so the idle's arm drop lands
+ // the arms at the sides instead of through the torso.
+ this._canonicalRestDirections = canonicalRestDirectionMapFromObject(model);
// World rotation of the Hips' parent (within the model), so root motion is
// re-expressed in the rig's own frame and travels the right way on any rig.
this._hipsParentWorldQuat = hipsParentWorldQuat(model);
@@ -316,6 +322,7 @@ export class AnimationManager {
const { clip: out } = retargetClip(clip, this._canonicalToNode, {
targetRest: this._canonicalRest,
targetWorldRest: this._canonicalWorldRest,
+ targetRestDirections: this._canonicalRestDirections,
hipsParentWorldQuat: this._hipsParentWorldQuat,
morphTargets: this._morphTargets,
hipScale,
@@ -392,6 +399,7 @@ export class AnimationManager {
this._canonicalToNode = null;
this._canonicalRest = null;
this._canonicalWorldRest = null;
+ this._canonicalRestDirections = null;
this._hipsParentWorldQuat = null;
this._morphTargets = null;
this._hipTargetLocalY = 0;
diff --git a/src/animation-retarget.js b/src/animation-retarget.js
index 50d96492c..c5e0b1f18 100644
--- a/src/animation-retarget.js
+++ b/src/animation-retarget.js
@@ -19,7 +19,12 @@
import { AnimationClip, Box3, Quaternion, Vector3 } from 'three';
import { canonicalizeBoneName, resolveArmShoulderCollisions } from './glb-canonicalize.js';
-import { CANONICAL_REST, CANONICAL_REST_WORLD } from './animation-canonical-rest.js';
+import {
+ CANONICAL_PARENT,
+ CANONICAL_REST,
+ CANONICAL_REST_POSITION,
+ CANONICAL_REST_WORLD,
+} from './animation-canonical-rest.js';
// A clip retargets cleanly only when enough of its tracks find a home on the
// target rig. Below this the motion would read as a few twitching joints rather
@@ -60,6 +65,65 @@ const SOURCE_WORLD_REST = new Map(
// rig that already matches the authoring convention round-trips bit-for-bit.
const BIND_EPSILON = 1e-6;
+// Limb bones whose REST DIRECTION is re-aimed onto the authoring rig's before a
+// clip plays, keyed to the canonical child that defines the bone's direction.
+//
+// Preserving a bone's world delta from rest (see `bindCorrections`) is only
+// right when the target rests in the same stance as the authoring rig. cz rests
+// in a T-pose, and the idle swings its upper arm about 73° down from there. A
+// rig that rests in an A-pose with bent elbows (the MakeHuman-derived Parametric
+// base, the selfie-girl Avatar Studio body) received the same 73° on top of an
+// arm that already hung 50° down, which drove the arm through the torso and left
+// the hand floating in front of the chest. Splayed hips got the idle's stance
+// added to a stance that was already wide. So each listed bone first turns, in
+// the rig's own world frame, from its rest direction onto the authoring rig's,
+// and the clip's delta is replayed from there. A T-pose rig turns by a few
+// degrees at most; cz itself turns by nothing and still round-trips unchanged.
+//
+// Every other bone inherits its parent's turn, so a hand stays rigid with its
+// forearm and fingers with their hand. The spine, neck, head and clavicles are
+// left alone: their rest angles are anatomy, not a stance convention.
+const LIMB_DIRECTION_CHILD = Object.freeze({
+ LeftArm: 'LeftForeArm',
+ LeftForeArm: 'LeftHand',
+ RightArm: 'RightForeArm',
+ RightForeArm: 'RightHand',
+ LeftUpLeg: 'LeftLeg',
+ LeftLeg: 'LeftFoot',
+ RightUpLeg: 'RightLeg',
+ RightLeg: 'RightFoot',
+});
+
+// Feet keep their own world rest instead of inheriting the leg's turn: a sole
+// that is flat on the floor at rest has to stay flat, whatever angle the shin
+// was re-aimed by. Toes inherit from the foot, so they stay put too.
+const WORLD_REST_BONES = new Set(['LeftFoot', 'RightFoot']);
+
+// Below this dot product the two rest directions differ enough to turn the bone
+// (about 0.08°). Anything closer is measurement noise between two exports of the
+// same skeleton and is treated as already aligned.
+const ALIGN_DOT = 1 - 1e-6;
+
+// Authoring rig's rest direction for each re-aimed limb bone, in cz's model frame.
+const SOURCE_REST_DIRECTION = new Map();
+for (const [bone, child] of Object.entries(LIMB_DIRECTION_CHILD)) {
+ const a = CANONICAL_REST_POSITION[bone];
+ const b = CANONICAL_REST_POSITION[child];
+ if (!a || !b) continue;
+ const dir = new Vector3(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+ if (dir.lengthSq() > 1e-12) SOURCE_REST_DIRECTION.set(bone, dir.normalize());
+}
+
+// Canonical bones parents-first, so a bone's turn can build on its parent's.
+const CANONICAL_TOPO_ORDER = (() => {
+ const depth = (bone) => {
+ let d = 0;
+ for (let p = CANONICAL_PARENT[bone]; p; p = CANONICAL_PARENT[p]) d++;
+ return d;
+ };
+ return Object.keys(CANONICAL_REST).sort((a, b) => depth(a) - depth(b));
+})();
+
// Track property prefix for a blendshape lane, e.g.
// `Face.morphTargetInfluences[browInnerUp]`.
const MORPH_PROPERTY = 'morphTargetInfluences[';
@@ -251,6 +315,93 @@ export function canonicalWorldRestMapFromRig(rig) {
return map;
}
+// Unit direction from each re-aimed limb bone to its canonical child, given a
+// canonical → node map and a function that reads a node's position in the frame
+// the world rest rotations were measured in. Bones whose child is missing, or
+// sits on top of them, are left out and simply inherit their parent's turn.
+function restDirectionMap(nodes, positionOf) {
+ const map = new Map();
+ for (const [bone, child] of Object.entries(LIMB_DIRECTION_CHILD)) {
+ const a = nodes.get(bone);
+ const b = nodes.get(child);
+ if (!a || !b) continue;
+ const dir = positionOf(b).sub(positionOf(a));
+ if (dir.lengthSq() > 1e-12) map.set(bone, dir.normalize());
+ }
+ return map;
+}
+
+/**
+ * Rest direction of each limb bone (upper arm, forearm, thigh, shin) toward its
+ * canonical child, in the same within-model frame as
+ * {@link canonicalWorldRestMapFromObject}. The retargeter uses it to re-aim an
+ * A-posed or splay-legged rig onto the authoring rig's stance before replaying a
+ * clip (see LIMB_DIRECTION_CHILD). Call while the model is in its bind pose.
+ *
+ * @param {import('three').Object3D} root
+ * @returns {Map<string,import('three').Vector3>}
+ */
+export function canonicalRestDirectionMapFromObject(root) {
+ if (!root?.traverse) return new Map();
+ root.updateMatrixWorld(true);
+ const nodes = canonicalBoneNodesFromObject(root);
+ return restDirectionMap(nodes, (node) => root.worldToLocal(node.getWorldPosition(new Vector3())));
+}
+
+/**
+ * Rest-direction map from a GltfRig/MannequinRig, in world space to match
+ * {@link canonicalWorldRestMapFromRig}.
+ *
+ * @param {{ getBones: () => Array<{key:string,node:import('three').Object3D}> }} rig
+ * @returns {Map<string,import('three').Vector3>}
+ */
+export function canonicalRestDirectionMapFromRig(rig) {
+ const nodes = new Map();
+ for (const { key, node } of rig.getBones?.() || []) {
+ if (node && !nodes.has(key)) nodes.set(key, node);
+ }
+ for (const node of nodes.values()) node.updateWorldMatrix(true, false);
+ return restDirectionMap(nodes, (node) => node.getWorldPosition(new Vector3()));
+}
+
+/**
+ * The world-frame turn that re-aims each canonical bone of the target from its
+ * own rest stance onto the authoring rig's (see LIMB_DIRECTION_CHILD). A limb
+ * bone turns by the shortest arc from its rest direction, already carried by
+ * its parent's turn, onto the authoring direction, so the elbow and knee only
+ * add the bend their parent did not already remove and no bone picks up a
+ * spurious twist. Feet keep their world rest; every other bone inherits its
+ * parent's turn. Only non-identity turns are returned.
+ *
+ * @param {Map<string,import('three').Vector3>|null} targetDirections
+ * @returns {Map<string,import('three').Quaternion>}
+ */
+export function restAlignments(targetDirections) {
+ const out = new Map();
+ if (!(targetDirections instanceof Map) || targetDirections.size === 0) return out;
+ const turn = new Map();
+ const dir = new Vector3();
+ for (const bone of CANONICAL_TOPO_ORDER) {
+ const parentTurn = turn.get(CANONICAL_PARENT[bone]) || null;
+ if (WORLD_REST_BONES.has(bone)) continue; // identity: the foot keeps its own rest
+ const target = targetDirections.get(bone);
+ const source = SOURCE_REST_DIRECTION.get(bone);
+ if (!target || !source) {
+ if (parentTurn) turn.set(bone, parentTurn);
+ continue;
+ }
+ dir.copy(target);
+ if (parentTurn) dir.applyQuaternion(parentTurn);
+ const own = dir.dot(source) > ALIGN_DOT ? null : new Quaternion().setFromUnitVectors(dir, source);
+ if (own && parentTurn) turn.set(bone, own.multiply(parentTurn));
+ else if (own || parentTurn) turn.set(bone, own || parentTurn);
+ }
+ for (const [bone, q] of turn) {
+ if (1 - Math.abs(q.w) >= BIND_EPSILON) out.set(bone, q);
+ }
+ return out;
+}
+
/**
* Map every blendshape name the target carries to the mesh nodes that own it, so
* a face lane authored once can be re-pointed at this avatar. Faces are commonly
@@ -288,6 +439,16 @@ export function morphTargetMapFromObject(root) {
* • the correct limb reframe for an A-pose clip on a T-pose rig, which a
* local-only `Rt·Rs⁻¹` premultiply skewed by ~30°.
*
+ * That world delta is only the right thing to replay when both rigs rest in the
+ * same stance. When the caller supplies the target's limb rest directions, each
+ * bone is first re-aimed onto the authoring stance by a world turn C (see
+ * {@link restAlignments}), which generalizes the correction to
+ *
+ * L = Rt · WT⁻¹ · Cp⁻¹ · WS · Rs⁻¹ R = WS⁻¹ · C · WT
+ *
+ * with Cp the turn of the bone's canonical parent. Without directions every C is
+ * identity and this is exactly the formula above.
+ *
* When world rests are unavailable we fall back to the prior local-only premultiply
* (`L = Rt·Rs⁻¹`, `R = I`) so callers that don't supply them still work. Bones whose
* correction is identity are omitted, so a matching rig skips the work and
@@ -295,12 +456,14 @@ export function morphTargetMapFromObject(root) {
*
* @param {Map<string,import('three').Quaternion>|null} targetRest target LOCAL bind
* @param {Map<string,import('three').Quaternion>|null} [targetWorldRest] target WORLD bind
+ * @param {Map<string,import('three').Vector3>|null} [targetDirections] target limb rest directions
* @returns {Map<string,{L:import('three').Quaternion,R:import('three').Quaternion|null}>}
*/
-function bindCorrections(targetRest, targetWorldRest) {
+function bindCorrections(targetRest, targetWorldRest, targetDirections) {
const out = new Map();
if (!(targetRest instanceof Map)) return out;
const haveWorld = targetWorldRest instanceof Map;
+ const turns = haveWorld ? restAlignments(targetDirections) : new Map();
for (const [canonical, Rs] of SOURCE_REST) {
const Rt = targetRest.get(canonical);
if (!Rt) continue;
@@ -309,13 +472,16 @@ function bindCorrections(targetRest, targetWorldRest) {
let L;
let R = null;
if (WS && WT) {
- // L = Rt · WT⁻¹ · WS · Rs⁻¹
- L = Rt.clone()
- .multiply(WT.clone().invert())
- .multiply(WS)
- .multiply(Rs.clone().invert());
- // R = WS⁻¹ · WT
- R = WS.clone().invert().multiply(WT);
+ const C = turns.get(canonical);
+ const Cp = turns.get(CANONICAL_PARENT[canonical]);
+ // L = Rt · WT⁻¹ · Cp⁻¹ · WS · Rs⁻¹
+ L = Rt.clone().multiply(WT.clone().invert());
+ if (Cp) L.multiply(Cp.clone().invert());
+ L.multiply(WS).multiply(Rs.clone().invert());
+ // R = WS⁻¹ · C · WT
+ R = WS.clone().invert();
+ if (C) R.multiply(C);
+ R.multiply(WT);
if (1 - Math.abs(R.w) < BIND_EPSILON) R = null; // identity post-factor
} else {
// Fallback: local-only premultiply (prior behaviour).
@@ -533,14 +699,18 @@ export function clipHipBaselineY(clip) {
*
* @param {AnimationClip} clip
* @param {Map<string,string>} canonicalToNode
- * @param {{ hipScale?: number, hipOffsetY?: number, minCoverage?: number, morphTargets?: Map<string,string[]> }} [opts]
+ * @param {{ hipScale?: number, hipOffsetY?: number, minCoverage?: number, morphTargets?: Map<string,string[]>, targetRest?: Map<string,import('three').Quaternion>, targetWorldRest?: Map<string,import('three').Quaternion>, targetRestDirections?: Map<string,import('three').Vector3>, hipsParentWorldQuat?: import('three').Quaternion }} [opts]
* @returns {RetargetResult}
*/
export function retargetClip(clip, canonicalToNode, opts = {}) {
const hipScale = Number.isFinite(opts.hipScale) && opts.hipScale > 0 ? opts.hipScale : 1;
const hipOffsetY = Number.isFinite(opts.hipOffsetY) ? opts.hipOffsetY : 0;
const minCoverage = opts.minCoverage ?? MIN_COVERAGE;
- const corrections = bindCorrections(opts.targetRest, opts.targetWorldRest);
+ const corrections = bindCorrections(
+ opts.targetRest,
+ opts.targetWorldRest,
+ opts.targetRestDirections,
+ );
const hipsPosCorrection = hipPositionCorrection(opts.hipsParentWorldQuat, corrections);
const dropped = [];
const tracks = [];
@@ -705,11 +875,14 @@ export function retargetClipToObject(clip, root, opts = {}) {
const map = canonicalNodeMapFromObject(root);
const targetRest = opts.targetRest || canonicalRestMapFromObject(root);
const targetWorldRest = opts.targetWorldRest || canonicalWorldRestMapFromObject(root);
+ const targetRestDirections =
+ opts.targetRestDirections || canonicalRestDirectionMapFromObject(root);
const hipsParentWorld = opts.hipsParentWorldQuat || hipsParentWorldQuat(root);
return retargetClip(clip, map, {
...opts,
targetRest,
targetWorldRest,
+ targetRestDirections,
hipsParentWorldQuat: hipsParentWorld,
morphTargets: opts.morphTargets ?? morphTargetMapFromObject(root),
});