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(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.jsnew file mode 100644index 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.jsindex 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, tasblendMode: 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.mjsindex 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 || '',