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.

26.8 KB
Raw Blame
/**
 * Eidon Tracker POV IMU → canonical-skeleton AnimationClip.
 *
 * The Eidon AI release (huggingface.co/datasets/eidon-ai/tracker-pov-imu,
 * CC-BY-4.0) is 1,274 hours of people doing household chores wearing a
 * seven-sensor IMU harness: both hands, both forearms, both upper arms and the
 * chest, each streaming an orientation quaternion at 24 Hz. This module turns
 * one recording into a clip on the same canonical skeleton the rest of the
 * library uses (`public/animations/clips/*.json`), so a real person's arms
 * folding laundry or scrubbing a pan retarget onto any rigged avatar exactly
 * like a Mixamo preset does.
 *
 * Nothing about the harness geometry is documented beyond the slot list, so
 * every mounting parameter is measured from the recording itself. The
 * estimators and the facts they rest on (all verified against the data, see
 * docs/animations.md "Real chores from the Eidon IMU dataset"):
 *
 *   • Each quaternion rotates sensor coordinates into a shared z-up world frame
 *     (the world up vector is constant in every sensor's own frame; it is not
 *     when the inverse convention is assumed).
 *   • An arm segment's long axis in its sensor's frame is the direction gravity
 *     points while that arm hangs straight and still. Arms hang between tasks
 *     often enough that nearly every recording has a second or more of it.
 *   • The elbow only flexes forward, so the direction the forearm swings toward
 *     in the upper-arm sensor's frame is the upper arm's anterior side. That
 *     pins the upper arm's roll with no sign ambiguity.
 *   • People work palm-down, so the side of the forearm that faces up while
 *     the forearm is horizontal is its dorsal side. That pins the forearm's
 *     roll (average pronation becomes the rest pronation).
 *   • The forearms point away from the body while working, so their average
 *     horizontal direction in the chest sensor's frame is the wearer's
 *     forward. The chest unit's yaw on the strap
 *     varies between sessions, so forward cannot be a constant.
 *   • The wrist is expressed relative to its own average pose, because the
 *     hand unit sits on a glove and its mounting is the least consistent.
 *
 * Every estimate falls back to a population prior (`HARNESS_PRIOR`, measured
 * across 60 recordings from 5 contributors) when the recording does not
 * contain the motion the estimator needs, and the calibration reports which
 * fell back and how far each estimate sits from the prior, so the build can
 * rank recordings by how trustworthy their conversion is.
 */
import { Matrix4, Quaternion, Vector3 } from 'three';
import {
	CANONICAL_REST,
	CANONICAL_REST_POSITION,
	CANONICAL_REST_WORLD,
} from '../src/animation-canonical-rest.js';
import { compactClipJson } from './compact-clips.mjs';

export const SAMPLE_HZ = 24;

/** Body slot ids as the dataset numbers them. */
export const SLOT = Object.freeze({
	leftHand: 0,
	leftForeArm: 1,
	leftArm: 2,
	rightHand: 3,
	rightForeArm: 4,
	rightArm: 5,
	chest: 6,
});
export const SLOT_COUNT = 7;

/** Sensor axes in each sensor's own frame, averaged over 60 recordings. */
export const HARNESS_PRIOR = Object.freeze({
	distal: {
		[SLOT.leftArm]: [-0.11, 0.9, -0.42],
		[SLOT.rightArm]: [0.15, 0.89, -0.43],
		[SLOT.leftForeArm]: [-0.3, 0.88, -0.38],
		[SLOT.rightForeArm]: [0.29, 0.84, -0.45],
	},
	anterior: {
		[SLOT.leftArm]: [0.87, 0, 0.49],
		[SLOT.rightArm]: [-0.93, 0, 0.38],
	},
	dorsal: {
		[SLOT.leftForeArm]: [0.67, 0, 0.74],
		[SLOT.rightForeArm]: [-0.59, 0, 0.81],
	},
});

