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.

42.6 KB
Raw Blame
// Runtime animation retargeting — apply a canonical-skeleton clip to an
// arbitrary rigged model whose bones may be named differently (Mixamo, Blender,
// Rigify, snake_case, …) and proportioned differently (tall, short, chunky).
//
// The pre-baked library in /public/animations/clips addresses tracks by the
// canonical Avaturn bone names (Hips, Spine, LeftArm, …). A loaded GLB rig might
// name the same bones `mixamorig:Hips`, `DEF-spine`, `left_arm`, etc. To drive
// (and export) that rig we rewrite each track's bone name to the *actual* node
// name on the target, drop tracks the rig has no bone for, and rescale the hip
// translation so root motion lands at the new rig's height instead of the
// authoring rig's. We retarget only the true-motion channels — joint rotations
// and the root (Hips) translation — and skip the clips' per-bone position/scale
// channels, which encode the *authoring* rig's bone lengths and would crush a
// differently-proportioned avatar into a heap. The result binds cleanly in both
// THREE.AnimationMixer (preview) and THREE.GLTFExporter (animated-GLB export).
//
// Pure module — three + the canonicalizer only — so it runs unchanged in the
// browser (the /pose gallery) and in Node (the apply_animation MCP tool, vitest).

import { AnimationClip, Box3, Quaternion, Vector3 } from 'three';
import { canonicalizeBoneName, resolveArmShoulderCollisions } from './glb-canonicalize.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
// than a performance, so callers surface an actionable "can't retarget" error.
export const MIN_COVERAGE = 0.5;

// Rest (bind-pose) local rotation of each canonical bone *on the authoring rig*
// the clips were baked against (the Avaturn-rigged public/avatars/cz.glb). The
// library stores absolute local rotations, so a clip only looks right when the
// target bone's rest matches the authoring rest — otherwise we must replay the
// motion in the target's own rest frame (see `bindCorrections`).
//
// The full skeleton is covered (generated from cz.glb into
// animation-canonical-rest.js), not just Hips. Hips carries the up-axis
// convention — Mixamo/FBX bake a +90°X on the armature and a −90°X on Hips, and
// copying the clip's Hips rotation verbatim wipes that out and tips the body onto
// its back. The limb bones carry the pose convention — cz rests in an A-pose,
// Mixamo in a T-pose — so without per-limb correction an upright avatar still
// plays clips with the arms/legs in the wrong frame. Because the values are cz's
// own rest, retargeting back onto cz yields an identity correction per bone
// (skipped below), so a matching rig round-trips byte-for-byte.
const SOURCE_REST = new Map(
	Object.entries(CANONICAL_REST).map(([bone, q]) => [bone, new Quaternion(q[0], q[1], q[2], q[3])]),
);

// World-space (model-frame) bind rotation of each canonical bone on the authoring
// rig. Paired with SOURCE_REST so the bind correction can preserve a clip bone's
// *world* motion delta (not just its local deviation) when the target rig rests
// in a different pose — see `bindCorrections`.
const SOURCE_WORLD_REST = new Map(
	Object.entries(CANONICAL_REST_WORLD).map(([bone, q]) => [
		bone,
		new Quaternion(q[0], q[1], q[2], q[3]),
	]),
);

// A quaternion within this of identity (|w| ≈ 1) is treated as no rotation, so a
// 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[';

const _v = new Vector3();
const _q = new Quaternion();

/**
 * @typedef {Object} RetargetResult
 * @property {AnimationClip|null} clip   Retargeted clip (track names rewritten to
 *   the target's bone names), or null when coverage is below MIN_COVERAGE.
 * @property {number} matched   Tracks successfully mapped onto the target.
 * @property {number} total     Tracks in the source clip.
 * @property {number} coverage  matched / total (0–1).
 * @property {string[]} dropped Canonical bone names the target rig lacks.
 * @property {number} hipScale  Factor applied to hip translation (1 = none).
 * @property {number} face      Blendshape lanes bound on the target (0 = no face).
 */

// Whether Object3D `a` is an ancestor of `b`. Feeds the hierarchy tie-break in
// resolveArmShoulderCollisions: the clavicle parents the upper arm.
function isAncestorObject(a, b) {
	for (let n = b?.parent; n; n = n.parent) if (n === a) return true;
	return false;
}

