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.

feat(animation): bake chores clips from the Eidon tracker IMU dataset

nirholasa21a6ce9dff1
diff --git a/scripts/build-eidon-clips.mjs b/scripts/build-eidon-clips.mjs
new file mode 100644
index 000000000..21e5df2c4
--- /dev/null
+++ b/scripts/build-eidon-clips.mjs
@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+/**
+ * Bake the chores clips listed in scripts/eidon-clips.config.json from the
+ * Eidon Tracker POV IMU dataset (huggingface.co/datasets/eidon-ai/tracker-pov-imu,
+ * CC-BY-4.0) into public/animations/clips/<name>.json.
+ *
+ * Each recording is fetched once, straight from the Hugging Face parquet
+ * shards with HTTP range reads (the shard index maps a recording to its shard
+ * and every recording is its own row group, so a 60 s recording is about a
+ * megabyte of transfer, never the 9.5 GB set), and cached as aligned frames in
+ * animation-sources/eidon/<recording>.json. Like every other source in that
+ * directory the cache is gitignored; the baked clip is the committed artifact,
+ * and a clean checkout without network access republishes it (PREBUILT), the
+ * same contract scripts/build-animations.mjs keeps for Mixamo sources.
+ *
+ * Usage:
+ * node scripts/build-eidon-clips.mjs bake every configured clip
+ * node scripts/build-eidon-clips.mjs --only=<name> one clip
+ * node scripts/build-eidon-clips.mjs --refetch ignore the frame cache
+ *
+ * Finding recordings worth baking:
+ * node scripts/build-eidon-clips.mjs --scan --task=doing_the_dishes --limit=20 [--seconds=14]
+ * ranks candidate recordings by how trustworthy their calibration is and
+ * prints the liveliest window of the requested length in each.
+ * node scripts/build-eidon-clips.mjs --inspect=<recording> [--seconds=14]
+ * full calibration report for one recording.
+ *
+ * Wired into `npm run build:animations` ahead of the manifest build, which
+ * merges these clips from the config the same way it merges the hand-authored
+ * extras.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { asyncBufferFromUrl, parquetMetadataAsync, parquetReadObjects } from 'hyparquet';
+import { compressors } from 'hyparquet-compressors';
+import {
+ alignFrames,
+ assessPose,
+ buildClip,
+ calibrate,
+ describeCalibration,
+ deserializeFrames,
+ liveliestWindow,
+ qualityScore,
+ serializeFrames,
+ SLOT,
+} from './eidon-imu-clip.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const CONFIG_PATH = resolve(ROOT, 'scripts/eidon-clips.config.json');
+const CLIPS_DIR = resolve(ROOT, 'public/animations/clips');
+const IDLE_PATH = resolve(CLIPS_DIR, 'idle.json');
+const CACHE_DIR = resolve(ROOT, 'animation-sources/eidon');
+
+const HF = 'https://huggingface.co/datasets/eidon-ai';
+const IMU_BASE = `${HF}/tracker-pov-imu/resolve/main`;
+const METADATA_URL = `${HF}/tracker-pov/resolve/main/recordings/metadata.parquet`;
+const IMU_COLUMNS = ['recording_id', 'time_ms', 'slot', 'quat_x', 'quat_y', 'quat_z', 'quat_w'];
+const META_COLUMNS = ['recording_id', 'contributor_id', 'task_type', 'duration_seconds', 'qc_status', 'n_slots', 'has_chest', 'good_frame_percent', 'hand_presence_ratio'];
+
+const args = new Map(process.argv.slice(2).map((a) => {
+ const m = a.match(/^--([^=]+)(?:=(.*))?$/);
+ return m ? [m[1], m[2] ?? true] : [a, true];
+}));
+const flag = (k) => args.has(k);
+const opt = (k, d) => (args.has(k) && args.get(k) !== true ? args.get(k) : d);
+
+const readJson = (p) => JSON.parse(readFileSync(p, 'utf8'));
+const writeJson = (p, data) => writeFileSync(p, `${JSON.stringify(data)}\n`);
+const cachePath = (name) => resolve(CACHE_DIR, name);
+
+async function cachedJson(name, produce) {
+ const path = cachePath(name);
+ if (!flag('refetch') && existsSync(path)) return readJson(path);
+ const data = await produce();
+ mkdirSync(CACHE_DIR, { recursive: true });
+ writeJson(path, data);
+ return data;
+}
+
+async function shardIndex() {
+ return cachedJson('shard_index.json', async () => {
+ const res = await fetch(`${IMU_BASE}/shard_index.json`);
+ if (!res.ok) throw new Error(`shard_index.json: HTTP ${res.status}`);
+ return res.json();
+ });
+}
+
+/** Recording metadata rows (the QC and task columns only), cached once. */
+async function metadata() {
+ return cachedJson('metadata.json', async () => {
+ const file = await asyncBufferFromUrl({ url: METADATA_URL });
+ const rows = await parquetReadObjects({ file, columns: META_COLUMNS, compressors });
+ return rows.map((r) => Object.fromEntries(Object.entries(r).map(([k, v]) => [k, typeof v === 'bigint' ? Number(v) : v])));
+ });
+}
+
+const shardMetadata = new Map();
+async function openShard(shard) {
+ if (!shardMetadata.has(shard)) {
+ const file = await asyncBufferFromUrl({ url: `${IMU_BASE}/${shard}` });
+ shardMetadata.set(shard, { file, meta: await parquetMetadataAsync(file) });
+ }
+ return shardMetadata.get(shard);
+}
+
+/** Fetch one recording's rows by locating its row group through the column statistics. */
+async function fetchRecordingRows(recording) {
+ const index = await shardIndex();
+ const entry = index.find((s) => s.first_recording_id <= recording && recording <= s.last_recording_id);
+ if (!entry) throw new Error(`recording ${recording} is in no shard of the index`);
+ const { file, meta } = await openShard(entry.shard);
+ let rowStart = 0;
+ for (const rg of meta.row_groups) {
+ const col = rg.columns.find((c) => c.meta_data.path_in_schema[0] === 'recording_id');
+ const stats = col.meta_data.statistics;
+ const min = Number(stats.min_value ?? stats.min);
+ const max = Number(stats.max_value ?? stats.max);
+ const rows = Number(rg.num_rows);
+ if (min <= recording && recording <= max) {
+ const all = await parquetReadObjects({ file, metadata: meta, columns: IMU_COLUMNS, rowStart, rowEnd: rowStart + rows, compressors });
+ return all.filter((r) => Number(r.recording_id) === recording);
+ }
+ rowStart += rows;
+ }
+ throw new Error(`recording ${recording} not found in ${entry.shard}`);
+}
+
+async function loadFrames(recording) {
+ const data = await cachedJson(`${recording}.json`, async () => {
+ const rows = await fetchRecordingRows(recording);
+ if (!rows.length) throw new Error(`recording ${recording} has no rows`);
+ return serializeFrames(alignFrames(rows));
+ });
+ return deserializeFrames(data);
+}
+
+function analyse(frames, seconds) {
+ const cal = calibrate(frames);
+ const pose = assessPose(frames, cal);
+ const score = qualityScore(cal, pose);
+ const window = liveliestWindow(frames, seconds);
+ return { cal, pose, score, window };
+}
+
+async function scan() {
+ const meta = await metadata();
+ const task = opt('task', null);
+ const contributor = opt('contributor', null);
+ const minSeconds = Number(opt('min-seconds', 10));
+ const maxSeconds = Number(opt('max-seconds', 60));
+ const limit = Number(opt('limit', 20));
+ const seconds = Number(opt('seconds', 14));
+ const candidates = meta
+ .filter((r) => r.qc_status === 'valid' && r.n_slots === 7 && r.has_chest)
+ .filter((r) => r.duration_seconds >= minSeconds && r.duration_seconds <= maxSeconds)
+ .filter((r) => !task || r.task_type === task)
+ .filter((r) => !contributor || String(r.contributor_id) === String(contributor))
+ .sort((a, b) => b.hand_presence_ratio - a.hand_presence_ratio || b.good_frame_percent - a.good_frame_percent)
+ .slice(0, limit);
+ console.log(`[eidon] scanning ${candidates.length} recordings${task ? ` (${task})` : ''}, ${seconds}s windows`);
+ const results = [];
+ for (const r of candidates) {
+ try {
+ const frames = await loadFrames(r.recording_id);
+ const { cal, pose, score, window } = analyse(frames, seconds);
+ results.push({ recording: r.recording_id, contributor: r.contributor_id, task: r.task_type, seconds: r.duration_seconds, score, window, report: describeCalibration(cal, pose, score) });
+ } catch (err) {
+ console.warn(`[eidon] ${r.recording_id}: ${err.message}`);
+ }
+ }
+ results.sort((a, b) => b.score - a.score);
+ if (flag('json')) { console.log(JSON.stringify(results, null, '\t')); return; }
+ for (const x of results) {
+ console.log(`${String(x.recording).padStart(6)} c${String(x.contributor).padEnd(3)} ${x.task.padEnd(16)} ${String(x.seconds.toFixed(0)).padStart(3)}s window ${x.window.start.toFixed(1)}-${x.window.end.toFixed(1)}s (${x.window.energy.toFixed(0)}°/s) ${x.report}`);
+ }
+}
+
+async function inspect(recording) {
+ const frames = await loadFrames(recording);
+ const seconds = Number(opt('seconds', 14));
+ const { cal, pose, score, window } = analyse(frames, seconds);
+ const f = (v) => v.toArray().map((n) => n.toFixed(2)).join(', ');
+ console.log(`[eidon] recording ${recording}: ${cal.frames} frames, ${cal.seconds.toFixed(1)}s`);
+ console.log(` chest: up [${f(cal.up)}] forward [${f(cal.forward)}] left [${f(cal.left)}] tilt ${cal.quality.chestTiltDeg.toFixed(1)}° yaw±${cal.quality.yawStd.toFixed(1)}°`);
+ for (const side of ['left', 'right']) {
+ const s = cal.sides[side];
+ const [armSlot, foreSlot] = side === 'left' ? [SLOT.leftArm, SLOT.leftForeArm] : [SLOT.rightArm, SLOT.rightForeArm];
+ console.log(` ${side}: distal arm [${f(s.distal[armSlot])}] fore [${f(s.distal[foreSlot])}] anterior [${f(s.anterior)}] dorsal [${f(s.dorsal)}]`);
+ console.log(` ${JSON.stringify(s.quality)}`);
+ }
+ console.log(` pose: ${JSON.stringify(pose)}`);
+ console.log(` liveliest ${seconds}s window: ${window.start.toFixed(1)}-${window.end.toFixed(1)}s (${window.energy.toFixed(0)}°/s), score ${score.toFixed(2)}`);
+}
+
+async function build() {
+ const config = readJson(CONFIG_PATH);
+ const idle = readJson(IDLE_PATH);
+ const only = opt('only', null);
+ let ok = 0;
+ let prebuilt = 0;
+ let failed = 0;
+ for (const def of config.clips) {
+ if (only && def.name !== only) continue;
+ const outPath = resolve(CLIPS_DIR, `${def.name}.json`);
+ let frames;
+ try {
+ frames = await loadFrames(def.recording);
+ } catch (err) {
+ if (existsSync(outPath)) {
+ console.log(`[eidon] PREBUILT ${def.name.padEnd(22)} recording ${def.recording} unavailable (${err.message})`);
+ prebuilt++;
+ continue;
+ }
+ console.error(`[eidon] FAIL ${def.name}: ${err.message}`);
+ failed++;
+ continue;
+ }
+ const { clip, calibration } = buildClip(frames, {
+ name: def.name,
+ idle,
+ start: def.start,
+ end: def.end,
+ loop: def.loop !== false,
+ userData: { task: def.task, contributor: def.contributor },
+ });
+ writeJson(outPath, clip);
+ const pose = assessPose(frames, calibration);
+ const score = qualityScore(calibration, pose);
+ console.log(`[eidon] BAKED ${def.name.padEnd(22)} rec ${String(def.recording).padStart(5)} ${def.start}-${def.end}s ${describeCalibration(calibration, pose, score)}`);
+ ok++;
+ }
+ console.log(`[eidon] ${ok} baked, ${prebuilt} prebuilt, ${failed} failed`);
+ if (failed) process.exit(1);
+}
+
+if (flag('scan')) await scan();
+else if (args.has('inspect')) await inspect(Number(opt('inspect')));
+else await build();
diff --git a/scripts/eidon-imu-clip.mjs b/scripts/eidon-imu-clip.mjs
new file mode 100644
index 000000000..e356aa2fe
--- /dev/null
+++ b/scripts/eidon-imu-clip.mjs
@@ -0,0 +1,677 @@
+/**
+ * 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')}`;
+}
diff --git a/tests/eidon-imu-clip.test.js b/tests/eidon-imu-clip.test.js
new file mode 100644
index 000000000..c0449aba4
--- /dev/null
+++ b/tests/eidon-imu-clip.test.js
@@ -0,0 +1,276 @@
+/**
+ * The Eidon IMU converter (scripts/eidon-imu-clip.mjs) measures every harness
+ * mounting parameter from the recording itself. These tests drive it with a
+ * synthetic wearer whose arm motion is known exactly: a body in a z-up world,
+ * seven sensors strapped on at mountings that sit a realistic 10-20 degrees
+ * off the population prior, doing a scripted routine (hang still, flex the
+ * elbow with the forearm level and palm down, reach forward, hang again). The
+ * converter must recover the elbow angle, the shoulder flexion, the wearer's
+ * forward direction and the chest lean on the canonical rig, and it must do so
+ * from the sensor streams alone, because no such truth exists for the real
+ * recordings.
+ */
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { Matrix4, Quaternion, Vector3 } from 'three';
+import {
+ alignFrames,
+ bakeClip,
+ calibrate,
+ deserializeFrames,
+ HARNESS_PRIOR,
+ liveliestWindow,
+ SAMPLE_HZ,
+ serializeFrames,
+ SLOT,
+} from '../scripts/eidon-imu-clip.mjs';
+import { CANONICAL_REST_POSITION, CANONICAL_REST_WORLD } from '../src/animation-canonical-rest.js';
+
+const idle = JSON.parse(readFileSync(new URL('../public/animations/clips/idle.json', import.meta.url), 'utf8'));
+const DEG = 180 / Math.PI;
+
+const v = (x, y, z) => new Vector3(x, y, z);
+const columns = (a, b, c) => new Quaternion().setFromRotationMatrix(new Matrix4().makeBasis(a, b, c));
+const axisAngle = (axis, deg) => new Quaternion().setFromAxisAngle(axis.clone().normalize(), deg / DEG);
+const perp = (vec, axis) => vec.clone().addScaledVector(axis, -vec.dot(axis)).normalize();
+const angle = (a, b) => a.angleTo(b) * DEG;
+
+/**
+ * A sensor's frame relative to its segment: the segment's distal and
+ * secondary axes expressed in sensor coordinates, taken from the harness prior
+ * and rotated by `tiltDeg` about a fixed axis so the estimators cannot simply
+ * echo the prior back.
+ */
+function mounting(distalPrior, secondaryPrior, tiltDeg) {
+ const tilt = axisAngle(v(1, 2, 3), tiltDeg);
+ const distal = v(...distalPrior).normalize().applyQuaternion(tilt);
+ const secondary = perp(v(...secondaryPrior).applyQuaternion(tilt), distal);
+ // Columns [distal, secondary, distal × secondary] map segment coordinates to
+ // sensor coordinates; the sensor's orientation is the segment's times the inverse.
+ return columns(distal, secondary, new Vector3().crossVectors(distal, secondary)).invert();
+}
+
+/** Scripted routine: returns shoulder flexion, elbow flexion and wrist wobble (degrees) at time t. */
+function routine(t) {
+ if (t < 6) return { shoulder: 0, elbow: 0, wrist: 0 };
+ if (t < 20) return { shoulder: 10 - 10 * Math.cos((t - 6) * 0.9), elbow: 50 - 50 * Math.cos((t - 6) * 1.3), wrist: 8 * Math.sin(t * 2.1) };
+ if (t < 30) return { shoulder: 60, elbow: 90 + 12 * Math.sin((t - 20) * 1.7), wrist: 8 * Math.sin(t * 2.1) };
+ return { shoulder: 0, elbow: 0, wrist: 0 };
+}
+
+/**
+ * Simulate the seven sensor streams for `seconds` of the routine.
+ * World: z up, the wearer faces +x, +y is the wearer's left.
+ */
+function simulate(seconds = 40) {
+ const up = v(0, 0, 1);
+ const rows = [];
+ const mounts = {
+ [SLOT.chest]: axisAngle(v(0.3, 1, 0.2), 140),
+ [SLOT.leftArm]: mounting(HARNESS_PRIOR.distal[SLOT.leftArm], HARNESS_PRIOR.anterior[SLOT.leftArm], 12),
+ [SLOT.rightArm]: mounting(HARNESS_PRIOR.distal[SLOT.rightArm], HARNESS_PRIOR.anterior[SLOT.rightArm], -15),
+ [SLOT.leftForeArm]: mounting(HARNESS_PRIOR.distal[SLOT.leftForeArm], HARNESS_PRIOR.dorsal[SLOT.leftForeArm], 18),
+ [SLOT.rightForeArm]: mounting(HARNESS_PRIOR.distal[SLOT.rightForeArm], HARNESS_PRIOR.dorsal[SLOT.rightForeArm], -9),
+ [SLOT.leftHand]: axisAngle(v(1, -0.5, 0.7), 75),
+ [SLOT.rightHand]: axisAngle(v(-0.4, 0.9, 0.3), -50),
+ };
+ const truth = [];
+ const frames = Math.round(seconds * SAMPLE_HZ);
+ for (let i = 0; i < frames; i++) {
+ const t = i / SAMPLE_HZ;
+ const timeMs = Math.round(t * 1000) + 42;
+ const { shoulder, elbow, wrist } = routine(t);
+ // Body: a constant heading plus a lean about the left axis and a small yaw wobble.
+ const lean = 6 * Math.sin(t * 0.5);
+ const body = axisAngle(up, 35 + 4 * Math.sin(t * 0.3)).multiply(axisAngle(v(0, 1, 0), lean));
+ const forward = v(1, 0, 0).applyQuaternion(body);
+ const left = v(0, 1, 0).applyQuaternion(body);
+ const bodyUp = v(0, 0, 1).applyQuaternion(body);
+ const push = (slot, segmentWorld) => {
+ const q = segmentWorld.clone().multiply(mounts[slot]);
+ rows.push({ recording_id: 1, time_ms: timeMs, slot, quat_x: q.x, quat_y: q.y, quat_z: q.z, quat_w: q.w });
+ };
+ push(SLOT.chest, body);
+ const perSide = {};
+ for (const side of ['left', 'right']) {
+ // Upper arm hangs (distal = -up, anterior = forward) and flexes forward at the shoulder.
+ const flex = axisAngle(left, -shoulder);
+ const armDistal = bodyUp.clone().negate().applyQuaternion(flex);
+ const armAnterior = forward.clone().applyQuaternion(flex);
+ const armThird = new Vector3().crossVectors(armDistal, armAnterior);
+ // Forearm flexes toward the anterior side; its dorsal side faces up when level (palm down).
+ const rad = elbow / DEG;
+ const foreDistal = armDistal.clone().multiplyScalar(Math.cos(rad)).addScaledVector(armAnterior, Math.sin(rad));
+ const foreDorsal = armDistal.clone().multiplyScalar(-Math.sin(rad)).addScaledVector(armAnterior, Math.cos(rad));
+ const foreThird = new Vector3().crossVectors(foreDistal, foreDorsal);
+ const foreWorld = columns(foreDistal, foreDorsal, foreThird);
+ const handWorld = axisAngle(foreThird, wrist).multiply(foreWorld);
+ const slots = side === 'left'
+ ? { arm: SLOT.leftArm, foreArm: SLOT.leftForeArm, hand: SLOT.leftHand }
+ : { arm: SLOT.rightArm, foreArm: SLOT.rightForeArm, hand: SLOT.rightHand };
+ push(slots.arm, columns(armDistal, armAnterior, armThird));
+ push(slots.foreArm, foreWorld);
+ push(slots.hand, handWorld);
+ perSide[side] = { armDistal, foreDistal };
+ }
+ truth.push({ t, shoulder, elbow, wrist, lean, forward, left, bodyUp, ...perSide });
+ }
+ return { rows, truth };
+}
+
+/** World rotation of every bone in a clip frame, composed from the clip's own local tracks. */
+function worldRotations(clip, frame) {
+ const parents = {
+ Spine: 'Hips', Spine1: 'Spine', Spine2: 'Spine1',
+ LeftShoulder: 'Spine2', LeftArm: 'LeftShoulder', LeftForeArm: 'LeftArm', LeftHand: 'LeftForeArm',
+ RightShoulder: 'Spine2', RightArm: 'RightShoulder', RightForeArm: 'RightArm', RightHand: 'RightForeArm',
+ };
+ const local = (bone) => {
+ const track = clip.tracks.find((tr) => tr.name === `${bone}.quaternion`);
+ return new Quaternion().fromArray(track.values, frame * 4).normalize();
+ };
+ const world = { Hips: local('Hips') };
+ for (const bone of Object.keys(parents)) world[bone] = world[parents[bone]].clone().multiply(local(bone));
+ return world;
+}
+
+/** A bone's distal direction on the canonical rig, in model space, for a clip frame. */
+function boneDirection(world, bone, child) {
+ const restDistal = v(...CANONICAL_REST_POSITION[child]).sub(v(...CANONICAL_REST_POSITION[bone])).normalize();
+ const restLocal = restDistal.applyQuaternion(new Quaternion().fromArray(CANONICAL_REST_WORLD[bone]).invert());
+ return restLocal.applyQuaternion(world[bone]);
+}
+
+describe('eidon imu clip: calibration from a synthetic wearer', () => {
+ const { rows, truth } = simulate();
+ const frames = alignFrames(rows);
+ const cal = calibrate(frames);
+
+ it('aligns the long-form rows into complete seven-slot frames', () => {
+ expect(frames.times.length).toBe(truth.length);
+ expect(frames.quats).toHaveLength(7);
+ expect(frames.times[1] - frames.times[0]).toBeCloseTo(1 / SAMPLE_HZ, 3);
+ });
+
+ it('finds the wearer\'s up, forward and left in the chest sensor frame', () => {
+ const chestInv = cal.chestMean.clone().invert();
+ const meanForward = truth.reduce((acc, f) => acc.add(f.forward), new Vector3()).normalize().applyQuaternion(chestInv);
+ const meanLeft = truth.reduce((acc, f) => acc.add(f.left), new Vector3()).normalize().applyQuaternion(chestInv);
+ expect(angle(cal.up, v(0, 0, 1).applyQuaternion(chestInv))).toBeLessThan(3);
+ expect(angle(cal.forward, meanForward)).toBeLessThan(6);
+ expect(angle(cal.left, meanLeft)).toBeLessThan(6);
+ });
+
+ it('measures every arm axis from the data instead of echoing the prior', () => {
+ for (const side of ['left', 'right']) {
+ const q = cal.sides[side].quality;
+ expect(q.hangingSeconds).toBeGreaterThan(3);
+ expect(q.anteriorFromPrior).not.toBeNull();
+ expect(q.dorsalFromPrior).not.toBeNull();
+ for (const value of Object.values(q.distalFromPrior)) expect(value).not.toBeNull();
+ // The mountings were tilted 9-18 degrees off the prior, and the estimate should follow the tilt, not the prior.
+ expect(q.anteriorFromPrior).toBeGreaterThan(4);
+ }
+ });
+
+ it('survives a recording that never hangs or flexes by falling back to the prior', () => {
+ const still = { ...frames, times: frames.times.slice(0, 60), quats: frames.quats.map((s) => s.slice(0, 60)) };
+ const calStill = calibrate(still);
+ expect(calStill.sides.left.quality.anteriorFromPrior).toBeNull();
+ expect(angle(calStill.sides.left.anterior, perp(v(...HARNESS_PRIOR.anterior[SLOT.leftArm]), calStill.sides.left.distal[SLOT.leftArm]))).toBeLessThan(1e-6);
+ });
+});
+
+describe('eidon imu clip: baked motion on the canonical rig', () => {
+ const { rows, truth } = simulate();
+ const frames = alignFrames(rows);
+ const cal = calibrate(frames);
+ const clip = bakeClip(frames, cal, { name: 'synthetic', idle, start: 2, end: 36, loop: false });
+ const fps = 30;
+ const truthAt = (clipTime) => truth[Math.round((2 + clipTime) * SAMPLE_HZ)];
+
+ it('has every idle track, at 30 fps, over the requested window', () => {
+ expect(clip.tracks.map((t) => t.name)).toEqual(idle.tracks.map((t) => t.name));
+ expect(clip.duration).toBeCloseTo(34, 5);
+ expect(clip.tracks[0].times[1]).toBeCloseTo(1 / fps, 6);
+ expect(JSON.parse(clip.userData)).toMatchObject({ source: 'eidon-ai/tracker-pov-imu', license: 'CC-BY-4.0', recording: 1 });
+ });
+
+ it('reproduces the elbow angle within a few degrees on both arms', () => {
+ let worst = 0;
+ for (let frame = 0; frame < clip.tracks[0].times.length; frame += 7) {
+ const world = worldRotations(clip, frame);
+ const expected = truthAt(clip.tracks[0].times[frame]).elbow;
+ for (const side of ['Left', 'Right']) {
+ const arm = boneDirection(world, `${side}Arm`, `${side}ForeArm`);
+ const fore = boneDirection(world, `${side}ForeArm`, `${side}Hand`);
+ worst = Math.max(worst, Math.abs(angle(arm, fore) - expected));
+ }
+ }
+ expect(worst).toBeLessThan(4);
+ });
+
+ it('hangs the arms straight down and raises them forward when the wearer reaches', () => {
+ const at = (clipTime) => worldRotations(clip, Math.round(clipTime * fps));
+ const hanging = at(1);
+ expect(angle(boneDirection(hanging, 'LeftArm', 'LeftForeArm'), v(0, -1, 0))).toBeLessThan(4);
+ expect(angle(boneDirection(hanging, 'RightArm', 'RightForeArm'), v(0, -1, 0))).toBeLessThan(4);
+ // t = 23 s in the routine (21 s into the clip): shoulder 60 degrees forward, elbow about 90.
+ const reaching = at(21);
+ const expectedArm = v(0, -Math.cos(60 / DEG), Math.sin(60 / DEG));
+ expect(angle(boneDirection(reaching, 'LeftArm', 'LeftForeArm'), expectedArm)).toBeLessThan(5);
+ expect(angle(boneDirection(reaching, 'RightArm', 'RightForeArm'), expectedArm)).toBeLessThan(5);
+ // The flexed forearm points up and forward (elbow flexes toward the anterior side), never backward.
+ const fore = boneDirection(reaching, 'LeftForeArm', 'LeftHand');
+ expect(fore.z).toBeGreaterThan(0.3);
+ expect(fore.y).toBeGreaterThan(0.3);
+ });
+
+ it('keeps the level forearm palm-down: its dorsal side faces up', () => {
+ // t = 14.8 s: elbow near 100 degrees with the upper arm hanging, so the forearm is roughly level.
+ const frame = Math.round((14.8 - 2) * fps);
+ const world = worldRotations(clip, frame);
+ const restDorsal = v(0, 1, 0).applyQuaternion(new Quaternion().fromArray(CANONICAL_REST_WORLD.LeftForeArm).invert());
+ const dorsal = restDorsal.applyQuaternion(world.LeftForeArm);
+ expect(dorsal.y).toBeGreaterThan(0.85);
+ });
+
+ it('leans the torso with the chest sensor and leaves the legs on the idle clip', () => {
+ const spine2 = (clipTime) => worldRotations(clip, Math.round(clipTime * fps)).Spine2;
+ const idleSpine2 = (clipTime) => {
+ const idleClip = { ...idle, tracks: idle.tracks };
+ const frame = Math.round(clipTime * fps) % idle.tracks[0].times.length;
+ return worldRotations(idleClip, frame).Spine2;
+ };
+ // The lean is 6 degrees at its peak around t = 3.14 s (1.14 s into the clip) and reverses at t = 9.4 s.
+ const forwardLean = spine2(1.14).angleTo(idleSpine2(1.14)) * DEG;
+ const backLean = spine2(7.4).angleTo(idleSpine2(7.4)) * DEG;
+ expect(forwardLean).toBeGreaterThan(3);
+ expect(backLean).toBeGreaterThan(3);
+ const legs = clip.tracks.find((t) => t.name === 'LeftUpLeg.quaternion');
+ const idleLegs = idle.tracks.find((t) => t.name === 'LeftUpLeg.quaternion');
+ expect(legs.values.slice(0, 4)).toEqual(idleLegs.values.slice(0, 4).map((n) => Number(n.toPrecision(7))));
+ });
+
+ it('closes a looping clip so the last frame returns to the first', () => {
+ const loop = bakeClip(frames, cal, { name: 'loop', idle, start: 8, end: 18, loop: true, loopBlend: 0.6 });
+ for (const bone of ['LeftArm', 'LeftForeArm', 'RightForeArm', 'Spine2']) {
+ const track = loop.tracks.find((t) => t.name === `${bone}.quaternion`);
+ const first = new Quaternion().fromArray(track.values, 0);
+ const last = new Quaternion().fromArray(track.values, (track.times.length - 1) * 4);
+ expect(first.angleTo(last) * DEG).toBeLessThan(3);
+ }
+ });
+
+ it('is deterministic and round-trips through the frame cache format', () => {
+ const again = bakeClip(deserializeFrames(serializeFrames(frames)), calibrate(deserializeFrames(serializeFrames(frames))), { name: 'synthetic', idle, start: 2, end: 36, loop: false });
+ expect(again).toEqual(clip);
+ });
+
+ it('picks the liveliest window after the loop margin', () => {
+ const window = liveliestWindow(frames, 10, { margin: 1 });
+ expect(window.start).toBeGreaterThanOrEqual(1);
+ expect(window.start).toBeGreaterThan(5);
+ expect(window.end - window.start).toBeCloseTo(10, 5);
+ });
+});