@pose_flow/babylon 0.0.0-stage → 0.2.0

package/dist/core/root-motion.d.ts

@@ -0,0 +1,24 @@
+import { type TrajectoryPoint } from './types.js';
+export interface RootMotionSample {
+    time: number;
+    x: number;
+    z: number;
+    yaw: number;
+}
+/** Unwrapped yaw in radians. Root track is a bake input, never a movement command. */
+export interface RootMotionTrack {
+    version: 1;
+    duration: number;
+    source: 'hips' | 'root';
+    samples: RootMotionSample[];
+}
+export declare function validateRootMotion(track: RootMotionTrack): void;
+/** Clamped sampling for non-looping clips; completed motion stays at its endpoint. */
+export declare function sampleRootMotion(track: RootMotionTrack, time: number, looping?: boolean): RootMotionSample;
+export declare function rootMotionFeatures(track: RootMotionTrack, time: number, derivativeStep?: number, horizons?: readonly number[], looping?: boolean): {
+    velocity: readonly [number, number, number];
+    angularVelocity: number;
+    trajectory: TrajectoryPoint[];
+};
+/** Crop to the same source interval as playback; preserve the source coordinate frame. */
+export declare function cropRootMotion(track: RootMotionTrack, start: number, end: number): RootMotionTrack;

package/dist/core/root-motion.js

@@ -0,0 +1,78 @@
+import { HORIZONS } from './types.js';
+import { toLocal } from './features.js';
+import { validateHorizons } from './schema.js';
+export function validateRootMotion(track) {
+    if (!track || track.version !== 1 || !['hips', 'root'].includes(track.source) || !Number.isFinite(track.duration) || track.duration <= 0 || !Array.isArray(track.samples) || track.samples.length < 2)
+        throw new Error('Invalid root motion track');
+    let previous = -Infinity;
+    for (const sample of track.samples) {
+        if (!sample || ![sample.time, sample.x, sample.z, sample.yaw].every(Number.isFinite) || sample.time <= previous || sample.time < 0 || sample.time > track.duration + 1e-6)
+            throw new Error('Invalid root motion sample');
+        previous = sample.time;
+    }
+    if (track.samples[0].time !== 0 || Math.abs(track.samples.at(-1).time - track.duration) > 1e-6)
+        throw new Error('Incomplete root motion track');
+}
+/** Clamped sampling for non-looping clips; completed motion stays at its endpoint. */
+export function sampleRootMotion(track, time, looping = false) {
+    if (!Number.isFinite(time))
+        throw new Error('Invalid root motion time');
+    if (looping) {
+        const cycle = Math.floor(time / track.duration), phase = time - cycle * track.duration;
+        if (!Number.isSafeInteger(cycle))
+            throw new Error('Root motion cycle out of range');
+        const first = track.samples[0], last = track.samples.at(-1);
+        const delta = toLocal(last.x - first.x, last.z - first.z, first.yaw), angle = last.yaw - first.yaw;
+        // Exponentiate planar rigid transforms, including negative cycles.
+        const compose = (a, b) => ({ time,
+            x: a.x + Math.cos(a.yaw) * b.x + Math.sin(a.yaw) * b.z,
+            z: a.z - Math.sin(a.yaw) * b.x + Math.cos(a.yaw) * b.z, yaw: a.yaw + b.yaw });
+        let power = { time, x: delta[0], z: delta[1], yaw: angle };
+        if (cycle < 0) {
+            const v = toLocal(-power.x, -power.z, angle);
+            power = { time, x: v[0], z: v[1], yaw: -angle };
+        }
+        let result = { time, x: 0, z: 0, yaw: 0 }, count = Math.abs(cycle);
+        while (count > 0) {
+            if (count % 2 === 1)
+                result = compose(result, power);
+            power = compose(power, power);
+            count = Math.floor(count / 2);
+        }
+        const sample = sampleRootMotion(track, phase), local = toLocal(sample.x - first.x, sample.z - first.z, first.yaw);
+        return compose(first, compose(result, { time, x: local[0], z: local[1], yaw: sample.yaw - first.yaw }));
+    }
+    const t = Math.max(0, Math.min(time, track.duration)), samples = track.samples;
+    let lo = 0, hi = samples.length - 1;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >>> 1;
+        if (samples[mid].time <= t)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const a = samples[lo], b = samples[hi], alpha = (t - a.time) / (b.time - a.time);
+    return { time: t, x: a.x + (b.x - a.x) * alpha, z: a.z + (b.z - a.z) * alpha, yaw: a.yaw + (b.yaw - a.yaw) * alpha };
+}
+export function rootMotionFeatures(track, time, derivativeStep = 1 / 30, horizons = HORIZONS, looping = false) {
+    validateHorizons(horizons);
+    if (!Number.isFinite(derivativeStep) || derivativeStep <= 0)
+        throw new Error('Invalid derivative step');
+    const now = sampleRootMotion(track, time, looping), a = sampleRootMotion(track, time - derivativeStep, looping), b = sampleRootMotion(track, time + derivativeStep, looping);
+    const elapsed = b.time - a.time;
+    const v = elapsed > 0 ? toLocal((b.x - a.x) / elapsed, (b.z - a.z) / elapsed, now.yaw) : [0, 0];
+    return { velocity: [v[0], 0, v[1]], angularVelocity: elapsed > 0 ? (b.yaw - a.yaw) / elapsed : 0,
+        trajectory: horizons.map(horizon => {
+            const future = sampleRootMotion(track, time + horizon, looping), yaw = future.yaw - now.yaw;
+            return { position: toLocal(future.x - now.x, future.z - now.z, now.yaw), facing: [Math.sin(yaw), Math.cos(yaw)] };
+        }) };
+}
+/** Crop to the same source interval as playback; preserve the source coordinate frame. */
+export function cropRootMotion(track, start, end) {
+    validateRootMotion(track);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end <= start || end > track.duration)
+        throw new Error('Invalid root motion range');
+    const samples = [sampleRootMotion(track, start), ...track.samples.filter(s => s.time > start && s.time < end), sampleRootMotion(track, end)]
+        .map(s => ({ ...s, time: s.time - start }));
+    return { version: 1, source: track.source, duration: end - start, samples };
+}