/**
 * Resolve every canonical bone the graph carries, in the order the maps below
 * read it: node-graph bones first, then skeleton bones some exporters name only
 * there. Each graph node is considered once, the clavicle/upper-arm collision is
 * resolved against the live hierarchy (see resolveArmShoulderCollisions), and
 * only then does first-wins pick one node per canonical name.
 *
 * Resolution has to happen BEFORE the first-wins claim: a Rigify rig lists
 * `shoulder.L` (the clavicle) ahead of `upper_arm.L` and both normalize onto
 * `LeftArm`, so claiming first would drop the upper arm before anything could
 * notice the two bones were fighting over one name.
 *
 * @param {import('three').Object3D} root
 * @returns {Array<{node: import('three').Object3D, raw: string, canonical: string}>}
 */
function canonicalBoneEntries(root) {
	const entries = [];
	const seen = new Set();
	const consider = (node) => {
		if (!node?.name || seen.has(node)) return;
		seen.add(node);
		const canonical = canonicalizeBoneName(node.name);
		if (canonical) entries.push({ node, raw: node.name, canonical });
	};
	const skinned = [];
	root.traverse((node) => {
		if (node.isSkinnedMesh) skinned.push(node);
		if (node.isBone) consider(node);
	});
	for (const sm of skinned) {
		for (const bone of sm.skeleton?.bones || []) consider(bone);
	}
	resolveArmShoulderCollisions(entries, {
		isAncestor: (a, b) => isAncestorObject(a.node, b.node),
	});
	const claimed = new Set();
	return entries.filter((e) => {
		if (claimed.has(e.canonical)) return false;
		claimed.add(e.canonical);
		return true;
	});
}

/**
 * Build a `canonical bone → target node name` map by walking an Object3D graph.
 * Used server-side (apply_animation) where there's no GltfRig wrapper. Prefers
 * SkinnedMesh skeleton bones, falls back to any named Bone nodes.
 *
 * @param {import('three').Object3D} root
 * @returns {Map<string,string>}
 */
export function canonicalNodeMapFromObject(root) {
	const map = new Map();
	for (const { canonical, node } of canonicalBoneEntries(root)) map.set(canonical, node.name);
	return map;
}

/**
 * Same walk as {@link canonicalNodeMapFromObject}, but keyed to the live nodes
 * rather than their names. Callers that need to *write* to the skeleton (the
 * skeleton-space proportion editor in src/avatar-proportions.js) need the node
 * itself; resolving by name afterwards would break on the duplicate bone names
 * a merged accessory or garment can introduce.
 *
 * @param {import('three').Object3D} root
 * @returns {Map<string,import('three').Object3D>}
 */
export function canonicalBoneNodesFromObject(root) {
	const map = new Map();
	if (!root?.traverse) return map;
	for (const { canonical, node } of canonicalBoneEntries(root)) map.set(canonical, node);
	return map;
}

/**
 * Build the same map from a GltfRig/MannequinRig (src/pose-rig.js), which has
 * already resolved canonical → node. We read each node's live `.name` so the
 * rewritten track binds to the real graph node.
 *
 * @param {{ getBones: () => Array<{key:string,node:import('three').Object3D}> }} rig
 * @returns {Map<string,string>}
 */
export function canonicalNodeMapFromRig(rig) {
	const map = new Map();
	for (const { key, node } of rig.getBones?.() || []) {
		if (node?.name) map.set(key, node.name);
	}
	return map;
}

/**
 * Capture each canonical bone's rest (bind-pose) local rotation by walking an
 * Object3D graph — the companion to {@link canonicalNodeMapFromObject}, read in
 * the same first-bone-wins order so the rest quaternion belongs to the very node
 * a track gets renamed onto. Call while the model is in its authored bind pose
 * (i.e. before any clip has been sampled), which is the case at attach time.
 *
 * @param {import('three').Object3D} root
 * @returns {Map<string,import('three').Quaternion>}
 */
export function canonicalRestMapFromObject(root) {
	const map = new Map();
	for (const { canonical, node } of canonicalBoneEntries(root)) {
		map.set(canonical, node.quaternion.clone());
	}
	return map;
}

/**
 * Rest-rotation map from a GltfRig/MannequinRig, mirroring
 * {@link canonicalNodeMapFromRig}.
 *
 * @param {{ getBones: () => Array<{key:string,node:import('three').Object3D}> }} rig
 * @returns {Map<string,import('three').Quaternion>}
 */
