@pose_flow/babylon 0.1.0 → 0.2.0

package/dist/offline/tools/profile-assets.js

@@ -0,0 +1,90 @@
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { NullEngine, Scene, SceneLoader, TransformNode } from '@babylonjs/core';
+import { GLTFFileLoader } from '@babylonjs/loaders/glTF/index.js';
+import { parseProfile, resolveProfile, validateRootMotion, compileSchema } from '../src/index.js';
+export function profileArgument() {
+    const at = process.argv.indexOf('--profile');
+    if (at >= 0 && !process.argv[at + 1])
+        throw new Error('Missing --profile JSON path');
+    return at >= 0 ? process.argv[at + 1] : `public/profiles/${process.argv.includes('--paladin') ? 'paladin' : 'kaykit'}.json`;
+}
+export const publicPath = (url) => resolve(process.argv.includes('--public-dir') ? process.argv[process.argv.indexOf('--public-dir') + 1] : 'public', '.' + url);
+export async function hashProfileAssets(profile) {
+    const urls = new Set([profile.model, ...profile.clips.flatMap(c => [c.file, ...(c.motionFile ? [c.motionFile] : [])])].map(f => profile.assetBase + f));
+    return Object.fromEntries(await Promise.all([...urls].sort().map(async (url) => [url, createHash('sha256').update(await readFile(publicPath(url))).digest('hex')])));
+}
+export async function readProfile(path) {
+    const profile = parseProfile(JSON.parse(await readFile(path, 'utf8')));
+    const [schema, set] = await Promise.all([profile.schema, profile.animationSet].map(async (url) => JSON.parse(await readFile(publicPath(url), 'utf8'))));
+    return resolveProfile(profile, schema, set);
+}
+export async function loadProfileAssets(profile) {
+    const layout = compileSchema(profile.schemaDefinition);
+    const engine = new NullEngine(), scene = new Scene(engine);
+    scene.useRightHandedSystem = true;
+    const hook = SceneLoader.OnPluginActivatedObservable.add(p => { if (p instanceof GLTFFileLoader)
+        p.skipMaterials = true; });
+    const containers = new Map();
+    const dispose = () => { SceneLoader.OnPluginActivatedObservable.remove(hook); scene.dispose(); engine.dispose(); };
+    try {
+        for (const file of new Set([profile.model, ...profile.clips.map(c => c.file)])) {
+            const data = new Uint8Array(await readFile(publicPath(profile.assetBase + file)));
+            const container = await SceneLoader.LoadAssetContainerAsync('', data, scene, undefined, '.glb');
+            container.animationGroups.forEach(g => g.stop());
+            for (const node of container.rootNodes)
+                if (node instanceof TransformNode)
+                    node.scaling.scaleInPlace(profile.scale);
+            containers.set(file, container);
+        }
+        const body = containers.get(profile.model);
+        const names = body.transformNodes.map(n => n.name);
+        if (new Set(names).size !== names.length)
+            throw new Error('Ambiguous duplicate model node names');
+        for (const node of [...Object.values(profile.rig), ...(profile.stripRoot ? [profile.stripRoot] : [])])
+            if (!names.includes(node))
+                throw new Error(`Model bone missing: ${node}`);
+        const warnings = [];
+        for (const clip of profile.clips) {
+            const container = containers.get(clip.file);
+            const groups = container.animationGroups.filter(g => g.name === clip.animation);
+            if (groups.length !== 1)
+                throw new Error(`${clip.id}: expected one animation named ${clip.animation}`);
+            const group = groups[0], fps = group.targetedAnimations[0]?.animation.framePerSecond;
+            if (!fps || group.to <= group.from || group.targetedAnimations.some(t => t.animation.framePerSecond !== fps))
+                throw new Error(`${clip.id}: empty clip or inconsistent FPS`);
+            if (clip.range && clip.range[1] > (group.to - group.from) / fps + 1e-6)
+                throw new Error(`${clip.id}: range exceeds source duration`);
+            const mapped = new Set();
+            for (const track of group.targetedAnimations) {
+                const target = profile.boneMap?.[track.target.name] ?? track.target.name;
+                if (!names.includes(target))
+                    throw new Error(`${clip.id}: unmapped target ${track.target.name}; provide boneMap or retarget the animation`);
+                mapped.add(target);
+            }
+            for (const role of Object.values(profile.rig)) {
+                const matches = container.transformNodes.filter(n => (profile.boneMap?.[n.name] ?? n.name) === role);
+                if (matches.length !== 1)
+                    throw new Error(`${clip.id}: missing/ambiguous source bone for ${role}`);
+            }
+            if (clip.motionFile) {
+                const motion = JSON.parse(await readFile(publicPath(profile.assetBase + clip.motionFile), 'utf8'));
+                validateRootMotion(motion);
+                if (Math.abs(motion.duration - (group.to - group.from) / fps) > 1e-5)
+                    throw new Error(`${clip.id}: motion/GLB duration mismatch`);
+            }
+            if (layout.bones.some(role => !mapped.has(profile.rig[role])))
+                warnings.push(`${clip.id}: schema bones depend on inherited transforms; verify visible pose`);
+        }
+        for (const gait of ['idle', 'walk', 'run', 'strafe', 'turn', 'stop'])
+            if (!profile.clips.some(c => c.gait === gait))
+                warnings.push(`Coverage absent: ${gait}`);
+        warnings.push('Name compatibility does not validate bind pose, proportions or retargeting. Visually verify a new rig.');
+        return { scene, engine, containers, warnings, dispose };
+    }
+    catch (error) {
+        dispose();
+        throw error;
+    }
+}