const SIDES = [
	{ key: 'left', arm: SLOT.leftArm, foreArm: SLOT.leftForeArm, hand: SLOT.leftHand, bones: ['LeftShoulder', 'LeftArm', 'LeftForeArm', 'LeftHand'] },
	{ key: 'right', arm: SLOT.rightArm, foreArm: SLOT.rightForeArm, hand: SLOT.rightHand, bones: ['RightShoulder', 'RightArm', 'RightForeArm', 'RightHand'] },
];

const WORLD_UP = new Vector3(0, 0, 1);
const CHAR_UP = new Vector3(0, 1, 0);
const CHAR_FORWARD = new Vector3(0, 0, 1);

/** How the chest's measured lean is distributed along the spine chain. */
const SPINE_SHARE = { Spine: 0.3, Spine1: 0.6, Spine2: 1 };

const DRIVEN_BONES = new Set([
	'Spine', 'Spine1', 'Spine2',
	'LeftArm', 'LeftForeArm', 'LeftHand',
	'RightArm', 'RightForeArm', 'RightHand',
]);

const STRAIGHT_ELBOW_DEG = 20;
const FLEXED_ELBOW_DEG = 25;
const STILL_RATE_DEG_PER_S = 40;
const MIN_ESTIMATE_FRAMES = SAMPLE_HZ;
const HORIZONTAL_COS = 0.5;
const PRIOR_DISAGREEMENT_DEG = 60;
const YAW_WINDOW_S = 5;

const DEG = 180 / Math.PI;

const v3 = (a) => new Vector3(a[0], a[1], a[2]);
const q4 = (a) => new Quaternion(a[0], a[1], a[2], a[3]);
const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));

/** Sign-aligned mean of unit quaternions, fine for the clustered rotations here. */
function meanQuaternion(quats) {
	const ref = quats[0];
	const acc = [0, 0, 0, 0];
	for (const q of quats) {
		const s = q.dot(ref) < 0 ? -1 : 1;
		acc[0] += s * q.x; acc[1] += s * q.y; acc[2] += s * q.z; acc[3] += s * q.w;
	}
	return new Quaternion(acc[0], acc[1], acc[2], acc[3]).normalize();
}

function meanVector(vectors) {
	const acc = new Vector3();
	for (const v of vectors) acc.add(v);
	return vectors.length ? acc.divideScalar(vectors.length) : acc;
}

/** Component of `v` perpendicular to unit `axis`, normalized. */
function perpendicular(v, axis) {
	return v.clone().addScaledVector(axis, -v.dot(axis)).normalize();
}

/** Angle in degrees between two vectors. */
function angleDeg(a, b) {
	return Math.acos(clamp(a.dot(b) / (a.length() * b.length() || 1), -1, 1)) * DEG;
}

/** Quaternion whose rotation maps sensor coordinates onto the (left, up, forward) basis. */
function basisQuaternion(xAxis, yAxis, zAxis) {
	// Rows of the rotation matrix are the target axes; Matrix4.makeBasis sets
	// columns, so build the transpose and invert.
	const m = new Matrix4().makeBasis(xAxis, yAxis, zAxis);
	return new Quaternion().setFromRotationMatrix(m).invert();
}

/** Quaternion of the matrix with the given column vectors. */
function columnsQuaternion(xAxis, yAxis, zAxis) {
	return new Quaternion().setFromRotationMatrix(new Matrix4().makeBasis(xAxis, yAxis, zAxis));
}

/** Frame with columns [distal, secondary, distal × secondary]. */
function segmentFrame(distal, secondary) {
	const d = distal.clone().normalize();
	const s = perpendicular(secondary, d);
	return columnsQuaternion(d, s, new Vector3().crossVectors(d, s));
}

/**
 * Align the long-form rows of one recording into per-timestamp frames.
 * Timestamps that lack any of the seven slots are dropped.
 *
 * @param {Array<{recording_id?:number,time_ms:number,slot:number,quat_x:number,quat_y:number,quat_z:number,quat_w:number}>} rows
 * @returns {{ recording: number|null, times: number[], quats: Quaternion[][] }} times in seconds; quats[slot][frame]
 */