export function canonicalRestMapFromRig(rig) {
	const map = new Map();
	for (const { key, node } of rig.getBones?.() || []) {
		if (node && !map.has(key)) map.set(key, node.quaternion.clone());
	}
	return map;
}

// World (model-frame) bind rotation of a node: the pure-quaternion product of its
// ancestors' rotations down to `stopAt` (exclusive), times the node's own. Stops
// at the model root so a placement rotation the viewer applies to the whole avatar
// is excluded — the same frame SOURCE_WORLD_REST is measured in. Requires local
// rotations to be at bind pose (true at attach time).
function worldRestQuat(node, stopAt) {
	const q = node.quaternion.clone();
	for (let n = node.parent; n && n !== stopAt; n = n.parent) q.premultiply(n.quaternion);
	return q;
}

/**
 * World bind-rotation map by walking an Object3D graph — the world-frame companion
 * to {@link canonicalRestMapFromObject}, read in the same first-bone-wins order.
 * Excludes `root` so it matches {@link hipsParentWorldQuat}'s within-model frame.
 *
 * @param {import('three').Object3D} root
 * @returns {Map<string,import('three').Quaternion>}
 */
export function canonicalWorldRestMapFromObject(root) {
	const map = new Map();
	for (const { canonical, node } of canonicalBoneEntries(root)) {
		map.set(canonical, worldRestQuat(node, root));
	}
	return map;
}

/**
 * World bind-rotation map from a GltfRig/MannequinRig. The rig is posed at the
 * origin (within-model == world), so we compose all the way to the top.
 *
 * @param {{ getBones: () => Array<{key:string,node:import('three').Object3D}> }} rig
 * @returns {Map<string,import('three').Quaternion>}
 */
