@pose_flow/babylon 0.0.0-stage → 0.2.0

package/dist/offline/src/core/schema.js

@@ -0,0 +1,123 @@
+export const LOCOMOTION_SCHEMA = {
+    version: 1, id: 'biped-locomotion', channels: [
+        { id: 'left-position', kind: 'bone-position', bone: 'leftFoot', weight: 1, normalization: 'standard' },
+        { id: 'right-position', kind: 'bone-position', bone: 'rightFoot', weight: 1, normalization: 'standard' },
+        { id: 'left-velocity', kind: 'bone-velocity', bone: 'leftFoot', weight: 1, normalization: 'standard' },
+        { id: 'right-velocity', kind: 'bone-velocity', bone: 'rightFoot', weight: 1, normalization: 'standard' },
+        { id: 'root-velocity', kind: 'root-velocity', weight: 1, normalization: 'standard' },
+        { id: 'future-position', kind: 'trajectory-position', horizons: [0.2, 0.4, 0.6], weight: 3, normalization: 'standard' },
+        { id: 'future-facing', kind: 'trajectory-facing', horizons: [0.2, 0.4, 0.6], weight: 3, normalization: 'standard' },
+    ],
+};
+for (const channel of LOCOMOTION_SCHEMA.channels) {
+    if ('horizons' in channel)
+        Object.freeze(channel.horizons);
+    Object.freeze(channel);
+}
+Object.freeze(LOCOMOTION_SCHEMA.channels);
+Object.freeze(LOCOMOTION_SCHEMA);
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const name = (v) => typeof v === 'string' && /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(v);
+export function validateHorizons(input) {
+    if (!Array.isArray(input) || input.length > 64 || [...input].some((v, i) => !Number.isFinite(v) || v <= 0 || v > 10 || (i > 0 && v <= input[i - 1])))
+        throw new Error('Schema: at most 64 horizons, increasing within (0, 10] seconds');
+}
+/** Strict JSON parsing: unsupported channels/options fail instead of being ignored. */
+export function parseSchema(input) {
+    if (!record(input) || input.version !== 1 || !name(input.id) || Object.keys(input).some(k => !['version', 'id', 'channels'].includes(k))
+        || !Array.isArray(input.channels) || !input.channels.length || input.channels.length > 128)
+        throw new Error('Schema: invalid version/id/channels');
+    const ids = new Set();
+    const channels = [...input.channels].map(value => {
+        if (!record(value) || !name(value.id) || ids.has(value.id) || typeof value.weight !== 'number' || !Number.isFinite(Math.fround(value.weight)) || value.weight < 0 || (value.weight > 0 && Math.fround(value.weight) === 0)
+            || !['standard', 'none'].includes(String(value.normalization)))
+            throw new Error('Schema: invalid channel id/weight/normalization');
+        ids.add(value.id);
+        const common = { id: value.id, kind: value.kind, weight: value.weight, normalization: value.normalization };
+        let result;
+        if (value.kind === 'bone-position' || value.kind === 'bone-velocity') {
+            if (!name(value.bone) || value.bone === 'root')
+                throw new Error('Schema: invalid semantic bone role');
+            result = { ...common, bone: value.bone };
+        }
+        else if (value.kind === 'root-velocity')
+            result = common;
+        else if (value.kind === 'trajectory-position' || value.kind === 'trajectory-facing') {
+            if (!Array.isArray(value.horizons) || !value.horizons.length)
+                throw new Error('Schema: missing horizons');
+            validateHorizons(value.horizons);
+            result = { ...common, horizons: [...value.horizons] };
+        }
+        else
+            throw new Error('Schema: unsupported channel kind');
+        if (Object.keys(value).some(k => !Object.hasOwn(result, k)))
+            throw new Error('Schema: unsupported channel option');
+        return result;
+    });
+    if (!channels.some(c => c.weight > 0))
+        throw new Error('Schema: at least one positive weight required');
+    validateHorizons([...new Set(channels.flatMap(c => 'horizons' in c ? [...c.horizons] : []))].sort((a, b) => a - b));
+    return { version: 1, id: input.id, channels };
+}
+/** Canonical content identity, not a lossy hash. Order of channels is significant. */
+export function compileSchema(input) {
+    const schema = parseSchema(input), bones = new Set(), horizons = new Set();
+    let dimensions = 0;
+    const channels = schema.channels.map(channel => {
+        if ('bone' in channel)
+            bones.add(channel.bone);
+        if ('horizons' in channel)
+            channel.horizons.forEach(h => horizons.add(h));
+        const width = 'horizons' in channel ? 2 * channel.horizons.length : 3;
+        const layout = Object.freeze({ channel, offset: dimensions, dimensions: width });
+        dimensions += width;
+        if ('horizons' in channel)
+            Object.freeze(channel.horizons);
+        Object.freeze(channel);
+        return layout;
+    });
+    Object.freeze(schema.channels);
+    Object.freeze(schema);
+    return Object.freeze({ schema, signature: 'pose-schema-v1:' + JSON.stringify(schema), dimensions,
+        channels: Object.freeze(channels), bones: Object.freeze([...bones]), horizons: Object.freeze([...horizons].sort((a, b) => a - b)) });
+}
+/** One encoder shared by bake and runtime. Trajectory points follow the sorted union of horizons. */
+export class SchemaQueryBuilder {
+    layout;
+    horizonIndices;
+    constructor(schema = LOCOMOTION_SCHEMA) {
+        this.layout = compileSchema(schema);
+        this.horizonIndices = new Map(this.layout.horizons.map((h, i) => [h, i]));
+    }
+    features(pose, trajectory, out = new Float32Array(this.layout.dimensions)) {
+        if (trajectory.length !== this.layout.horizons.length || out.length !== this.layout.dimensions)
+            throw new Error('Invalid schema pose/trajectory dimensions');
+        const put = (values, offset, length) => {
+            if (!values || values.length !== length || !values.every(Number.isFinite))
+                throw new Error('Invalid schema feature values');
+            out.set(values, offset);
+        };
+        for (const { channel, offset } of this.layout.channels) {
+            if ('bone' in channel) {
+                const bone = Object.hasOwn(pose.bones, channel.bone) ? pose.bones[channel.bone] : undefined;
+                if (!bone)
+                    throw new Error('Missing semantic bone: ' + channel.bone);
+                put(channel.kind === 'bone-position' ? bone.position : bone.velocity, offset, 3);
+            }
+            else if ('horizons' in channel) {
+                channel.horizons.forEach((h, i) => {
+                    const point = trajectory[this.horizonIndices.get(h)];
+                    put(channel.kind === 'trajectory-position' ? point?.position : point?.facing, offset + i * 2, 2);
+                });
+            }
+            else
+                put(pose.rootVelocity, offset, 3);
+        }
+        if (!out.every(Number.isFinite))
+            throw new Error('Invalid schema float32 feature values');
+        return out;
+    }
+    build(pose, trajectory) {
+        return { features: this.features(pose, trajectory), schemaSignature: this.layout.signature };
+    }
+}