export function alignFrames(rows) {
	const byTime = new Map();
	let recording = null;
	for (const r of rows) {
		if (recording == null && r.recording_id != null) recording = Number(r.recording_id);
		const t = Number(r.time_ms);
		let entry = byTime.get(t);
		if (!entry) { entry = new Array(SLOT_COUNT).fill(null); byTime.set(t, entry); }
		entry[Number(r.slot)] = new Quaternion(Number(r.quat_x), Number(r.quat_y), Number(r.quat_z), Number(r.quat_w)).normalize();
	}
	const times = [];
	const quats = Array.from({ length: SLOT_COUNT }, () => []);
	for (const t of [...byTime.keys()].sort((a, b) => a - b)) {
		const entry = byTime.get(t);
		if (entry.some((q) => q === null)) continue;
		times.push(t / 1000);
		for (let s = 0; s < SLOT_COUNT; s++) quats[s].push(entry[s]);
	}
	return { recording, times, quats };
}

/** Serialize aligned frames for the on-disk cache (`animation-sources/eidon/<id>.json`). */
export function serializeFrames(frames) {
	return {
		recording: frames.recording,
		hz: SAMPLE_HZ,
		times: frames.times,
		quats: frames.quats.map((slot) => slot.flatMap((q) => [q.x, q.y, q.z, q.w])),
	};
}

export function deserializeFrames(data) {
	return {
		recording: data.recording,
		times: data.times,
		quats: data.quats.map((flat) => {
			const out = [];
			for (let i = 0; i < flat.length; i += 4) out.push(new Quaternion(flat[i], flat[i + 1], flat[i + 2], flat[i + 3]));
			return out;
		}),
	};
}

/** World-frame vector `v` expressed in the sensor's own frame. */
function inSensorFrame(q, v) {
	return v.clone().applyQuaternion(q.clone().invert());
}

/** Degrees per second of rotation between consecutive frames. */
function rotationRates(quats, times) {
	const rates = new Array(quats.length).fill(0);
	for (let i = 1; i < quats.length; i++) {
		const dt = times[i] - times[i - 1] || 1 / SAMPLE_HZ;
		rates[i] = (quats[i].angleTo(quats[i - 1]) * DEG) / dt;
	}
	if (rates.length > 1) rates[0] = rates[1];
	return rates;
}

function elbowAngles(armQ, foreQ, distalArm, distalFore) {
	const out = new Array(armQ.length);
	for (let i = 0; i < armQ.length; i++) {
		const rel = armQ[i].clone().invert().multiply(foreQ[i]);
		out[i] = angleDeg(distalFore.clone().applyQuaternion(rel), distalArm);
	}
	return out;
}

function percentile(values, p) {
	if (!values.length) return NaN;
	const sorted = [...values].sort((a, b) => a - b);
	const idx = clamp(Math.round((p / 100) * (sorted.length - 1)), 0, sorted.length - 1);
	return sorted[idx];
}

/**
 * Estimate one arm's sensor mountings from the recording.
 * @returns {{ distal: Record<number, Vector3>, anterior: Vector3, dorsal: Vector3, quality: object }}
 */