export function canonicalWorldRestMapFromRig(rig) {
	const map = new Map();
	for (const { key, node } of rig.getBones?.() || []) {
		if (node && !map.has(key)) map.set(key, worldRestQuat(node, null));
	}
	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
 * split across several meshes (head, teeth, brows), and all of them need driving.
 *
 * @param {import('three').Object3D} root
 * @returns {Map<string,string[]>}
 */
export function morphTargetMapFromObject(root) {
	const map = new Map();
	root.traverse((node) => {
		if (!node?.morphTargetDictionary || !node.name) return;
		for (const shape of Object.keys(node.morphTargetDictionary)) {
			if (!map.has(shape)) map.set(shape, []);
			const meshes = map.get(shape);
			if (!meshes.includes(node.name)) meshes.push(node.name);
		}
	});
	return map;
}

/**
 * Per-bone bind correction `{L, R}` such that `q' = L · q · R` re-expresses a clip
 * bone's keyframe so it produces the SAME world-space rotation delta on a target
 * rig that rests in a different pose:
 *
 *   L = Rt · WT⁻¹ · WS · Rs⁻¹      R = WS⁻¹ · WT
 *
 * where Rs/Rt are the source/target LOCAL bind rotations and WS/WT their WORLD
 * (model-frame) bind rotations. This is the standard world-delta-preserving
 * retarget (trgLocal = WTp⁻¹·WSp · q · WS⁻¹·WT, with the parent worlds derived as
 * WSp = WS·Rs⁻¹, WTp = WT·Rt⁻¹). It collapses to:
 *   • the pure axis-convention reframe for the Hips (different parent frame, same
 *     world rest — e.g. a Mixamo Hips baked at −90°X), and
 *   • 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
 * round-trips unchanged.
 *
 * @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, 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;
		const WS = SOURCE_WORLD_REST.get(canonical);
		const WT = haveWorld ? targetWorldRest.get(canonical) : null;
		let L;
		let R = null;
		if (WS && 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).
			L = Rt.clone().multiply(Rs.clone().invert());
		}
		const identityL = 1 - Math.abs(L.w) < BIND_EPSILON;
		if (identityL && !R) continue; // nothing to do → round-trips unchanged
		out.set(canonical, { L: identityL ? null : L, R });
	}
	return out;
}

// Apply the bind correction `q ← L · q · R` to every [x,y,z,w] keyframe in place.
// Either factor may be null (identity).
function correctQuaternionTrack(values, { L, R }) {
	for (let i = 0; i < values.length; i += 4) {
		_q.set(values[i], values[i + 1], values[i + 2], values[i + 3]);
		if (L) _q.premultiply(L);
		if (R) _q.multiply(R);
		values[i] = _q.x;
		values[i + 1] = _q.y;
		values[i + 2] = _q.z;
		values[i + 3] = _q.w;
	}
}

// Rotate every [x,y,z] keyframe of a position track by `c` in place, so root
// motion stays aligned once the parent armature's axis convention is corrected.
function rotateVectorTrack(values, c) {
	for (let i = 0; i < values.length; i += 3) {
		_v.set(values[i], values[i + 1], values[i + 2]).applyQuaternion(c);
		values[i] = _v.x;
		values[i + 1] = _v.y;
		values[i + 2] = _v.z;
	}
}

// Rotation to apply to the Hips position (root-motion) track. The clip authors
// hip translation in the authoring rig's hips-parent frame, whose world rotation
// is identity (cz's armature has none). To preserve world motion on the target,
// rotate by the inverse of the target's hips-parent world rotation. When the
// caller can't supply that (a bare retargetClip call), fall back to the Hips
// bone correction — exact for any rig whose hips are upright at bind, i.e. every
// real humanoid. Returns null when no rotation is needed.
function hipPositionCorrection(hipsParentWorldQuat, corrections) {
	if (hipsParentWorldQuat) {
		const q = hipsParentWorldQuat.isQuaternion
			? hipsParentWorldQuat.clone()
			: new Quaternion(
					hipsParentWorldQuat[0],
					hipsParentWorldQuat[1],
					hipsParentWorldQuat[2],
					hipsParentWorldQuat[3],
				);
		q.invert();
		return 1 - Math.abs(q.w) < BIND_EPSILON ? null : q;
	}
	// Fallback: the Hips correction's premultiply (parent-frame) factor, which for
	// the Hips carries the axis-convention reframe (its post-factor is identity
	// when source and target share a world rest).
	return corrections.get('Hips')?.L || null;
}

/**
 * World rotation of the target Hips' parent, measured *within the model* (i.e.
 * relative to `root`, so a placement rotation the viewer applies to the whole
 * avatar is excluded). Inverting it lets {@link retargetClip} re-express a clip's
 * authored hip translation in the target's hips-parent frame, so root motion
 * travels the same world direction on a Mixamo `+90°X` armature, an RPM rig, etc.
 * Requires the graph's local rotations to be at bind pose (true at attach time).
 *
 * @param {import('three').Object3D} root
 * @returns {import('three').Quaternion|null}
 */
export function hipsParentWorldQuat(root) {
	let hips = null;
	root.traverse((n) => {
		if (!hips && n.isBone && n.name && canonicalizeBoneName(n.name) === 'Hips') hips = n;
	});
	if (!hips) {
		root.traverse((n) => {
			if (!hips && n.name && canonicalizeBoneName(n.name) === 'Hips') hips = n;
		});
	}
	if (!hips || !hips.parent) return null;
	const q = new Quaternion();
	for (let n = hips.parent; n && n !== root; n = n.parent) q.premultiply(n.quaternion);
	return q;
}

/**
 * World-space rest height of the target's hips, used to scale root translation
 * onto a differently-sized rig. Returns 0 if it can't be determined (callers
 * then skip hip scaling). Requires world matrices to be current.
 *
 * @param {{ getNode: (k:string) => import('three').Object3D|null }} rig
 * @returns {number}
 */
export function hipRestHeight(rig) {
	const hips = rig.getNode?.('Hips');
	if (!hips) return 0;
	hips.updateWorldMatrix(true, false);
	hips.getWorldPosition(_v);
	return _v.y;
}

// Bounding-box bottom of the model, or NaN when it can't be computed. Guarded:
// three's pose-aware SkinnedMesh.computeBoundingBox walks skin attributes per
// vertex and throws on synthetic rigs whose geometry lacks them; a rig we can't
// measure just keeps the pre-floor behavior instead of failing the mount.
function safeFloorY(root) {
	try {
		return new Box3().setFromObject(root).min.y;
	} catch {
		return NaN;
	}
}

const _hipScalePos = new Vector3();
const _hipScaleQuat = new Quaternion();
const _hipScaleScale = new Vector3();

/**
 * Rest height of an Object3D rig's Hips expressed in the *hips-parent's local
 * units*, i.e. world height divided by the parent's accumulated world scale.
 * Hip-position tracks are authored in metres and set the Hips bone's *local*
 * position, so the scale factor that lands them at the right place is this local
 * height ÷ the clip's authored baseline — not the world height. The two agree
 * for a metre-native rig (parent scale ≈ 1) but diverge hard for a centimetre
 * rig (e.g. a Mixamo armature exported at `scale 0.01`, whose Hips local sits
 * near −100): matching world heights there would collapse the hip track to ~1cm
 * of motion and sink the avatar a metre into the floor. Returns 0 when the hips
 * or a usable parent scale can't be determined (caller then skips hip scaling).
 *
 * @param {import('three').Object3D} root
 * @returns {number}
 */
export function hipRestLocalHeight(root) {
	let hips = null;
	root.traverse((n) => {
		if (!hips && n.isBone && n.name && canonicalizeBoneName(n.name) === 'Hips') hips = n;
	});
	if (!hips) {
		root.traverse((n) => {
			if (!hips && n.name && canonicalizeBoneName(n.name) === 'Hips') hips = n;
		});
	}
	if (!hips || !hips.parent) return 0;
	hips.updateWorldMatrix(true, false);
	hips.getWorldPosition(_hipScalePos);
	let worldY = _hipScalePos.y;
	// Measure above the model's own floor (its bounding-box bottom), not above
	// world y=0. Viewers recenter content around the origin (setContent
	// subtracts the bbox center) and origin-centered GLB exports put the floor
	// below zero; measured from world zero, both read as "hips at or below the
	// ground", which skipped scaling and let the metre-authored hip track fling
	// a small rig into the air. Clips author ground at 0, so hips-above-floor
	// is the like-for-like height. For a ground-native rig floorY is 0 and
	// nothing changes.
	const floorY = safeFloorY(root);
	if (Number.isFinite(floorY)) worldY -= floorY;
	hips.parent.matrixWorld.decompose(_hipScalePos, _hipScaleQuat, _hipScaleScale);
	const parentScale = (_hipScaleScale.x + _hipScaleScale.y + _hipScaleScale.z) / 3;
	if (!(parentScale > 1e-6) || !(worldY > 0) || !Number.isFinite(worldY)) return 0;
	return worldY / parentScale;
}

/**
 * The model's floor (bounding-box bottom) expressed in the hips-parent's local
 * frame — the Y a hip-position track must be offset by so the clip's ground
 * (authored at 0) lands on this rig's actual ground. 0 for a ground-native rig
 * (floor at local 0); negative for an origin-centered export (floor below the
 * local origin). Returns 0 when it can't be determined, which leaves the
 * retarget exactly as before.
 *
 * @param {import('three').Object3D} root
 * @returns {number}
 */
export function hipGroundLocalY(root) {
	let hips = null;
	root.traverse((n) => {
		if (!hips && n.isBone && n.name && canonicalizeBoneName(n.name) === 'Hips') hips = n;
	});
	if (!hips) {
		root.traverse((n) => {
			if (!hips && n.name && canonicalizeBoneName(n.name) === 'Hips') hips = n;
		});
	}
	if (!hips || !hips.parent) return 0;
	hips.updateWorldMatrix(true, false);
	const floorY = safeFloorY(root);
	if (!Number.isFinite(floorY)) return 0;
	hips.getWorldPosition(_hipScalePos);
	// The floor point under the hips, mapped into the parent's local frame so
	// the offset composes with the track's local-position values.
	const local = hips.parent.worldToLocal(new Vector3(_hipScalePos.x, floorY, _hipScalePos.z));
	return Number.isFinite(local.y) ? local.y : 0;
}

// First Y value of a `Hips.position` track — the height the clip's root motion
// was authored around. The retarget scales other-height rigs by target/source.
export function clipHipBaselineY(clip) {
	const track = clip.tracks.find(
		(t) =>
			t.name.endsWith('.position') && canonicalizeBoneName(t.name.split('.')[0]) === 'Hips',
	);
	if (!track || track.values.length < 3) return 0;
	return track.values[1]; // [x, y, z, …] — Y of the first keyframe
}

/**
 * Core rewrite. Splits each track into `bone.property`, canonicalizes the bone,
 * looks up the target's node name, and emits a renamed track. Hip position
 * tracks are scaled by `hipScale`. Returns null clip when coverage is too low.
 *
 * @param {AnimationClip} clip
 * @param {Map<string,string>} canonicalToNode
 * @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,
		opts.targetRestDirections,
	);
	const hipsPosCorrection = hipPositionCorrection(opts.hipsParentWorldQuat, corrections);
	const dropped = [];
	const tracks = [];
	const faceTracks = [];
	// Denominator counts only *retargetable* tracks (see below), so a clip baked
	// with per-bone position/scale channels still reports honest coverage.
	let total = 0;

	for (const track of clip.tracks) {
		const dot = track.name.indexOf('.');
		if (dot === -1) continue;
		const boneRaw = track.name.slice(0, dot);
		const property = track.name.slice(dot + 1);

		// Face (morph-target) lanes. Signing carries grammar on the face — raised
		// brows make a question, furrowed brows a wh-question — so a clip may drive
		// blendshapes as well as bones. They are authored against a placeholder node
		// (`Face.morphTargetInfluences[browInnerUp]`) and re-pointed here at whatever
		// mesh on THIS avatar owns that shape, because the mesh is named differently
		// on every rig and a face is often split across several. An avatar with no
		// such shape simply loses the lane: the sign still performs, just without the
		// marker. They never count toward bone coverage, so a face-less rig is not
		// judged to have failed the retarget.
		if (property.startsWith(MORPH_PROPERTY)) {
			const shape = property.slice(MORPH_PROPERTY.length, -1);
			const meshes = opts.morphTargets instanceof Map ? opts.morphTargets.get(shape) : null;
			if (!meshes?.length) {
				dropped.push(shape);
				continue;
			}
			for (const meshName of meshes) {
				const next = track.clone();
				next.name = `${meshName}.${property}`;
				faceTracks.push(next);
			}
			continue;
		}

		const canonical = canonicalizeBoneName(boneRaw) || boneRaw;

		// The clips are baked from cz with a full position/quaternion/scale channel
		// per bone. A bone's local scale and its local position (its fixed offset
		// from its parent — i.e. the skeleton's bone lengths) are *structure of the
		// authoring rig*, not motion. Rewriting them onto a differently-proportioned
		// or differently-scaled avatar overwrites that rig's own bone lengths with
		// cz's centimetre-vs-metre offsets and folds the whole skeleton into a heap —
		// even though every bone "matches", so coverage lies at 100%. Only joint
		// rotations and the root (Hips) translation are true motion; retarget those
		// and skip the structural channels so every rig keeps its own proportions.
		const retargetable =
			property === 'quaternion' || (property === 'position' && canonical === 'Hips');
		if (!retargetable) continue;

		total++;
		const nodeName = canonicalToNode.get(canonical);
		if (!nodeName) {
			dropped.push(canonical);
			continue;
		}
		const next = track.clone();
		next.name = `${nodeName}.${property}`;
		if (property === 'quaternion') {
			// Bind correction q ← L·q·R: replay the clip bone's motion as the same
			// world-space delta on the target's rest pose, so a clip authored for one
			// rest pose (cz's A-pose) drives a differently-rigged avatar (a Mixamo
			// T-pose, or a Hips baked at −90°X that would otherwise read as "lying
			// down") without skewing limbs.
			const correction = corrections.get(canonical);
			if (correction) correctQuaternionTrack(next.values, correction);
		} else {
			// Root motion (Hips.position): the clip authors hip translation in the
			// authoring rig's world-Y-up frame; re-express it in the target's
			// hips-parent frame so it travels the same world direction on any rig,
			// then scale for height.
			if (hipsPosCorrection) rotateVectorTrack(next.values, hipsPosCorrection);
			if (hipScale !== 1) {
				for (let i = 0; i < next.values.length; i++) next.values[i] *= hipScale;
			}
			// Land the clip's ground (authored at 0) on this rig's actual floor:
			// origin-centered exports keep their floor below the local origin, and
			// without this offset the scaled track still hovers the body a
			// floor-height above the mesh.
			if (hipOffsetY !== 0) {
				for (let i = 1; i < next.values.length; i += 3) next.values[i] += hipOffsetY;
			}
		}
		tracks.push(next);
	}

	const matched = tracks.length;
	const coverage = total > 0 ? matched / total : 0;
	if (coverage < minCoverage) {
		return { clip: null, matched, total, coverage, dropped, hipScale, face: 0 };
	}
	const out = clip.clone();
	out.tracks = [...tracks, ...faceTracks];
	return { clip: out, matched, total, coverage, dropped, hipScale, face: faceTracks.length };
}

/**
 * High-level: retarget a canonical clip onto a rig (GltfRig/MannequinRig),
 * computing hip scaling from the rig's actual proportions.
 *
 * The bind correction (and hip scaling) is measured from the rig's LIVE bone
 * transforms, so they must read the rig's true rest pose — not whatever pose a
 * previously-previewed clip left the bones in. A preview mixer leaves the bones
 * mid-animation after it stops, so without this the second clip a user plays is
 * retargeted against a garbage "rest" and its limbs skew by 60–90° (an avatar
 * that plays one clip fine, then plays the next with its arms stuck overhead).
 * We restore the rig to its bind pose first; the caller's mixer immediately
 * re-poses it on the next frame, so the reset is invisible. Aside from that
 * normalization the clip itself is not mutated.
 *
 * @param {AnimationClip} clip
 * @param {object} rig
 * @param {{ scaleHips?: boolean, minCoverage?: number }} [opts]
 * @returns {RetargetResult}
 */
export function retargetClipToRig(clip, rig, opts = {}) {
	rig.resetPose?.(); // read the bind pose, not a leftover preview pose
	const map = canonicalNodeMapFromRig(rig);
	const targetRest = canonicalRestMapFromRig(rig);
	const targetWorldRest = canonicalWorldRestMapFromRig(rig);
	// Same re-aim the viewer and server paths apply, so an A-posed rig previewed
	// or exported from the Animation Studio keeps its arms out of the torso.
	const targetRestDirections = canonicalRestDirectionMapFromRig(rig);
	let hipScale = 1;
	if (opts.scaleHips !== false) {
		const targetY = hipRestHeight(rig);
		const sourceY = clipHipBaselineY(clip);
		if (targetY > 0.05 && sourceY > 0.05) {
			// Clamp so a wildly off baseline (or a near-zero in-place clip) can't
			// fling the root metres away.
			hipScale = Math.min(5, Math.max(0.2, targetY / sourceY));
		}
	}
	// Walk the hips' ancestor chain to the top so root motion is corrected for the
	// rig's axis convention (the rig is posed at origin, so within-model == world).
	let hipsParent = null;
	const hipsNode = rig.getNode?.('Hips');
	if (hipsNode?.parent) {
		hipsParent = new Quaternion();
		for (let n = hipsNode.parent; n; n = n.parent) hipsParent.premultiply(n.quaternion);
	}
	return retargetClip(clip, map, {
		hipScale,
		minCoverage: opts.minCoverage,
		targetRest,
		targetWorldRest,
		targetRestDirections,
		hipsParentWorldQuat: hipsParent,
		morphTargets: opts.morphTargets ?? (rig.root ? morphTargetMapFromObject(rig.root) : undefined),
	});
}

/**
 * Retarget onto a raw Object3D graph (server-side apply_animation). No hip
 * scaling by default — the caller may pass an explicit factor.
 *
 * @param {AnimationClip} clip
 * @param {import('three').Object3D} root
 * @param {{ hipScale?: number, minCoverage?: number }} [opts]
 * @returns {RetargetResult}
 */
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),
	});
}