package/dist/offline/tools/rig.js

@@ -0,0 +1,47 @@
+import { Matrix, Quaternion, Vector3 } from '@babylonjs/core';
+import { readGLB } from './glb.js';
+/** Validate rest geometry, not animation names. Missing bind data is an error, never a pass. */
+export function compareBindRigs(target, source, rootName, boneMap = {}, tolerance = .001) {
+    const bind = (bytes) => {
+        const { json, binary } = readGLB(bytes);
+        const skins = json.skins;
+        if (skins?.length !== 1)
+            throw new Error('Bind validation requires exactly one skin with inverse bind matrices');
+        const skin = skins[0], accessor = json.accessors[skin.inverseBindMatrices];
+        if (!accessor || accessor.type !== 'MAT4' || accessor.componentType !== 5126 || accessor.count !== skin.joints.length)
+            throw new Error('Unsupported inverse bind accessor');
+        const view = json.bufferViews[accessor.bufferView];
+        const data = new DataView(binary.buffer, binary.byteOffset, binary.byteLength), result = new Map();
+        skin.joints.forEach((node, index) => {
+            const name = json.nodes[node].name;
+            if (!name || result.has(name))
+                throw new Error('Ambiguous skin joint');
+            const offset = (view.byteOffset ?? 0) + (accessor.byteOffset ?? 0) + index * (view.byteStride ?? 64);
+            const matrix = Matrix.FromArray(Array.from({ length: 16 }, (_, j) => data.getFloat32(offset + j * 4, true)));
+            if (!matrix.asArray().every(Number.isFinite) || Math.abs(matrix.determinant()) < 1e-12)
+                throw new Error('Invalid inverse bind matrix');
+            result.set(name, Matrix.Invert(matrix));
+        });
+        return result;
+    };
+    const a = bind(target), b = bind(source), sourceRoot = [...b.keys()].filter(name => (boneMap[name] ?? name) === rootName);
+    if (!a.has(rootName) || sourceRoot.length !== 1)
+        throw new Error('Missing/ambiguous bind root');
+    const inverseA = Matrix.Invert(a.get(rootName)), inverseB = Matrix.Invert(b.get(sourceRoot[0])), errors = [];
+    for (const [name, matrix] of b) {
+        const mapped = boneMap[name] ?? name, targetMatrix = a.get(mapped);
+        if (!targetMatrix) {
+            errors.push(`Missing mapped bind joint: ${name} -> ${mapped}`);
+            continue;
+        }
+        const qa = new Quaternion(), qb = new Quaternion(), pa = new Vector3(), pb = new Vector3(), sa = new Vector3(), sb = new Vector3();
+        targetMatrix.multiply(inverseA).decompose(sa, qa, pa);
+        matrix.multiply(inverseB).decompose(sb, qb, pb);
+        if (Vector3.Distance(pa, pb) > tolerance || Vector3.Distance(sa, sb) > tolerance || 1 - Math.abs(Quaternion.Dot(qa, qb)) > 1e-5)
+            errors.push(`Bind mismatch: ${name} -> ${mapped} (position ${Vector3.Distance(pa, pb).toFixed(5)} m)`);
+    }
+    for (const name of a.keys())
+        if (![...b.keys()].some(sourceName => (boneMap[sourceName] ?? sourceName) === name))
+            errors.push('Missing source bind joint: ' + name);
+    return errors;
+}

package/dist/offline/tools/validate-assets.js