function calibrateSide(frames, side, prior) {
	const { times, quats } = frames;
	const armQ = quats[side.arm];
	const foreQ = quats[side.foreArm];
	const n = times.length;
	const rates = rotationRates(armQ, times);
	const down = WORLD_UP.clone().negate();

	// 1. Long axes, from the frames where the arm hangs straight and still.
	//    Straightness needs the long axes, so run two passes: the prior axes
	//    find the hanging frames, the axes those frames yield refine them.
	const distal = {};
	const distalFromPrior = {};
	for (const slot of [side.arm, side.foreArm]) { distal[slot] = v3(prior.distal[slot]).normalize(); distalFromPrior[slot] = null; }
	let hanging = [];
	for (let pass = 0; pass < 2; pass++) {
		const straight = elbowAngles(armQ, foreQ, distal[side.arm], distal[side.foreArm]);
		hanging = [];
		for (let i = 0; i < n; i++) if (straight[i] < STRAIGHT_ELBOW_DEG && rates[i] < STILL_RATE_DEG_PER_S) hanging.push(i);
		if (hanging.length < MIN_ESTIMATE_FRAMES) hanging = straight.map((a, i) => (a < STRAIGHT_ELBOW_DEG ? i : -1)).filter((i) => i >= 0);
		if (hanging.length < MIN_ESTIMATE_FRAMES) break;
		for (const slot of [side.arm, side.foreArm]) {
			const priorAxis = v3(prior.distal[slot]).normalize();
			const est = meanVector(hanging.map((i) => inSensorFrame(quats[slot][i], down))).normalize();
			const disagreement = angleDeg(est, priorAxis);
			if (disagreement <= PRIOR_DISAGREEMENT_DEG) { distal[slot] = est; distalFromPrior[slot] = disagreement; }
		}
	}
	const hangingSeconds = hanging.length / SAMPLE_HZ;

	// 2. Anterior side of the upper arm: where the forearm swings when flexed.
	const elbow = elbowAngles(armQ, foreQ, distal[side.arm], distal[side.foreArm]);
	const swing = [];
	for (let i = 0; i < n; i++) {
		if (elbow[i] <= FLEXED_ELBOW_DEG) continue;
		const rel = armQ[i].clone().invert().multiply(foreQ[i]);
		swing.push(perpendicular(distal[side.foreArm].clone().applyQuaternion(rel), distal[side.arm]));
	}
	const anteriorPrior = perpendicular(v3(prior.anterior[side.arm]), distal[side.arm]);
	let anterior = anteriorPrior;
	let anteriorFromPrior = null;
	let anteriorSpread = null;
	if (swing.length >= MIN_ESTIMATE_FRAMES) {
		const est = meanVector(swing).normalize();
		anteriorSpread = meanVector(swing).length();
		const disagreement = angleDeg(est, anteriorPrior);
		if (disagreement <= PRIOR_DISAGREEMENT_DEG) { anterior = perpendicular(est, distal[side.arm]); anteriorFromPrior = disagreement; }
	}

	// 3. Dorsal side of the forearm: what faces up while the forearm is level.
	const level = [];
	for (let i = 0; i < n; i++) {
		const worldDistal = distal[side.foreArm].clone().applyQuaternion(foreQ[i]);
		if (Math.abs(worldDistal.dot(WORLD_UP)) < HORIZONTAL_COS) level.push(i);
	}
	const dorsalPrior = perpendicular(v3(prior.dorsal[side.foreArm]), distal[side.foreArm]);
	let dorsal = dorsalPrior;
	let dorsalFromPrior = null;
	if (level.length >= MIN_ESTIMATE_FRAMES) {
		const est = perpendicular(meanVector(level.map((i) => inSensorFrame(foreQ[i], WORLD_UP))), distal[side.foreArm]);
		const disagreement = angleDeg(est, dorsalPrior);
		if (disagreement <= PRIOR_DISAGREEMENT_DEG) { dorsal = est; dorsalFromPrior = disagreement; }
	}

	return {
		distal,
		anterior,
		dorsal,
		quality: {
			hangingSeconds,
			levelSeconds: level.length / SAMPLE_HZ,
			distalFromPrior,
			anteriorFromPrior,
			anteriorSpread,
			dorsalFromPrior,
			elbowP10: percentile(elbow, 10),
			elbowP50: percentile(elbow, 50),
			elbowP90: percentile(elbow, 90),
		},
	};
}

/**
 * Measure every mounting parameter the conversion needs from one recording.
 *
 * @param {{times:number[], quats:Quaternion[][]}} frames
 * @param {{ prior?: typeof HARNESS_PRIOR }} [opts]
 */