/**
 * Resample a clip's timing to play at `factor`× speed (1.8 turns a walk into a
 * run). Used so an exported GLB carries the tempo the user previewed, not just
 * a mixer timeScale that doesn't survive the file. Pure — returns a clone.
 *
 * @param {AnimationClip} clip
 * @param {number} factor  >1 faster, <1 slower
 * @returns {AnimationClip}
 */
export function scaleClipSpeed(clip, factor) {
	if (!(factor > 0) || factor === 1) return clip;
	const out = clip.clone();
	const inv = 1 / factor;
	for (const track of out.tracks) {
		for (let i = 0; i < track.times.length; i++) track.times[i] *= inv;
	}
	out.duration = clip.duration * inv;
	return out;
}

/**
 * Convenience: parse a clip from its three.js JSON (the on-disk clip format),
 * naming it. Centralised so browser and server load clips identically.
 *
 * @param {object} json
 * @param {string} name
 * @returns {AnimationClip}
 */
export function parseClipJSON(json, name) {
	const clip = AnimationClip.parse(json);
	if (name) clip.name = name;
	return clip;
}

/**
 * Cut a clip down to [startTime, endTime] (seconds, clamped to the clip's own
 * duration) and re-zero its times so the trimmed clip starts at 0. Used by
 * Animation Studio's trim handles before export/save so a generated or preset
 * clip can be shortened to the useful part without re-authoring it as
 * keyframes.
 *
 * Boundary samples are taken through each track's own interpolant (quaternion
 * tracks slerp, vector tracks lerp) rather than nearest-keyframe, so a cut that
 * lands between two keyframes still starts and ends on the exact pose the
 * player would have shown there.
 *
 * @param {AnimationClip} clip
 * @param {number} startTime
 * @param {number} endTime
 * @returns {AnimationClip}
 */
