3D engine that AI agents drive
Bind glTF clip tracks to unique node names and accept zero scale (closes #565, closes #551)
Nguyen Xuan An9d444d72d6b4
diff --git a/changes/565.md b/changes/565.mdnew file mode 100644index 00000000..eb3d8cc9--- /dev/null+++ b/changes/565.md@@ -0,0 +1 @@+- Load and animate glTF files with duplicate or missing node names (issues #565 and #551). The decoder made names unique with a `_N` suffix but could still hand a later node the name it had just generated, so two channels collided and createAnimationClip threw "Each target property can have only one track"; it now skips taken suffixes. Unnamed nodes were named by a random uuid in clip tracks and by an empty string in the asset's node metadata, so a skinned file such as Khronos BrainStem threw "no clip track names a joint of this rig"; both now use the source id (`node-4`). Scale keys of exactly 0 are accepted (zero hides a node; negative still throws), and a skin whose joint has zero scale loads with that joint collapsed (and the existing warning) instead of throwing a singular joint transform error. `createRigFromSkin` no longer crashes on a singular inverse bind matrix.diff --git a/changes/565.size.md b/changes/565.size.mdnew file mode 100644index 00000000..baf77973--- /dev/null+++ b/changes/565.size.md@@ -0,0 +1,2 @@+- goal:gltf-box: +59 bytes gzip for loading glTF files with duplicate or unnamed nodes and zero-scale joints (#565, #551); a fixed load failure, not a look change.+- goal:agent-scene: +16 bytes gzip, the same loader fix.diff --git a/docs/learn/deterministic-animation.md b/docs/learn/deterministic-animation.mdindex 3ae43e5b..47e70535 100644--- a/docs/learn/deterministic-animation.md+++ b/docs/learn/deterministic-animation.md@@ -110,7 +110,7 @@ A track names one part (`target`) and one `property`. Each target property can h| Option | Values | Meaning || --- | --- | --- || `target` | A unique part name | The part that the track drives. |-| `property` | `translation`, `rotation`, `scale`, `metallic`, `roughness`, `emission` | Rotation is a quaternion in XYZW order. Scale must stay positive. |+| `property` | `translation`, `rotation`, `scale`, `metallic`, `roughness`, `emission` | Rotation is a quaternion in XYZW order. Scale cannot be negative; zero is allowed and hides the node. || `interpolation` | `LINEAR` (default), `STEP`, `SMOOTH`, `CUBICSPLINE` | How values blend between keyframes. || `keyframes` | `{ time, value }` | Times are in seconds, from 0 to the clip `duration`. || keyframe `easing` | `easeOutBack`, `easeInOutCubic`, `cubic-bezier(...)` and the other names | Shapes the segment that starts at that keyframe. |diff --git a/src/animation.js b/src/animation.jsindex 69d97c3f..82e5f00c 100644--- a/src/animation.js+++ b/src/animation.js@@ -47,7 +47,7 @@ function normalizedValue(property, value) {if (!Number.isFinite(length) || length < 1e-8) throw new RangeError('Rotation keyframes need a finite nonzero quaternion length.');return Object.freeze(result.map(component => component / length));}- if (property === 'scale' && result.some(component => component <= 0)) throw new RangeError('Scale keyframes must stay positive.');+ if (property === 'scale' && result.some(component => component < 0)) throw new RangeError('Scale keyframes cannot be negative. Zero is allowed and hides the node.');return Object.freeze(result);}diff --git a/src/gltf-animation.js b/src/gltf-animation.jsindex 799fa0b5..02428ca6 100644--- a/src/gltf-animation.js+++ b/src/gltf-animation.js@@ -151,8 +151,10 @@ function validateRotations(values, interpolation) {}}+/** Unnamed nodes are addressed by their source id ("node-4"), the same id the asset's node metadata falls back to. */function nodeTrackName(node) {- return node.name ? node.name : node.uuid;+ if (node.name) return node.name;+ return node.association?.nodes === undefined ? node.uuid : `node-${node.association.nodes}`;}function tracksForChannel(channel, sampler, node, readAccessor) {diff --git a/src/gltf-decode.js b/src/gltf-decode.jsindex c0b5ba01..87ff446f 100644--- a/src/gltf-decode.js+++ b/src/gltf-decode.js@@ -143,13 +143,21 @@ export async function decodeGltf({ document, glbBinary, resourceBytes, decoders,function uniqueName(originalName) {const sanitized = sanitizeNodeName(originalName);- if (usedNames.has(sanitized)) {- const count = usedNames.get(sanitized) + 1;- usedNames.set(sanitized, count);- return `${sanitized}_${count}`;+ if (!usedNames.has(sanitized)) {+ usedNames.set(sanitized, 0);+ return sanitized;}- usedNames.set(sanitized, 0);- return sanitized;+ // A later node may really be called "Bone_1", so skip suffixes that are taken: names stay unique and clip+ // tracks, which address nodes by name, never collide.+ let count = usedNames.get(sanitized);+ let candidate;+ do {+ count++;+ candidate = `${sanitized}_${count}`;+ } while (usedNames.has(candidate));+ usedNames.set(sanitized, count);+ usedNames.set(candidate, 0);+ return candidate;}function imageBytes(index) {diff --git a/src/gltf.js b/src/gltf.jsindex 1992b384..5bfc3c5c 100644--- a/src/gltf.js+++ b/src/gltf.js@@ -7,7 +7,7 @@ import { decodeGltf, isLinePrimitive, overLimit, textureSourceIndex, throwOverruimport { readPunctualLights } from './gltf-lights.js';import { Matrix4 } from './gltf-nodes.js';import { textureDescriptorInfo } from './renderer.js';-import { createSkinPose, updateSkinPose, validateSkinGeometry, validateSkinPose } from './skinning.js';+import { createSkinPose, matrixDeterminant, updateSkinPose, validateSkinGeometry, validateSkinPose } from './skinning.js';import { MAX_MORPH_TARGETS, createMorphPose, validateMorphGeometry, validateMorphPose, validateMorphTransform } from './morph.js';// The defaults fit one large exported scene (a 240 MB GLB of 8 million vertices with 8K textures) and still bound a hostile file.@@ -950,6 +950,7 @@ function makeSkinBinding(node) {const pendingPose = createSkinPose(count);const inverseBindMatrices = new Float32Array(count * 16);let repairedInverseBindMatrices = 0;+ let collapsedJoints = false;const jointWorldMatrices = new Float32Array(count * 16);const pendingWorld = new Float32Array(count * 16);const joints = node.skeleton.bones.map((bone, index) => {@@ -959,11 +960,15 @@ function makeSkinBinding(node) {// A non-finite inverse bind matrix would turn every vertex of the joint into NaN: bind that joint at the identity.inverse.set(IDENTITY_MATRIX);repairedInverseBindMatrices++;+ } else if (Math.abs(matrixDeterminant(inverse, 0)) < 1e-10) {+ // A joint authored at zero scale has no inverse. Keep the file's matrices usable: its vertices collapse to a speck.+ inverse.set(IDENTITY_MATRIX);+ collapsedJoints = true;}return { name: bone.name, parent: node.skeleton.bones.indexOf(bone.parent) };});const skin = Object.assign(pose, { joints, inverseBindMatrices, jointWorldMatrices, bindMatrix: new Float32Array(node.bindMatrix.elements) });- return { node, skin, pendingPose, pendingWorld, palette: skin.jointMatrices, jointWorld: skin.jointWorldMatrices, repairedInverseBindMatrices };+ return { node, skin, pendingPose, pendingWorld, palette: skin.jointMatrices, jointWorld: skin.jointWorldMatrices, repairedInverseBindMatrices, collapsedJoints };}const IDENTITY_MATRIX = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];@@ -1386,7 +1391,7 @@ export async function parseGltf(data, options = {}) {Math.abs(value - composed.elements[index]) <= 1e-6 * Math.max(1, Math.abs(value)));const meshIds = meshIdsByNode.get(node);// `name` is the decoded node name, which clip tracks address; `label` is the name as authored in the file.- return { id, label: String(original.name ?? id).slice(0, 256), name: node.name, parent: sourceIds.get(parent) ?? null,+ return { id, label: String(original.name ?? id).slice(0, 256), name: node.name || id, parent: sourceIds.get(parent) ?? null,translation: node.position.toArray(), rotation: node.quaternion.toArray(), scale: node.scale.toArray(),editable, joint: jointNodes.has(node), meshIds };});diff --git a/src/retarget.js b/src/retarget.jsindex 3df325d8..0fd507e4 100644--- a/src/retarget.js+++ b/src/retarget.js@@ -164,17 +164,22 @@ function decomposeMatrix(matrix) {};}+/** The inverse of a matrix, or the identity when it has none (a joint authored at zero scale). */+function invertOrIdentity(matrix) {+ return mat4.invert(mat4.create(), matrix) ?? mat4.create();+}+/*** Build a rig from an imported skin pose. The bind pose becomes the rest pose.* `rootMatrix` is the world matrix of whatever sits above the root joints (for example a scaled Armature node).*/export function createRigFromSkin(skin, { rootMatrix = mat4.create() } = {}) {if (!skin?.joints || !skin.inverseBindMatrices) throw new TypeError('A skin with joints and inverseBindMatrices is required.');- const bindWorldMatrices = skin.joints.map((_, index) => mat4.invert(mat4.create(), skin.inverseBindMatrices.subarray(index * 16, index * 16 + 16)));- const inverseRoot = mat4.invert(mat4.create(), rootMatrix);+ const bindWorldMatrices = skin.joints.map((_, index) => invertOrIdentity(skin.inverseBindMatrices.subarray(index * 16, index * 16 + 16)));+ const inverseRoot = invertOrIdentity(rootMatrix);const joints = skin.joints.map((joint, index) => {const parentWorld = joint.parent >= 0 ? bindWorldMatrices[joint.parent] : rootMatrix;- const inverseParent = joint.parent >= 0 ? mat4.invert(mat4.create(), parentWorld) : inverseRoot;+ const inverseParent = joint.parent >= 0 ? invertOrIdentity(parentWorld) : inverseRoot;const local = mat4.multiply(mat4.create(), inverseParent, bindWorldMatrices[index]);return { name: joint.name, parent: joint.parent, ...decomposeMatrix(local) };});diff --git a/src/skinning.js b/src/skinning.jsindex b5d98f6d..e4fa8b71 100644--- a/src/skinning.js+++ b/src/skinning.js@@ -9,7 +9,7 @@ function finiteFloat(value) {return Number.isFinite(value) && Number.isFinite(Math.fround(value));}-function matrixDeterminant(values, offset) {+export function matrixDeterminant(values, offset) {const matrixXX = Math.fround(values[offset]);const matrixYX = Math.fround(values[offset + 1]);const matrixZX = Math.fround(values[offset + 2]);diff --git a/tests/animation.test.js b/tests/animation.test.jsindex 9399f4d9..70eb1775 100644--- a/tests/animation.test.js+++ b/tests/animation.test.js@@ -108,7 +108,7 @@ test('invalid tracks, values and bindings fail explicitly', () => {assert.throws(() => createAnimationClip({ duration: 1, tracks: [{ ...track, keyframes: [track.keyframes[0], track.keyframes[0]] }] }), RangeError);assert.throws(() => createAnimationClip({ duration: 1, tracks: [{ ...track, keyframes: [{ time: 2, value: [0, 0, 0] }] }] }), RangeError);assert.throws(() => createAnimationClip({ duration: 1, tracks: [{ ...track, property: 'rotation', keyframes: [{ time: 0, value: [0, 0, 0, 0] }] }] }), RangeError);- assert.throws(() => createAnimationClip({ duration: 1, tracks: [{ ...track, property: 'scale', keyframes: [{ time: 0, value: [0, 1, 1] }] }] }), RangeError);+ assert.throws(() => createAnimationClip({ duration: 1, tracks: [{ ...track, property: 'scale', keyframes: [{ time: 0, value: [-1, 1, 1] }] }] }), RangeError);assert.throws(() => sampleAnimationClip(valueClip(), Infinity), TypeError);assert.throws(() => createAnimationPlayer(createAnimationClip({ duration: 1, tracks: [track] }), []), RangeError);});diff --git a/tests/gltf-track-binding.test.js b/tests/gltf-track-binding.test.jsnew file mode 100644index 00000000..85dbb405--- /dev/null+++ b/tests/gltf-track-binding.test.js@@ -0,0 +1,92 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { parseGltf } from '../src/gltf.js';+import { createRigFromSkin } from '../src/retarget.js';+import { clipFromGltfAnimation, createAssetPose } from '../src/skeleton-pose.js';+import { skinnedStripAsset } from './fixtures/skinned-strip.js';++// Issues #565 (clip tracks keyed by node name) and #551 (a skinned file whose nodes have no names).+// Strip nodes: 0 Character, 1 Strip (mesh), 2 Root, 3 Tip. Clip "Bend" rotates node 3.++/** A second bone chain that reuses the first chain's names, animated by the same clip. */+function withDuplicateSkeleton(names) {+ return (document, append) => {+ document.nodes.push({ name: names[0], children: [5] }, { name: names[1], translation: [0, 1, 0] });+ document.nodes[0].children.push(4);+ const bend = document.animations[0];+ bend.channels.push({ sampler: 0, target: { node: 4, path: 'rotation' } }, { sampler: 0, target: { node: 5, path: 'rotation' } });+ };+}++async function posedAt(asset, clip, time) {+ const pose = createAssetPose(asset, { layers: [{ clip }] });+ pose.apply(time);+ return pose;+}++const BENT = [0, 0, Math.SQRT1_2, Math.SQRT1_2];++function assertRotation(actual, expected) {+ actual.forEach((component, axis) => assert.ok(Math.abs(component - expected[axis]) < 1e-6, `${actual} is not ${expected}`));+}++test('two skeletons with the same bone names each follow the clip (#565)', async () => {+ const asset = await parseGltf(skinnedStripAsset(withDuplicateSkeleton(['Root', 'Tip'])));+ const clip = clipFromGltfAnimation(asset.animations[0]);+ assert.equal(new Set(clip.tracks.map(track => track.target)).size, clip.tracks.length);+ const pose = await posedAt(asset, clip, 2);+ assertRotation(pose.jointWorld('Tip').rotation, BENT);+ assertRotation(pose.jointWorld('Root_1').rotation, BENT);+ assertRotation(pose.jointWorld('Tip_1').rotation, [0, 0, 1, 0]);+ asset.dispose();+});++test('a real node named like a generated duplicate name does not collide (#565)', async () => {+ const asset = await parseGltf(skinnedStripAsset((document, append) => {+ withDuplicateSkeleton(['Root', 'Tip'])(document, append);+ document.nodes[5].name = 'Root_1';+ }));+ const clip = clipFromGltfAnimation(asset.animations[0]);+ assert.equal(new Set(clip.tracks.map(track => track.target)).size, clip.tracks.length);+ await posedAt(asset, clip, 1);+ asset.dispose();+});++test('nodes without names bind their own tracks (#551)', async () => {+ const asset = await parseGltf(skinnedStripAsset(document => {+ for (const node of document.nodes) delete node.name;+ }));+ const clip = clipFromGltfAnimation(asset.animations[0]);+ assert.equal(clip.tracks.length, 1);+ const pose = await posedAt(asset, clip, 2);+ assertRotation(pose.jointWorld('node-3').rotation, BENT);+ asset.dispose();+});++test('scale keys of exactly zero hide a node instead of throwing (#565)', async () => {+ const asset = await parseGltf(skinnedStripAsset((document, append) => {+ const times = document.animations[0].samplers[0].input;+ const scales = append(new Float32Array([1, 1, 1, 0, 0, 0]), 'VEC3');+ document.animations[0].samplers.push({ input: times, output: scales, interpolation: 'LINEAR' });+ document.animations[0].channels.push({ sampler: 1, target: { node: 3, path: 'scale' } });+ }));+ const clip = clipFromGltfAnimation(asset.animations[0]);+ const scaleTrack = clip.tracks.find(track => track.property === 'scale');+ assert.deepEqual(scaleTrack.keyframes[1].value, [0, 0, 0]);+ await posedAt(asset, clip, 2);+ asset.dispose();+});++test('a skin joint with zero scale still gives a rig (#565)', async () => {+ const asset = await parseGltf(skinnedStripAsset((document, append) => {+ document.nodes[3].scale = [0, 0, 0];+ document.skins[0].inverseBindMatrices = append(new Float32Array([+ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1,+ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1,+ ]), 'MAT4');+ }));+ const rig = createRigFromSkin(asset.parts[0].skin);+ assert.equal(rig.joints.length, 2);+ assert.ok(rig.joints.every(joint => joint.rotation.every(Number.isFinite) && joint.translation.every(Number.isFinite)));+ asset.dispose();+});