export function calibrate(frames, { prior = HARNESS_PRIOR } = {}) {
	const { times, quats } = frames;
	const n = times.length;
	if (n < MIN_ESTIMATE_FRAMES) throw new Error(`recording too short to calibrate: ${n} aligned frames`);
	const chestQ = quats[SLOT.chest];
	const chestMean = meanQuaternion(chestQ);
	const chestMeanInv = chestMean.clone().invert();
	const up = inSensorFrame(chestMean, WORLD_UP).normalize();

	const sides = {};
	for (const side of SIDES) sides[side.key] = calibrateSide(frames, side, prior);

	// Forward: where the forearms point, horizontally, in the mean chest frame.
	const pointing = [];
	const windows = new Map();
	for (let i = 0; i < n; i++) {
		const frameSum = new Vector3();
		for (const side of SIDES) {
			const d = sides[side.key].distal[side.foreArm];
			frameSum.add(d.clone().applyQuaternion(chestMeanInv.clone().multiply(quats[side.foreArm][i])));
		}
		pointing.push(frameSum);
		const w = Math.floor(times[i] / YAW_WINDOW_S);
		if (!windows.has(w)) windows.set(w, new Vector3());
		windows.get(w).add(frameSum);
	}
	const forward = perpendicular(meanVector(pointing), up);
	const left = new Vector3().crossVectors(up, forward).normalize();
	const yaws = [...windows.values()].map((sum) => {
		const d = perpendicular(sum, up);
		return Math.atan2(d.dot(left), d.dot(forward)) * DEG;
	});
	const yawMean = yaws.reduce((a, b) => a + b, 0) / (yaws.length || 1);
	const yawStd = Math.sqrt(yaws.reduce((a, y) => a + (y - yawMean) ** 2, 0) / (yaws.length || 1));

	// Wrist: the hand relative to its own average pose in the forearm sensor frame.
	const wristMean = {};
	for (const side of SIDES) {
		const rel = [];
		for (let i = 0; i < n; i++) rel.push(quats[side.foreArm][i].clone().invert().multiply(quats[side.hand][i]));
		wristMean[side.key] = meanQuaternion(rel);
	}

	return {
		recording: frames.recording ?? null,
		frames: n,
		seconds: times[n - 1] - times[0],
		chestMean,
		up,
		forward,
		left,
		toCharacter: basisQuaternion(left, up, forward),
		sides,
		wristMean,
		quality: { yawStd, chestTiltDeg: angleDeg(up, new Vector3(0, Math.sign(up.y) || 1, 0)) },
	};
}

/** Rest-pose geometry of one arm on the canonical rig, from the bind data. */
function restArm(side) {
	const [shoulder, arm, foreArm, hand] = side.bones;
	const pArm = v3(CANONICAL_REST_POSITION[arm]);
	const pFore = v3(CANONICAL_REST_POSITION[foreArm]);
	const pHand = v3(CANONICAL_REST_POSITION[hand]);
	const armDistal = pFore.clone().sub(pArm).normalize();
	const foreDistal = pHand.clone().sub(pFore).normalize();
	return {
		shoulder,
		arm,
		foreArm,
		hand,
		armWorld: q4(CANONICAL_REST_WORLD[arm]),
		foreWorld: q4(CANONICAL_REST_WORLD[foreArm]),
		handLocal: q4(CANONICAL_REST[hand]),
		armFrame: segmentFrame(armDistal, CHAR_FORWARD),
		foreFrame: segmentFrame(foreDistal, CHAR_UP),
		armLength: pFore.distanceTo(pArm),
		foreLength: pHand.distanceTo(pFore),
		armDistalLocal: armDistal.clone().applyQuaternion(q4(CANONICAL_REST_WORLD[arm]).invert()),
		foreDistalLocal: foreDistal.clone().applyQuaternion(q4(CANONICAL_REST_WORLD[foreArm]).invert()),
		shoulderPosition: pArm,
	};
}

/**
 * Per-frame world (model-space) rotations of the driven bones, plus the
 * chest deviation, for one sample index. Everything is relative to the
 * recording's mean chest pose, which stands in for "upright".
 */
