3D engine that AI agents drive
Load skeleton-only glTF files and skip degenerate primitives (#480, #481)
Nguyen Xuan An40d4c3f670d0
diff --git a/changes/480.md b/changes/480.mdnew file mode 100644index 00000000..06f81eea--- /dev/null+++ b/changes/480.md@@ -0,0 +1 @@+- `loadGltf` and `parseGltf` load a glTF with a skin or animation clips but no mesh (issue #480), such as the skeleton-only 100STYLE clips. The result has `parts: []`, `nodes` with the skin's joints marked `joint: true`, and the clips in `animations`, so `clipFromGltfAnimation` and `createAssetPose` work on it. A file with no mesh, no skin and no animation still throws, now with "no supported triangle meshes and no skin or animation".diff --git a/changes/480.size.md b/changes/480.size.mdnew file mode 100644index 00000000..3e2ba988--- /dev/null+++ b/changes/480.size.md@@ -0,0 +1,2 @@+- scene:gltf-box: skeleton-only files and per-primitive skipping with named warnings (issues #480 and #481) let real assets that three.js and Blender load stop failing; the gltf entry grows 539 B gzip, inside its own allowance, and the scene stays under its goal of 80000+- scene:gltf-box+lazy: the same loader change (issues #480 and #481), 541 B gzipdiff --git a/changes/481.md b/changes/481.mdnew file mode 100644index 00000000..be5cfc21--- /dev/null+++ b/changes/481.md@@ -0,0 +1 @@+- `loadGltf` and `parseGltf` skip a degenerate triangle primitive instead of throwing for the whole file (issue #481). A missing or short POSITION accessor, a bad index count, an index out of range and a primitive of only zero-area triangles each give one entry in `asset.warnings` that names the mesh, the primitive index and the reason. The file throws only when no primitive survives, and the error lists the skipped ones. A vertex with no generated normal because no triangle with area uses it no longer stops the primitive.diff --git a/docs/gltf.md b/docs/gltf.mdindex 153b7c4c..2425e856 100644--- a/docs/gltf.md+++ b/docs/gltf.md@@ -133,6 +133,8 @@ Alpha masking, alpha blending and double-sided materials import onto `alphaMode`It supports base-color, normal, metallic-roughness, occlusion and emissive texture channels.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.+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.## Extensionsdiff --git a/src/gltf-decode.js b/src/gltf-decode.jsindex b7907494..c0b5ba01 100644--- a/src/gltf-decode.js+++ b/src/gltf-decode.js@@ -48,9 +48,12 @@ export function throwOverruns(overruns) {throw new RangeError(`glTF over its limits: ${overruns.map(overrun => overrun.text).join('; ')}. Fix: pass { ${fix} }.`);}-/** POINTS, LINES, LINE_LOOP and LINE_STRIP (modes 0 to 3) are not drawn, so the decoder leaves them out. */+/** Primitives the loader found unusable (bad accessors) before decoding; the decoder leaves them out and the file still loads. */+export const unusablePrimitives = new WeakSet();++/** POINTS, LINES, LINE_LOOP and LINE_STRIP (modes 0 to 3) and primitives marked unusable are not drawn, so the decoder leaves them out. */export function isLinePrimitive(primitive) {- return primitive.mode >= 0 && primitive.mode <= 3;+ return (primitive.mode >= 0 && primitive.mode <= 3) || unusablePrimitives.has(primitive);}export function textureSourceIndex(texture) {diff --git a/src/gltf.js b/src/gltf.jsindex 2ddcada6..96f0421c 100644--- a/src/gltf.js+++ b/src/gltf.js@@ -3,7 +3,7 @@ import { GLTF_LAYER_EXTENSIONS, layerTextureReferences, materialLayersFromGltf }import { attributeFloats } from './gltf-accessors.js';import { describeCompressedImage } from './compressed-texture.js';export { ktx2WorkerConfigFor } from './compressed-texture.js';-import { decodeGltf, isLinePrimitive, overLimit, textureSourceIndex, throwOverruns } from './gltf-decode.js';+import { decodeGltf, isLinePrimitive, overLimit, textureSourceIndex, throwOverruns, unusablePrimitives } from './gltf-decode.js';import { readPunctualLights } from './gltf-lights.js';import { Matrix4 } from './gltf-nodes.js';import { textureDescriptorInfo } from './renderer.js';@@ -502,7 +502,7 @@ function skippedPrimitiveWarnings(document) {(document.meshes ?? []).forEach((mesh, meshIndex) => {const counts = new Map();for (const primitive of mesh.primitives ?? []) {- if (!isLinePrimitive(primitive)) continue;+ if (!(primitive.mode >= 0 && primitive.mode <= 3)) continue;const modeName = LINE_MODE_NAMES[primitive.mode];counts.set(modeName, (counts.get(modeName) ?? 0) + 1);}@@ -514,6 +514,41 @@ function skippedPrimitiveWarnings(document) {return warnings;}+function primitiveLabel(document, meshIndex, primitiveIndex) {+ const name = document.meshes[meshIndex].name;+ return `primitive ${primitiveIndex} of mesh ${name ? `"${name}"` : meshIndex}`;+}++/** Why a triangle primitive cannot be drawn judging by its accessors alone, or null. Index values and areas need the decoded data. */+function accessorProblemOf(document, primitive) {+ const position = document.accessors?.[primitive.attributes?.POSITION];+ if (!position || position.type !== 'VEC3' || !Number.isSafeInteger(position.count) || position.count < 3) {+ return 'its POSITION accessor is missing, is not VEC3 or has fewer than 3 vertices';+ }+ const index = primitive.indices === undefined ? null : document.accessors?.[primitive.indices];+ if (primitive.indices !== undefined && (!index || index.type !== 'SCALAR' || !Number.isSafeInteger(index.count) || index.count < 3)) {+ return 'its index accessor is missing or has fewer than 3 indices';+ }+ const indexCount = index?.count ?? position.count;+ if (indexCount % 3 !== 0) return `its index count ${indexCount} is not a multiple of 3`;+ return null;+}++/** Marks triangle primitives with unusable accessors so the loader skips them, and returns one warning for each. */+function skipUnusablePrimitives(document) {+ const warnings = [];+ (document.meshes ?? []).forEach((mesh, meshIndex) => {+ (mesh.primitives ?? []).forEach((primitive, primitiveIndex) => {+ if (!primitive || (primitive.mode ?? 4) !== 4) return;+ const problem = accessorProblemOf(document, primitive);+ if (!problem) return;+ unusablePrimitives.add(primitive);+ warnings.push(`Skipped ${primitiveLabel(document, meshIndex, primitiveIndex)}: ${problem}.`);+ });+ });+ return warnings;+}+function validateHierarchy(nodes) {const parents = new Set();for (const node of nodes) {@@ -767,34 +802,56 @@ function copyAttribute(attribute, size) {return values;}+/** The corner offsets of a triangle and its area-weighted normal (the cross product of two edges). */+function triangleAt(positions, indices, corner) {+ const [first, second, third] = [indices[corner] * 3, indices[corner + 1] * 3, indices[corner + 2] * 3];+ const edgeAB = [positions[second] - positions[first], positions[second + 1] - positions[first + 1], positions[second + 2] - positions[first + 2]];+ const edgeAC = [positions[third] - positions[first], positions[third + 1] - positions[first + 1], positions[third + 2] - positions[first + 2]];+ const cross = [edgeAB[1] * edgeAC[2] - edgeAB[2] * edgeAC[1], edgeAB[2] * edgeAC[0] - edgeAB[0] * edgeAC[2], edgeAB[0] * edgeAC[1] - edgeAB[1] * edgeAC[0]];+ return { corners: [first, second, third], cross };+}+function computeVertexNormals(positions, indices) {const normals = new Float32Array(positions.length);for (let corner = 0; corner < indices.length; corner += 3) {- const [first, second, third] = [indices[corner] * 3, indices[corner + 1] * 3, indices[corner + 2] * 3];- const edgeAB = [positions[second] - positions[first], positions[second + 1] - positions[first + 1], positions[second + 2] - positions[first + 2]];- const edgeAC = [positions[third] - positions[first], positions[third + 1] - positions[first + 1], positions[third + 2] - positions[first + 2]];- const cross = [edgeAB[1] * edgeAC[2] - edgeAB[2] * edgeAC[1], edgeAB[2] * edgeAC[0] - edgeAB[0] * edgeAC[2], edgeAB[0] * edgeAC[1] - edgeAB[1] * edgeAC[0]];- for (const vertexOffset of [first, second, third]) {+ const { corners, cross } = triangleAt(positions, indices, corner);+ for (const vertexOffset of corners) {for (let axis = 0; axis < 3; axis++) normals[vertexOffset + axis] += cross[axis];}}return normals;}+/** A primitive whose decoded data cannot be drawn; the loader skips it with a warning instead of refusing the file. */+class UnusablePrimitiveError extends Error {}++function hasTriangleWithArea(positions, indices) {+ for (let corner = 0; corner < indices.length; corner += 3) {+ if (Math.hypot(...triangleAt(positions, indices, corner).cross) > 0) return true;+ }+ return false;+}+function convertGeometry(source, mirrored, primitive, secondUvSet, onIgnoredVertexAlpha) {const { position, normal, uv, uv1, color, skinIndex, skinWeight } = source.attributes;const positions = copyAttribute(position, 3);const indices = new Uint32Array(source.index?.count ?? position.count);for (let index = 0; index < indices.length; index++) {const value = source.index ? source.index.array[index] : index;- if (!Number.isInteger(value) || value < 0 || value >= position.count) throw new Error('Mesh index is out of range.');+ if (!Number.isInteger(value) || value < 0 || value >= position.count) throw new UnusablePrimitiveError('an index is out of range of its POSITION accessor');indices[index] = value;}if (normal && normal.count !== position.count) throw new Error('NORMAL and POSITION counts must match.');+ 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 };for (let offset = 0; offset < normals.length; offset += 3) {const length = Math.hypot(...normals.subarray(offset, offset + 3));+ if (length < 1e-8 && !normal) {+ // A vertex that no triangle with area touches has no generated normal; it draws nothing, so any unit vector will do.+ normals[offset + 1] = 1;+ continue;+ }if (length < 1e-8) throw new Error('Degenerate geometry has no usable vertex normal.');for (let axis = 0; axis < 3; axis++) normals[offset + axis] /= length;}@@ -1023,6 +1080,7 @@ export async function parseGltf(data, options = {}) {const decoders = options.decoders ?? {};let resampler = null;let validated;+ const unusablePrimitiveWarnings = skipUnusablePrimitives(document);try {validated = validateDocument(document, limits, allowedExtensionsFor(decoders));} catch (error) {@@ -1033,7 +1091,7 @@ export async function parseGltf(data, options = {}) {}const { ignoredExtensions, overruns } = validated;await loadLayerShadersFor(document);- const warnings = [...fallbackWarnings, ...ignoredExtensions.map(extension => `${extension} is accepted but not rendered.`), ...skippedPrimitiveWarnings(document)];+ const warnings = [...fallbackWarnings, ...ignoredExtensions.map(extension => `${extension} is accepted but not rendered.`), ...skippedPrimitiveWarnings(document), ...unusablePrimitiveWarnings];const dataBytes = typeof data === 'string' ? new TextEncoder().encode(data).byteLength : data.byteLength;const { resourceBytes, textureScaling } = await prepareResources(document, data, dataBytes, options, limits, overruns);if (textureScaling.scaledTextures.length) {@@ -1087,11 +1145,19 @@ export async function parseGltf(data, options = {}) {if (!geometries.has(geometryKey)) {actualVertices += node.geometry.attributes.position.count * (1 + (primitive.targets?.length ?? 0));throwOverruns(overLimit([], 'decoded vertices', actualVertices, 'maxVertices', limits.maxVertices));- const converted = convertGeometry(node.geometry, geometryMirrored, primitive, secondUvSet, () => meshNamesWithIgnoredAlpha.add(node.name));- if (converted.uvs) bakeUvTransform(converted.uvs, uvTransform);- geometries.set(geometryKey, converted);+ try {+ const converted = convertGeometry(node.geometry, geometryMirrored, primitive, secondUvSet, () => meshNamesWithIgnoredAlpha.add(node.name));+ if (converted.uvs) bakeUvTransform(converted.uvs, uvTransform);+ geometries.set(geometryKey, converted);+ } catch (error) {+ if (!(error instanceof UnusablePrimitiveError)) throw error;+ const warning = `Skipped ${primitiveLabel(document, association.meshes, association.primitives)}: ${error.message}.`;+ if (!warnings.includes(warning)) warnings.push(warning);+ geometries.set(geometryKey, null);+ }}const geometry = geometries.get(geometryKey);+ 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 };@@ -1122,7 +1188,11 @@ export async function parseGltf(data, options = {}) {}});validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform);- if (!parts.length) throw new Error('glTF scene contains no supported triangle meshes.');+ // 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 '));+ throw new Error(`glTF scene contains no supported triangle meshes and no skin or animation.${skipped.length ? ` ${skipped.join(' ')}` : ''}`);+ }const { lights, warnings: lightWarnings } = readPunctualLights(document, lightNodes);warnings.push(...lightWarnings);if (meshNamesWithIgnoredAlpha.size) {@@ -1140,6 +1210,11 @@ export async function parseGltf(data, options = {}) {}const sourceIds = new Map([...sourceNodes].map(([id, node]) => [node, id]));const jointNodes = new Set(skinBindings.flatMap(binding => binding.node.skeleton.bones));+ // A skin no mesh uses (a skeleton-only file) still names joints.+ const skinJointIndices = new Set((document.skins ?? []).flatMap(skin => skin.joints));+ for (const node of sourceNodes.values()) {+ if (skinJointIndices.has(node.association.nodes)) jointNodes.add(node);+ }const meshIdsByNode = new Map([...sourceNodes.values()].map(node => [node, []]));for (let index = 0; index < bindings.length; index++) {let ancestor = bindings[index].node;diff --git a/tests/gltf-skeleton-and-bad-primitives.test.js b/tests/gltf-skeleton-and-bad-primitives.test.jsnew file mode 100644index 00000000..5af00272--- /dev/null+++ b/tests/gltf-skeleton-and-bad-primitives.test.js@@ -0,0 +1,137 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { parseGltf } from '../src/gltf.js';+import { retargetAssetClip } from '../src/agent-retarget.js';+import { clipFromGltfAnimation, createAssetPose } from '../src/skeleton-pose.js';++function dataUri(bytes) {+ return `data:application/octet-stream;base64,${Buffer.from(bytes).toString('base64')}`;+}++/** Two joints (Hips with child Spine), a skin, and one clip that turns the Spine; no mesh. */+function skeletonDocument(edit = () => {}) {+ const floats = new Float32Array([0, 1, 0, 0, 0, 1, 0, 0.7071068, 0, 0.7071068]);+ const bytes = new Uint8Array(floats.buffer);+ const document = {+ asset: { version: '2.0' },+ scene: 0,+ scenes: [{ nodes: [0] }],+ nodes: [{ name: 'Hips', children: [1] }, { name: 'Spine', translation: [0, 1, 0] }],+ skins: [{ joints: [0, 1] }],+ animations: [{+ name: 'Turn',+ samplers: [{ input: 0, output: 1 }],+ channels: [{ sampler: 0, target: { node: 1, path: 'rotation' } }],+ }],+ accessors: [+ { bufferView: 0, byteOffset: 0, componentType: 5126, count: 2, type: 'SCALAR', min: [0], max: [1] },+ { bufferView: 0, byteOffset: 8, componentType: 5126, count: 2, type: 'VEC4' },+ ],+ bufferViews: [{ buffer: 0, byteOffset: 0, byteLength: bytes.length }],+ buffers: [{ byteLength: bytes.length, uri: dataUri(bytes) }],+ };+ edit(document);+ return JSON.stringify(document);+}++test('a skeleton-only file loads as nodes, joints and clips with zero parts', async () => {+ const asset = await parseGltf(skeletonDocument());+ assert.deepEqual(asset.parts, []);+ assert.equal(asset.animations.length, 1);+ assert.deepEqual(asset.nodes.map(node => [node.name, node.joint]), [['Hips', true], ['Spine', true]]);+ assert.equal(asset.nodes[1].parent, asset.nodes[0].id);+});++test('a skeleton-only asset can be posed from its own clip', async () => {+ const asset = await parseGltf(skeletonDocument());+ const clip = clipFromGltfAnimation(asset.animations[0]);+ const pose = createAssetPose(asset, { layers: [{ clip }] });+ assert.deepEqual(pose.apply(0), []);+ const rest = Array.from(pose.jointWorld('Spine').position);+ pose.apply(1);+ assert.deepEqual(Array.from(pose.jointWorld('Spine').position), rest);+ assert.notDeepEqual(Array.from(pose.jointWorld('Spine').rotation), [0, 0, 0, 1]);+});++test('the retarget addon reads a skeleton-only asset as a rig and asks for humanoid bones', async () => {+ const asset = await parseGltf(skeletonDocument());+ const clip = clipFromGltfAnimation(asset.animations[0]);+ assert.throws(() => retargetAssetClip(asset.nodes, asset.nodes, clip), /Source rig is not humanoid\. Missing bones: head/);+});++test('a file with neither a mesh nor a skin or clip is still refused', async () => {+ const data = skeletonDocument(document => {+ delete document.skins;+ delete document.animations;+ });+ await assert.rejects(parseGltf(data), /no supported triangle meshes and no skin or animation/);+});++const GOOD_TRIANGLE = [0, 0, 0, 1, 0, 0, 0, 1, 0];++/**+ * A mesh "Body" whose primitive 0 draws and whose primitive 1 is built by `edit(document, helpers)`.+ * Accessor 0 is the good triangle; accessors added by a case follow it.+ */+function twoPrimitiveDocument(edit) {+ const floats = new Float32Array([...GOOD_TRIANGLE, 0, 0, 0, 1, 1, 1, 2, 2, 2, 5, 0, 0, 0, 0, 0, 0, 0, 0, 0]);+ const indexBytes = new Uint8Array(new Uint16Array([0, 1, 2, 0, 1, 9, 0, 1]).buffer);+ const floatBytes = new Uint8Array(floats.buffer);+ const bytes = new Uint8Array(floatBytes.length + indexBytes.length);+ bytes.set(floatBytes);+ bytes.set(indexBytes, floatBytes.length);+ const document = {+ asset: { version: '2.0' },+ scene: 0,+ scenes: [{ nodes: [0] }],+ nodes: [{ name: 'Body', mesh: 0 }],+ meshes: [{ name: 'Body', primitives: [{ attributes: { POSITION: 0 } }, { attributes: { POSITION: 0 } }] }],+ accessors: [+ { bufferView: 0, byteOffset: 0, componentType: 5126, count: 3, type: 'VEC3', min: [0, 0, 0], max: [1, 1, 0] },+ // 1: two vertices only. 2: three vertices on one point (zero area). 3: six indices, the last three out of range.+ { bufferView: 0, byteOffset: 36, componentType: 5126, count: 2, type: 'VEC3', min: [0, 0, 0], max: [1, 1, 1] },+ { bufferView: 0, byteOffset: 36, componentType: 5126, count: 3, type: 'VEC3', min: [0, 0, 0], max: [2, 2, 2] },+ { bufferView: 1, byteOffset: 0, componentType: 5123, count: 6, type: 'SCALAR' },+ { bufferView: 1, byteOffset: 0, componentType: 5123, count: 4, type: 'SCALAR' },+ // 5: four vertices, the last one unused. 6: the triangle 0, 1, 2.+ { bufferView: 0, byteOffset: 0, componentType: 5126, count: 4, type: 'VEC3', min: [0, 0, 0], max: [1, 1, 0] },+ { bufferView: 1, byteOffset: 0, componentType: 5123, count: 3, type: 'SCALAR' },+ ],+ bufferViews: [{ buffer: 0, byteOffset: 0, byteLength: floatBytes.length }, { buffer: 0, byteOffset: floatBytes.length, byteLength: indexBytes.length }],+ buffers: [{ byteLength: bytes.length, uri: dataUri(bytes) }],+ };+ edit(document.meshes[0].primitives[1]);+ return JSON.stringify(document);+}++const BAD_PRIMITIVES = {+ 'fewer than 3 vertices': [primitive => { primitive.attributes.POSITION = 1; }, /primitive 1 of mesh "Body": its POSITION accessor .* fewer than 3 vertices/],+ 'a missing POSITION accessor': [primitive => { primitive.attributes = {}; }, /primitive 1 of mesh "Body": its POSITION accessor is missing/],+ 'an index count that is not a multiple of 3': [primitive => { primitive.indices = 4; }, /primitive 1 of mesh "Body": its index count 4 is not a multiple of 3/],+ 'an index out of range': [primitive => { primitive.indices = 3; primitive.attributes.POSITION = 0; }, /primitive 1 of mesh "Body": an index is out of range/],+ 'only zero-area triangles': [primitive => { primitive.attributes.POSITION = 2; }, /primitive 1 of mesh "Body": every triangle has zero area/],+};++for (const [name, [edit, expected]] of Object.entries(BAD_PRIMITIVES)) {+ test(`a primitive with ${name} is skipped with one warning and the rest loads`, async () => {+ const asset = await parseGltf(twoPrimitiveDocument(edit));+ assert.equal(asset.parts.length, 1);+ assert.equal(asset.warnings.length, 1);+ assert.match(asset.warnings[0], expected);+ });+}++test('an unused vertex without a generated normal does not stop a primitive that has real triangles', async () => {+ const asset = await parseGltf(twoPrimitiveDocument(primitive => {+ primitive.attributes.POSITION = 5;+ primitive.indices = 6;+ }));+ assert.equal(asset.parts.length, 2);+ assert.deepEqual(asset.warnings, []);+});++test('a file whose only primitive is unusable says why and throws', async () => {+ const data = JSON.parse(twoPrimitiveDocument(primitive => { primitive.attributes.POSITION = 1; }));+ data.meshes[0].primitives.shift();+ await assert.rejects(parseGltf(JSON.stringify(data)), /no supported triangle meshes.*Skipped primitive 0 of mesh "Body"/);+});