package/dist/offline/src/core/search.js

@@ -0,0 +1,97 @@
+import { validateDatabase } from './database.js';
+import { compileSchema, LOCOMOTION_SCHEMA } from './schema.js';
+export function defaultWeights(schema = LOCOMOTION_SCHEMA) {
+    const layout = compileSchema(schema), weights = new Float32Array(layout.dimensions);
+    for (const { channel, offset, dimensions } of layout.channels)
+        weights.fill(channel.weight, offset, offset + dimensions);
+    if (!weights.every(Number.isFinite))
+        throw new Error('Invalid feature weights');
+    return weights;
+}
+const legacySignature = compileSchema(LOCOMOTION_SCHEMA).signature;
+export class PoseSearch {
+    database;
+    normalized;
+    dimensions;
+    rootOffset;
+    weights;
+    constructor(database, weights) {
+        this.database = database;
+        validateDatabase(database);
+        this.dimensions = database.manifest.dimensions;
+        this.rootOffset = compileSchema(database.manifest.schema).channels.find(c => c.channel.kind === 'root-velocity')?.offset;
+        this.normalized = new Float32Array(this.dimensions);
+        weights ??= defaultWeights(database.manifest.schema);
+        if (weights.length !== this.dimensions || !weights.every(v => Number.isFinite(v) && v >= 0))
+            throw new Error('Invalid feature weights');
+        this.weights = weights.slice();
+    }
+    validateQuery(query) {
+        if (query.schemaSignature !== this.database.manifest.schemaSignature && !(query.schemaSignature === undefined && this.database.manifest.schemaSignature === legacySignature))
+            throw new Error('Incompatible query schema');
+        if (query.features.length !== this.dimensions || !query.features.every(Number.isFinite))
+            throw new Error('Invalid pose query');
+        if (query.allowTemporalReselection !== undefined && typeof query.allowTemporalReselection !== 'boolean')
+            throw new Error('Invalid temporal reselection option');
+        if (query.velocityTolerance !== undefined && (!Number.isFinite(query.velocityTolerance) || query.velocityTolerance < 0 || this.rootOffset === undefined))
+            throw new Error('Velocity tolerance requires a root-velocity channel and a finite nonnegative value');
+    }
+    normalize(query) {
+        this.validateQuery(query);
+        const { mean, std } = this.database.manifest;
+        for (let j = 0; j < this.dimensions; j++)
+            this.normalized[j] = (query.features[j] - mean[j]) / std[j];
+        if (!this.normalized.every(Number.isFinite))
+            throw new Error('Invalid normalized pose query');
+    }
+    cost(index) {
+        const { features } = this.database;
+        let sum = 0;
+        for (let j = 0; j < this.dimensions; j++)
+            sum += this.weights[j] * (this.normalized[j] - features[index * this.dimensions + j]) ** 2;
+        return sum;
+    }
+    /** Physical error, independent of normalization/pose weights. Query must have been validated. */
+    rootVelocityError(index, query) {
+        if (this.rootOffset === undefined || !Number.isInteger(index) || index < 0 || index >= this.database.manifest.frames.length)
+            return Infinity;
+        const { mean, std } = this.database.manifest;
+        let squared = 0;
+        for (let axis = 0; axis < 3; axis++) {
+            const j = this.rootOffset + axis, value = this.database.features[index * this.dimensions + j] * std[j] + mean[j];
+            squared += (value - query.features[j]) ** 2;
+        }
+        return Math.sqrt(squared);
+    }
+    search(query) {
+        this.normalize(query);
+        const { frames, clips } = this.database.manifest;
+        let index = -1, cost = Infinity;
+        let velocityLimit = Infinity;
+        if (query.velocityTolerance !== undefined) {
+            let nearest = Infinity;
+            for (let i = 0; i < frames.length; i++) {
+                if (query.excludedClips?.has(frames[i].clip) || (query.gaits && !query.gaits.has(clips[frames[i].clip].gait)))
+                    continue;
+                nearest = Math.min(nearest, this.rootVelocityError(i, query));
+            }
+            // Sparse datasets retain a deterministic nearest-velocity fallback. Never
+            // expand the pool to arbitrary stationary poses just because coverage is missing.
+            velocityLimit = Math.max(query.velocityTolerance, nearest + 1e-6);
+        }
+        for (let i = 0; i < frames.length; i++) {
+            if (query.excludedClips?.has(frames[i].clip))
+                continue;
+            if (query.gaits && !query.gaits.has(clips[frames[i].clip].gait))
+                continue;
+            if (query.velocityTolerance !== undefined && this.rootVelocityError(i, query) > velocityLimit)
+                continue;
+            const score = this.cost(i);
+            if (score < cost) {
+                index = i;
+                cost = score;
+            }
+        }
+        return index < 0 ? null : { ...frames[index], index, cost };
+    }
+}