@@ -0,0 +1,43 @@
+import { readFile } from 'node:fs/promises';
+import { NullEngine, Scene, SceneLoader } from '@babylonjs/core';
+import { GLTFFileLoader } from '@babylonjs/loaders/glTF/index.js';
+import { suggestRig } from '../src/index.js';
+import { loadProfileAssets, profileArgument, publicPath, readProfile } from './profile-assets.js';
+import { compareBindRigs } from './rig.js';
+const inspectAt = process.argv.indexOf('--inspect');
+if (inspectAt >= 0) {
+    const path = process.argv[inspectAt + 1];
+    if (!path)
+        throw new Error('Provide a local GLB path after --inspect');
+    const engine = new NullEngine(), scene = new Scene(engine);
+    scene.useRightHandedSystem = true;
+    const hook = SceneLoader.OnPluginActivatedObservable.add(p => { if (p instanceof GLTFFileLoader)
+        p.skipMaterials = true; });
+    try {
+        const container = await SceneLoader.LoadAssetContainerAsync('', new Uint8Array(await readFile(path)), scene, undefined, '.glb');
+        const nodes = container.transformNodes.map(n => n.name);
+        console.log(JSON.stringify({ nodes, animations: container.animationGroups.map(g => g.name), suggestions: suggestRig(nodes), note: 'Suggestions require explicit confirmation in a profile; ambiguous roots are not selected automatically.' }, null, 2));
+    }
+    finally {
+        SceneLoader.OnPluginActivatedObservable.remove(hook);
+        scene.dispose();
+        engine.dispose();
+    }
+}
+else {
+    const profile = await readProfile(profileArgument()), assets = await loadProfileAssets(profile);
+    try {
+        if (process.argv.includes('--check-bind')) {
+            const target = new Uint8Array(await readFile(publicPath(profile.assetBase + profile.model)));
+            for (const file of new Set(profile.clips.map(c => c.file))) {
+                const errors = compareBindRigs(target, new Uint8Array(await readFile(publicPath(profile.assetBase + file))), profile.rig.root, profile.boneMap);
+                if (errors.length)
+                    throw new Error(`${file}: incompatible bind geometry; retarget offline first\n${errors.join('\n')}`);
+            }
+        }
+        console.log(JSON.stringify({ profile: profile.id, valid: true, bindChecked: process.argv.includes('--check-bind'), clips: profile.clips.length, warnings: assets.warnings }, null, 2));
+    }
+    finally {
+        assets.dispose();
+    }
+}

package/package.json

@@ -1,39 +1,48 @@
-{
-  "name": "@pose_flow/babylon",
-  "version": "0.1.0",
-  "license": "MIT",
-  "type": "module",
-  "files": [
-    "dist"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./babylon": {
-      "types": "./dist/babylon.d.ts",
-      "import": "./dist/babylon.js"
-    }
-  },
-  "scripts": {
-    "dev": "vite --host 127.0.0.1",
-    "build": "tsc -p tsconfig.build.json && vite build",
-    "typecheck": "tsc --noEmit",
-    "test": "tsx --test tests/*.test.ts",
-    "bake": "tsx tools/bake.ts",
-    "validate:assets": "tsx tools/validate-assets.ts",
-    "benchmark": "tsx tools/benchmark.ts"
-  },
-  "peerDependencies": {
-    "@babylonjs/core": "^7.54.3"
-  },
-  "devDependencies": {
-    "@babylonjs/core": "7.54.3",
-    "@babylonjs/loaders": "7.54.3",
-    "@types/node": "^22.0.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0",
-    "vite": "^6.0.0"
-  }
-}
+{
+  "name": "@pose_flow/babylon",
+  "version": "0.2.0",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./babylon": {
+      "types": "./dist/babylon.d.ts",
+      "import": "./dist/babylon.js"
+    },
+    "./AI_USAGE.md": "./dist/AI_USAGE.md",
+    "./PUBLISHING.md": "./dist/PUBLISHING.md"
+  },
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.offline.json && vite build && node tools/copy-docs.mjs",
+    "prepack": "npm run build",
+    "check:docs": "node tools/copy-docs.mjs --check",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/*.test.ts",
+    "bake": "tsx tools/bake.ts",
+    "validate:assets": "tsx tools/validate-assets.ts",
+    "benchmark": "tsx tools/benchmark.ts"
+  },
+  "peerDependencies": {
+    "@babylonjs/core": "^7.54.3"
+  },
+  "devDependencies": {
+    "@babylonjs/core": "7.54.3",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  },
+  "bin": {
+    "pose-flow": "./dist/offline/tools/cli.js"
+  },
+  "dependencies": {
+    "@babylonjs/loaders": "7.54.3"
+  }
+}