Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.md
index 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 win
The 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 textu
An 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.md
index 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 indepe
The 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.js
index 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, onIgnoredVert
if (!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, onIgnoredVert
normals[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, onIgnoredVert
geometry.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.js
new file mode 100644
index 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/);
+});