package/dist/offline/src/core/types.js

@@ -0,0 +1,3 @@
+/** Legacy preset constants; dynamic consumers must use compileSchema. */
+export const DIMENSIONS = 27;
+export const HORIZONS = [0.2, 0.4, 0.6];

package/dist/offline/src/index.js

@@ -0,0 +1,8 @@
+export * from './core/types.js';
+export * from './core/schema.js';
+export * from './core/features.js';
+export * from './core/database.js';
+export * from './core/search.js';
+export * from './core/controller.js';
+export * from './core/root-motion.js';
+export * from './core/profile.js';

package/dist/offline/tools/bake.js

@@ -0,0 +1,86 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { FreeCamera, TransformNode, Vector3 } from '@babylonjs/core';
+import { hashProfileAssets, loadProfileAssets, profileArgument, publicPath, readProfile } from './profile-assets.js';
+import { buildDatabase, encodeFeatures, SchemaQueryBuilder, rootMotionFeatures, cropRootMotion, validateRootMotion, profileSignature } from '../src/index.js';
+import { BabylonMotionPlayer, BabylonSchemaPoseReader } from '../src/babylon.js';
+const profile = await readProfile(profileArgument());
+const builder = new SchemaQueryBuilder(profile.schemaDefinition), layout = builder.layout;
+const assets = await loadProfileAssets(profile);
+try {
+    const { scene, containers } = assets, body = containers.get(profile.model);
+    new FreeCamera('bake-camera', new Vector3(0, 2, -5), scene);
+    body.addAllToScene();
+    const controller = new TransformNode('bake-controller', scene);
+    body.rootNodes.forEach(n => n.parent = controller);
+    const nodes = new Map(body.transformNodes.map(n => [n.name, n])), targets = new Map(nodes);
+    for (const [source, target] of Object.entries(profile.boneMap ?? {}))
+        targets.set(source, nodes.get(target));
+    const reader = new BabylonSchemaPoseReader(controller, new Map(layout.bones.map(role => [role, nodes.get(profile.rig[role])])), layout.schema);
+    const clips = [], frames = [], raw = [], sampleRate = profile.sampleRate;
+    for (const spec of profile.clips) {
+        const { id, file, animation, gait, looping } = spec, nominalVelocity = spec.nominalVelocity ?? [0, 0, 0];
+        const source = containers.get(file).animationGroups.find(g => g.name === animation);
+        const fps = source.targetedAnimations[0].animation.framePerSecond, sourceDuration = (source.to - source.from) / fps;
+        const [start, end] = spec.range ?? [0, sourceDuration], duration = end - start;
+        let motion = spec.motionFile ? JSON.parse(await readFile(publicPath(profile.assetBase + spec.motionFile), 'utf8')) : undefined;
+        if (motion) {
+            validateRootMotion(motion);
+            motion.samples = motion.samples.map(sample => ({ ...sample, x: sample.x * profile.scale, z: sample.z * profile.scale }));
+            if (Math.abs(motion.duration - sourceDuration) > 1e-5)
+                throw new Error(`Motion/GLB time mismatch: ${id}`);
+        }
+        if (motion && spec.range)
+            motion = cropRootMotion(motion, start, end);
+        const descriptor = { id, file, animation, duration, looping, gait, ...(spec.range ? { sourceStart: start } : {}), ...(spec.rootOrientation ? { rootOrientation: spec.rootOrientation } : {}),
+            ...(motion ? { motionSource: motion.source } : { nominalVelocity, motionSource: 'nominal' }) };
+        const player = new BabylonMotionPlayer(scene, [descriptor], new Map([[id, source]]), targets, 0, profile.stripRoot ?? '');
+        const clipTime = (t) => looping ? ((t % duration) + duration) % duration : Math.max(0, Math.min(t, duration));
+        // Sample the same target model/player/root stripping used at runtime.
+        const sample = (t) => {
+            player.update({ clip: 0, time: clipTime(t), switched: false, match: null }, 0);
+            scene.render();
+            return reader.read(0);
+        };
+        try {
+            const clip = clips.length;
+            clips.push(descriptor);
+            const average = [0, 0, 0], count = Math.ceil(duration * sampleRate);
+            for (let i = 0; i < Math.ceil(duration * sampleRate); i++) {
+                const time = i / sampleRate, h = 1 / sampleRate;
+                const before = sample(time - h), after = sample(time + h), now = sample(time);
+                const measured = motion ? rootMotionFeatures(motion, time, h, layout.horizons, looping) : undefined;
+                const rootVelocity = measured?.velocity ?? nominalVelocity;
+                if (measured)
+                    for (let axis = 0; axis < 3; axis++)
+                        average[axis] += rootVelocity[axis] / count;
+                const elapsed = looping ? 2 * h : clipTime(time + h) - clipTime(time - h);
+                const bones = Object.fromEntries(layout.bones.map(role => {
+                    const position = now.bones[role].position;
+                    const velocity = position.map((_, j) => (after.bones[role].position[j] - before.bones[role].position[j]) / elapsed + rootVelocity[j]);
+                    velocity[0] += (measured?.angularVelocity ?? 0) * position[2];
+                    velocity[2] -= (measured?.angularVelocity ?? 0) * position[0];
+                    return [role, { position, velocity: velocity }];
+                }));
+                const pose = { bones, rootVelocity };
+                const future = measured?.trajectory ?? layout.horizons.map(t => ({ position: [nominalVelocity[0] * t, nominalVelocity[2] * t], facing: [0, 1] }));
+                raw.push(...builder.features(pose, future));
+                frames.push({ clip, time });
+            }
+            if (motion)
+                descriptor.averageVelocity = average;
+        }
+        finally {
+            player.dispose();
+        }
+        console.log(`${id}: ${duration.toFixed(3)}s`);
+    }
+    const db = buildDatabase({ profileId: profile.id, profileSignature: profileSignature(profile), assetHashes: await hashProfileAssets(profile), sampleRate, clips, frames }, Float32Array.from(raw), layout.schema);
+    const output = publicPath(profile.database);
+    await mkdir(output, { recursive: true });
+    await writeFile(`${output}/manifest.json`, JSON.stringify(db.manifest, null, 2));
+    await writeFile(`${output}/poses.bin`, new Uint8Array(encodeFeatures(db)));
+    console.log(`Baked ${frames.length} poses × ${layout.dimensions} features (${layout.schema.id}); ${db.features.byteLength} bytes.`);
+}
+finally {
+    assets.dispose();
+}

