Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.jsnew file mode 100644index 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);+ });+});