package/dist/core/schema.d.ts

@@ -0,0 +1,56 @@
+import type { Query, Vec3, TrajectoryPoint } from './types.js';
+export type Normalization = 'standard' | 'none';
+interface ChannelBase {
+    id: string;
+    weight: number;
+    normalization: Normalization;
+}
+export type FeatureChannel = ChannelBase & ({
+    kind: 'bone-position' | 'bone-velocity';
+    bone: string;
+} | {
+    kind: 'root-velocity';
+} | {
+    kind: 'trajectory-position' | 'trajectory-facing';
+    horizons: readonly number[];
+});
+export interface PoseSchema {
+    version: 1;
+    id: string;
+    channels: readonly FeatureChannel[];
+}
+export interface SchemaPose {
+    bones: Readonly<Record<string, {
+        position: Vec3;
+        velocity: Vec3;
+    }>>;
+    rootVelocity: Vec3;
+}
+export interface ChannelLayout {
+    channel: FeatureChannel;
+    offset: number;
+    dimensions: number;
+}
+export interface CompiledSchema {
+    schema: PoseSchema;
+    signature: string;
+    dimensions: number;
+    channels: readonly ChannelLayout[];
+    bones: readonly string[];
+    horizons: readonly number[];
+}
+export declare const LOCOMOTION_SCHEMA: PoseSchema;
+export declare function validateHorizons(input: readonly number[]): void;
+/** Strict JSON parsing: unsupported channels/options fail instead of being ignored. */
+export declare function parseSchema(input: unknown): PoseSchema;
+/** Canonical content identity, not a lossy hash. Order of channels is significant. */
+export declare function compileSchema(input: PoseSchema): CompiledSchema;
+/** One encoder shared by bake and runtime. Trajectory points follow the sorted union of horizons. */
+export declare class SchemaQueryBuilder {
+    readonly layout: CompiledSchema;
+    private horizonIndices;
+    constructor(schema?: PoseSchema);
+    features(pose: SchemaPose, trajectory: readonly TrajectoryPoint[], out?: Float32Array<ArrayBuffer>): Float32Array;
+    build(pose: SchemaPose, trajectory: readonly TrajectoryPoint[]): Query;
+}
+export {};

