Skip to content

3D engine that AI agents drive

Ignore TANGENT morph deltas in glTF with a warning (#2073)

Nguyen Xuan Anf752f9252ff6
diff --git a/changes/2073.md b/changes/2073.md
new file mode 100644
index 00000000..369e8dce
--- /dev/null
+++ b/changes/2073.md
@@ -0,0 +1 @@
+- glTF files with TANGENT morph target deltas (such as Khronos AnimatedMorphCube) now load: the TANGENT deltas are ignored with a warning, and other unsupported morph semantics are refused with a message that says to re-export the GLB without them (#2073)
diff --git a/changes/2073.size.md b/changes/2073.size.md
new file mode 100644
index 00000000..48008de4
--- /dev/null
+++ b/changes/2073.size.md
@@ -0,0 +1,4 @@
+- scene:gltf-box: 122 bytes gzip let glTF files with TANGENT morph targets (Khronos AnimatedMorphCube) load with a warning instead of being refused whole, and turn the "fix the recipe" error into a re-export instruction
+- scene:gltf-box+lazy: the same 122 bytes in the lazy bundle
+- entry:gltf: the same loader change, 135 bytes
+- entry:gltf+lazy: the same loader change, 135 bytes
diff --git a/docs/gltf.md b/docs/gltf.md
index da747740..54e8b3e3 100644
--- a/docs/gltf.md
+++ b/docs/gltf.md
@@ -155,7 +155,7 @@ The current source supports four-influence [GPU skinning](https://crucible.codep
Negative skin weights, which three.js and Blender also accept, are clamped to 0 and each vertex is renormalised. A vertex left with no positive weight binds fully to joint 0. `warnings` names the primitive and counts the clamped weights. NaN and Infinity weights still fail.
The current source also supports relative POSITION/NORMAL morph targets and weight animations. See [morph import](https://crucible.codepawl.com/gltf-morph.md).
-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.
+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 morph deltas are ignored with a warning (`unsupported-asset-feature` in `scene_create_asset`); any other morph semantic is refused, and the error says to re-export the GLB without it.
The caller owns the CrucibleRenderer instance.
`asset.dispose()` releases importer textures, image bitmaps, parser resources, and temporary object URLs.
diff --git a/src/gltf.js b/src/gltf.js
index 302b5907..24c95bc9 100644
--- a/src/gltf.js
+++ b/src/gltf.js
@@ -366,7 +366,9 @@ function validateDocument(document, limits, allowedExtensions) {
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}.`);
+ // TANGENT deltas are derived data the renderer never reads; they are ignored with a warning (see ignoredMorphTangentWarnings).
+ if (semantic === 'TANGENT') continue;
+ if (!['POSITION', 'NORMAL'].includes(semantic)) throw new Error(`Unsupported morph target semantic: ${semantic}. Crucible reads morph POSITION and NORMAL (TANGENT is ignored). Re-export the GLB without ${semantic} morph deltas.`);
const accessor = document.accessors?.[accessorIndex];
// 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.');
@@ -867,6 +869,13 @@ function computeVertexNormals(positions, indices) {
return normals;
}
+/** One warning when any morph target carries TANGENT deltas, which the loader ignores. */
+function ignoredMorphTangentWarnings(document) {
+ const hasTangentDeltas = (document.meshes ?? []).some(mesh => (mesh.primitives ?? [])
+ .some(primitive => (primitive.targets ?? []).some(target => target?.TANGENT !== undefined)));
+ return hasTangentDeltas ? ['Ignored morph target TANGENT deltas; the POSITION and NORMAL morphs and the weight animation load as authored.'] : [];
+}
+
/** A primitive whose decoded data cannot be drawn; the loader skips it with a warning instead of refusing the file. */
class UnusablePrimitiveError extends Error {}
@@ -1263,7 +1272,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), ...unusablePrimitiveWarnings, ...clampedIorWarnings(document)];
+ const warnings = [...fallbackWarnings, ...ignoredExtensions.map(extension => `${extension} is accepted but not rendered.`), ...skippedPrimitiveWarnings(document), ...unusablePrimitiveWarnings, ...clampedIorWarnings(document), ...ignoredMorphTangentWarnings(document)];
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) {
diff --git a/tests/gltf-morph-normals-and-nan.test.js b/tests/gltf-morph-normals-and-nan.test.js
index 7e183d30..123b9121 100644
--- a/tests/gltf-morph-normals-and-nan.test.js
+++ b/tests/gltf-morph-normals-and-nan.test.js
@@ -74,3 +74,25 @@ test('a NaN joint transform loads with a warning and a finite palette', async ()
assert.ok(Array.from(asset.parts[0].skin.jointMatrices).every(Number.isFinite));
asset.dispose();
});
+
+function tangentMorphDocument() {
+ const document = JSON.parse(morphDocument());
+ document.accessors.push({ ...document.accessors[1] });
+ document.meshes[0].primitives[0].targets = [{ POSITION: 1, TANGENT: 2 }];
+ return document;
+}
+
+test('TANGENT morph deltas are ignored with a warning that names TANGENT, and the POSITION morph loads', async () => {
+ const asset = await parseGltf(JSON.stringify(tangentMorphDocument()));
+ const channels = asset.parts[0].geometry.morphTargets[0];
+ assert.equal(channels.positions.length, 9);
+ assert.equal(channels.tangents, undefined);
+ assert.ok(asset.warnings.some(warning => /morph target TANGENT deltas/.test(warning)));
+ asset.dispose();
+});
+
+test('another unsupported morph semantic is refused with a message that says to re-export the GLB', async () => {
+ const document = tangentMorphDocument();
+ document.meshes[0].primitives[0].targets = [{ POSITION: 1, TEXCOORD_0: 2 }];
+ await assert.rejects(() => parseGltf(JSON.stringify(document)), /Unsupported morph target semantic: TEXCOORD_0\..*Re-export the GLB without TEXCOORD_0 morph deltas/);
+});
diff --git a/tests/gltf.test.js b/tests/gltf.test.js
index 10466a43..92b531f6 100644
--- a/tests/gltf.test.js
+++ b/tests/gltf.test.js
@@ -168,7 +168,7 @@ test('unsupported features fail explicitly before loading resources', async () =
[document => {
const primitive = document.meshes[0].primitives[0];
primitive.attributes.NORMAL = primitive.attributes.POSITION;
- primitive.targets = [{ TANGENT: 0 }];
+ primitive.targets = [{ TEXCOORD_0: 0 }];
}, /Unsupported morph/],
[document => { document.meshes[0].primitives[0].attributes.COLOR_0 = 1; }, /COLOR_0/],
[document => { document.meshes[0].primitives[0].mode = 5; }, /TRIANGLES/],