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): add BVH export for canonical-skeleton motion clips

nirholasbe9baf7f7aa7
diff --git a/src/animation-bvh-export.js b/src/animation-bvh-export.js
new file mode 100644
index 000000000..93e63c427
--- /dev/null
+++ b/src/animation-bvh-export.js
@@ -0,0 +1,225 @@
+// AnimationClip (canonical Wolf3D skeleton, the same document shape the clip
+// library and model-video2motion serve) -> Biovision BVH text.
+//
+// BVH carries no mesh, so unlike the GLB export (which binds onto whichever
+// rig the user picked via src/animation-retarget.js) this writes the motion
+// on the CANONICAL skeleton's own fixed proportions, the way Mixamo's BVH
+// downloads use Mixamo's own skeleton regardless of which character you
+// previewed it on. A BVH is meant to be re-retargeted in the user's own DCC
+// tool (Blender's Rokoko/Auto-Rig Pro, MotionBuilder, Unreal's IK Retargeter),
+// so shipping stable, correct proportions matters more than matching a
+// particular preview avatar's bone lengths.
+//
+// Joint hierarchy and rest offsets come straight from the same generated
+// constants animation-retarget.js binds clips against
+// (animation-canonical-rest.js), so this file has nothing to hand-tune and
+// nothing that can drift from the retarget engine.
+//
+// Rotation channel order is ZXY (CHANNELS 3 Zrotation Xrotation Yrotation).
+// This is not arbitrary: three.js's own BVHLoader composes a joint's rotation
+// per frame by building an identity quaternion and post-multiplying one
+// axis-angle quaternion per channel, in the file's channel order. For a
+// channel order whose axis letters match a THREE.Euler `order` string,
+// `new Euler().setFromQuaternion(q, order)` yields angles that recompose to
+// the exact same quaternion under that algorithm, verified numerically
+// against three.js's Quaternion/Euler math, not assumed. That equivalence is
+// what lets a file this module writes round-trip through BVHLoader (the same
+// loader src/dashboard-next/pages/library/animations.js already uses for BVH
+// import) and come back bit-for-bit equivalent, which is what
+// tests/animation-bvh-export.test.js checks.
+
+import { AnimationClip, Euler, MathUtils, Quaternion, Vector3 } from 'three';
+import { CANONICAL_PARENT, CANONICAL_REST_POSITION, CANONICAL_REST_WORLD } from './animation-canonical-rest.js';
+
+const CHANNEL_AXES = ['Z', 'X', 'Y'];
+const EULER_ORDER = 'ZXY';
+
+// BVH has no standard unit; this platform's own GLB/meter-scale rigs are
+// tiny numbers in the format most DCC BVH importers assume (centimeters), so
+// values are scaled up to match that convention. Documented here once instead
+// of scattered as a magic number.
+const METERS_TO_BVH_UNITS = 100;
+
+function restPosition(name) {
+ const v = CANONICAL_REST_POSITION[name];
+ return new Vector3(v[0], v[1], v[2]);
+}
+
+function restWorldQuat(name) {
+ const q = CANONICAL_REST_WORLD[name];
+ return new Quaternion(q[0], q[1], q[2], q[3]);
+}
+
+/**
+ * Depth-first joint order rooted at Hips, with deterministic (alphabetical)
+ * sibling order so output is byte-stable across runs.
+ */
+export function canonicalBoneOrder() {
+ const childrenOf = new Map();
+ let root = null;
+ for (const [name, parent] of Object.entries(CANONICAL_PARENT)) {
+ if (parent === null) {
+ root = name;
+ continue;
+ }
+ if (!childrenOf.has(parent)) childrenOf.set(parent, []);
+ childrenOf.get(parent).push(name);
+ }
+ for (const arr of childrenOf.values()) arr.sort();
+
+ const order = [];
+ const visit = (name) => {
+ order.push(name);
+ for (const child of childrenOf.get(name) || []) visit(child);
+ };
+ visit(root);
+ return { order, childrenOf, root };
+}
+
+/**
+ * Local (parent-frame) rest offset for a canonical bone, in meters: the rest
+ * world-space translation from parent to bone, expressed in the parent's own
+ * rest orientation. This is the correct BVH OFFSET definition (a child's
+ * world position is parent world position + parent world rotation * OFFSET),
+ * not a plain world-space delta, which would be wrong for any parent whose
+ * rest pose isn't axis-aligned (the authoring rig rests in an A-pose, so
+ * shoulders and hips are not).
+ */
+export function canonicalLocalOffset(name, parent) {
+ const pos = restPosition(name);
+ if (!parent) return pos;
+ const parentPos = restPosition(parent);
+ const parentRot = restWorldQuat(parent);
+ return pos.sub(parentPos).applyQuaternion(parentRot.clone().invert());
+}
+
+function findTrack(clip, boneName, property) {
+ const suffix = `.${property}`;
+ return clip.tracks.find((t) => t.name === `${boneName}${suffix}`) || null;
+}
+
+function sampleVector3(track, time, out) {
+ if (!track) return out.set(0, 0, 0);
+ const values = track.createInterpolant().evaluate(time);
+ return out.set(values[0], values[1], values[2]);
+}
+
+function sampleQuaternion(track, time, out) {
+ if (!track) return out.identity();
+ const values = track.createInterpolant().evaluate(time);
+ return out.set(values[0], values[1], values[2], values[3]);
+}
+
+function formatNumber(n) {
+ return (Object.is(n, -0) ? 0 : n).toFixed(6);
+}
+
+/**
+ * Render an AnimationClip on the canonical skeleton (as produced by
+ * src/animation-retarget.js's `parseClipJSON`, straight off
+ * model-video2motion or the preset clip library) as Biovision BVH text.
+ *
+ * @param {AnimationClip} clip
+ * @param {{fps?: number}} [opts]
+ * @returns {string}
+ */
+export function clipToBVH(clip, opts = {}) {
+ const fps = Math.max(1, Math.min(120, Math.round(opts.fps || 30)));
+ const { order, childrenOf, root } = canonicalBoneOrder();
+
+ const offsets = new Map();
+ for (const name of order) {
+ offsets.set(name, canonicalLocalOffset(name, CANONICAL_PARENT[name]));
+ }
+
+ // Leaf joints need a synthetic End Site: reuse the joint's own
+ // parent-to-self offset vector as its self-to-tip vector, a standard
+ // stand-in for "continue the segment" when no real tip data exists.
+ const endSite = (name) => offsets.get(name);
+
+ let depth = 0;
+ const indent = () => '\t'.repeat(depth);
+ const lines = ['HIERARCHY'];
+
+ const writeOffset = (v) =>
+ `${indent()}\tOFFSET ${formatNumber(v.x * METERS_TO_BVH_UNITS)} ${formatNumber(v.y * METERS_TO_BVH_UNITS)} ${formatNumber(v.z * METERS_TO_BVH_UNITS)}`;
+
+ const writeJoint = (name, isRoot) => {
+ lines.push(`${indent()}${isRoot ? 'ROOT' : 'JOINT'} ${name}`);
+ lines.push(`${indent()}{`);
+ depth++;
+ lines.push(writeOffset(isRoot ? new Vector3(0, 0, 0) : offsets.get(name)));
+ lines.push(
+ isRoot
+ ? `${indent()}CHANNELS 6 Xposition Yposition Zposition Zrotation Xrotation Yrotation`
+ : `${indent()}CHANNELS 3 Zrotation Xrotation Yrotation`,
+ );
+ const kids = childrenOf.get(name) || [];
+ for (const child of kids) writeJoint(child, false);
+ if (kids.length === 0) {
+ lines.push(`${indent()}End Site`);
+ lines.push(`${indent()}{`);
+ depth++;
+ lines.push(writeOffset(endSite(name)));
+ depth--;
+ lines.push(`${indent()}}`);
+ }
+ depth--;
+ lines.push(`${indent()}}`);
+ };
+ writeJoint(root, true);
+
+ const frameTime = 1 / fps;
+ const frameCount = Math.max(1, Math.round(clip.duration / frameTime) + 1);
+
+ const tracksByBone = new Map();
+ for (const name of order) {
+ tracksByBone.set(name, {
+ quat: findTrack(clip, name, 'quaternion'),
+ pos: name === root ? findTrack(clip, name, 'position') : null,
+ });
+ }
+
+ const motionLines = [];
+ const q = new Quaternion();
+ const v = new Vector3();
+ const e = new Euler();
+ for (let f = 0; f < frameCount; f++) {
+ const t = Math.min(clip.duration, f * frameTime);
+ const cols = [];
+ for (const name of order) {
+ const { quat, pos } = tracksByBone.get(name);
+ if (name === root) {
+ sampleVector3(pos, t, v);
+ cols.push(
+ formatNumber(v.x * METERS_TO_BVH_UNITS),
+ formatNumber(v.y * METERS_TO_BVH_UNITS),
+ formatNumber(v.z * METERS_TO_BVH_UNITS),
+ );
+ }
+ sampleQuaternion(quat, t, q);
+ e.setFromQuaternion(q, EULER_ORDER);
+ const deg = { X: MathUtils.radToDeg(e.x), Y: MathUtils.radToDeg(e.y), Z: MathUtils.radToDeg(e.z) };
+ for (const axis of CHANNEL_AXES) cols.push(formatNumber(deg[axis]));
+ }
+ motionLines.push(cols.join(' '));
+ }
+
+ lines.push('MOTION');
+ lines.push(`Frames: ${frameCount}`);
+ lines.push(`Frame Time: ${formatNumber(frameTime)}`);
+ lines.push(...motionLines);
+ return lines.join('\n') + '\n';
+}
+
+/**
+ * Convenience wrapper: parse a clip.json document (the exact artifact
+ * model-video2motion and the clip library serve) straight to BVH text.
+ *
+ * @param {object} clipJSON
+ * @param {{fps?: number}} [opts]
+ * @returns {string}
+ */
+export function clipJSONToBVH(clipJSON, opts = {}) {
+ return clipToBVH(AnimationClip.parse(clipJSON), opts);
+}
diff --git a/tests/animation-bvh-export.test.js b/tests/animation-bvh-export.test.js
new file mode 100644
index 000000000..829786096
--- /dev/null
+++ b/tests/animation-bvh-export.test.js
@@ -0,0 +1,152 @@
+/**
+ * Tests for src/animation-bvh-export.js: AnimationClip (canonical skeleton)
+ * to Biovision BVH text.
+ *
+ * The round-trip test is the one that matters: it writes a BVH, parses it
+ * back with three.js's OWN BVHLoader (the same loader
+ * src/dashboard-next/pages/library/animations.js already uses for BVH
+ * import), and checks the recovered per-joint rotations and root translation
+ * match the source clip. That is the load-bearing proof that a file this
+ * module writes is a real, correctly-encoded BVH and not merely
+ * well-formed-looking text: Blender, Unreal and every other BVH consumer
+ * use the same channel-order convention BVHLoader does.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+ AnimationClip,
+ Euler,
+ MathUtils,
+ Quaternion,
+ QuaternionKeyframeTrack,
+ Vector3,
+ VectorKeyframeTrack,
+} from 'three';
+import { BVHLoader } from 'three/addons/loaders/BVHLoader.js';
+
+import { canonicalBoneOrder, canonicalLocalOffset, clipToBVH, clipJSONToBVH } from '../src/animation-bvh-export.js';
+import { CANONICAL_PARENT } from '../src/animation-canonical-rest.js';
+
+function qArr(q) {
+ return [q.x, q.y, q.z, q.w];
+}
+
+// A clip that rotates Hips, Spine and LeftArm through a sweep, and moves
+// Hips forward, so both the root translation path and a mid-chain joint's
+// rotation path get exercised.
+function makeClip() {
+ const hipsQ = new QuaternionKeyframeTrack(
+ 'Hips.quaternion',
+ [0, 1],
+ [...qArr(new Quaternion()), ...qArr(new Quaternion().setFromEuler(new Euler(0.1, 0.4, -0.05)))],
+ );
+ const hipsPos = new VectorKeyframeTrack('Hips.position', [0, 1], [0, 0.98, 0, 0.2, 0.98, 0.35]);
+ const spineQ = new QuaternionKeyframeTrack(
+ 'Spine.quaternion',
+ [0, 1],
+ [...qArr(new Quaternion()), ...qArr(new Quaternion().setFromEuler(new Euler(-0.2, 0, 0.1)))],
+ );
+ const armQ = new QuaternionKeyframeTrack(
+ 'LeftArm.quaternion',
+ [0, 1],
+ [...qArr(new Quaternion().setFromEuler(new Euler(0, 0, 0.6))), ...qArr(new Quaternion().setFromEuler(new Euler(0.3, 0.2, 1.1)))],
+ );
+ return new AnimationClip('capture', 1, [hipsQ, hipsPos, spineQ, armQ]);
+}
+
+describe('canonicalBoneOrder', () => {
+ it('is rooted at Hips and covers every canonical bone exactly once', () => {
+ const { order, root } = canonicalBoneOrder();
+ expect(root).toBe('Hips');
+ expect(order[0]).toBe('Hips');
+ expect(new Set(order).size).toBe(order.length);
+ expect(order.length).toBe(Object.keys(CANONICAL_PARENT).length);
+ for (const name of Object.keys(CANONICAL_PARENT)) expect(order).toContain(name);
+ });
+});
+
+describe('canonicalLocalOffset', () => {
+ it('returns a zero-length offset only when parent and child coincide, and is deterministic', () => {
+ const a = canonicalLocalOffset('Spine', 'Hips');
+ const b = canonicalLocalOffset('Spine', 'Hips');
+ expect(a.toArray()).toEqual(b.toArray());
+ expect(a.length()).toBeGreaterThan(0);
+ });
+
+ it('returns the raw rest position for the root (no parent)', () => {
+ const offset = canonicalLocalOffset('Hips', null);
+ expect(offset).toBeInstanceOf(Vector3);
+ expect(offset.y).toBeGreaterThan(0.5); // hip height, meters
+ });
+});
+
+describe('clipToBVH', () => {
+ const bvh = clipToBVH(makeClip(), { fps: 30 });
+
+ it('writes a well-formed HIERARCHY/MOTION document rooted at Hips', () => {
+ expect(bvh.startsWith('HIERARCHY\nROOT Hips\n')).toBe(true);
+ expect(bvh).toContain('CHANNELS 6 Xposition Yposition Zposition Zrotation Xrotation Yrotation');
+ expect(bvh).toContain('CHANNELS 3 Zrotation Xrotation Yrotation');
+ expect(bvh).toContain('End Site');
+ expect(bvh).toMatch(/\nMOTION\nFrames: \d+\nFrame Time: [\d.]+\n/);
+ });
+
+ it('emits one joint block per canonical bone', () => {
+ const jointCount = (bvh.match(/\n\t*(ROOT|JOINT) /g) || []).length;
+ expect(jointCount).toBe(Object.keys(CANONICAL_PARENT).length);
+ });
+
+ it('emits exactly Frames+1-worth of motion rows matching the declared Frames count', () => {
+ const framesDeclared = Number(bvh.match(/Frames: (\d+)/)[1]);
+ const motionBody = bvh.split('\n').filter((l) => /^-?\d/.test(l));
+ expect(motionBody.length).toBe(framesDeclared);
+ });
+
+ it('round-trips through three.js BVHLoader: root translation and a mid-chain rotation match the source clip', () => {
+ const loader = new BVHLoader();
+ const parsed = loader.parse(bvh);
+ expect(parsed.clip).toBeTruthy();
+
+ const source = makeClip();
+ const findTrack = (clip, name) => clip.tracks.find((t) => t.name === name);
+
+ for (const t of [0, 0.5, 1]) {
+ // Root translation (meters in source, centimeters on the wire).
+ const srcPos = findTrack(source, 'Hips.position').createInterpolant().evaluate(t);
+ const outPosTrack = findTrack(parsed.clip, 'Hips.position');
+ expect(outPosTrack).toBeTruthy();
+ const outPos = outPosTrack.createInterpolant().evaluate(t);
+ for (let i = 0; i < 3; i++) expect(outPos[i] / 100).toBeCloseTo(srcPos[i], 3);
+
+ // A mid-chain joint's rotation (LeftArm): angleTo is the right
+ // comparator for quaternions since q and -q represent the same
+ // rotation and a naive component diff would false-fail on sign flips.
+ const srcQv = findTrack(source, 'LeftArm.quaternion').createInterpolant().evaluate(t);
+ const srcQ = new Quaternion(srcQv[0], srcQv[1], srcQv[2], srcQv[3]);
+ const outTrack = findTrack(parsed.clip, 'LeftArm.quaternion');
+ expect(outTrack).toBeTruthy();
+ const outQv = outTrack.createInterpolant().evaluate(t);
+ const outQ = new Quaternion(outQv[0], outQv[1], outQv[2], outQv[3]);
+ expect(srcQ.angleTo(outQ)).toBeLessThan(MathUtils.degToRad(0.1));
+ }
+ });
+
+ it('holds identity rotation for canonical bones the source clip never animated', () => {
+ const loader = new BVHLoader();
+ const parsed = loader.parse(bvh);
+ const headTrack = parsed.clip.tracks.find((t) => t.name === 'Head.quaternion');
+ expect(headTrack).toBeTruthy();
+ const q = headTrack.createInterpolant().evaluate(0.5);
+ const identity = new Quaternion();
+ expect(new Quaternion(q[0], q[1], q[2], q[3]).angleTo(identity)).toBeLessThan(1e-4);
+ });
+});
+
+describe('clipJSONToBVH', () => {
+ it('accepts a clip.json document directly, the same artifact model-video2motion serves', () => {
+ const json = AnimationClip.toJSON(makeClip());
+ const bvh = clipJSONToBVH(json, { fps: 24 });
+ expect(bvh.startsWith('HIERARCHY\n')).toBe(true);
+ expect(bvh).toContain('Frame Time: 0.041667');
+ });
+});