@pose_flow/babylon 0.2.0 → 0.3.0

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

@@ -1,5 +1,6 @@
 import { validateDatabase } from './database.js';
 import { compileSchema, LOCOMOTION_SCHEMA } from './schema.js';
+import { matchesContext, validateContext, withinWindows } from './selection.js';
 export function defaultWeights(schema = LOCOMOTION_SCHEMA) {
     const layout = compileSchema(schema), weights = new Float32Array(layout.dimensions);
     for (const { channel, offset, dimensions } of layout.channels)
@@ -9,6 +10,20 @@ export function defaultWeights(schema = LOCOMOTION_SCHEMA) {
     return weights;
 }
 const legacySignature = compileSchema(LOCOMOTION_SCHEMA).signature;
+export function readCandidateTrajectory(database, index) {
+    if (!Number.isInteger(index) || index < 0 || index >= database.manifest.frames.length)
+        throw new Error('Invalid candidate frame');
+    const { dimensions, mean, std } = database.manifest, layout = compileSchema(database.manifest.schema);
+    const points = new Map(layout.horizons.map(horizon => [horizon, { horizon }]));
+    for (const { channel, offset } of layout.channels)
+        if (channel.kind === 'trajectory-position' || channel.kind === 'trajectory-facing') {
+            channel.horizons.forEach((horizon, h) => {
+                const j = offset + h * 2, value = [database.features[index * dimensions + j] * std[j] + mean[j], database.features[index * dimensions + j + 1] * std[j + 1] + mean[j + 1]];
+                points.get(horizon)[channel.kind === 'trajectory-position' ? 'position' : 'facing'] = value;
+            });
+        }
+    return [...points.values()];
+}
 export class PoseSearch {
     database;
     normalized;
@@ -27,6 +42,8 @@ export class PoseSearch {
         this.weights = weights.slice();
     }
     validateQuery(query) {
+        if (query.context !== undefined)
+            validateContext(query.context);
         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))
@@ -36,6 +53,16 @@ export class PoseSearch {
         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');
     }
+    /** Context/gait validity is separate from eligibility to enter at a sample. */
+    allowsClip(clip, query) {
+        const descriptor = this.database.manifest.clips[clip];
+        return !!descriptor && !query.excludedClips?.has(clip) && (!query.gaits || query.gaits.has(descriptor.gait)) && (!query.context || matchesContext(descriptor.context, query.context));
+    }
+    allowsFrame(index, query) {
+        const frame = this.database.manifest.frames[index], clip = this.database.manifest.clips[frame.clip];
+        return this.allowsClip(frame.clip, query) && withinWindows(frame.time, clip.entryWindows)
+            && (clip.excludedWindows === undefined || !withinWindows(frame.time, clip.excludedWindows));
+    }
     normalize(query) {
         this.validateQuery(query);
         const { mean, std } = this.database.manifest;
@@ -66,24 +93,28 @@ export class PoseSearch {
     search(query) {
         this.normalize(query);
         const { frames, clips } = this.database.manifest;
+        // Context is clip-level: resolve it once per clip, rather than once per
+        // sample in each of the velocity and ranking passes.
+        const eligibleClips = clips.map((_, clip) => this.allowsClip(clip, query));
+        const candidates = [];
+        for (let i = 0; i < frames.length; i++) {
+            const frame = frames[i], clip = clips[frame.clip];
+            if (eligibleClips[frame.clip] && withinWindows(frame.time, clip.entryWindows)
+                && (clip.excludedWindows === undefined || !withinWindows(frame.time, clip.excludedWindows)))
+                candidates.push(i);
+        }
         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;
+            for (const i of candidates) {
                 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;
+        for (const i of candidates) {
             if (query.velocityTolerance !== undefined && this.rootVelocityError(i, query) > velocityLimit)
                 continue;
             const score = this.cost(i);
@@ -94,4 +125,57 @@ export class PoseSearch {
         }
         return index < 0 ? null : { ...frames[index], index, cost };
     }
+    /** Opt-in diagnostic pass. Bounded output, exact ranking, no change to filters/weights. */
+    inspect(query, limit = 5) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 50)
+            throw new Error('Invalid diagnostic limit');
+        const best = this.search(query), { frames, clips } = this.database.manifest;
+        const rejected = { 'excluded-clip': 0, gait: 0, context: 0, 'entry-window': 0, 'excluded-window': 0, velocity: 0 };
+        const examples = [], candidates = [];
+        const layout = compileSchema(this.database.manifest.schema);
+        let nearest = Infinity, eligible = 0;
+        if (query.velocityTolerance !== undefined)
+            for (let i = 0; i < frames.length; i++)
+                if (this.allowsFrame(i, query))
+                    nearest = Math.min(nearest, this.rootVelocityError(i, query));
+        const velocityLimit = query.velocityTolerance === undefined ? null : Math.max(query.velocityTolerance, nearest + 1e-6);
+        for (let index = 0; index < frames.length; index++) {
+            const frame = frames[index], clip = clips[frame.clip];
+            let reason;
+            if (query.excludedClips?.has(frame.clip))
+                reason = 'excluded-clip';
+            else if (query.gaits && !query.gaits.has(clip.gait))
+                reason = 'gait';
+            else if (!matchesContext(clip.context, query.context))
+                reason = 'context';
+            else if (!withinWindows(frame.time, clip.entryWindows))
+                reason = 'entry-window';
+            else if (clip.excludedWindows !== undefined && withinWindows(frame.time, clip.excludedWindows))
+                reason = 'excluded-window';
+            else if (velocityLimit !== null && this.rootVelocityError(index, query) > velocityLimit)
+                reason = 'velocity';
+            if (reason) {
+                rejected[reason]++;
+                if (examples.length < limit)
+                    examples.push({ index, ...frame, reason });
+                continue;
+            }
+            eligible++;
+            const cost = this.cost(index);
+            if (candidates.length >= limit && cost >= candidates[candidates.length - 1].cost)
+                continue;
+            const channels = layout.channels.map(({ channel, offset, dimensions }) => {
+                let cost = 0;
+                for (let j = offset; j < offset + dimensions; j++)
+                    cost += this.weights[j] * (this.normalized[j] - this.database.features[index * this.dimensions + j]) ** 2;
+                return { id: channel.id, cost };
+            });
+            const candidate = { index, ...frame, cost, channels, velocityError: this.rootOffset === undefined ? null : this.rootVelocityError(index, query) };
+            const at = candidates.findIndex(c => c.cost > cost);
+            candidates.splice(at < 0 ? candidates.length : at, 0, candidate);
+            if (candidates.length > limit)
+                candidates.pop();
+        }
+        return { best, candidates, rejected, examples, eligible, total: frames.length, velocityLimit: Number.isFinite(velocityLimit) ? velocityLimit : null };
+    }
 }

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

@@ -0,0 +1,41 @@
+export function validateContext(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || !Object.entries(value).every(([k, v]) => k.trim().length > 0 && typeof v === 'string' && v.trim().length > 0))
+        throw new Error('Invalid selection context');
+}
+export function matchesContext(metadata, requested = {}) {
+    return Object.entries(requested).every(([key, value]) => metadata !== undefined && Object.hasOwn(metadata, key) && metadata[key] === value);
+}
+export function withinWindows(time, windows) {
+    return windows === undefined || windows.some(([start, end]) => time >= start && time <= end);
+}
+export function validateSelection(value, duration = Infinity) {
+    if (value.context !== undefined)
+        validateContext(value.context);
+    for (const key of ['entryWindows', 'exitWindows', 'excludedWindows']) {
+        const windows = value[key];
+        if (windows !== undefined && (!Array.isArray(windows) || !windows.every(w => Array.isArray(w) && w.length === 2 && w.every(Number.isFinite)
+            && w[0] >= 0 && w[1] >= w[0] && w[1] <= duration)))
+            throw new Error('Invalid selection windows: ' + key);
+    }
+}
+/** Route before searching; costs from independent normalizations are never compared.
+ * Caller must use the selected bank's schema, compatible rig/player and matcher.
+ */
+export function selectContextBank(banks, context) {
+    validateContext(context);
+    const ids = new Set();
+    let selected = null;
+    for (const bank of banks) {
+        if (!bank.id.trim() || ids.has(bank.id))
+            throw new Error('Invalid/duplicate context bank id');
+        ids.add(bank.id);
+        validateContext(bank.context);
+        if (!matchesContext(bank.context, context))
+            continue;
+        if (selected)
+            throw new Error('Ambiguous context bank selection');
+        selected = bank;
+    }
+    return selected;
+}

package/dist/offline/src/index.js

@@ -6,3 +6,6 @@ export * from './core/search.js';
 export * from './core/controller.js';
 export * from './core/root-motion.js';
 export * from './core/profile.js';
+export * from './core/selection.js';
+export * from './core/inertialization.js';
+export * from './core/scenario.js';

package/dist/offline/tools/bake.js

@@ -31,7 +31,9 @@ try {
         }
         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 } : {}),
+        const descriptor = { id, file, animation, duration, looping, gait,
+            ...Object.fromEntries(['context', 'entryWindows', 'exitWindows', 'excludedWindows'].filter(key => key in spec).map(key => [key, spec[key]])),
+            ...(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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pose_flow/babylon",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -30,10 +30,10 @@
     "benchmark": "tsx tools/benchmark.ts"
   },
   "peerDependencies": {
-    "@babylonjs/core": "^7.54.3"
+    "@babylonjs/core": "^9.32.1"
   },
   "devDependencies": {
-    "@babylonjs/core": "7.54.3",
+    "@babylonjs/core": "9.32.1",
     "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
@@ -43,6 +43,6 @@
     "pose-flow": "./dist/offline/tools/cli.js"
   },
   "dependencies": {
-    "@babylonjs/loaders": "7.54.3"
+    "@babylonjs/loaders": "9.32.1"
   }
 }