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(motion): bake generated clips onto the rig and flatten the lane's root ramp

nirholas92e4ad09a5d2
diff --git a/api/_lib/motion-glb.js b/api/_lib/motion-glb.js
new file mode 100644
index 000000000..4dba7f9c9
--- /dev/null
+++ b/api/_lib/motion-glb.js
@@ -0,0 +1,410 @@
+// Bake a generated motion clip onto a rig and emit a self-contained animated GLB.
+//
+// WHY THIS EXISTS. The generated half of the animation library
+// (animations/library/generated/clips/*.json) is public clip JSON: it drives
+// avatars in the browser, where src/animation-retarget.js maps it onto whatever
+// skeleton the page loaded. That JSON is not a product anyone would buy, because
+// it is already free and it is useless outside three.ws. The sellable artifact is
+// the motion baked onto the platform's own rig as one portable GLB a buyer can
+// drop into Blender, Unity or Unreal. This module is the bake.
+//
+// HOW. A three.js AnimationClip.toJSON() track set is, channel for channel, a
+// glTF animation: per-bone quaternion tracks are `rotation` channels, the root
+// translation track is a `translation` channel, and the sample times are the
+// sampler input. So the bake is a container edit, not a render: parse the rig's
+// GLB, append the keyframe floats to the BIN chunk, add the accessors and
+// bufferViews that describe them, and write one `animations` entry. Nothing is
+// decoded, no mesh is touched, and a meshopt-compressed rig survives untouched
+// because its bufferViews are never read.
+//
+// The alternative was three.js GLTFLoader plus GLTFExporter in-process, which
+// needs a DOM (`self`, FileReader, createObjectURL) and would decode and
+// re-encode every texture in the rig to write a few hundred KB of keyframes.
+//
+// THE CLIP MUST BE RETARGETED FIRST, and this is the part that is easy to get
+// wrong: library clips are authored in the `cz` rig's rest basis (an A-pose),
+// so their per-bone quaternions are local rotations RELATIVE TO THAT REST. Write
+// them straight onto a rig that rests differently and the pose is not merely
+// imprecise, it is broken. Baking one onto the Ready Player Me default rig
+// without the correction puts the feet at 1.85 m and the head at 1.46 m: the
+// legs fold up over the body. So the bake runs the clip through
+// src/animation-retarget.js, the same retarget the browser applies before
+// playing any library clip, which composes the bind correction
+// (q <- L * q * R) from the source rest basis to this rig's. A rig that rests
+// in the authoring basis gets an identity correction and round-trips unchanged.
+//
+// Retargeting also settles the track policy, which is why this module does not
+// re-implement it: quaternions for every bone the rig has, translation for the
+// root (Hips) only, scaled to the target's hip height, and nothing else. A
+// clip's per-bone position and scale channels describe the SOURCE rig's bone
+// lengths, and writing them onto another skeleton overwrites its proportions.
+//
+// ROOT DRIFT is removed before the bake by default. The published generated
+// clips predate flattenRootDrift (api/_lib/motion-seed.js) and still carry the
+// lane's constant forward ramp, so a GLB baked straight from one walks a metre
+// forward while it applauds. The sellable artifact is the thing a buyer opens in
+// Blender, so it gets the corrected motion whether or not the clip JSON behind
+// it has been republished yet. Pass `flatten: false` to bake a clip exactly as
+// given, which is what the round-trip tests do.
+//
+// Spec: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
+
+import { AnimationClip, Quaternion } from 'three';
+
+import { canonicalizeBoneName } from '../../src/glb-canonicalize.js';
+import { clipHipBaselineY, retargetClip } from '../../src/animation-retarget.js';
+import { flattenRootDrift } from './motion-seed.js';
+
+const GLB_MAGIC = 0x46546c67; // 'glTF'
+const CHUNK_JSON = 0x4e4f534a; // 'JSON'
+const CHUNK_BIN = 0x004e4942; // 'BIN\0'
+
+const FLOAT = 5126;
+const HEADER_BYTES = 12;
+const CHUNK_HEADER_BYTES = 8;
+
+// Every bone name a generated clip can carry is canonical (Hips, Spine, LeftArm
+// ...) because the seeding gate rejects anything else, so the root track is
+// found by exact name rather than by re-running canonicalization here.
+const ROOT_BONE = 'Hips';
+
+/**
+ * Split a GLB into its JSON and BIN chunks.
+ *
+ * @param {Buffer|Uint8Array} buf
+ * @returns {{ json: any, bin: Buffer }}
+ */
+export function readGlbChunks(buf) {
+ if (!buf || typeof buf.length !== 'number' || buf.length < HEADER_BYTES + CHUNK_HEADER_BYTES) {
+ throw new Error('not a glb: too short');
+ }
+ const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+ if (view.getUint32(0, true) !== GLB_MAGIC) throw new Error('not a glb: bad magic');
+ if (view.getUint32(4, true) !== 2) throw new Error('not a glb: unsupported version');
+
+ let json = null;
+ let bin = null;
+ let offset = HEADER_BYTES;
+ while (offset + CHUNK_HEADER_BYTES <= buf.length) {
+ const length = view.getUint32(offset, true);
+ const type = view.getUint32(offset + 4, true);
+ const start = offset + CHUNK_HEADER_BYTES;
+ const end = start + length;
+ if (end > buf.length) throw new Error('not a glb: chunk overruns the file');
+ if (type === CHUNK_JSON && json === null) {
+ json = JSON.parse(Buffer.from(buf.buffer, buf.byteOffset + start, length).toString('utf8'));
+ } else if (type === CHUNK_BIN && bin === null) {
+ bin = Buffer.from(Buffer.from(buf.buffer, buf.byteOffset + start, length));
+ }
+ offset = end + padding(length);
+ }
+ if (!json) throw new Error('not a glb: no JSON chunk');
+ return { json, bin: bin || Buffer.alloc(0) };
+}
+
+/**
+ * Re-assemble a GLB from a JSON chunk and a BIN chunk, padding both to the
+ * 4-byte boundary the spec requires (JSON with spaces, BIN with zeros).
+ *
+ * @param {any} json
+ * @param {Buffer} bin
+ * @returns {Buffer}
+ */
+export function writeGlbChunks(json, bin) {
+ const jsonBytes = Buffer.from(JSON.stringify(json), 'utf8');
+ const jsonPad = Buffer.alloc(padding(jsonBytes.length), 0x20);
+ const binPad = Buffer.alloc(padding(bin.length), 0x00);
+
+ const jsonLength = jsonBytes.length + jsonPad.length;
+ const binLength = bin.length + binPad.length;
+ const total =
+ HEADER_BYTES +
+ CHUNK_HEADER_BYTES +
+ jsonLength +
+ (binLength > 0 ? CHUNK_HEADER_BYTES + binLength : 0);
+
+ const head = Buffer.alloc(HEADER_BYTES + CHUNK_HEADER_BYTES);
+ head.writeUInt32LE(GLB_MAGIC, 0);
+ head.writeUInt32LE(2, 4);
+ head.writeUInt32LE(total, 8);
+ head.writeUInt32LE(jsonLength, 12);
+ head.writeUInt32LE(CHUNK_JSON, 16);
+
+ const parts = [head, jsonBytes, jsonPad];
+ if (binLength > 0) {
+ const binHead = Buffer.alloc(CHUNK_HEADER_BYTES);
+ binHead.writeUInt32LE(binLength, 0);
+ binHead.writeUInt32LE(CHUNK_BIN, 4);
+ parts.push(binHead, bin, binPad);
+ }
+ return Buffer.concat(parts, total);
+}
+
+function padding(length) {
+ return (4 - (length % 4)) % 4;
+}
+
+/**
+ * World-space rest height of a rig's root bone, walking the node hierarchy and
+ * accumulating each ancestor's translation and uniform Y scale. This is the
+ * number a clip's root-motion track is rescaled against.
+ *
+ * @param {any} gltf parsed glTF JSON
+ * @param {string} [boneName]
+ * @returns {number|null} null when the rig has no such bone
+ */
+export function restBoneHeight(gltf, boneName = ROOT_BONE) {
+ const nodes = Array.isArray(gltf?.nodes) ? gltf.nodes : [];
+ const index = nodes.findIndex((n) => n?.name === boneName);
+ if (index === -1) return null;
+
+ const parents = new Map();
+ nodes.forEach((node, i) => {
+ for (const child of node?.children || []) parents.set(child, i);
+ });
+
+ let height = 0;
+ let cursor = index;
+ const seen = new Set();
+ while (cursor !== undefined && !seen.has(cursor)) {
+ seen.add(cursor);
+ const node = nodes[cursor];
+ if (!node) break;
+ const scaleY = Array.isArray(node.scale) ? node.scale[1] : 1;
+ const translateY = Array.isArray(node.translation) ? node.translation[1] : 0;
+ height = translateY + height * scaleY;
+ cursor = parents.get(cursor);
+ }
+ return height;
+}
+
+// glTF animation target path for a three.js track property, or null to drop it.
+// Only the channels the retarget already decided to keep reach this, so there is
+// no bone-name test here: a `.position` track that survived the retarget is the
+// root's by construction.
+function targetPathFor(property) {
+ if (property === 'quaternion') return 'rotation';
+ if (property === 'position') return 'translation';
+ return null;
+}
+
+function componentsFor(path) {
+ return path === 'rotation' ? 4 : 3;
+}
+
+function typeFor(path) {
+ return path === 'rotation' ? 'VEC4' : 'VEC3';
+}
+
+/**
+ * The rig's rest basis, read straight out of the glTF JSON: for every node whose
+ * name canonicalizes to a known humanoid bone, its local rest rotation and its
+ * world (model-frame) rest rotation. These are the two maps `retargetClip` needs
+ * to build the bind correction, and deriving them from the container means the
+ * bake never has to instantiate a three.js scene graph.
+ *
+ * First name wins, matching canonicalNodeMapFromObject's traversal order.
+ *
+ * @param {any} gltf parsed glTF JSON
+ */
+export function restBasisFromGltf(gltf) {
+ const nodes = Array.isArray(gltf?.nodes) ? gltf.nodes : [];
+ const parents = new Map();
+ nodes.forEach((node, i) => {
+ for (const child of node?.children || []) parents.set(child, i);
+ });
+
+ const localOf = (i) => {
+ const r = nodes[i]?.rotation;
+ return Array.isArray(r) ? new Quaternion(r[0], r[1], r[2], r[3]) : new Quaternion();
+ };
+ // worldRestQuat(node, null): the node's own rotation with every ancestor's
+ // premultiplied onto it, walking to the top of the graph.
+ const worldOf = (i) => {
+ const q = localOf(i);
+ for (let cursor = parents.get(i); cursor !== undefined; cursor = parents.get(cursor)) {
+ q.premultiply(localOf(cursor));
+ }
+ return q;
+ };
+
+ const canonicalToNode = new Map();
+ const targetRest = new Map();
+ const targetWorldRest = new Map();
+ let hipsParentWorldQuat = null;
+
+ nodes.forEach((node, i) => {
+ const name = node?.name;
+ if (!name) return;
+ const canonical = canonicalizeBoneName(name);
+ if (!canonical || canonicalToNode.has(canonical)) return;
+ canonicalToNode.set(canonical, name);
+ targetRest.set(canonical, localOf(i));
+ targetWorldRest.set(canonical, worldOf(i));
+ if (canonical === ROOT_BONE) {
+ const parent = parents.get(i);
+ if (parent !== undefined) hipsParentWorldQuat = worldOf(parent);
+ }
+ });
+
+ return { canonicalToNode, targetRest, targetWorldRest, hipsParentWorldQuat };
+}
+
+/**
+ * Bake one clip onto one rig.
+ *
+ * @param {{
+ * rig: Buffer|Uint8Array,
+ * clip: { name?: string, duration?: number, tracks: Array<{ name: string, type?: string, times: number[], values: number[] }> },
+ * name?: string,
+ * flatten?: boolean,
+ * retarget?: boolean,
+ * }} input
+ * @returns {{ glb: Buffer, channels: number, droppedTracks: string[], hipScale: number, duration: number, driftRemoved: number, coverage: number }}
+ */
+export function bakeMotionGlb({ rig, clip: input, name, flatten = true, retarget = true }) {
+ if (!input || !Array.isArray(input.tracks) || input.tracks.length === 0) {
+ throw new Error('clip has no tracks');
+ }
+ const drift = flatten ? flattenRootDrift(input) : { clip: input, removed: 0 };
+ const { json, bin } = readGlbChunks(rig);
+ const nodes = Array.isArray(json.nodes) ? json.nodes : [];
+ if (nodes.length === 0) throw new Error('rig has no nodes');
+
+ const nodeIndex = new Map();
+ nodes.forEach((node, i) => {
+ if (node?.name && !nodeIndex.has(node.name)) nodeIndex.set(node.name, i);
+ });
+
+ const { clip, hipScale, coverage, droppedTracks } = prepareClip(drift.clip, json, { retarget, name });
+
+ const chunks = [bin];
+ let cursor = bin.length;
+ const bufferViews = Array.isArray(json.bufferViews) ? json.bufferViews : (json.bufferViews = []);
+ const accessors = Array.isArray(json.accessors) ? json.accessors : (json.accessors = []);
+
+ /** Append float data to the BIN chunk and return its accessor index. */
+ const pushAccessor = (values, count, type, bounds) => {
+ const pad = padding(cursor);
+ if (pad) {
+ chunks.push(Buffer.alloc(pad));
+ cursor += pad;
+ }
+ const data = Buffer.from(new Float32Array(values).buffer);
+ chunks.push(data);
+ bufferViews.push({ buffer: 0, byteOffset: cursor, byteLength: data.length });
+ cursor += data.length;
+ accessors.push({
+ bufferView: bufferViews.length - 1,
+ componentType: FLOAT,
+ count,
+ type,
+ ...(bounds ? { min: bounds.min, max: bounds.max } : {}),
+ });
+ return accessors.length - 1;
+ };
+
+ const samplers = [];
+ const channels = [];
+ // One clip resamples every track on the same grid, so identical time arrays
+ // are shared rather than written once per bone.
+ const timeAccessors = new Map();
+ let duration = Number(clip.duration) || 0;
+
+ for (const track of clip.tracks) {
+ const rawName = String(track?.name || '');
+ const dot = rawName.lastIndexOf('.');
+ const bone = dot === -1 ? rawName : rawName.slice(0, dot);
+ const property = dot === -1 ? '' : rawName.slice(dot + 1);
+ const path = targetPathFor(property);
+ const node = nodeIndex.get(bone);
+
+ if (path === null || node === undefined) {
+ droppedTracks.push(rawName);
+ continue;
+ }
+ const times = Array.from(track.times || []);
+ const stride = componentsFor(path);
+ const values = Array.from(track.values || []);
+ if (times.length === 0 || values.length !== times.length * stride) {
+ droppedTracks.push(rawName);
+ continue;
+ }
+
+ const key = `${times.length}:${times[0]}:${times[times.length - 1]}`;
+ let input_ = timeAccessors.get(key);
+ if (input_ === undefined) {
+ // The spec requires min and max on an animation sampler's input.
+ input_ = pushAccessor(times, times.length, 'SCALAR', {
+ min: [times[0]],
+ max: [times[times.length - 1]],
+ });
+ timeAccessors.set(key, input_);
+ }
+ duration = Math.max(duration, times[times.length - 1]);
+
+ const output = pushAccessor(values, times.length, typeFor(path));
+ samplers.push({ input: input_, output, interpolation: 'LINEAR' });
+ channels.push({ sampler: samplers.length - 1, target: { node, path } });
+ }
+
+ if (channels.length === 0) throw new Error('no clip track matched a bone on this rig');
+
+ const animations = Array.isArray(json.animations) ? json.animations : (json.animations = []);
+ animations.push({ name: name || clip.name || 'motion', channels, samplers });
+
+ const merged = Buffer.concat(chunks, cursor);
+ json.buffers = Array.isArray(json.buffers) ? json.buffers : [];
+ if (json.buffers.length === 0) json.buffers.push({ byteLength: merged.length });
+ else json.buffers[0] = { ...json.buffers[0], byteLength: merged.length };
+
+ return {
+ glb: writeGlbChunks(json, merged),
+ channels: channels.length,
+ droppedTracks,
+ hipScale,
+ duration,
+ driftRemoved: drift.removed,
+ coverage,
+ };
+}
+
+/**
+ * Run the clip through the platform retarget so its rotations are expressed in
+ * THIS rig's rest basis, and its root translation in this rig's scale. Returns
+ * the clip in the shape the writer above consumes: track names are target node
+ * names, and only retargetable channels survive.
+ */
+function prepareClip(source, gltf, { retarget, name }) {
+ if (!retarget) {
+ return { clip: source, hipScale: 1, coverage: 1, droppedTracks: [] };
+ }
+ const basis = restBasisFromGltf(gltf);
+ const parsed = AnimationClip.parse({ ...source, name: name || source.name || 'motion' });
+
+ // Root translation is authored around the source rig's hip height; scale it
+ // onto this one, clamped exactly as retargetClipToRig clamps it so a
+ // near-zero baseline on an in-place clip cannot fling the root away.
+ let hipScale = 1;
+ const targetY = restBoneHeight(gltf, ROOT_BONE);
+ const sourceY = clipHipBaselineY(parsed);
+ if (targetY > 0.05 && sourceY > 0.05) hipScale = Math.min(5, Math.max(0.2, targetY / sourceY));
+
+ const result = retargetClip(parsed, basis.canonicalToNode, {
+ hipScale,
+ targetRest: basis.targetRest,
+ targetWorldRest: basis.targetWorldRest,
+ hipsParentWorldQuat: basis.hipsParentWorldQuat,
+ });
+ if (!result.clip) {
+ throw new Error(
+ `retarget covered only ${(result.coverage * 100).toFixed(0)}% of the clip's bones on this rig`,
+ );
+ }
+ return {
+ clip: result.clip,
+ hipScale,
+ coverage: result.coverage,
+ droppedTracks: Array.isArray(result.dropped) ? [...result.dropped] : [],
+ };
+}
diff --git a/api/_lib/motion-seed.js b/api/_lib/motion-seed.js
index 0578e1e1f..0abe7d26c 100644
--- a/api/_lib/motion-seed.js
+++ b/api/_lib/motion-seed.js
@@ -455,6 +455,24 @@ export const MOTION_GATE = Object.freeze({
MAX_SLIDE_PER_STRIDE: 0.85,
// Absolute slide ceiling in metres for a clip that does not travel.
MAX_STATIONARY_SLIDE: 0.55,
+ // Rest-basis check, and the rule whose absence let 133 clips ship with their
+ // legs folded up over the body. Every other threshold here measures a clip
+ // against ITSELF, so a clip expressed in the wrong rest basis is perfectly
+ // self-consistent and passes all of them.
+ //
+ // It takes TWO signals, because neither alone is safe. A clip that is never
+ // upright is suspicious but might be a pushup or a swim stroke, which are
+ // prone by definition. A clip whose upper legs sit near identity is
+ // suspicious but a single published clip reached 148 degrees. Requiring both
+ // leaves real margin on the measured distributions: over the published set,
+ // clips in the wrong basis peak at 0.435 m of head clearance with a median
+ // leg angle of 23.6 degrees, while the same clips rebased clear 0.939 m at
+ // p05 and never fall below 74.9 degrees.
+ MIN_UPRIGHT_GAP: 0.5,
+ MIN_LEG_BASIS_DEGREES: 60,
+ // Frames sampled when looking for the clip's most upright moment. Twelve is
+ // enough to catch a squat standing back up without walking every frame.
+ UPRIGHT_SAMPLES: 12,
});
function isFiniteSeq(seq) {
@@ -570,6 +588,24 @@ export function gateMotionClip(clip, opts = {}) {
const travels = foot.stride > 0.05;
if (travels && foot.slidePerStride > MOTION_GATE.MAX_SLIDE_PER_STRIDE) reasons.push('foot_sliding');
if (!travels && foot.slide > MOTION_GATE.MAX_STATIONARY_SLIDE) reasons.push('foot_sliding_in_place');
+
+ // Rest basis. A clip that never gets upright AND whose upper legs never
+ // leave the identity basis is not choreography, it is a clip expressed in
+ // the wrong rest frame, and it will play with the legs folded over the
+ // body on every rig. Either signal alone would reject real prone motion,
+ // so both have to agree.
+ const upright = maxUprightGap(clip);
+ const legs = legBasisDegrees(clip);
+ metrics.uprightGap = upright;
+ metrics.legBasisDegrees = legs;
+ if (
+ Number.isFinite(upright) &&
+ Number.isFinite(legs) &&
+ upright < MOTION_GATE.MIN_UPRIGHT_GAP &&
+ legs < MOTION_GATE.MIN_LEG_BASIS_DEGREES
+ ) {
+ reasons.push('wrong_rest_basis');
+ }
}
return { ok: reasons.length === 0, reasons, metrics };
@@ -592,6 +628,7 @@ export function toLibraryClip(raw, { name, promptId, prompt, category, loop, tas
blendMode: raw.blendMode ?? 0,
userData: {
source: 'text2motion',
+ basis: CLIP_BASIS,
prompt_id: promptId,
prompt,
category,
@@ -798,6 +835,267 @@ function slerp(a, b, t) {
return [a[0] * wa + bx * wb, a[1] * wa + by * wb, a[2] * wa + bz * wb, a[3] * wa + bw * wb];
}
+// ── Rest basis ──────────────────────────────────────────────────────────────
+//
+// Library clips are authored in the `cz` rig's rest basis: every per-bone
+// quaternion is a local rotation RELATIVE TO THAT REST, which is why a Mixamo
+// walk carries roughly 180 degrees on each upper leg (cz rests with the leg
+// bones pointing up, so the clip has to turn them down). Everything downstream
+// assumes that basis: forwardKinematicsFrame below composes the clip's
+// quaternions onto CANONICAL_REST, and src/animation-retarget.js builds its bind
+// correction from cz to whatever rig the page loaded.
+//
+// The text2motion lane does not produce that basis. Its clips come out of a
+// Kabsch fit against the HumanML3D skeleton's own raw offsets
+// (workers/model-text2motion/mdm_sampler.py `_positions_to_local_quats`), where
+// a joint at rest yields the IDENTITY quaternion, and smpl_to_clip.py's own
+// `rest_offsets` hook, the place that difference was meant to be calibrated
+// away, was never given a value. So a generated clip carries 29 degrees on the
+// upper legs where an authored one carries 176, and playing it composes the
+// missing half-turn into the legs: measured on all 133 clips published before
+// 2026-09-09, forward kinematics puts the FEET AT 1.71 m and the HEAD AT 1.45 m.
+// Every one of them plays with the legs folded up over the body.
+//
+// The conversion is bindCorrections (src/animation-retarget.js) with the source
+// rest set to identity, which is what the Kabsch formulation means:
+//
+// L = Rt * Wt^-1 * Ws * Rs^-1 -> Rt * Wt^-1 (Ws = Rs = identity)
+// R = Ws^-1 * Wt -> Wt
+// q <- L * q * R
+//
+// Verified against the whole published set: head-above-feet goes from -0.26 m to
+// +1.38 m, and 127 of 133 clear a 0.6 m upright bar. The six that do not are a
+// pushup, a squat, a swim stroke, a crouch, a sneak and a meditation, which are
+// low-posture by definition and correct as they are.
+
+/**
+ * Rewrite a clip's rotations from the generator's identity-rest basis into the
+ * library's canonical (cz) rest basis, so it composes correctly with every other
+ * library clip. Returns a NEW clip; the input is not modified.
+ *
+ * @param {any} clip
+ * @returns {{ clip: any, rebasedTracks: number }}
+ */
+export function rebaseToCanonicalRest(clip) {
+ const source = clip?.tracks;
+ if (!Array.isArray(source)) return { clip, rebasedTracks: 0 };
+
+ let rebasedTracks = 0;
+ const tracks = source.map((track) => {
+ const name = String(track?.name || '');
+ if (!name.endsWith('.quaternion')) return track;
+ const bone = name.slice(0, name.lastIndexOf('.'));
+ const restLocal = CANONICAL_REST[bone];
+ const restWorld = CANONICAL_REST_WORLD[bone];
+ if (!restLocal || !restWorld) return track;
+
+ // L = Rt * Wt^-1, R = Wt.
+ const L = quatMul(restLocal, quatConjugate(restWorld));
+ const R = restWorld;
+ const values = Array.from(track.values ?? []);
+ for (let i = 0; i + 3 < values.length; i += 4) {
+ const q = [values[i], values[i + 1], values[i + 2], values[i + 3]];
+ const out = quatMul(quatMul(L, q), R);
+ values[i] = out[0];
+ values[i + 1] = out[1];
+ values[i + 2] = out[2];
+ values[i + 3] = out[3];
+ }
+ rebasedTracks += 1;
+ return { ...track, values };
+ });
+
+ return { clip: { ...clip, tracks }, rebasedTracks };
+}
+
+// Stamped on every clip written in the library's basis, so a repair pass can
+// tell a converted clip from one of the 133 that predate the conversion and
+// never rebases the same clip twice.
+export const CLIP_BASIS = 'canonical-rest-v1';
+
+/** True when a clip still carries the generator's identity-rest basis. */
+export function needsRebase(clip) {
+ return clip?.userData?.basis !== CLIP_BASIS;
+}
+
+/**
+ * Mean angle, in degrees, that the upper-leg bones sit away from identity across
+ * the whole clip. The library's canonical rest points the leg bones up, so an
+ * authored clip has to turn them down and carries roughly 180 degrees on them;
+ * a clip still in the generator's identity-rest basis carries almost nothing.
+ *
+ * @param {any} clip
+ * @returns {number} NaN when the clip animates neither upper leg
+ */
+export function legBasisDegrees(clip) {
+ let total = 0;
+ let count = 0;
+ for (const track of clip?.tracks ?? []) {
+ if (!/^(Left|Right)UpLeg\.quaternion$/.test(String(track?.name || ''))) continue;
+ const values = track.values ?? [];
+ for (let i = 0; i + 3 < values.length; i += 4) {
+ total += (2 * Math.acos(Math.min(1, Math.abs(values[i + 3])) ) * 180) / Math.PI;
+ count += 1;
+ }
+ }
+ return count === 0 ? NaN : total / count;
+}
+
+/**
+ * The clip's most upright moment: the largest head clearance over the higher
+ * foot, in metres, sampled across the clip. Sampling rather than reading frame 0
+ * is what lets a squat or a bow through, since both stand up again.
+ *
+ * @param {any} clip
+ * @returns {number} NaN when the clip lacks the bones to judge
+ */
+export function maxUprightGap(clip) {
+ const frames = frameCount(clip);
+ if (frames === 0) return NaN;
+ const step = Math.max(1, Math.floor(frames / MOTION_GATE.UPRIGHT_SAMPLES));
+ let best = -Infinity;
+ for (let frame = 0; frame < frames; frame += step) {
+ const gap = uprightGap(clip, frame);
+ if (Number.isFinite(gap)) best = Math.max(best, gap);
+ }
+ return Number.isFinite(best) ? best : NaN;
+}
+
+/**
+ * Head height above the higher foot at a given frame, in metres. The cheapest
+ * check that a clip is the right way up, and the one whose absence let an
+ * entire inverted library through the gate.
+ *
+ * @param {any} clip
+ * @param {number} [frameIndex]
+ * @returns {number} NaN when the clip lacks the bones to judge
+ */
+export function uprightGap(clip, frameIndex = 0) {
+ const joints = forwardKinematicsFrame(clip, frameIndex);
+ const head = joints.Head?.[1];
+ const left = joints.LeftFoot?.[1];
+ const right = joints.RightFoot?.[1];
+ if (!Number.isFinite(head) || (!Number.isFinite(left) && !Number.isFinite(right))) return NaN;
+ return head - Math.max(Number.isFinite(left) ? left : -Infinity, Number.isFinite(right) ? right : -Infinity);
+}
+
+// ── Root drift ──────────────────────────────────────────────────────────────
+//
+// The text2motion lane's root translation channel carries a constant forward
+// ramp that is not part of the motion. Measured over the 133 clips published on
+// 2026-09-09, every clip travels forward at 0.2577 m/s (sd 0.0248) regardless of
+// what was asked for: emotes fit a straight line to a residual of 0.0002 m, and
+// idles (0.2502 m/s) drift FASTER than locomotion (0.2841 m/s). A channel where
+// "a person stands still breathing" and "a person sprints at full speed" travel
+// at the same speed carries no prompt signal at all.
+//
+// The cause is denormalization, and it is upstream of us. MDM samples in
+// HumanML3D's normalized feature space and mdm_sampler denormalizes with the
+// dataset's own mean and std before recover_from_ric integrates the root
+// velocity (workers/model-text2motion/mdm_sampler.py). Feature 2 is the root's
+// forward velocity, and most of HumanML3D walks, so that feature's dataset MEAN
+// is a brisk walk. When the model has no strong locomotion signal to express it
+// emits a normalized value near zero, and denormalizing "near zero" yields
+// exactly the dataset's average walking speed. The integration then turns a
+// constant velocity into a straight ramp.
+//
+// So the fix is to remove the component that is indistinguishable from a
+// constant-velocity ramp and keep everything else. Fitting the horizontal root
+// track by least squares and subtracting the fitted line leaves the residual
+// intact, which is where the real signal lives: a pirouette's sway and a walk's
+// per-step surge survive (locomotion residual 0.0051 m) while a clip whose root
+// track is a straight line flattens to nothing (emote residual 0.0002 m).
+// Vertical travel is never touched, because a crouch, a jump and a fall are all
+// real motion in Y.
+//
+// This is also what makes the library's convention honest: three.ws clips play
+// on an avatar standing where the page put it, and a game engine expects an
+// in-place clip it can drive from its own character controller. Run this BEFORE
+// gating and before closing a loop seam. Before gating, because the foot-slide
+// rule measures planted-foot slide against the stride the clip covers, and a
+// fake 1 m stride makes that rule far too lenient. Before the seam, because the
+// seam search is looking for the frame whose pose repeats frame 0, and a ramp
+// guarantees no frame ever does.
+
+export const ROOT_DRIFT = Object.freeze({
+ // Below this the fitted ramp is not worth removing: a clip that travels a
+ // centimetre over its whole length is already in place.
+ MIN_SPEED: 0.02,
+});
+
+/**
+ * Remove the constant-velocity horizontal ramp from a clip's root translation.
+ *
+ * Returns a NEW clip; the input is not modified. A clip with no root position
+ * track, too few frames, or no measurable ramp is returned unchanged, so this is
+ * always safe to call.
+ *
+ * @param {any} clip
+ * @returns {{ clip: any, speed: number, removed: number, residual: number }}
+ * speed is the fitted ramp in m/s, removed the total metres taken out, and
+ * residual the RMS of what was left behind (the real motion).
+ */
+export function flattenRootDrift(clip, opts = {}) {
+ const minSpeed = opts.minSpeed ?? ROOT_DRIFT.MIN_SPEED;
+ const tracks = clip?.tracks ?? [];
+ const index = tracks.findIndex((t) => String(t?.name || '') === 'Hips.position');
+ if (index === -1) return { clip, speed: 0, removed: 0, residual: 0 };
+
+ const track = tracks[index];
+ const times = Array.from(track.times ?? []);
+ const values = Array.from(track.values ?? []);
+ const n = times.length;
+ if (n < 2 || values.length !== n * 3) return { clip, speed: 0, removed: 0, residual: 0 };
+
+ const meanTime = times.reduce((s, t) => s + t, 0) / n;
+ let timeVariance = 0;
+ for (const t of times) timeVariance += (t - meanTime) ** 2;
+ if (timeVariance <= 0) return { clip, speed: 0, removed: 0, residual: 0 };
+
+ // Fit and subtract independently on X and Z: a clip can ramp on either axis.
+ const slopes = [0, 0];
+ const residuals = [0, 0];
+ for (const [slot, axis] of [[0, 0], [1, 2]]) {
+ let meanValue = 0;
+ for (let i = 0; i < n; i += 1) meanValue += values[i * 3 + axis];
+ meanValue /= n;
+
+ let covariance = 0;
+ for (let i = 0; i < n; i += 1) covariance += (times[i] - meanTime) * (values[i * 3 + axis] - meanValue);
+ const slope = covariance / timeVariance;
+ slopes[slot] = slope;
+
+ let sumSquares = 0;
+ const intercept = meanValue - slope * meanTime;
+ for (let i = 0; i < n; i += 1) sumSquares += (values[i * 3 + axis] - (slope * times[i] + intercept)) ** 2;
+ residuals[slot] = Math.sqrt(sumSquares / n);
+ }
+
+ const speed = Math.hypot(slopes[0], slopes[1]);
+ if (speed < minSpeed) {
+ return { clip, speed, removed: 0, residual: Math.hypot(residuals[0], residuals[1]) };
+ }
+
+ // Subtract the ramp relative to frame 0, so the clip still starts exactly
+ // where it started and only the travel is taken away.
+ const flattened = values.slice();
+ const t0 = times[0];
+ for (let i = 0; i < n; i += 1) {
+ const elapsed = times[i] - t0;
+ flattened[i * 3] -= slopes[0] * elapsed;
+ flattened[i * 3 + 2] -= slopes[1] * elapsed;
+ }
+
+ const out = { ...clip, tracks: tracks.slice() };
+ out.tracks[index] = { ...track, times, values: flattened };
+ return {
+ clip: out,
+ speed,
+ removed: speed * (times[n - 1] - t0),
+ residual: Math.hypot(residuals[0], residuals[1]),
+ };
+}
+
export const LOOP_SEAM = Object.freeze({
// Never cut away more than this fraction of the clip hunting for a cycle: a
// clip trimmed to a third of its length is a different clip.
diff --git a/scripts/gcp/seed-motion.mjs b/scripts/gcp/seed-motion.mjs
index 2dd116791..ecc1a6e12 100644
--- a/scripts/gcp/seed-motion.mjs
+++ b/scripts/gcp/seed-motion.mjs
@@ -43,7 +43,7 @@ import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { gateMotionClip, explainMotionGate, MOTION_GATE_VERSION } from '../../api/_lib/motion-quality.js';
-import { closeLoopSeam } from '../../api/_lib/motion-seed.js';
+import { closeLoopSeam, flattenRootDrift } from '../../api/_lib/motion-seed.js';
const __dirname = dirname(fileURLToPath(import.meta.url));
const ROOT = resolve(__dirname, '../..');
@@ -233,14 +233,23 @@ async function runPrompt(prompt) {
const fetched = await fetchClip(clipUrl);
const elapsedSeconds = Math.round((Date.now() - started) / 1000);
+ // The lane's root channel is a constant forward ramp carrying no prompt
+ // signal (see ROOT_DRIFT in api/_lib/motion-seed.js), so it is removed first,
+ // before anything else reads the clip. Order matters twice over: the gate's
+ // foot-slide rule divides planted-foot slide by the stride the clip covers,
+ // and a fake one-metre stride makes that rule vacuous, and the seam search
+ // below is hunting for the frame whose pose repeats frame 0, which a ramp
+ // guarantees no frame ever does.
+ const flattened = flattenRootDrift(fetched);
+
// A loop prompt needs a clip that actually loops, and the sampler never
// returns one: it samples a window, so the last frame has no reason to meet
// the first. Close the seam before the gate sees it, or 41% of the prompt
// library is rejected for a defect we know how to repair. The repair
// self-verifies and returns the original clip untouched if closing the seam
// would cost more than it buys.
- const seam = prompt.loop === true ? closeLoopSeam(fetched) : null;
- const raw = seam ? seam.clip : fetched;
+ const seam = prompt.loop === true ? closeLoopSeam(flattened.clip) : null;
+ const raw = seam ? seam.clip : flattened.clip;
const verdict = gateMotionClip(raw, {
loop: prompt.loop === true,
@@ -268,6 +277,11 @@ async function runPrompt(prompt) {
loop_seam: seam
? { before: seam.seamBefore, after: seam.seamAfter, trimmed_frames: seam.trimmedFrames, kept_original: seam.rejected || null }
: null,
+ root_drift: {
+ speed_m_s: Number(flattened.speed.toFixed(4)),
+ removed_m: Number(flattened.removed.toFixed(4)),
+ residual_m: Number(flattened.residual.toFixed(4)),
+ },
status: verdict.pass ? 'accepted' : 'rejected',
reasons: verdict.reasons,
detail: verdict.detail || '',