Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.js
index 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.js
index 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.js
index 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.js
index 1992b384..5bfc3c5c 100644
--- a/src/gltf.js
+++ b/src/gltf.js
@@ -7,7 +7,7 @@ import { decodeGltf, isLinePrimitive, overLimit, textureSourceIndex, throwOverru
import { 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.js
index 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.js
index 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.js
index 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.js
new file mode 100644
index 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();
+});