export function trimClip(clip, startTime, endTime) {
	const duration = clip.duration;
	const start = Math.max(0, Math.min(startTime, duration));
	const end = Math.max(start + 1 / 1000, Math.min(endTime, duration));
	if (start <= 1e-6 && end >= duration - 1e-6) return clip.clone();

	const out = clip.clone();
	for (let i = 0; i < out.tracks.length; i++) {
		const srcTrack = clip.tracks[i];
		const track = out.tracks[i];
		const itemSize = track.values.length / track.times.length;
		const interpolant = srcTrack.createInterpolant();

		const newTimes = [start];
		const newValues = Array.from(interpolant.evaluate(start));
		for (let t = 0; t < srcTrack.times.length; t++) {
			const time = srcTrack.times[t];
			if (time > start && time < end) {
				newTimes.push(time);
				const i0 = t * itemSize;
				for (let c = 0; c < itemSize; c++) newValues.push(srcTrack.values[i0 + c]);
			}
		}
		newTimes.push(end);
		newValues.push(...interpolant.evaluate(end));

		const ctor = track.constructor;
		out.tracks[i] = new ctor(
			track.name,
			newTimes.map((t) => t - start),
			newValues,
		);
	}
	out.duration = end - start;
	out.resetDuration();
	return out;
}

