Skip to content

3D engine that AI agents drive

Judge glTF node singularity by axis ratio, not an absolute determinant (#2077)

Nguyen Xuan Andf0705bcf498
diff --git a/changes/2077.md b/changes/2077.md
new file mode 100644
index 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.md
index 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 textu
An 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.js
index 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.js
index 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 when
assert.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\./);
+});