3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Judge glTF node singularity by axis ratio, not an absolute determinant (#2077)
Nguyen Xuan Andf0705bcf498
diff --git a/changes/2077.md b/changes/2077.mdnew file mode 100644index 00000000..5d14ed08--- /dev/null+++ b/changes/2077.md@@ -0,0 +1 @@+- glTF nodes with a scale of 1e-5 or smaller now load at their real size instead of being skipped as singular, and a skipped node's warning names its axis scales and the limit (#2077).diff --git a/docs/gltf.md b/docs/gltf.mdindex da747740..85d7ede5 100644--- a/docs/gltf.md+++ b/docs/gltf.md@@ -178,7 +178,7 @@ It supports base-color, normal, metallic-roughness, occlusion and emissive textuAn optional extension that Crucible does not read is ignored and named in `warnings`, as the glTF specification allows. An extension listed in `extensionsRequired` that Crucible does not read still fails the load with `Unsupported glTF extension`.`KHR_materials_pbrSpecularGlossiness` (also when listed in `extensionsRequired`) is converted to metallic-roughness: the diffuse color and texture become the base color, metallic is 0, roughness is 1 minus `glossinessFactor`. The specular color and `specularGlossinessTexture` are not read, and `warnings` says so. The base color and layer maps may read `TEXCOORD_1` beside maps on `TEXCOORD_0`, and so may every other texture. If every map of a material reads `TEXCOORD_1` and one is a base color or layer map or carries a real `KHR_texture_transform` (an identity transform counts as none), the primitives take that set as `TEXCOORD_0` and the maps move with it, with a warning naming the material, because the light bake reads only the first set and a transform is baked into one set only. If the material also has maps on `TEXCOORD_0`, only a map on `TEXCOORD_1` that carries a transform is dropped, with a warning naming the material; the others keep reading their own set (every path tracer reads each map with its own set: the WebGL and WebGPU tracers keep both UV sets in the triangle record, ten texels a triangle, and a bit mask in the material record names the maps on `TEXCOORD_1`). A map on `TEXCOORD_1` needs `geometry.lightUvs` on every part that uses it: the path tracer refuses the scene with a message naming the part otherwise, instead of sampling UV (0, 0). The native Cook kernel reads each map with its own set too: the trace scene hands it each map's set as `uvSet` and the second UV set as `uv1s` (on a flattened scene, and on the geometry of an instanced one, taken from `lightUvs`). The refusal above covers the maps the tracer reads: the base color, normal, metallic-roughness, transmission and clearcoat maps, and the emissive map while the material emits. A light bake skips a part whose maps or layer maps read `TEXCOORD_1` and names its material in `report.skipped`, because the bake replaces that set with the lightmap atlas. A texture on a primitive without the UV set it reads is dropped from that primitive with a warning that names the materials, and the mesh still loads. A negative `texCoord` (Blender writes -1 for a map on a mesh without UVs) or one above 1 (Crucible reads two UV sets) drops that map, and a `metallicFactor` or `roughnessFactor` outside 0..1 is clamped, each with a warning naming the material, the way three.js reads such files.A triangle primitive that cannot be drawn is skipped with one warning that names its mesh, its index and the reason, and the rest of the file loads: a missing or short POSITION accessor (fewer than 3 vertices), an index accessor with fewer than 3 indices or a count that is not a multiple of 3, an index outside the POSITION range, or only zero-area triangles. A file with no primitive left, no skin and no animation throws, and the error repeats those warnings.-Repairs keep the file loading and add one warning each: authored vertex normals of zero length are rebuilt from the triangles ("Repaired primitive ..."), and a mesh on a node whose world transform is singular or non-finite (a zero scale, for example) is skipped ("Skipped node ..."). A pose that later makes a node singular still throws.+Repairs keep the file loading and add one warning each: authored vertex normals of zero length are rebuilt from the triangles ("Repaired primitive ..."), and a mesh on a node whose world transform is non-finite or singular is skipped ("Skipped node ..."), and the warning names the axis scales and the limit. A transform is singular when its smallest axis scale is not above 1e-12 times its largest, so a zero scale on one axis is skipped while a uniform scale of 1e-7 loads at its real size. A pose that later makes a node singular still throws.A file with a skin or animation but no mesh (a skeleton-only clip such as the 100STYLE skeletons) loads with `parts: []`. `nodes` marks the skin's joints with `joint: true` and `animations` holds the clips, so `clipFromGltfAnimation`, `createAssetPose` and `pose.jointWorld` work on it. `skins` is empty because no mesh uses one.POINTS, LINES, LINE_LOOP and LINE_STRIP primitives are skipped with a warning that names the mesh and their count. Drawing them is not supported. TRIANGLE_STRIP and TRIANGLE_FAN primitives are still refused.diff --git a/src/gltf.js b/src/gltf.jsindex 302b5907..897c0f82 100644--- a/src/gltf.js+++ b/src/gltf.js@@ -987,28 +987,9 @@ function makeSkinBinding(node) {const IDENTITY_MATRIX = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];-/** True when collapseSingularMatrix would replace the matrix at this offset: a non-finite value or a determinant below its floor. */+/** True when collapseSingularMatrix would replace the matrix at this offset: a non-finite value or a singular axis ratio. */function needsCollapse(values, offset) {- for (let index = offset; index < offset + 16; index++) {- if (!Number.isFinite(values[index])) return true;- }- // The determinant of mat4.determinant, read at an offset.- const a00 = values[offset], a01 = values[offset + 1], a02 = values[offset + 2], a03 = values[offset + 3];- const a10 = values[offset + 4], a11 = values[offset + 5], a12 = values[offset + 6], a13 = values[offset + 7];- const a20 = values[offset + 8], a21 = values[offset + 9], a22 = values[offset + 10], a23 = values[offset + 11];- const a30 = values[offset + 12], a31 = values[offset + 13], a32 = values[offset + 14], a33 = values[offset + 15];- const b0 = a00 * a11 - a01 * a10;- const b1 = a00 * a12 - a02 * a10;- const b2 = a01 * a12 - a02 * a11;- const b3 = a20 * a31 - a21 * a30;- const b4 = a20 * a32 - a22 * a30;- const b5 = a21 * a32 - a22 * a31;- const b6 = a00 * b5 - a01 * b4 + a02 * b3;- const b7 = a10 * b5 - a11 * b4 + a12 * b3;- const b8 = a20 * b2 - a21 * b1 + a22 * b0;- const b9 = a30 * b2 - a31 * b1 + a32 * b0;- const determinant = a13 * b6 - a03 * b7 + a33 * b8 - a23 * b9;- return !Number.isFinite(determinant) || Math.abs(determinant) < 1e-12;+ return singularReason(values.subarray(offset, offset + 16)) !== undefined;}function prepareSkinBinding(binding, geometry, checks = true) {@@ -1019,7 +1000,7 @@ function prepareSkinBinding(binding, geometry, checks = true) {pendingWorld.set(node.skeleton.bones[joint].matrixWorld.elements, offset);// A joint at zero scale collapses its vertices to a point instead of refusing the pose. Only a joint that needs// the repair gets a view, so a normal pose allocates nothing.- if (needsCollapse(pendingWorld, offset) && collapseSingularMatrix(pendingWorld.subarray(offset, offset + 16), undefined, COLLAPSED_JOINT_SCALE)) binding.collapsedJoints = true;+ if (needsCollapse(pendingWorld, offset) && collapseSingularMatrix(pendingWorld.subarray(offset, offset + 16), COLLAPSED_JOINT_SCALE)) binding.collapsedJoints = true;}updateSkinPose(pendingPose, pendingWorld, skin.inverseBindMatrices, node.matrixWorld.elements, skin.bindMatrix, checks);if (checks) validateSkinPose(pendingPose, geometry, node.matrixWorld.elements);@@ -1052,23 +1033,41 @@ function prepareMorphBinding(binding) {}const COLLAPSED_SCALE = 2e-4;+/** A transform is singular when its smallest axis scale is under this fraction of its largest: the test follows the scale, so a uniform 1e-7 stays valid. */+const SINGULAR_AXIS_RATIO = 1e-12;++/** The scale along each axis of a column-major affine matrix, read as doubles. */+function axisScales(elements) {+ return [0, 4, 8].map(offset => Math.hypot(elements[offset], elements[offset + 1], elements[offset + 2]));+}++/** Why a world matrix cannot be drawn: 'non-finite', 'singular', or undefined when it is valid at any size. */+function singularReason(elements) {+ for (let index = 0; index < 16; index++) {+ if (!Number.isFinite(elements[index])) return 'non-finite';+ }+ const [scaleX, scaleY, scaleZ] = axisScales(elements);+ const determinant = mat4.determinant(elements);+ if (!Number.isFinite(determinant)) return 'non-finite';+ return Math.abs(determinant) > SINGULAR_AXIS_RATIO * scaleX * scaleY * scaleZ ? undefined : 'singular';+}++/** The sentence a skipped node carries: the measured axis scales and the limit, or the non-finite cause. */+function singularWarning(label, elements, reason) {+ if (reason === 'non-finite') return `Skipped node ${label}: its world transform is non-finite (NaN or Infinity in its translation, rotation or scale); pass finite node values.`;+ const scales = axisScales(elements);+ const smallest = Math.min(...scales);+ const largest = Math.max(...scales);+ return `Skipped node ${label}: its world transform is singular. Its axis scales are ${scales.map(value => value.toExponential(2)).join(', ')}; the smallest (${smallest.toExponential(2)}) must exceed ${SINGULAR_AXIS_RATIO} times the largest (${(SINGULAR_AXIS_RATIO * largest).toExponential(2)}). Pass a nonzero scale on every axis.`;+}const COLLAPSED_JOINT_SCALE = 1e-2;/*** 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, determinantFloor = 1e-12, collapsedScale = COLLAPSED_SCALE) {- let finite = true;- for (let index = 0; index < 16; index++) {- if (!Number.isFinite(elements[index])) {- finite = false;- break;- }- }- // mat4.determinant reads the elements as doubles, the same values a Float64 copy would hold.- const determinant = finite ? mat4.determinant(elements) : NaN;- if (finite && Number.isFinite(determinant) && Math.abs(determinant) >= determinantFloor) return false;+function collapseSingularMatrix(elements, collapsedScale = COLLAPSED_SCALE) {+ if (!singularReason(elements)) return false;const position = [elements[12], elements[13], elements[14]];const keepPosition = position.every(Number.isFinite);elements.fill(0);@@ -1100,12 +1099,11 @@ function isKeyedInClip(node, keyedNodeIndices) {* 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.*/-function validateNodeTransforms(nodes, pending, transform, tolerated) {+function validateNodeTransforms(nodes, pending, tolerated) {for (const node of nodes) {pending.set(node.matrixWorld.elements);const finite = pending.every(Number.isFinite);- const determinant = finite ? transform.fromArray(pending).determinant() : NaN;- if (finite && Number.isFinite(determinant) && Math.abs(determinant) >= 1e-12) continue;+ if (singularReason(pending) === undefined) continue;if (tolerated.has(node)) continue;if (!tolerated.collecting) throw new Error(finite ? 'Animation creates a singular Float32 node transform.' : 'Animation creates a non-finite Float32 world matrix.');tolerated.add(node);@@ -1313,18 +1311,19 @@ export async function parseGltf(data, options = {}) {if (!materials.has(node.material)) materials.set(node.material, convertMaterial(node.material, limits, maps, document.materials?.[materialIndex]));const material = materials.get(node.material);for (const instanceMatrix of instanceMatricesOf(node, limits.maxInstances)) {- const determinant = worldMatrixOf(node, instanceMatrix, pendingTransform).determinant();- const singular = !Number.isFinite(determinant) || Math.abs(determinant) < 1e-12;+ const worldElements = worldMatrixOf(node, instanceMatrix, pendingTransform).elements;+ const singularCause = singularReason(worldElements);+ const singular = singularCause !== undefined;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.`;+ : singularWarning(label, worldElements, singularCause);if (!warnings.includes(warning)) warnings.push(warning);if (!keyed) continue;}- const mirrored = singular ? false : determinant < 0;+ const mirrored = singular ? false : mat4.determinant(worldElements) < 0;const geometryKey = `${node.geometry.uuid}:${uvKey}:${secondUvSet}`;if (!geometries.has(geometryKey)) {await node.geometry.load();@@ -1399,7 +1398,7 @@ export async function parseGltf(data, options = {}) {await checkpoint();}const toleratedNodes = Object.assign(new Set(), { collecting: true });- validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform, toleratedNodes);+ validateNodeTransforms(nodes, pendingNodeMatrix, toleratedNodes);toleratedNodes.collecting = false;// A skeleton-only file (a skin or clips, no mesh) loads with zero parts so it can be posed and retargeted.if (!parts.length && !document.skins?.length && !gltf.animations.length) {@@ -1529,7 +1528,7 @@ export async function parseGltf(data, options = {}) {/** Pose every part from the scene graph. `checks: false` keeps the zero-scale repairs and skips the finite, singular and winding checks. */function preparePose(checks = true) {gltf.scene.updateMatrixWorld(true);- if (checks) validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform, toleratedNodes);+ if (checks) validateNodeTransforms(nodes, pendingNodeMatrix, toleratedNodes);const worldMatrix = new Matrix4();for (const { node, instanceMatrix, part, mirrored, matrix, pendingMatrix, skin } of bindings) {if (part.matrix !== matrix || matrix.length !== 16) {@@ -1547,7 +1546,7 @@ export async function parseGltf(data, options = {}) {}const determinant = worldMatrix.determinant();const roundedDeterminant = pendingTransform.fromArray(pendingMatrix).determinant();- if (!Number.isFinite(determinant) || !Number.isFinite(roundedDeterminant) || Math.abs(roundedDeterminant) < 1e-12 || (determinant < 0) !== mirrored || (roundedDeterminant < 0) !== mirrored) {+ if (!Number.isFinite(determinant) || !Number.isFinite(roundedDeterminant) || singularReason(pendingMatrix) !== undefined || (determinant < 0) !== mirrored || (roundedDeterminant < 0) !== mirrored) {throw new Error('Animation creates a singular transform or changes triangle winding.');}}diff --git a/tests/gltf-tolerance.test.js b/tests/gltf-tolerance.test.jsindex 4f7733e3..58e69203 100644--- a/tests/gltf-tolerance.test.js+++ b/tests/gltf-tolerance.test.js@@ -47,7 +47,7 @@ test('valid normals load with no warning', async () => {test('a node with a zero scale is skipped with a warning and the rest of the file loads', async () => {const asset = await parseGltf(documentWith(FACE_NORMALS, document => { document.nodes[0].scale = [0, 0, 0]; }));assert.equal(asset.parts.length, 1);- assert.deepEqual(asset.warnings, ['Skipped node "Good": its world transform is singular or non-finite.']);+ assert.deepEqual(asset.warnings, ['Skipped node "Good": its world transform is singular. Its axis scales are 0.00e+0, 0.00e+0, 0.00e+0; the smallest (0.00e+0) must exceed 1e-12 times the largest (0.00e+0). Pass a nonzero scale on every axis.']);});test('a singular group node skips the meshes under it', async () => {@@ -99,3 +99,35 @@ test('a primitive without NORMAL falls back to a touching face normal or up whenassert.deepEqual(Array.from(asset.parts[0].geometry.normals), [0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 1, 0]);assert.deepEqual(asset.warnings, []);});++function partDiagonal(asset) {+ const { matrix } = asset.parts[0];+ return [matrix[0], matrix[5], matrix[10]];+}++for (const scale of [1e-4, 1e-5, 1e-6, 1e-7]) {+ test(`a uniform node scale of ${scale} loads and keeps its size (#2077)`, async () => {+ const asset = await parseGltf(documentWith(FACE_NORMALS, document => {+ document.nodes[0].scale = [scale, scale, scale];+ }));+ assert.deepEqual(asset.warnings, []);+ assert.equal(asset.parts.length, 2);+ for (const value of partDiagonal(asset)) assert.ok(Math.abs(value - scale) <= scale * 1e-6, `scale ${value} should be ${scale}`);+ });+}++test('a tiny scale under a tiny parent multiplies instead of falling under an absolute floor (#2077)', async () => {+ const asset = await parseGltf(documentWith(FACE_NORMALS, document => {+ document.nodes = [{ name: 'Millimetres', scale: [1e-3, 1e-3, 1e-3], children: [1] }, { name: 'Micrometres', scale: [1e-3, 1e-3, 1e-3], mesh: 0 }];+ document.scenes[0].nodes = [0];+ }));+ assert.deepEqual(asset.warnings, []);+ assert.ok(Math.abs(partDiagonal(asset)[0] - 1e-6) < 1e-12);+});++test('a zero axis still skips the node and the warning names the axis scales and the limit (#2077)', async () => {+ const asset = await parseGltf(documentWith(FACE_NORMALS, document => { document.nodes[0].scale = [1e-5, 0, 1e-5]; }));+ assert.equal(asset.parts.length, 1);+ assert.match(asset.warnings[0], /Skipped node "Good": its world transform is singular\. Its axis scales are 1\.00e-5, 0\.00e\+0, 1\.00e-5;/);+ assert.match(asset.warnings[0], /must exceed 1e-12 times the largest \(1\.00e-17\)\. Pass a nonzero scale on every axis\./);+});