function poseAt(frames, cal, i) {
	const { quats } = frames;
	const C = cal.toCharacter;
	const chestInv = cal.chestMean.clone().invert();
	const chest = C.clone().multiply(chestInv.clone().multiply(quats[SLOT.chest][i])).multiply(C.clone().invert());
	const arms = {};
	for (const side of SIDES) {
		const s = cal.sides[side.key];
		const rest = restArm(side);
		const armK = segmentFrame(s.distal[side.arm], s.anterior).multiply(rest.armFrame.clone().invert()).multiply(rest.armWorld);
		const foreK = segmentFrame(s.distal[side.foreArm], s.dorsal).multiply(rest.foreFrame.clone().invert()).multiply(rest.foreWorld);
		const armWorld = C.clone().multiply(chestInv.clone().multiply(quats[side.arm][i])).multiply(armK);
		const foreSensorToChar = C.clone().multiply(chestInv.clone().multiply(quats[side.foreArm][i]));
		const foreWorld = foreSensorToChar.clone().multiply(foreK);
		const wrist = quats[side.foreArm][i].clone().invert().multiply(quats[side.hand][i]).multiply(cal.wristMean[side.key].clone().invert());
		const wristWorld = foreSensorToChar.clone().multiply(wrist).multiply(foreSensorToChar.clone().invert());
		const handWorld = wristWorld.multiply(foreWorld.clone().multiply(rest.handLocal));
		arms[side.key] = { armWorld, foreWorld, handWorld, rest };
	}
	return { chest, arms };
}

/**
 * Biomechanical sanity of the converted motion: hands in front of the body,
 * below the head, elbows never hyperextended. Used to rank recordings.
 */
export function assessPose(frames, cal, { step = 4 } = {}) {
	let total = 0;
	let inFront = 0;
	let belowHead = 0;
	let elbowOk = 0;
	const headY = CANONICAL_REST_POSITION.Head[1];
	for (let i = 0; i < frames.times.length; i += step) {
		const pose = poseAt(frames, cal, i);
		for (const side of SIDES) {
			const a = pose.arms[side.key];
			const elbowPos = a.rest.shoulderPosition.clone().addScaledVector(a.rest.armDistalLocal.clone().applyQuaternion(a.armWorld), a.rest.armLength);
			const handPos = elbowPos.clone().addScaledVector(a.rest.foreDistalLocal.clone().applyQuaternion(a.foreWorld), a.rest.foreLength);
			const armDir = a.rest.armDistalLocal.clone().applyQuaternion(a.armWorld);
			const foreDir = a.rest.foreDistalLocal.clone().applyQuaternion(a.foreWorld);
			total++;
			if (handPos.z > -0.08) inFront++;
			if (handPos.y < headY + 0.05) belowHead++;
			if (angleDeg(armDir, foreDir) < 160) elbowOk++;
		}
	}
	return { inFront: inFront / total, belowHead: belowHead / total, elbowOk: elbowOk / total };
}

/** 0..1 ranking of how trustworthy a recording's conversion is. */
export function qualityScore(cal, pose) {
	let score = 1;
	score *= clamp(1 - cal.quality.yawStd / 45, 0, 1);
	for (const side of SIDES) {
		const q = cal.sides[side.key].quality;
		if (q.hangingSeconds < 1) score *= 0.85;
		if (q.anteriorFromPrior == null) score *= 0.7;
		if (q.dorsalFromPrior == null) score *= 0.9;
		if (q.distalFromPrior[side.arm] == null || q.distalFromPrior[side.foreArm] == null) score *= 0.85;
	}
	score *= 0.4 + 0.6 * pose.inFront;
	score *= 0.4 + 0.6 * pose.belowHead;
	score *= 0.4 + 0.6 * pose.elbowOk;
	return score;
}

/** Mean rotation rate of the six arm sensors, degrees per second, per frame. */
export function motionEnergy(frames) {
	const rates = [];
	for (let s = 0; s < SLOT.chest; s++) rates.push(rotationRates(frames.quats[s], frames.times));
	return frames.times.map((_, i) => rates.reduce((a, r) => a + r[i], 0) / rates.length);
}

/**
 * The `seconds`-long window with the most arm motion, at least `margin`
 * seconds after the start so a looping clip has frames to blend back into.
 */
export function liveliestWindow(frames, seconds, { margin = 1 } = {}) {
	const energy = motionEnergy(frames);
	const { times } = frames;
	let best = { start: margin, end: margin + seconds, energy: -1 };
	for (let i = 0; i < times.length; i++) {
		const start = times[i];
		if (start < margin) continue;
		const end = start + seconds;
		if (end > times[times.length - 1]) break;
		let sum = 0;
		let count = 0;
		for (let j = i; j < times.length && times[j] <= end; j++) { sum += energy[j]; count++; }
		const mean = count ? sum / count : 0;
		if (mean > best.energy) best = { start, end, energy: mean };
	}
	return best;
}