// Quaternion track names end in `.quaternion`; every other track this platform
// authors (`.position`, `.scale`) blends with plain per-component lerp.
const QUATERNION_TRACK_RE = /\.quaternion$/;

/**
 * Crossfade the tail of a clip into its own first pose so it loops without a
 * pop. Standard game-animation "loop blend": over the last `blendSeconds` of
 * the clip, each track's samples are interpolated (slerp for quaternion
 * tracks, lerp otherwise) toward the value the clip started with, weighted by
 * how far into the blend window the sample sits, so the last frame equals the
 * first frame exactly, and the approach is gradual rather than a jump cut.
 *
 * @param {AnimationClip} clip
 * @param {number} blendSeconds
 * @returns {AnimationClip}
 */
export function blendClipLoop(clip, blendSeconds) {
	const maxBlend = clip.duration / 2;
	const blend = Math.max(0, Math.min(blendSeconds, maxBlend));
	if (blend <= 1e-6) return clip.clone();

	const out = clip.clone();
	const blendStart = clip.duration - blend;
	const q1 = new Quaternion();
	const q2 = new Quaternion();

	for (let i = 0; i < out.tracks.length; i++) {
		const srcTrack = clip.tracks[i];
		const track = out.tracks[i];
		const isQuat = QUATERNION_TRACK_RE.test(track.name);
		const itemSize = track.values.length / track.times.length;
		const startValues = Array.from(srcTrack.createInterpolant().evaluate(0));

		for (let t = 0; t < track.times.length; t++) {
			const time = track.times[t];
			if (time < blendStart) continue;
			const weight = Math.min(1, (time - blendStart) / blend);
			const i0 = t * itemSize;
			if (isQuat) {
				q1.fromArray(track.values, i0);
				q2.fromArray(startValues, 0);
				q1.slerp(q2, weight).toArray(track.values, i0);
			} else {
				for (let c = 0; c < itemSize; c++) {
					const a = track.values[i0 + c];
					const b = startValues[c];
					track.values[i0 + c] = a + (b - a) * weight;
				}
			}
		}
	}
	return out;
}