package/dist/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/core/search.d.ts

@@ -0,0 +1,17 @@
+import { type Database, type Match, type Query } from './types.js';
+import { type PoseSchema } from './schema.js';
+export declare function defaultWeights(schema?: PoseSchema): Float32Array;
+export declare class PoseSearch {
+    readonly database: Database;
+    private normalized;
+    private dimensions;
+    private rootOffset?;
+    readonly weights: Float32Array;
+    constructor(database: Database, weights?: Float32Array);
+    validateQuery(query: Query): void;
+    normalize(query: Query): void;
+    cost(index: number): number;
+    /** Physical error, independent of normalization/pose weights. Query must have been validated. */
+    rootVelocityError(index: number, query: Query): number;
+    search(query: Query): Match | null;
+}

package/dist/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/core/types.d.ts

@@ -0,0 +1,75 @@
+import type { PoseSchema } from './schema.js';
+/** Legacy preset constants; dynamic consumers must use compileSchema. */
+export declare const DIMENSIONS = 27;
+export declare const HORIZONS: readonly [0.2, 0.4, 0.6];
+export type Vec3 = readonly [number, number, number];
+export type Quat = readonly [number, number, number, number];
+export type Gait = 'idle' | 'walk' | 'run' | 'strafe' | 'turn' | 'stop';
+export interface Clip {
+    id: string;
+    file: string;
+    animation: string;
+    duration: number;
+    looping: boolean;
+    gait: Gait;
+    /** Explicit authoring velocity for in-place clips, never inferred root motion. */
+    nominalVelocity?: Vec3;
+    /** Hips is a measured pelvis proxy, not a dedicated animation root. */
+    motionSource?: 'nominal' | 'hips' | 'root';
+    /** Mean of measured local velocities; reference for demo controls, not gameplay authority. */
+    averageVelocity?: Vec3;
+    /** Source start in seconds; duration is the cropped duration. */
+    sourceStart?: number;
+    /** Optional absolute local orientation of the stripped rig root, as a static pose correction. */
+    rootOrientation?: Quat;
+}
+export interface Frame {
+    clip: number;
+    time: number;
+}
+export interface DatabaseManifest {
+    profileId?: string;
+    profileSignature?: string;
+    /** SHA-256 by public URL; verified by the loader. */
+    assetHashes?: Record<string, string>;
+    version: 2;
+    dimensions: number;
+    schema: PoseSchema;
+    schemaSignature: string;
+    sampleRate: number;
+    coordinates: 'meters-y-up-z-forward';
+    horizons: readonly number[];
+    clips: Clip[];
+    frames: Frame[];
+    mean: number[];
+    std: number[];
+}
+export interface Database {
+    manifest: DatabaseManifest;
+    features: Float32Array;
+}
+export interface Match extends Frame {
+    index: number;
+    cost: number;
+}
+export interface Query {
+    features: Float32Array;
+    schemaSignature?: string;
+    gaits?: ReadonlySet<Gait>;
+    excludedClips?: ReadonlySet<number>;
+    /** Optional root-velocity compatibility band in m/s. If uncovered, use nearest velocity before pose cost. */
+    velocityTolerance?: number;
+    /** False keeps the phase of the current loop; searches may still select another clip. Default true. */
+    allowTemporalReselection?: boolean;
+}
+export interface Pose {
+    leftPosition: Vec3;
+    rightPosition: Vec3;
+    leftVelocity: Vec3;
+    rightVelocity: Vec3;
+    rootVelocity: Vec3;
+}
+export interface TrajectoryPoint {
+    position: readonly [number, number];
+    facing: readonly [number, number];
+}

package/dist/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/index.d.ts

@@ -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/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';