/** Index of the last sample at or before `t`, clamped into range. */
function indexBefore(times, t) {
	let lo = 0;
	let hi = times.length - 1;
	while (lo < hi) {
		const mid = (lo + hi + 1) >> 1;
		if (times[mid] <= t) lo = mid; else hi = mid - 1;
	}
	return lo;
}

/** Pose at an arbitrary time, slerped between the two nearest IMU samples. */
function poseAtTime(frames, cal, t) {
	const { times } = frames;
	const i = indexBefore(times, t);
	const j = Math.min(i + 1, times.length - 1);
	const span = times[j] - times[i];
	const w = span > 0 ? clamp((t - times[i]) / span, 0, 1) : 0;
	const a = poseAt(frames, cal, i);
	if (w === 0 || i === j) return a;
	const b = poseAt(frames, cal, j);
	const out = { chest: a.chest.clone().slerp(b.chest, w), arms: {} };
	for (const side of SIDES) {
		const x = a.arms[side.key];
		const y = b.arms[side.key];
		out.arms[side.key] = {
			armWorld: x.armWorld.clone().slerp(y.armWorld, w),
			foreWorld: x.foreWorld.clone().slerp(y.foreWorld, w),
			handWorld: x.handWorld.clone().slerp(y.handWorld, w),
			rest: x.rest,
		};
	}
	return out;
}

/** Sample a clip track (quaternion or vector) at time `t`, interpolating. */
function sampleTrack(track, t) {
	const size = track.type === 'quaternion' ? 4 : track.type === 'vector' ? 3 : 1;
	const i = indexBefore(track.times, t);
	const j = Math.min(i + 1, track.times.length - 1);
	const span = track.times[j] - track.times[i];
	const w = span > 0 ? clamp((t - track.times[i]) / span, 0, 1) : 0;
	const a = track.values.slice(i * size, i * size + size);
	if (w === 0 || i === j) return a;
	const b = track.values.slice(j * size, j * size + size);
	if (track.type === 'quaternion') return q4(a).slerp(q4(b), w).toArray();
	return a.map((v, k) => v + (b[k] - v) * w);
}

function smoothstep(x) {
	const t = clamp(x, 0, 1);
	return t * t * (3 - 2 * t);
}

/**
 * Bake a window of the recording into a clip on the canonical skeleton.
 *
 * Bones the harness does not measure (hips, legs, neck, head, fingers,
 * clavicles) play the `idle` clip, time-warped so it completes whole cycles
 * inside the window, which keeps a looping clip seamless. Looping clips also
 * blend their final `loopBlend` seconds back toward the frames just before the
 * window, so the wrap is continuous.
 *
 * @param {{times:number[], quats:Quaternion[][]}} frames
 * @param {ReturnType<typeof calibrate>} cal
 * @param {{ name:string, idle:object, start:number, end:number, fps?:number, loop?:boolean, loopBlend?:number, userData?:object }} opts
 */
