Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.js
index 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.js
new file mode 100644
index 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);
+});