package/dist/offline/tools/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/** Node-only entry; paths are relative to the caller, never to this installation. */
+const command = process.argv[2];
+try {
+    if (command === 'bake')
+        await import('./bake.js');
+    else if (command === 'prepare') {
+        const at = process.argv.indexOf('--config');
+        if (at < 0 || !process.argv[at + 1])
+            throw new Error('Provide --config preparation.json');
+        const { readFile } = await import('node:fs/promises');
+        const { parsePreparation, prepareGLB } = await import('./prepare.js');
+        console.log(JSON.stringify(await prepareGLB(parsePreparation(JSON.parse(await readFile(process.argv[at + 1], 'utf8')))), null, 2));
+    }
+    else if (command === 'validate' || command === 'inspect') {
+        if (command === 'inspect')
+            process.argv.splice(3, 0, '--inspect');
+        await import('./validate-assets.js');
+    }
+    else {
+        console.log('pose-flow bake|validate --profile public/profiles/rig.json [--public-dir public]\npose-flow inspect model.glb\npose-flow prepare --config preparation.json');
+        if (command && command !== '--help')
+            process.exitCode = 1;
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+export {};

package/dist/offline/tools/glb.js

@@ -0,0 +1,54 @@
+export function readGLB(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (bytes.length < 20 || view.getUint32(0, true) !== 0x46546c67 || view.getUint32(4, true) !== 2 || view.getUint32(8, true) !== bytes.length)
+        throw new Error('Invalid GLB header');
+    let json, binary = new Uint8Array();
+    for (let offset = 12; offset < bytes.length;) {
+        if (offset + 8 > bytes.length)
+            throw new Error('Truncated GLB chunk');
+        const length = view.getUint32(offset, true), kind = view.getUint32(offset + 4, true);
+        offset += 8;
+        if (length % 4 || offset + length > bytes.length)
+            throw new Error('Invalid GLB chunk');
+        if (kind === 0x4e4f534a)
+            json = JSON.parse(new TextDecoder().decode(bytes.subarray(offset, offset + length)));
+        else if (kind === 0x004e4942)
+            binary = bytes.slice(offset, offset + length);
+        offset += length;
+    }
+    if (!json || json.buffers?.length !== 1 || json.buffers[0].uri || json.buffers[0].byteLength > binary.length || json.images?.some(i => i.uri && !i.uri.startsWith('data:')))
+        throw new Error('Preparation requires a self-contained GLB with one embedded buffer/images');
+    return { json, binary };
+}
+export function writeGLB(json, binary) {
+    const data = new TextEncoder().encode(JSON.stringify(json)), jsonLength = Math.ceil(data.length / 4) * 4, binLength = Math.ceil(binary.length / 4) * 4;
+    const output = new Uint8Array(28 + jsonLength + binLength), view = new DataView(output.buffer);
+    view.setUint32(0, 0x46546c67, true);
+    view.setUint32(4, 2, true);
+    view.setUint32(8, output.length, true);
+    view.setUint32(12, jsonLength, true);
+    view.setUint32(16, 0x4e4f534a, true);
+    output.fill(32, 20, 20 + jsonLength);
+    output.set(data, 20);
+    view.setUint32(20 + jsonLength, binLength, true);
+    view.setUint32(24 + jsonLength, 0x004e4942, true);
+    output.set(binary, 28 + jsonLength);
+    return output;
+}
+export function appendFloats(document, values, width) {
+    if (!values.length || values.length % width || !values.every(Number.isFinite))
+        throw new Error('Invalid prepared samples');
+    const { json } = document, offset = Math.ceil(document.binary.length / 4) * 4;
+    const binary = new Uint8Array(offset + values.length * 4);
+    binary.set(document.binary);
+    const view = new DataView(binary.buffer);
+    values.forEach((v, i) => view.setFloat32(offset + i * 4, v, true));
+    const bufferView = (json.bufferViews ??= []).length;
+    json.bufferViews.push({ buffer: 0, byteOffset: offset, byteLength: values.length * 4 });
+    const accessor = (json.accessors ??= []).length;
+    json.accessors.push({ bufferView, componentType: 5126, count: values.length / width, type: width === 1 ? 'SCALAR' : 'VEC' + width,
+        ...(width === 1 ? { min: [values.reduce((min, v) => Math.min(min, v), Infinity)], max: [values.reduce((max, v) => Math.max(max, v), -Infinity)] } : {}) });
+    json.buffers[0].byteLength = binary.length;
+    document.binary = binary;
+    return accessor;
+}

package/dist/offline/tools/prepare.js

@@ -0,0 +1,165 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { FreeCamera, Matrix, NullEngine, Quaternion, Scene, SceneLoader, Vector3 } from '@babylonjs/core';
+import { GLTFFileLoader } from '@babylonjs/loaders/glTF/index.js';
+import { validateRootMotion } from '../src/index.js';
+import { appendFloats, readGLB, writeGLB } from './glb.js';
+export function parsePreparation(input) {
+    if (!input || typeof input !== 'object')
+        throw new Error('Invalid preparation config');
+    const c = input;
+    if (c.version !== 1 || ![c.input, c.output, c.animation, c.rootNode].every(v => typeof v === 'string' && v.trim())
+        || !['root', 'hips'].includes(c.source) || !['horizontal', 'all'].includes(c.position) || typeof c.heading !== 'boolean'
+        || !Number.isFinite(c.sampleRate) || c.sampleRate < 1 || c.sampleRate > 120
+        || (c.unitScale !== undefined && (!Number.isFinite(c.unitScale) || c.unitScale <= 0))
+        || (c.yawOffset !== undefined && !Number.isFinite(c.yawOffset)))
+        throw new Error('Invalid preparation config');
+    if (c.playbackRate !== undefined && (!Number.isFinite(c.playbackRate) || c.playbackRate < .25 || c.playbackRate > 4))
+        throw new Error('Preparation playbackRate must be between .25 and 4');
+    if (!c.input.endsWith('.glb') || !c.output.endsWith('.glb') || resolve(c.input) === resolve(c.output))
+        throw new Error('Preparation requires distinct input/output GLB paths');
+    return structuredClone(c);
+}
+/** Offline only. No character names; the prepared GLB and measured track are a pair. */
+export async function prepareGLB(input) {
+    const config = parsePreparation(input), bytes = new Uint8Array(await readFile(config.input)), document = readGLB(bytes), { json } = document;
+    const matches = json.nodes.flatMap((node, index) => node.name === config.rootNode ? [index] : []);
+    if (matches.length !== 1)
+        throw new Error('Missing/ambiguous preparation root node');
+    const rootIndex = matches[0];
+    const animations = json.animations?.filter(a => a.name === config.animation);
+    if (animations?.length !== 1)
+        throw new Error('Missing/ambiguous preparation animation');
+    const selected = animations[0];
+    json.animations = [selected];
+    // Keep axis/unit conversion in the exported GLB, not only in the measured JSON.
+    const conversion = Matrix.Scaling(config.unitScale ?? 1, config.unitScale ?? 1, config.unitScale ?? 1).multiply(Matrix.RotationY(config.yawOffset ?? 0));
+    for (const index of json.scenes[json.scene ?? 0].nodes) {
+        const node = json.nodes[index];
+        const original = node.matrix ? Matrix.FromArray(node.matrix) : Matrix.Compose(Vector3.FromArray(node.scale ?? [1, 1, 1]), Quaternion.FromArray(node.rotation ?? [0, 0, 0, 1]), Vector3.FromArray(node.translation ?? [0, 0, 0]));
+        if (selected.channels.some(c => c.target.node === index))
+            throw new Error('Animated scene root requires offline axis/unit conversion before preparation');
+        node.matrix = original.multiply(conversion).asArray();
+        delete node.translation;
+        delete node.rotation;
+        delete node.scale;
+    }
+    const engine = new NullEngine(), scene = new Scene(engine);
+    scene.useRightHandedSystem = true;
+    new FreeCamera('preparation-camera', new Vector3(0, 2, -5), scene);
+    const hook = SceneLoader.OnPluginActivatedObservable.add(p => { if (p instanceof GLTFFileLoader)
+        p.skipMaterials = true; });
+    try {
+        const container = await SceneLoader.LoadAssetContainerAsync('', writeGLB(json, document.binary), scene, undefined, '.glb');
+        container.animationGroups.forEach(g => g.stop());
+        container.addAllToScene();
+        const roots = container.transformNodes.filter(n => n.name === config.rootNode);
+        if (roots.length !== 1)
+            throw new Error('Missing/ambiguous evaluated root');
+        const root = roots[0], group = container.animationGroups[0], fps = group.targetedAnimations[0]?.animation.framePerSecond;
+        if (!fps || group.targetedAnimations.some(t => t.animation.framePerSecond !== fps) || group.to <= group.from)
+            throw new Error('Invalid preparation clip/FPS');
+        const duration = (group.to - group.from) / fps, count = Math.ceil(duration * config.sampleRate);
+        if (count > 1_000_000)
+            throw new Error('Preparation clip too long');
+        const times = [], positions = [], rotations = [], motion = { version: 1, source: config.source, duration, samples: [] };
+        let initialPosition, initialRotation, previousYaw = 0, previousQ;
+        group.start(true, 0);
+        group.pause();
+        for (let i = 0; i <= count; i++) {
+            const time = duration * i / count;
+            group.goToFrame(group.from + time * fps, true);
+            scene.render();
+            root.computeWorldMatrix(true);
+            const scale = new Vector3(), rotation = new Quaternion(), position = new Vector3();
+            if (!root.getWorldMatrix().decompose(scale, rotation, position) || Math.min(scale.x, scale.y, scale.z) <= 0 || Math.max(scale.x, scale.y, scale.z) - Math.min(scale.x, scale.y, scale.z) > 1e-4)
+                throw new Error('Preparation requires positive uniform world scale without shear');
+            const recomposed = Matrix.Compose(scale, rotation, position).asArray();
+            if (root.getWorldMatrix().asArray().some((v, j) => Math.abs(v - recomposed[j]) > 1e-4))
+                throw new Error('Preparation does not support shear');
+            if (root.parent) {
+                const parentScale = new Vector3();
+                root.parent.getWorldMatrix().decompose(parentScale);
+                if (Math.min(parentScale.x, parentScale.y, parentScale.z) <= 0 || Math.max(parentScale.x, parentScale.y, parentScale.z) - Math.min(parentScale.x, parentScale.y, parentScale.z) > 1e-4)
+                    throw new Error('Preparation requires a uniformly scaled root parent');
+            }
+            initialPosition ??= position.clone();
+            initialRotation ??= rotation.clone();
+            const relative = rotation.multiply(initialRotation.conjugate()), forward = new Vector3(0, 0, 1).applyRotationQuaternion(relative);
+            if (config.heading && Math.hypot(forward.x, forward.z) < 1e-5)
+                throw new Error('Undefined planar heading');
+            const angle = Math.atan2(forward.x, forward.z), yaw = config.heading ? previousYaw + Math.atan2(Math.sin(angle - previousYaw), Math.cos(angle - previousYaw)) : 0;
+            previousYaw = yaw;
+            motion.samples.push({ time, x: position.x - initialPosition.x, z: position.z - initialPosition.z, yaw });
+            position.x = initialPosition.x;
+            position.z = initialPosition.z;
+            if (config.position === 'all')
+                position.y = initialPosition.y;
+            const corrected = Matrix.Compose(scale, Quaternion.RotationAxis(Vector3.Up(), -yaw).multiply(rotation), position);
+            const local = root.parent ? corrected.multiply(Matrix.Invert(root.parent.getWorldMatrix())) : corrected;
+            const localScale = new Vector3(), q = new Quaternion(), p = new Vector3();
+            if (!local.decompose(localScale, q, p))
+                throw new Error('Cannot decompose prepared root');
+            if (i === 0) {
+                const node = json.nodes[rootIndex];
+                delete node.matrix;
+                node.translation = p.asArray();
+                node.rotation = q.asArray();
+                node.scale = localScale.asArray();
+            }
+            if (previousQ && Quaternion.Dot(previousQ, q) < 0)
+                q.scaleInPlace(-1);
+            previousQ = q;
+            times.push(time);
+            positions.push(p.x, p.y, p.z);
+            rotations.push(q.x, q.y, q.z, q.w);
+        }
+        const rate = config.playbackRate ?? 1;
+        motion.duration /= rate;
+        motion.samples.forEach(s => s.time /= rate);
+        validateRootMotion(motion);
+        const timeAccessor = appendFloats(document, times.map(t => t / rate), 1);
+        selected.channels = selected.channels.filter(c => c.target.node !== rootIndex || !['translation', 'rotation'].includes(c.target.path));
+        if (rate !== 1) {
+            const remapped = new Map();
+            for (const index of new Set(selected.channels.map(c => c.sampler))) {
+                const sampler = selected.samplers[index];
+                if (sampler.interpolation === 'CUBICSPLINE')
+                    throw new Error('Time scaling requires LINEAR/STEP source channels; resample cubic channels offline first');
+                if (!remapped.has(sampler.input)) {
+                    const accessor = json.accessors[sampler.input];
+                    if (accessor.type !== 'SCALAR' || accessor.componentType !== 5126 || accessor.sparse)
+                        throw new Error('Unsupported timeline accessor');
+                    const view = json.bufferViews[accessor.bufferView];
+                    const data = new DataView(document.binary.buffer, document.binary.byteOffset, document.binary.byteLength);
+                    const values = Array.from({ length: accessor.count }, (_, i) => data.getFloat32((view.byteOffset ?? 0) + (accessor.byteOffset ?? 0) + i * (view.byteStride ?? 4), true) / rate);
+                    remapped.set(sampler.input, appendFloats(document, values, 1));
+                }
+                sampler.input = remapped.get(sampler.input);
+            }
+        }
+        for (const [path, values, width] of [['translation', positions, 3], ['rotation', rotations, 4]]) {
+            const sampler = selected.samplers.length;
+            selected.samplers.push({ input: timeAccessor, output: appendFloats(document, [...values], width), interpolation: 'LINEAR' });
+            selected.channels.push({ sampler, target: { node: rootIndex, path } });
+        }
+        // Babylon GLTF frames are seconds × FPS; GLTF accessor times are seconds.
+        // Reject nonzero source origins rather than silently offsetting other channels.
+        if (Math.abs(group.from) > 1e-5)
+            throw new Error('Preparation requires source animation starting at zero; crop/convert offline first');
+        const output = resolve(config.output), motionFile = output.replace(/\.glb$/, '.motion.json');
+        await mkdir(dirname(output), { recursive: true });
+        await writeFile(output, writeGLB(json, document.binary));
+        await writeFile(motionFile, JSON.stringify(motion, null, 2));
+        const report = { config, inputSHA256: createHash('sha256').update(bytes).digest('hex'), duration: motion.duration, samples: times.length,
+            displacement: motion.samples.at(-1), note: 'Paired prepared GLB + measured planar trajectory. No retargeting; preserve source provenance/license. Horizontal policy preserves vertical motion.' };
+        await writeFile(output.replace(/\.glb$/, '.preparation.json'), JSON.stringify(report, null, 2));
+        return report;
+    }
+    finally {
+        SceneLoader.OnPluginActivatedObservable.remove(hook);
+        scene.dispose();
+        engine.dispose();
+    }
+}