export function bakeClip(frames, cal, { name, idle, start, end, fps = 30, loop = true, loopBlend = 0.6, userData = {} }) {
	const first = frames.times[0];
	const last = frames.times[frames.times.length - 1];
	if (!(end > start)) throw new Error(`window end ${end} must be after start ${start}`);
	if (start < first || end > last) throw new Error(`window ${start}-${end}s is outside the recording (${first.toFixed(2)}-${last.toFixed(2)}s)`);
	const duration = end - start;
	const blend = loop ? Math.min(loopBlend, start - first, duration / 2) : 0;
	const frameCount = Math.max(2, Math.round(duration * fps) + 1);
	const times = Array.from({ length: frameCount }, (_, k) => k / fps);
	const idleCycles = Math.max(1, Math.round(duration / idle.duration));
	const idleTime = (t) => ((t / duration) * idleCycles * idle.duration) % idle.duration;

	const idleTracks = new Map(idle.tracks.map((tr) => [tr.name, tr]));
	const idleLocal = (bone, t) => q4(sampleTrack(idleTracks.get(`${bone}.quaternion`), idleTime(t)));

	/** Driven world rotations at recording time `rt`, composed onto the idle skeleton at clip time `t`. */
	const drivenAt = (rt, t) => {
		const pose = poseAtTime(frames, cal, rt);
		const hipsWorld = idleLocal('Hips', t);
		const chain = { Hips: hipsWorld };
		let parentIdle = hipsWorld;
		for (const bone of ['Spine', 'Spine1', 'Spine2']) {
			parentIdle = parentIdle.clone().multiply(idleLocal(bone, t));
			const share = new Quaternion().slerp(pose.chest, SPINE_SHARE[bone]);
			chain[bone] = share.multiply(parentIdle);
		}
		const world = { ...chain };
		for (const side of SIDES) {
			const [shoulder, arm, foreArm, hand] = side.bones;
			const a = pose.arms[side.key];
			world[shoulder] = chain.Spine2.clone().multiply(idleLocal(shoulder, t));
			world[arm] = a.armWorld;
			world[foreArm] = a.foreWorld;
			world[hand] = a.handWorld;
		}
		const parents = { Spine: 'Hips', Spine1: 'Spine', Spine2: 'Spine1', LeftArm: 'LeftShoulder', LeftForeArm: 'LeftArm', LeftHand: 'LeftForeArm', RightArm: 'RightShoulder', RightForeArm: 'RightArm', RightHand: 'RightForeArm' };
		const local = {};
		for (const bone of DRIVEN_BONES) local[bone] = world[parents[bone]].clone().invert().multiply(world[bone]);
		return local;
	};

	const drivenFrames = times.map((t) => {
		const raw = drivenAt(start + t, t);
		if (!blend || t < duration - blend) return raw;
		const w = smoothstep((t - (duration - blend)) / blend);
		const target = drivenAt(start + t - duration, t);
		const out = {};
		for (const bone of DRIVEN_BONES) out[bone] = raw[bone].clone().slerp(target[bone], w);
		return out;
	});

	const tracks = idle.tracks.map((track) => {
		const bone = track.name.slice(0, track.name.indexOf('.'));
		if (track.type === 'quaternion' && DRIVEN_BONES.has(bone)) {
			return { name: track.name, type: track.type, times, values: drivenFrames.flatMap((f) => f[bone].normalize().toArray()) };
		}
		return { name: track.name, type: track.type, times, values: times.flatMap((t) => sampleTrack(track, idleTime(t))) };
	});

	return compactClipJson({
		name,
		duration: times[times.length - 1],
		tracks,
		blendMode: idle.blendMode,
		userData: JSON.stringify({
			source: 'eidon-ai/tracker-pov-imu',
			license: 'CC-BY-4.0',
			recording: cal.recording,
			window: [start, end],
			loop,
			neutralPose: 'public/animations/clips/idle.json',
			...userData,
		}),
	});
}

/** Calibrate and bake in one call. */
export function buildClip(frames, opts) {
	const cal = calibrate(frames, { prior: opts.prior });
	return { clip: bakeClip(frames, cal, opts), calibration: cal };
}

/** One-line calibration report for logs and the scan table. */
export function describeCalibration(cal, pose, score) {
	const s = (side) => {
		const q = cal.sides[side].quality;
		const f = (v) => (v == null ? 'prior' : `${v.toFixed(0)}°`);
		return `hang ${q.hangingSeconds.toFixed(1)}s ant ${f(q.anteriorFromPrior)} dors ${f(q.dorsalFromPrior)} elbow ${q.elbowP10.toFixed(0)}/${q.elbowP50.toFixed(0)}/${q.elbowP90.toFixed(0)}`;
	};
	return `score ${score.toFixed(2)} yaw±${cal.quality.yawStd.toFixed(0)}° front ${(pose.inFront * 100).toFixed(0)}% | L ${s('left')} | R ${s('right')}`;
}