3D engine that AI agents drive
Repair zero-length normals, skip singular nodes and load morphs without base NORMAL in glTF (#496)
Nguyen Xuan An53c7f7d0811a
diff --git a/changes/496.md b/changes/496.mdnew file mode 100644index 00000000..d97b7d46--- /dev/null+++ b/changes/496.md@@ -0,0 +1 @@+- `loadGltf` and `parseGltf` no longer refuse a file over three more Sketchfab-style defects (issue #496): authored vertex normals of zero length are rebuilt from the triangles, a mesh whose node has a zero or non-finite world transform is skipped, and morph targets without a base `NORMAL` load with generated normals and no morph normal deltas. Each repair adds an entry to `asset.warnings` that names the mesh, primitive or node.diff --git a/changes/496.size.md b/changes/496.size.mdnew file mode 100644index 00000000..6768a964--- /dev/null+++ b/changes/496.size.md@@ -0,0 +1,2 @@+- scene:gltf-box: the loader repairs zero-length authored normals, skips singular nodes and loads morph targets without a base NORMAL instead of refusing the file, 280 bytes; 27% of sampled Objaverse models were refused before.+- scene:gltf-box+lazy: the same loader repairs, 280 bytes.diff --git a/docs/gltf-morph.md b/docs/gltf-morph.mdindex 3f3b958c..56dcf6c0 100644--- a/docs/gltf-morph.md+++ b/docs/gltf-morph.md@@ -27,8 +27,7 @@ Position deltas require finite ordered `min` and `max` bounds.A target channel also requires its corresponding base attribute.Unsupported semantics, including `TANGENT`, fail explicitly before resource decoding.-Morph primitives require authored base normals.-The bridge rejects missing base normals instead of silently preserving normals when a target requires new flat normals.+A morph primitive without authored base normals loads with generated base normals; its morph NORMAL deltas are dropped and a warning is reported.Per-target flat normal generation remains unsupported.The converted geometry stores relative Float32 deltas in `geometry.morphTargets`.diff --git a/docs/gltf.md b/docs/gltf.mdindex 5875eb3c..fbdc1cc1 100644--- a/docs/gltf.md+++ b/docs/gltf.md@@ -114,7 +114,7 @@ The importer rejects animation poses that become singular or change triangle winThe current source supports four-influence [GPU skinning](https://67js.codepawl.com/skinning.md). GPU skinning is available from version `0.4.0`.The current source also supports relative POSITION/NORMAL morph targets and weight animations. See [morph import](https://67js.codepawl.com/gltf-morph.md).-Morph primitives require authored base normals. TANGENT targets and per-target flat normal generation remain unsupported.+A morph primitive without an authored base NORMAL loads with normals generated from its triangles; its morph NORMAL deltas are dropped, with a warning. TANGENT targets remain unsupported.The caller owns the Renderer67 instance.`asset.dispose()` releases importer textures, image bitmaps, parser resources, and temporary object URLs.@@ -135,6 +135,7 @@ It supports base-color, normal, metallic-roughness, occlusion and emissive textuAn optional extension that 67js does not read is ignored and named in `warnings`, as the glTF specification allows. An extension listed in `extensionsRequired` that 67js 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. A texture on a primitive without `TEXCOORD_0` is dropped from that primitive with a warning instead of failing the load.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.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/docs/morph-targets.md b/docs/morph-targets.mdindex 7ab01158..552fa266 100644--- a/docs/morph-targets.md+++ b/docs/morph-targets.md@@ -143,7 +143,7 @@ Repeated instances retain shared meshes while their signed weights remain indepeThe export contains editable targets and a static pose, rather than baked vertex positions.It does not serialize animation clips. Skinning and material textures still fail explicitly at export.-The source importer opens these snapshots. Morph import requires authored base normals and rejects tangent targets.+The source importer opens these snapshots. Morph import generates base normals when none are authored (dropping the morph normal deltas) and rejects tangent targets.The source [exporter](export-glb.md) also preserves opaque vertex colors, UVs and independent active HDR emission.Skinning, textures, procedural shaders and animation clips still prevent a complete asset roundtrip.diff --git a/src/gltf.js b/src/gltf.jsindex 96f0421c..855e1e64 100644--- a/src/gltf.js+++ b/src/gltf.js@@ -30,7 +30,7 @@ export const GLTF_CAPABILITIES = Object.freeze({ignoredExtensions: ['KHR_materials_variants', 'KHR_materials_dispersion', 'KHR_materials_diffuse_roughness', 'EXT_materials_bump', 'EXT_texture_avif'],optionalExtensions: 'Any other optional extension is ignored and named in warnings. One listed in extensionsRequired that 67js does not read is refused.',skippedPrimitives: ['POINTS', 'LINES', 'LINE_LOOP', 'LINE_STRIP'],- unsupported: ['more than four skin influences', 'singular weighted skin transforms', 'reflected skin transforms', 'TANGENT morph targets', 'morph targets without authored base normals', 'drawing vertex alpha (it is ignored with a warning)','different texture transforms on one material, except a normal map that differs by scale and offset', 'skinned or morphed GPU instancing', 'transmission, iridescence and specular textures (their factors are used)', 'texture transforms on TEXCOORD_1'],+ unsupported: ['more than four skin influences', 'singular weighted skin transforms', 'reflected skin transforms', 'TANGENT morph targets', 'drawing vertex alpha (it is ignored with a warning)','different texture transforms on one material, except a normal map that differs by scale and offset', 'skinned or morphed GPU instancing', 'transmission, iridescence and specular textures (their factors are used)', 'texture transforms on TEXCOORD_1'],});const LAYER_SHADER_EXTENSIONS = Object.freeze(['KHR_materials_anisotropy', 'KHR_materials_iridescence']);@@ -354,13 +354,13 @@ function validateDocument(document, limits, allowedExtensions) {}if (primitive.targets !== undefined && (!Array.isArray(primitive.targets) || !primitive.targets.length || primitive.targets.length !== targetCount)) throw new Error('Morph target counts must match across all mesh primitives.');if ((primitive.targets?.length ?? 0) !== targetCount) throw new Error('Morph target counts must match across all mesh primitives.');- if (targetCount && primitive.attributes?.NORMAL === undefined) throw new Error('Morph targets require authored base NORMAL. Per-target flat normal generation is unsupported.');for (const target of primitive.targets ?? []) {if (!target || typeof target !== 'object' || Array.isArray(target) || !Object.keys(target).length) throw new Error('Morph targets require POSITION or NORMAL channels.');for (const [semantic, accessorIndex] of Object.entries(target)) {if (!['POSITION', 'NORMAL'].includes(semantic)) throw new Error(`Unsupported morph target semantic: ${semantic}.`);const accessor = document.accessors?.[accessorIndex];- if (primitive.attributes?.[semantic] === undefined) throw new Error('Morph target channels require corresponding base attributes.');+ // A morph NORMAL without a base NORMAL is dropped at conversion with a warning, so it needs no base attribute here.+ if (primitive.attributes?.[semantic] === undefined && semantic !== 'NORMAL') throw new Error('Morph target channels require corresponding base attributes.');if (!Number.isInteger(accessorIndex) || !accessor || accessor.type !== 'VEC3' || accessor.componentType !== 5126 || accessor.normalized || accessor.count !== position.count) throw new Error('Morph target channels require matching float VEC3 accessors.');if (semantic === 'POSITION' && (!Array.isArray(accessor.min) || !Array.isArray(accessor.max) || accessor.min.length !== 3 || accessor.max.length !== 3|| accessor.min.some((value, axis) => typeof value !== 'number' || !Number.isFinite(Math.fround(value)) || typeof accessor.max[axis] !== 'number' || !Number.isFinite(Math.fround(accessor.max[axis])) || value > accessor.max[axis]))) throw new Error('Morph POSITION requires finite ordered min/max bounds.');@@ -832,7 +832,7 @@ function hasTriangleWithArea(positions, indices) {return false;}-function convertGeometry(source, mirrored, primitive, secondUvSet, onIgnoredVertexAlpha) {+function convertGeometry(source, mirrored, primitive, secondUvSet, onIgnoredVertexAlpha, onRepair) {const { position, normal, uv, uv1, color, skinIndex, skinWeight } = source.attributes;const positions = copyAttribute(position, 3);const indices = new Uint32Array(source.index?.count ?? position.count);@@ -845,6 +845,7 @@ function convertGeometry(source, mirrored, primitive, secondUvSet, onIgnoredVertif (!hasTriangleWithArea(positions, indices)) throw new UnusablePrimitiveError('every triangle has zero area');const normals = normal ? copyAttribute(normal, 3) : computeVertexNormals(positions, indices);const geometry = { positions, normals, indices };+ const repairedNormals = [];for (let offset = 0; offset < normals.length; offset += 3) {const length = Math.hypot(...normals.subarray(offset, offset + 3));if (length < 1e-8 && !normal) {@@ -852,9 +853,21 @@ function convertGeometry(source, mirrored, primitive, secondUvSet, onIgnoredVertnormals[offset + 1] = 1;continue;}- if (length < 1e-8) throw new Error('Degenerate geometry has no usable vertex normal.');+ if (length < 1e-8) {+ repairedNormals.push(offset);+ continue;+ }for (let axis = 0; axis < 3; axis++) normals[offset + axis] /= length;}+ if (repairedNormals.length) {+ // An authored normal of zero length cannot light anything: use the face normal of the triangles at that vertex, or up.+ const faceNormals = computeVertexNormals(positions, indices);+ for (const offset of repairedNormals) {+ const length = Math.hypot(...faceNormals.subarray(offset, offset + 3));+ for (let axis = 0; axis < 3; axis++) normals[offset + axis] = length > 1e-8 ? faceNormals[offset + axis] / length : axis === 1 ? 1 : 0;+ }+ onRepair(`${repairedNormals.length} vertex normal(s) had zero length and were rebuilt from the triangles`);+ }if (mirrored) {for (let index = 0; index < indices.length; index += 3) {const second = indices[index + 1];@@ -876,9 +889,12 @@ function convertGeometry(source, mirrored, primitive, secondUvSet, onIgnoredVertgeometry.morphTargets = primitive.targets.map((target, index) => {const channels = {};if (target.POSITION !== undefined) channels.positions = copyAttribute(source.morphPositions[index], 3);- if (target.NORMAL !== undefined) channels.normals = copyAttribute(source.morphNormals[index], 3);+ if (target.NORMAL !== undefined && normal) channels.normals = copyAttribute(source.morphNormals[index], 3);return channels;});+ if (!normal && primitive.targets.some(target => target.NORMAL !== undefined)) {+ onRepair('it has morph targets but no base NORMAL; normals are generated from the triangles and the morph normal deltas are dropped');+ }}return geometry;}@@ -932,12 +948,19 @@ function prepareMorphBinding(binding) {validateMorphPose(binding.pendingPose, binding.metadata);}-function validateNodeTransforms(nodes, pending, transform) {+/**+ * 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) {for (const node of nodes) {pending.set(node.matrixWorld.elements);- for (const value of pending) if (!Number.isFinite(value)) throw new Error('Animation creates a non-finite Float32 world matrix.');- const determinant = transform.fromArray(pending).determinant();- if (!Number.isFinite(determinant) || Math.abs(determinant) < 1e-12) throw new Error('Animation creates a singular Float32 node transform.');+ 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 (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);}}@@ -1138,7 +1161,11 @@ 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) throw new Error('Mesh world transform is singular or non-finite.');+ 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.`;+ if (!warnings.includes(warning)) warnings.push(warning);+ continue;+ }const mirrored = determinant < 0;const geometryMirrored = node.isSkinnedMesh ? false : mirrored;const geometryKey = `${node.geometry.uuid}:${geometryMirrored}:${uvKey}:${secondUvSet}`;@@ -1146,7 +1173,11 @@ export async function parseGltf(data, options = {}) {actualVertices += node.geometry.attributes.position.count * (1 + (primitive.targets?.length ?? 0));throwOverruns(overLimit([], 'decoded vertices', actualVertices, 'maxVertices', limits.maxVertices));try {- const converted = convertGeometry(node.geometry, geometryMirrored, primitive, secondUvSet, () => meshNamesWithIgnoredAlpha.add(node.name));+ const onRepair = reason => {+ const warning = `Repaired ${primitiveLabel(document, association.meshes, association.primitives)}: ${reason}.`;+ if (!warnings.includes(warning)) warnings.push(warning);+ };+ const converted = convertGeometry(node.geometry, geometryMirrored, primitive, secondUvSet, () => meshNamesWithIgnoredAlpha.add(node.name), onRepair);if (converted.uvs) bakeUvTransform(converted.uvs, uvTransform);geometries.set(geometryKey, converted);} catch (error) {@@ -1187,7 +1218,9 @@ export async function parseGltf(data, options = {}) {throwOverruns(overLimit([], 'decoded parts', parts.length, 'maxParts', limits.maxParts));}});- validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform);+ const toleratedNodes = Object.assign(new Set(), { collecting: true });+ validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform, 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) {const skipped = warnings.filter(warning => warning.startsWith('Skipped '));@@ -1291,7 +1324,7 @@ export async function parseGltf(data, options = {}) {function preparePose() {gltf.scene.updateMatrixWorld(true);- validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform);+ validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform, toleratedNodes);const worldMatrix = new Matrix4();for (const { node, instanceMatrix, part, mirrored, matrix, pendingMatrix, skin } of bindings) {if (part.matrix !== matrix || matrix.length !== 16) {diff --git a/tests/gltf-tolerance.test.js b/tests/gltf-tolerance.test.jsnew file mode 100644index 00000000..faa4b840--- /dev/null+++ b/tests/gltf-tolerance.test.js@@ -0,0 +1,73 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { parseGltf } from '../src/gltf.js';++const TRIANGLE = [0, 0, 0, 1, 0, 0, 0, 1, 0];+const ZERO_NORMALS = [0, 0, 0, 0, 0, 0, 0, 0, 0];+const FACE_NORMALS = [0, 0, 1, 0, 0, 1, 0, 0, 1];+const MORPH_DELTA = [0, 0, 0.5, 0, 0, 0.5, 0, 0, 0.5];++/** One triangle (accessor 0), its normals (1), a morph position delta (2) and a morph normal delta (3). */+function documentWith(normals, edit) {+ const floats = new Float32Array([...TRIANGLE, ...normals, ...MORPH_DELTA, ...FACE_NORMALS]);+ const bytes = new Uint8Array(floats.buffer);+ const vec3 = byteOffset => ({ bufferView: 0, byteOffset, componentType: 5126, count: 3, type: 'VEC3' });+ const document = {+ asset: { version: '2.0' },+ scene: 0,+ scenes: [{ nodes: [0, 1] }],+ nodes: [{ name: 'Good', mesh: 0 }, { name: 'Other', mesh: 0, translation: [2, 0, 0] }],+ meshes: [{ name: 'Tri', primitives: [{ attributes: { POSITION: 0, NORMAL: 1 } }] }],+ accessors: [+ { ...vec3(0), min: [0, 0, 0], max: [1, 1, 0] },+ vec3(36),+ { ...vec3(72), min: [0, 0, 0.5], max: [0, 0, 0.5] },+ vec3(108),+ ],+ bufferViews: [{ buffer: 0, byteOffset: 0, byteLength: bytes.length }],+ buffers: [{ byteLength: bytes.length, uri: `data:application/octet-stream;base64,${Buffer.from(bytes).toString('base64')}` }],+ };+ edit?.(document);+ return JSON.stringify(document);+}++test('authored vertex normals of zero length are rebuilt from the triangles with a warning', async () => {+ const asset = await parseGltf(documentWith(ZERO_NORMALS));+ assert.equal(asset.parts.length, 2);+ assert.deepEqual(Array.from(asset.parts[0].geometry.normals), FACE_NORMALS);+ assert.deepEqual(asset.warnings, ['Repaired primitive 0 of mesh "Tri": 3 vertex normal(s) had zero length and were rebuilt from the triangles.']);+});++test('valid normals load with no warning', async () => {+ const asset = await parseGltf(documentWith(FACE_NORMALS));+ assert.deepEqual(asset.warnings, []);+ assert.deepEqual(Array.from(asset.parts[0].geometry.normals), FACE_NORMALS);+});++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.']);+});++test('a singular group node skips the meshes under it', async () => {+ const asset = await parseGltf(documentWith(FACE_NORMALS, document => {+ document.nodes = [{ name: 'Group', scale: [0, 1, 1], children: [1] }, { name: 'Child', mesh: 0 }, { name: 'Free', mesh: 0 }];+ document.scenes[0].nodes = [0, 2];+ }));+ assert.equal(asset.parts.length, 1);+ assert.match(asset.warnings[0], /Skipped node "Child"/);+});++test('morph targets without a base NORMAL load: normals are generated and the morph normal deltas are dropped', async () => {+ const asset = await parseGltf(documentWith(FACE_NORMALS, document => {+ const primitive = document.meshes[0].primitives[0];+ delete primitive.attributes.NORMAL;+ primitive.targets = [{ POSITION: 2, NORMAL: 3 }, { POSITION: 2 }];+ }));+ assert.equal(asset.parts.length, 2);+ assert.deepEqual(Array.from(asset.parts[0].geometry.normals), FACE_NORMALS);+ assert.equal(asset.parts[0].geometry.morphTargets.length, 2);+ assert.equal(asset.parts[0].geometry.morphTargets[0].normals, undefined);+ assert.match(asset.warnings[0], /^Repaired primitive 0 of mesh "Tri": it has morph targets but no base NORMAL/);+});