3D engine that AI agents drive
Keep glTF nodes that a clip scales to zero instead of refusing the pose (#496)
Nguyen Xuan Anee4d006137ed
diff --git a/changes/496-clips.md b/changes/496-clips.mdnew file mode 100644index 00000000..5fd6b192--- /dev/null+++ b/changes/496-clips.md@@ -0,0 +1 @@+- `loadGltf` and `parseGltf` keep a node that a clip scales to zero (issue #496): it draws a speck while its scale is zero and a node that starts at zero scale shows again when a clip scales it up, instead of throwing at that pose.diff --git a/changes/496-clips.size.md b/changes/496-clips.size.mdnew file mode 100644index 00000000..538b1074--- /dev/null+++ b/changes/496-clips.size.md@@ -0,0 +1,3 @@+- scene:gltf-box: a node that a clip scales to zero draws a speck at that pose instead of refusing the file, 268 bytes; this is the keyed-clip half of the #496 loader fixes.+- scene:gltf-box+lazy: the same loader change, 268 bytes.+- goal:gltf-box: the 96 bytes over the goal buy loading Objaverse and Sketchfab models with zero-scale animated nodes.diff --git a/src/gltf.js b/src/gltf.jsindex 8b0f9260..8098c2bb 100644--- a/src/gltf.js+++ b/src/gltf.js@@ -958,6 +958,45 @@ function prepareMorphBinding(binding) {validateMorphPose(binding.pendingPose, binding.metadata);}+const COLLAPSED_SCALE = 2e-4;+const collapseScratch = new Matrix4();++/**+ * Replaces a singular or non-finite world matrix, in place, with a uniform scale of 0.0002 at the same position so the+ * part is a speck that stays finite and invertible. Returns true when it replaced the matrix.+ */+function collapseSingularMatrix(elements) {+ const finite = elements.every(Number.isFinite);+ const determinant = finite ? collapseScratch.fromArray(elements).determinant() : NaN;+ if (finite && Number.isFinite(determinant) && Math.abs(determinant) >= 1e-12) return false;+ const positionIsFinite = [elements[12], elements[13], elements[14]].every(Number.isFinite);+ elements.fill(0);+ elements[0] = elements[5] = elements[10] = COLLAPSED_SCALE;+ elements[15] = 1;+ if (positionIsFinite) {+ for (const index of [12, 13, 14]) elements[index] = collapseScratch.elements[index];+ }+ return true;+}++/** Indices of the source nodes that any animation clip keys. */+function nodesKeyedInClips(document) {+ const keyed = new Set();+ for (const animation of document.animations ?? []) {+ for (const channel of animation.channels ?? []) {+ if (Number.isInteger(channel.target?.node)) keyed.add(channel.target.node);+ }+ }+ return keyed;+}++function isKeyedInClip(node, keyedNodeIndices) {+ for (let current = node; current; current = current.parent) {+ if (keyedNodeIndices.has(current.association?.nodes)) return true;+ }+ return false;+}+/*** Rejects a pose that makes a node's world matrix non-finite or singular. A node that was already singular at load* (its meshes were skipped with a warning) is listed in `tolerated` and is not checked again.@@ -1151,6 +1190,7 @@ export async function parseGltf(data, options = {}) {const lightNodes = [];const pendingTransform = new Matrix4();const pendingNodeMatrix = new Float32Array(16);+ const keyedNodeIndices = nodesKeyedInClips(document);let actualVertices = 0;gltf.scene.traverse(node => {nodes.push(node);@@ -1171,12 +1211,17 @@ export async function parseGltf(data, options = {}) {const material = materials.get(node.material);for (const instanceMatrix of instanceMatricesOf(node, limits.maxInstances)) {const determinant = worldMatrixOf(node, instanceMatrix, pendingTransform).determinant();- if (!Number.isFinite(determinant) || Math.abs(determinant) < 1e-12) {- const warning = `Skipped node ${node.name ? `"${node.name}"` : association.nodes}: its world transform is singular or non-finite.`;+ const singular = !Number.isFinite(determinant) || Math.abs(determinant) < 1e-12;+ if (singular) {+ const keyed = isKeyedInClip(node, keyedNodeIndices);+ const label = node.name ? `"${node.name}"` : association.nodes;+ const warning = keyed+ ? `Node ${label} starts with a singular or non-finite world transform; it draws nothing while its scale is zero.`+ : `Skipped node ${label}: its world transform is singular or non-finite.`;if (!warnings.includes(warning)) warnings.push(warning);- continue;+ if (!keyed) continue;}- const mirrored = determinant < 0;+ const mirrored = singular ? false : determinant < 0;const geometryMirrored = node.isSkinnedMesh ? false : mirrored;const geometryKey = `${node.geometry.uuid}:${geometryMirrored}:${uvKey}:${secondUvSet}`;if (!geometries.has(geometryKey)) {@@ -1201,7 +1246,9 @@ export async function parseGltf(data, options = {}) {if (!geometry) continue;const firstSetMaps = [...MATERIAL_TEXTURES.map(([field]) => material[field]), ...Object.values(material.layerMaps ?? {})];if (firstSetMaps.some(map => map && map.uvChannel === 0) && !geometry.uvs) throw new Error('Material textures require TEXCOORD_0.');- const part = { name: node.name || `glTF mesh ${parts.length + 1}`, geometry, matrix: new Float32Array(worldMatrixOf(node, instanceMatrix, pendingTransform).elements), material };+ const initialMatrix = new Float32Array(worldMatrixOf(node, instanceMatrix, pendingTransform).elements);+ collapseSingularMatrix(initialMatrix);+ const part = { name: node.name || `glTF mesh ${parts.length + 1}`, geometry, matrix: initialMatrix, material };const transformBinding = { node, instanceMatrix, part, mirrored, matrix: part.matrix, pendingMatrix: new Float32Array(16) };let pendingSkin;if (node.isSkinnedMesh) {@@ -1258,6 +1305,10 @@ export async function parseGltf(data, options = {}) {for (const node of sourceNodes.values()) {if (skinJointIndices.has(node.association.nodes)) jointNodes.add(node);}+ // A mesh or group node posed to zero scale draws nothing; only skin joints still refuse a singular pose.+ for (const node of nodes) {+ if (!jointNodes.has(node)) toleratedNodes.add(node);+ }const meshIdsByNode = new Map([...sourceNodes.values()].map(node => [node, []]));for (let index = 0; index < bindings.length; index++) {let ancestor = bindings[index].node;@@ -1344,6 +1395,7 @@ export async function parseGltf(data, options = {}) {throw new Error('Imported skin pose identity must remain unchanged.');}pendingMatrix.set(worldMatrixOf(node, instanceMatrix, worldMatrix).elements);+ if (collapseSingularMatrix(pendingMatrix)) continue;for (const value of pendingMatrix) {if (!Number.isFinite(value)) {throw new Error('Animation creates a non-finite Float32 world matrix.');diff --git a/tests/gltf-tolerance-clip.test.js b/tests/gltf-tolerance-clip.test.jsnew file mode 100644index 00000000..ea60a27b--- /dev/null+++ b/tests/gltf-tolerance-clip.test.js@@ -0,0 +1,49 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { parseGltf } from '../src/gltf.js';++/** One triangle with normals (accessors 0 and 1) and a clip keying node 0's scale at 0 s and 1 s (accessors 2 and 3). */+function documentWithScaleClip(firstScale, lastScale, edit) {+ const floats = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 1, ...firstScale, ...lastScale]);+ const bytes = new Uint8Array(floats.buffer);+ const document = {+ asset: { version: '2.0' },+ scene: 0,+ scenes: [{ nodes: [0] }],+ nodes: [{ name: 'Keyed', mesh: 0 }],+ meshes: [{ name: 'Tri', primitives: [{ attributes: { POSITION: 0, NORMAL: 1 } }] }],+ accessors: [+ { bufferView: 0, byteOffset: 0, componentType: 5126, count: 3, type: 'VEC3', min: [0, 0, 0], max: [1, 1, 0] },+ { bufferView: 0, byteOffset: 36, componentType: 5126, count: 3, type: 'VEC3' },+ { bufferView: 0, byteOffset: 72, componentType: 5126, count: 2, type: 'SCALAR', min: [0], max: [1] },+ { bufferView: 0, byteOffset: 80, componentType: 5126, count: 2, type: 'VEC3' },+ ],+ bufferViews: [{ buffer: 0, byteOffset: 0, byteLength: bytes.length }],+ buffers: [{ byteLength: bytes.length, uri: `data:application/octet-stream;base64,${Buffer.from(bytes).toString('base64')}` }],+ animations: [{ samplers: [{ input: 2, output: 3, interpolation: 'LINEAR' }], channels: [{ sampler: 0, target: { node: 0, path: 'scale' } }] }],+ };+ edit?.(document);+ return JSON.stringify(document);+}++function partScaleAt(asset, time) {+ asset.stagePose({ animation: { clip: 0, time } }).commit();+ return asset.parts[0].matrix[0];+}++test('a node keyed to zero scale draws a speck at that pose instead of refusing the file', async () => {+ const asset = await parseGltf(documentWithScaleClip([1, 1, 1], [0, 0, 0]));+ assert.equal(partScaleAt(asset, 0), 1);+ assert.ok(partScaleAt(asset, 1) < 1e-3);+ assert.ok(partScaleAt(asset, 0.5) > 0.4);+});++test('a node that starts at zero scale shows again when a clip scales it up', async () => {+ const asset = await parseGltf(documentWithScaleClip([0, 0, 0], [1, 1, 1], document => {+ document.nodes[0].scale = [0, 0, 0];+ }));+ assert.equal(asset.parts.length, 1);+ assert.match(asset.warnings[0], /draws nothing while its scale is zero/);+ assert.ok(partScaleAt(asset, 0) < 1e-3);+ assert.equal(partScaleAt(asset, 1), 1);+});