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): close the loop seam so a generated walk stops popping every cycle
nirholasa84aa6d3b520
diff --git a/api/_lib/motion-quality.js b/api/_lib/motion-quality.jsindex 8d31c6d41..2313b5130 100644--- a/api/_lib/motion-quality.js+++ b/api/_lib/motion-quality.js@@ -35,7 +35,7 @@ import {CANONICAL_REST_POSITION,CANONICAL_REST_WORLD,} from '../../src/animation-canonical-rest.js';-import { worldMotionMetrics, footContactMetrics } from './motion-seed.js';+import { worldMotionMetrics, footContactMetrics, loopSeamDistance } from './motion-seed.js';export const MOTION_GATE_VERSION = 2;@@ -73,9 +73,14 @@ export const MOTION_BOUNDS = Object.freeze({// median of 1.69 and a worst case of 5.79, so 6.5 leaves headroom.// See docs/animation-seeding.md.maxWorldStepRatio: 6.5,- // Loop clips only: the pose distance between the first and last frame. A- // seam wider than this visibly pops every cycle.- maxLoopSeamDeg: 30,+ // Loop clips only: how far, in metres, a joint sits from where it started,+ // measured hips-relative in world space so a travelling loop still counts as+ // a loop. Measured on local rotations instead this reports a 178 degree seam+ // on a clip whose joints are 2.9 cm apart, because the twist flips the child+ // bone cancels land in that comparison too. Authored loops sit at 0.000 and a+ // generated clip run through closeLoopSeam() also lands at 0.000, while a raw+ // generated walk ends 0.25 m out.+ maxLoopSeamMetres: 0.08,// Space.// Planted-foot drift as a multiple of the stride the clip actually covers,@@ -522,7 +527,7 @@ export function decideMotionVerdict(m, opts = {}) {if (m.maxRootSpeedMetresPerSecond > b.maxRootSpeedMetresPerSecond) reasons.push('root_velocity_implausible');if (m.slidePerStride > b.maxSlidePerStride) reasons.push('foot_slide');if (m.groundPenetrationMetres > b.maxGroundPenetration) reasons.push('ground_penetration');- if (opts.loop && m.loopSeamDeg > b.maxLoopSeamDeg) reasons.push('loop_seam_open');+ if (opts.loop && m.loopSeamMetres > b.maxLoopSeamMetres) reasons.push('loop_seam_open');const requested = Number(opts.requestedDuration);if (Number.isFinite(requested) && requested > 0) {@@ -566,6 +571,7 @@ export function gateMotionClip(raw, opts = {}) {metrics.worstWitnessJoint = world.continuityJoint;metrics.slidePerStride = foot.slidePerStride;metrics.plantedFrames = foot.plantedFrames;+ metrics.loopSeamMetres = loopSeamDistance(raw);const { pass, reasons } = decideMotionVerdict(metrics, opts);return { pass, reasons, detail: '', metrics, gateVersion: MOTION_GATE_VERSION };}diff --git a/api/_lib/motion-seed.js b/api/_lib/motion-seed.jsindex f59ada178..55548b209 100644--- a/api/_lib/motion-seed.js+++ b/api/_lib/motion-seed.js@@ -714,3 +714,201 @@ export function assertSelfHostedLane(jobId) {}return { host, taskId: envelope.taskId };}++// ── Loop seams ──────────────────────────────────────────────────────────────+//+// A motion-diffusion sampler does not produce seamless loops: it samples a+// window, and the last frame has no reason to meet the first. Measured on real+// output, a generated walk ends 25 cm (per joint, hips-relative) away from where+// it started, while the authored library's loop clips sit at 0.000. Since 41% of+// data/motion-prompts.json is tagged `loop`, publishing generated clips as loops+// without closing the seam would ship a library that visibly pops every cycle.+//+// Seam distance is measured in world space, hips-relative, for the same reason+// the continuity test is: comparing the first and last LOCAL rotations reports a+// 178 degree seam on a clip whose joints are actually 2.9 cm apart, because the+// twist flips the child bone cancels land in that comparison too.++const SEAM_JOINTS = Object.freeze([+ 'LeftHand',+ 'RightHand',+ 'LeftToeBase',+ 'RightToeBase',+ 'Head',+ 'LeftFoot',+ 'RightFoot',+ 'Spine2',+]);++/**+ * How far frame `a` is from frame `b`, per joint, ignoring where the body has+ * travelled to (a travelling walk loop is still a loop).+ */+function seamDistanceBetween(clip, a, b) {+ const pa = forwardKinematicsFrame(clip, a);+ const pb = forwardKinematicsFrame(clip, b);+ const ha = pa.Hips;+ const hb = pb.Hips;+ if (!ha || !hb) return Infinity;+ let worst = 0;+ for (const joint of SEAM_JOINTS) {+ if (!pa[joint] || !pb[joint]) continue;+ const d = Math.hypot(+ pb[joint][0] - hb[0] - (pa[joint][0] - ha[0]),+ pb[joint][1] - hb[1] - (pa[joint][1] - ha[1]),+ pb[joint][2] - hb[2] - (pa[joint][2] - ha[2]),+ );+ worst = Math.max(worst, d);+ }+ return worst;+}++/** World-space seam of a clip as it stands: frame 0 against the final frame. */+export function loopSeamDistance(clip) {+ const frames = frameCount(clip);+ if (frames < 2) return 0;+ return seamDistanceBetween(clip, 0, frames - 1);+}++function slerp(a, b, t) {+ let [bx, by, bz, bw] = b;+ let dot = a[0] * bx + a[1] * by + a[2] * bz + a[3] * bw;+ // Take the short way round; q and -q are the same rotation.+ if (dot < 0) {+ bx = -bx;+ by = -by;+ bz = -bz;+ bw = -bw;+ dot = -dot;+ }+ if (dot > 0.9995) {+ const out = [+ a[0] + (bx - a[0]) * t,+ a[1] + (by - a[1]) * t,+ a[2] + (bz - a[2]) * t,+ a[3] + (bw - a[3]) * t,+ ];+ const len = Math.hypot(...out) || 1;+ return out.map((v) => v / len);+ }+ const theta = Math.acos(Math.min(1, dot));+ const sin = Math.sin(theta);+ const wa = Math.sin((1 - t) * theta) / sin;+ const wb = Math.sin(t * theta) / sin;+ return [a[0] * wa + bx * wb, a[1] * wa + by * wb, a[2] * wa + bz * wb, a[3] * wa + bw * wb];+}++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.+ MAX_TRIM_FRACTION: 0.35,+ // Frames blended back toward the start. Long enough to hide the correction,+ // short enough not to smear the motion.+ BLEND_FRAMES: 8,+ // A seam this small is already invisible; authored loops sit at 0.000.+ TARGET: 0.02,+ // A trim must beat the untrimmed seam by at least this much to be worth+ // taking. Without it a clip whose seam is already nearly closed gets a third+ // of its length cut off chasing a millimetre, and the blend that follows has+ // to move a joint far enough to create the very pop this is meant to avoid.+ TRIM_IMPROVEMENT: 0.7,+});++/**+ * Close a generated clip's loop seam.+ *+ * Two steps, in order:+ * 1. Trim to the cycle. Search the tail for the frame whose pose is closest to+ * frame 0 and cut there. For a periodic motion (a walk, an idle) this alone+ * usually finds a near-perfect seam, because the cycle really is in there.+ * 2. Blend what is left. Over the final BLEND_FRAMES, slerp each rotation+ * toward the value it holds at frame 0, ramping to a full match on the last+ * frame, so the seam closes exactly. The root's height is matched the same+ * way while its horizontal travel is preserved, so a travelling walk still+ * travels.+ *+ * Returns a NEW clip; the input is not modified. A clip with too few frames to+ * work with is returned unchanged, so this is always safe to call.+ */+export function closeLoopSeam(clip, opts = {}) {+ const blendFrames = opts.blendFrames ?? LOOP_SEAM.BLEND_FRAMES;+ const maxTrim = opts.maxTrimFraction ?? LOOP_SEAM.MAX_TRIM_FRACTION;+ const frames = frameCount(clip);+ if (frames < blendFrames * 3) return { clip, trimmedFrames: 0, seamBefore: 0, seamAfter: 0 };++ const seamBefore = seamDistanceBetween(clip, 0, frames - 1);++ // 1. Find the best cycle end in the tail.+ const earliest = Math.max(blendFrames * 2, Math.floor(frames * (1 - maxTrim)));+ let bestEnd = frames - 1;+ let bestDistance = seamBefore;+ for (let k = earliest; k < frames; k += 1) {+ const d = seamDistanceBetween(clip, 0, k);+ if (d < bestDistance) {+ bestDistance = d;+ bestEnd = k;+ }+ }+ // Only pay for a trim that actually buys a better seam.+ if (bestEnd !== frames - 1 && bestDistance > seamBefore * LOOP_SEAM.TRIM_IMPROVEMENT) {+ bestEnd = frames - 1;+ }++ // 2. Rebuild the clip up to that frame, blending the tail back to the start.+ const keep = bestEnd + 1;+ const tracks = [];+ for (const track of clip.tracks ?? []) {+ const stride = track.type === 'quaternion' ? 4 : 3;+ const available = Math.floor(track.values.length / stride);+ const n = Math.min(keep, available);+ const times = Array.from(track.times).slice(0, n);+ const values = Array.from(track.values).slice(0, n * stride);++ const first = values.slice(0, stride);+ const blend = Math.min(blendFrames, n - 1);+ for (let i = 0; i < blend; i += 1) {+ const index = n - blend + i;+ // Ramp to a full match on the final frame.+ const t = (i + 1) / blend;+ const at = index * stride;+ if (track.type === 'quaternion') {+ const blended = slerp(values.slice(at, at + 4), first, t);+ for (let c = 0; c < 4; c += 1) values[at + c] = blended[c];+ } else {+ // Height and depth-of-stance are matched; horizontal travel is kept,+ // so a travelling loop still covers ground.+ values[at + 1] += (first[1] - values[at + 1]) * t;+ }+ }+ tracks.push({ ...track, times, values });+ }++ const fps = frames > 1 ? (frames - 1) / Math.max(clip.duration, 1e-6) : 30;+ const closed = { ...clip, duration: (keep - 1) / fps, tracks };++ // Self-verify. Closing a seam moves joints, and on a clip that barely needed+ // it the correction can cost more than the seam did. If the result is less+ // continuous than the gate allows while the original was fine, keep the+ // original and say so rather than publishing a clip this made worse.+ const after = worldMotionMetrics(closed);+ const original = worldMotionMetrics(clip);+ if (+ after.continuity > MOTION_GATE.MAX_WORLD_STEP_RATIO &&+ original.continuity <= MOTION_GATE.MAX_WORLD_STEP_RATIO+ ) {+ return {+ clip,+ trimmedFrames: 0,+ seamBefore,+ seamAfter: seamBefore,+ rejected: 'closing the seam would have cost more continuity than it bought',+ };+ }++ return {+ clip: closed,+ trimmedFrames: frames - keep,+ seamBefore,+ seamAfter: loopSeamDistance(closed),+ };+}diff --git a/tests/motion-seed.test.js b/tests/motion-seed.test.jsindex c8f3ee934..9b708e333 100644--- a/tests/motion-seed.test.js+++ b/tests/motion-seed.test.js@@ -28,6 +28,9 @@ import {motionPromptById,assertSelfHostedLane,decodeJobEnvelope,+ closeLoopSeam,+ loopSeamDistance,+ LOOP_SEAM,} from '../api/_lib/motion-seed.js';const BODY_BONES = [@@ -341,3 +344,75 @@ describe('lane assertion', () => {expect(() => assertSelfHostedLane('not-base64-json')).toThrow(/not a provider envelope/);});});++describe('loop seams', () => {+ /** A clip whose pose at the end is deliberately far from where it started. */+ const openSeam = () =>+ buildClip({+ frames: 120,+ mutate: (c) => {+ for (const track of c.tracks) {+ if (track.type !== 'quaternion') continue;+ const n = track.values.length / 4;+ // Drift the last third away from the opening pose.+ for (let i = Math.floor(n * 0.66); i < n; i += 1) {+ const t = (i - n * 0.66) / (n - n * 0.66);+ const q = quatX(0.9 * t);+ for (let c2 = 0; c2 < 4; c2 += 1) track.values[i * 4 + c2] = q[c2];+ }+ }+ },+ });++ it('measures the seam in metres, hips relative', () => {+ expect(loopSeamDistance(openSeam())).toBeGreaterThan(LOOP_SEAM.TARGET);+ });++ it('closes an open seam', () => {+ const result = closeLoopSeam(openSeam());+ expect(result.seamAfter).toBeLessThan(result.seamBefore);+ expect(result.seamAfter).toBeLessThanOrEqual(LOOP_SEAM.TARGET);+ });++ it('does not modify the clip it was given', () => {+ const clip = openSeam();+ const before = JSON.stringify(clip.tracks[0].values);+ closeLoopSeam(clip);+ expect(JSON.stringify(clip.tracks[0].values)).toBe(before);+ });++ it('leaves a clip that is already seamless alone rather than trimming it', () => {+ const clip = buildClip({ frames: 120 });+ const result = closeLoopSeam(clip);+ expect(result.trimmedFrames).toBe(0);+ });++ it('never trims away more than the cap', () => {+ const clip = openSeam();+ const result = closeLoopSeam(clip);+ expect(result.trimmedFrames).toBeLessThanOrEqual(Math.ceil(120 * LOOP_SEAM.MAX_TRIM_FRACTION));+ });++ it('keeps the closed clip playable', () => {+ const result = closeLoopSeam(openSeam());+ const verdict = gateMotionClip(result.clip, {});+ expect(verdict.reasons).not.toContain('non_finite_keyframes');+ expect(verdict.reasons.some((r) => r.startsWith('world_discontinuity'))).toBe(false);+ });++ it('is safe to call on a clip too short to work with', () => {+ const tiny = { name: 't', duration: 0.1, tracks: [], uuid: 'u', blendMode: 0 };+ expect(closeLoopSeam(tiny).clip).toBe(tiny);+ });++ it('preserves horizontal travel so a walking loop still covers ground', () => {+ const clip = openSeam();+ const result = closeLoopSeam(clip);+ const hips = result.clip.tracks.find((t) => t.name === 'Hips.position');+ const n = hips.values.length / 3;+ // The root track is built with zero travel here, so assert the axis was+ // left untouched rather than dragged back to the start by the blend.+ expect(Number.isFinite(hips.values[(n - 1) * 3])).toBe(true);+ expect(hips.values[(n - 1) * 3]).toBe(clip.tracks.find((t) => t.name === 'Hips.position').values[(n - 1) * 3]);+ });+});