Skip to content

3D engine that AI agents drive

Keep child transforms under rotated, unevenly scaled parents in GLB export (#2127)

Nguyen Xuan Anf78277a8d23f
diff --git a/changes/2127.md b/changes/2127.md
new file mode 100644
index 00000000..eb11b773
--- /dev/null
+++ b/changes/2127.md
@@ -0,0 +1 @@
+- GLB export keeps a child's transform under a rotated, unevenly scaled parent (the preview rebuilt it with a wrong rotation), writes an emissive color above 1 as a factor plus `KHR_materials_emissive_strength`, and names the part, its parent chain or the material in shear and emissive errors (#2127, #2129)
diff --git a/changes/2127.size.md b/changes/2127.size.md
new file mode 100644
index 00000000..61ff54d8
--- /dev/null
+++ b/changes/2127.size.md
@@ -0,0 +1,2 @@
+- entry:core: 318 bytes gzip for the actionable shear and emissive errors that name the part and material, the emissive-above-1 fold into KHR_materials_emissive_strength, and the correct rotation under non-uniform scale
+- entry:core+lazy: 318 bytes gzip for the same export change
diff --git a/docs/export-glb.md b/docs/export-glb.md
index 33ba3ff4..e73b7dc2 100644
--- a/docs/export-glb.md
+++ b/docs/export-glb.md
@@ -47,7 +47,8 @@ UV coordinates remain editable even though this exporter rejects textures.
## Materials and emission
-`material.color` and `material.emissiveColor` contain three linear RGB components within `[0,1]`.
+`material.color` contains three linear RGB components within `[0,1]`.
+`material.emissiveColor` takes three finite components of 0 or more. A channel above 1 is divided out and its factor goes into the emissive strength, so `emissiveColor [2, 1, 0.5]` with `emission 2` writes factor `[1, 0.5, 0.25]` and strength 4.
`metallic` and `roughness` must each lie within `[0,1]`.
`emission` defaults to zero and must be finite, nonnegative, and representable as Float32.
An omitted `emissiveColor` uses `material.color`.
@@ -108,6 +109,8 @@ Differences: the shader blends the three projections across an edge and the expo
A skinned part (`part.skin` with `joints`, `inverseBindMatrices` and `jointWorldMatrices`) needs joint nodes.
Pass `options.nodes`, the `nodes` of the parsed asset, to keep the asset's hierarchy and mesh nodes.
+
+A part whose world transform has shear (axes not at right angles, such as a rotated child under a parent with non-uniform scale and its own rotation) fails with the part's name; glTF nodes cannot hold shear. `options.nodePaths` (part name to a label such as `parent > child`) adds the parent chain to that error, and `scene_export_glb` fills it in.
Without it the exporter derives one node per joint from the current joint world matrices.
Weights are normalised to sum to one, the skin's `bindMatrix` is folded into the inverse bind matrices, and a skinned mesh sits at the origin.
diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.js
index 2aa2e758..72213de4 100644
--- a/scripts/agent-preview-browser.js
+++ b/scripts/agent-preview-browser.js
@@ -29,6 +29,7 @@ import { createAgentAssetScene } from '../src/agent-asset.js';
import { parseGltf } from '../src/gltf.js';
import { assetCopyKey, recipeAssetNeeds } from '../src/agent-scene-assets.js';
import { exportGlb } from '../src/export.js';
+import { matrixFrame } from '../src/export-skeleton.js';
import '../src/texture-update.js';
import { staleRevisionMessage } from '../src/agent-errors.js';
import { updatePartVertices } from '../src/update-part-vertices.js';
@@ -777,7 +778,20 @@ function seekForExport(record, motionTime) {
// The scene's parts already carry the current pose, including IK and node overrides, so skinned parts export it as is.
function posedExport(record) {
const rig = record.scene.rigExport?.() ?? { nodes: [], clips: [] };
- return { parts: record.scene.parts.map(withoutRoundoffShear), options: rig.nodes.length ? rig : {} };
+ const options = rig.nodes.length ? rig : {};
+ return { parts: record.scene.parts.map(withoutRoundoffShear), options: { ...options, nodePaths: nodePathsOf(record.scene.exportRecipe().nodes) } };
+}
+
+/** "parent > child" for each node that has a parent, so an export error says where the node sits. */
+function nodePathsOf(nodes = []) {
+ const parentOf = new Map(nodes.map(node => [node.id, node.parent]));
+ const paths = {};
+ for (const node of nodes) {
+ const chain = [node.id];
+ for (let parent = node.parent; parent && chain.length <= nodes.length; parent = parentOf.get(parent)) chain.unshift(parent);
+ if (chain.length > 1) paths[node.id] = chain.join(' > ');
+ }
+ return paths;
}
// Chains of bone transforms leave world matrices with Float32 roundoff that the exporter reads as shear. Real shear
@@ -793,9 +807,7 @@ function withoutRoundoffShear(part) {
});
const dots = [[0, 1], [0, 2], [1, 2]].map(([first, second]) => Math.abs(columns[first].reduce((sum, value, axis) => sum + value * columns[second][axis], 0)));
if (Math.max(...dots) > ROUNDOFF_SHEAR_LIMIT) return part;
- const scale = mat4.getScaling([0, 0, 0], part.matrix);
- const rotation = mat4.getRotation([0, 0, 0, 1], part.matrix);
- const translation = mat4.getTranslation([0, 0, 0], part.matrix);
+ const { translation, rotation, scale } = matrixFrame(part.matrix);
return { ...part, matrix: mat4.fromRotationTranslationScale(mat4.create(), rotation, translation, scale) };
}
diff --git a/src/export-skeleton.js b/src/export-skeleton.js
index d2d45a0e..3c89ea8e 100644
--- a/src/export-skeleton.js
+++ b/src/export-skeleton.js
@@ -19,18 +19,26 @@ function transformFields(translation, rotation, scale) {
return fields;
}
-/** Split an affine matrix into glTF translation, rotation and scale fields. */
-export function decomposeMatrix(matrix) {
+/**
+ * Translation, rotation and scale of an affine matrix. gl-matrix's getRotation divides the wrong entries by the scale,
+ * so under a non-uniform scale it returns a wrong rotation: the rotation is taken from the unit-length columns instead.
+ * A mirrored matrix (negative determinant) keeps its reflection as a negative x scale, so the rotation stays proper.
+ */
+export function matrixFrame(matrix) {
const translation = mat4.getTranslation(vec3.create(), matrix);
const scale = mat4.getScaling(vec3.create(), matrix);
- // A mirrored matrix (negative determinant) keeps its reflection as a negative x scale, so the rotation stays proper.
- const mirrored = mat4.determinant(matrix) < 0;
- const properMatrix = Float32Array.from(matrix);
- if (mirrored) {
- scale[0] = -scale[0];
- for (let index = 0; index < 3; index++) properMatrix[index] = -properMatrix[index];
- }
- const rotation = mat4.getRotation(quat.create(), properMatrix);
+ if (mat4.determinant(matrix) < 0) scale[0] = -scale[0];
+ const unitColumns = [0, 4, 8].flatMap((offset, column) => {
+ const axisScale = scale[column] || 1;
+ return [matrix[offset] / axisScale, matrix[offset + 1] / axisScale, matrix[offset + 2] / axisScale];
+ });
+ const rotation = quat.normalize(quat.create(), quat.fromMat3(quat.create(), unitColumns));
+ return { translation, rotation, scale };
+}
+
+/** Split an affine matrix into glTF translation, rotation and scale fields. */
+export function decomposeMatrix(matrix) {
+ const { translation, rotation, scale } = matrixFrame(matrix);
return transformFields(translation, rotation, scale);
}
diff --git a/src/export.js b/src/export.js
index 978dcaf0..01c2a32c 100644
--- a/src/export.js
+++ b/src/export.js
@@ -71,27 +71,44 @@ function validateGeometry(geometry) {
}
// A skinned part takes its pose from its joints, so only parts with a node transform need a valid matrix.
-function validateMatrix(matrix) {
+function validateMatrix(matrix, part, nodePaths) {
if (!matrix || matrix.length !== 16 || Array.from(matrix).some(value => !Number.isFinite(value) || !Number.isFinite(Math.fround(value)))) {
throw new RangeError('GLB matrix requires 16 finite components.');
}
if (matrix[3] !== 0 || matrix[7] !== 0 || matrix[11] !== 0 || matrix[15] !== 1) {
throw new RangeError('GLB matrix requires an affine transform.');
}
- validateTransformColumns(matrix);
+ validateTransformColumns(matrix, part, nodePaths);
+}
+
+function partLabel(part, nodePaths) {
+ const path = nodePaths?.[part.name];
+ return `part "${part.name}"${path && path !== part.name ? ` (${path})` : ''}`;
+}
+
+function materialLabel(part) {
+ return part.material.id ? `material "${part.material.id}" of ${part.name}` : `material of part "${part.name}"`;
+}
+
+// An emissive color above 1 is allowed: the writer moves the excess into KHR_materials_emissive_strength.
+function validateEmissiveColor(part) {
+ const color = part.material.emissiveColor ?? part.material.color;
+ if (!color || color.length !== 3 || Array.from(color).some(value => !Number.isFinite(Math.fround(value)) || value < 0)) {
+ throw new RangeError(`GLB ${materialLabel(part)} needs emissiveColor as three finite numbers of 0 or more, such as [1, 0.5, 0.1].`);
+ }
}
function validatePart(part) {
const material = part.material;
if (!material || typeof material !== 'object') throw new TypeError('GLB parts require a material.');
validateColor(material.color, 'GLB base color');
- validateColor(material.emissiveColor ?? material.color, 'GLB emissive color');
+ validateEmissiveColor(part);
validateFactor(material.metallic, 'GLB metallic factor');
validateFactor(material.roughness, 'GLB roughness factor');
validateFactor(material.emission ?? 0, 'GLB emission', Infinity);
}
-function validateTransformColumns(matrix) {
+function validateTransformColumns(matrix, part, nodePaths) {
const columns = [0, 4, 8].map(offset => {
const values = [Math.fround(matrix[offset]), Math.fround(matrix[offset + 1]), Math.fround(matrix[offset + 2])];
const length = Math.hypot(...values);
@@ -105,13 +122,13 @@ function validateTransformColumns(matrix) {
for (let second = first + 1; second < 3; second++) {
let dot = 0;
for (let axis = 0; axis < 3; axis++) dot += columns[first][axis] * columns[second][axis];
- if (Math.abs(dot) > tolerance) throw new RangeError('GLB matrix cannot preserve shear. Use a transform with orthogonal rotation and scale columns.');
+ if (Math.abs(dot) > tolerance) throw new RangeError(`GLB ${partLabel(part, nodePaths)} cannot preserve shear: its world transform stretches along axes that are not at right angles, which a glTF node cannot hold. Put the stretch on the node that holds the mesh (the child), or give its parents a uniform scale.`);
}
}
}
const TEXTURE_CHANNELS = ['map', 'normalMap', 'metallicRoughnessMap', 'occlusionMap', 'emissiveMap'];
-const OPTION_NAMES = ['clips', 'nodes', 'maxTextureSize'];
+const OPTION_NAMES = ['clips', 'nodes', 'maxTextureSize', 'nodePaths'];
function validateOptions(options) {
if (!options || typeof options !== 'object') throw new TypeError('GLB export options must be an object.');
@@ -178,6 +195,14 @@ function writeLightMap(writer, textureWriter, material, gltfMaterial) {
}
}
+/** An emissive factor holds at most 1 per channel: the excess moves into the strength, which renders the same. */
+function foldEmissiveExcess(gltfMaterial, strength) {
+ const peak = Math.max(...gltfMaterial.emissiveFactor);
+ if (strength === 0 || peak <= 1) return strength;
+ gltfMaterial.emissiveFactor = gltfMaterial.emissiveFactor.map(channel => channel / peak);
+ return strength * peak;
+}
+
function writeMaterial(writer, textureWriter, material) {
const pbr = { baseColorFactor: [...material.color, 1], metallicFactor: material.metallic, roughnessFactor: material.roughness };
const gltfMaterial = {
@@ -189,7 +214,7 @@ function writeMaterial(writer, textureWriter, material) {
for (const extensionName of Object.keys(layerExtensions)) writer.addExtension(extensionName);
writeLayerTextures(writer, textureWriter, material, layerExtensions);
if (Object.keys(layerExtensions).length > 0) gltfMaterial.extensions = layerExtensions;
- const strength = material.emission ?? 0;
+ const strength = foldEmissiveExcess(gltfMaterial, material.emission ?? 0);
if (strength > 0 && strength < 1) {
// KHR_materials_emissive_strength allows only values of 1 or more, so a weaker emission is folded into the factor.
gltfMaterial.emissiveFactor = gltfMaterial.emissiveFactor.map(channel => channel * strength);
@@ -249,7 +274,8 @@ function usesSecondUvSet(material) {
/**
* Returns a self-contained GLB ArrayBuffer for the parts.
* Options: `clips` (createAnimationClip form, track targets are node names), `nodes` (the `nodes` of a parsed asset,
- * which hold joints and groups, so skinned parts and clips keep their hierarchy), `maxTextureSize` (default 2048).
+ * which hold joints and groups, so skinned parts and clips keep their hierarchy), `maxTextureSize` (default 2048),
+ * `nodePaths` (part name to a label such as "parent > child", which an error names).
*/
export function exportGlb(parts, options = {}) {
if (!Array.isArray(parts) || parts.length === 0) throw new TypeError('GLB export requires a nonempty parts array.');
@@ -276,7 +302,7 @@ export function exportGlb(parts, options = {}) {
parts.forEach((part, partIndex) => {
if (part.skin) return;
const host = part.matrix?.length === 16 ? hostOfPart(partIndex, hierarchy, worldCache) : null;
- validateMatrix(host ? relativeMatrix(part.matrix, host.world) : part.matrix);
+ validateMatrix(host ? relativeMatrix(part.matrix, host.world) : part.matrix, part, options.nodePaths);
});
const writer = createGlbWriter();
const { document } = writer;
diff --git a/tests/export.test.js b/tests/export.test.js
index 3171c634..d1079114 100644
--- a/tests/export.test.js
+++ b/tests/export.test.js
@@ -305,3 +305,19 @@ test('GLB export writes an additive material as BLEND because glTF has no additi
assert.equal(loaded.transparent, true);
assert.ok(Math.abs(loaded.opacity - 0.5) < 1e-6);
});
+
+test('GLB errors name the part and the material and say what to pass', () => {
+ const part = { name: 'lamp', geometry: box(), matrix: mat4.create(), material: { id: 'hot', color: [1, 1, 1], metallic: 0, roughness: 1, emission: 1, emissiveColor: [-1, 0, 0] } };
+ assert.throws(() => exportGlb([part]), /material "hot" of lamp needs emissiveColor as three finite numbers of 0 or more/);
+ const stretched = { ...part, name: 'kid', material: { ...part.material, emissiveColor: [1, 1, 1] }, matrix: mat4.fromValues(3, 0, 0, 0, 1.5, 1.5, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1) };
+ assert.throws(() => exportGlb([stretched], { nodePaths: { kid: 'p > kid' } }), /part "kid" \(p > kid\) cannot preserve shear.*uniform scale/);
+ assert.throws(() => exportGlb([stretched]), /part "kid" cannot preserve shear/);
+});
+
+test('GLB moves an emissive color above 1 into the emissive strength', () => {
+ const part = { name: 'lamp', geometry: box(), matrix: mat4.create(), material: { color: [1, 1, 1], metallic: 0, roughness: 1, emission: 0.5, emissiveColor: [4, 2, 1] } };
+ const binary = exportGlb([part]);
+ const [material] = JSON.parse(new TextDecoder().decode(new Uint8Array(binary, 20, new DataView(binary).getUint32(12, true)))).materials;
+ assert.deepEqual(material.emissiveFactor, [1, 0.5, 0.25]);
+ assert.equal(material.extensions.KHR_materials_emissive_strength.emissiveStrength, 2);
+});
diff --git a/tests/mcp-export-glb-transforms.test.js b/tests/mcp-export-glb-transforms.test.js
new file mode 100644
index 00000000..a1395bda
--- /dev/null
+++ b/tests/mcp-export-glb-transforms.test.js
@@ -0,0 +1,102 @@
+// scene_export_glb through the real MCP server on the CPU backend (issues 2127 and 2129): a child under a rotated,
+// unevenly scaled parent keeps its place in the file, and export errors name the node or material and the way out.
+import test, { after, before } from 'node:test';
+import assert from 'node:assert/strict';
+import { copyFile, mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+import { readGlb } from '../scripts/recode-glb-textures.mjs';
+
+const BOUNDS_TOLERANCE = 1e-4;
+const CAMERA = { eye: [3, 2, 4], target: [0, 0.5, 0], fov: 45 };
+let directory;
+let client;
+
+before(async () => {
+ directory = await mkdtemp(join(tmpdir(), 'crucible-export-transforms-'));
+ await mkdir(join(directory, 'assets'));
+ const transport = new StdioClientTransport({ command: process.execPath,
+ args: [resolve('bin/crucible-mcp.mjs'), '--backend', 'cpu', '--memory', '96', '--assets', join(directory, 'assets'), '--jobs', join(directory, 'jobs')], cwd: directory, stderr: 'pipe' });
+ client = new Client({ name: 'crucible-export-transforms-test', version: '1' });
+ await client.connect(transport, { timeout: 240000 });
+});
+
+after(async () => {
+ await client?.close();
+ await rm(directory, { recursive: true, force: true });
+});
+
+function recipeOf(nodes, materials = [{ id: 'm' }]) {
+ return { format: 'crucible.scene', schemaVersion: 1, geometries: [{ id: 'cone', type: 'cone' }, { id: 'box', type: 'box' }], materials, nodes, camera: CAMERA };
+}
+
+async function call(name, argumentsValue) {
+ return client.callTool({ name, arguments: argumentsValue }, { timeout: 120000 });
+}
+
+async function createScene(recipe) {
+ const created = await call('scene_create', { recipe });
+ assert.equal(created.isError, undefined, created.content?.[0]?.text);
+ return created.structuredContent.sessionId;
+}
+
+async function exportError(recipe) {
+ const exported = await call('scene_export_glb', { sessionId: await createScene(recipe) });
+ assert.equal(exported.isError, true, 'the export should fail');
+ return exported.content[0].text;
+}
+
+async function worldBounds(sessionId) {
+ const report = (await call('scene_inspect', { sessionId, includeBounds: true })).structuredContent;
+ const boxes = report.nodes.filter(node => node.bounds).map(node => node.bounds);
+ assert.ok(boxes.length > 0, 'the scene should report bounds');
+ const min = [0, 1, 2].map(axis => Math.min(...boxes.map(box => box.min[axis])));
+ const max = [0, 1, 2].map(axis => Math.max(...boxes.map(box => box.max[axis])));
+ return { min, max };
+}
+
+test('a child under a rotated, unevenly scaled parent keeps its bounds through export and reimport', { timeout: 300000 }, async () => {
+ const recipe = recipeOf([
+ { id: 'group', scale: [1, 2, 1], rotation: [0, 0, 0.3826834, 0.9238795], translation: [0, 0, 6] },
+ { id: 'kid', parent: 'group', geometry: 'cone', material: 'm', translation: [0, 1, 0] }]);
+ const authored = await worldBounds(await createScene(recipe));
+ const exported = await call('scene_export_glb', { sessionId: await createScene(recipe) });
+ assert.equal(exported.isError, undefined, exported.content?.[0]?.text);
+ await copyFile(exported.structuredContent.path, join(directory, 'assets', 'sheared-parent.glb'));
+ const catalog = (await call('scene_asset_catalog', {})).structuredContent;
+ const asset = catalog.assets.find(entry => entry.name === 'sheared-parent.glb' || entry.filename === 'sheared-parent.glb') ?? catalog.assets[0];
+ const assetId = asset.assetId ?? asset.id;
+ const imported = await call('scene_create_asset', { recipe: { format: 'crucible.asset', schemaVersion: 1, assetId } });
+ assert.equal(imported.isError, undefined, imported.content?.[0]?.text);
+ const reimported = await worldBounds(imported.structuredContent.sessionId);
+ for (let axis = 0; axis < 3; axis++) {
+ assert.ok(Math.abs(reimported.min[axis] - authored.min[axis]) < BOUNDS_TOLERANCE, `min[${axis}] ${reimported.min[axis]} against ${authored.min[axis]}`);
+ assert.ok(Math.abs(reimported.max[axis] - authored.max[axis]) < BOUNDS_TOLERANCE, `max[${axis}] ${reimported.max[axis]} against ${authored.max[axis]}`);
+ }
+ const { json } = readGlb(await readFile(exported.structuredContent.path));
+ const kid = json.nodes.find(node => node.name === 'kid');
+ const expected = [0.7071068, 0.7071068, 0, 0, -1.4142136, 1.4142136, 0, 0, 0, 0, 1, 0, -1.4142136, 1.4142136, 6, 1];
+ kid.matrix.forEach((value, index) => assert.ok(Math.abs(value - expected[index]) < 1e-4, `matrix[${index}] ${value} against ${expected[index]}`));
+});
+
+test('a sheared node is named with its parent chain and the way out', { timeout: 120000 }, async () => {
+ const message = await exportError(recipeOf([
+ { id: 'p', scale: [3, 1, 1] },
+ { id: 'shear', parent: 'p', geometry: 'box', material: 'm', rotation: [0, 0.3826834, 0, 0.9238795] }]));
+ assert.match(message, /part "shear" \(p > shear\) cannot preserve shear/);
+ assert.match(message, /Put the stretch on the node that holds the mesh/);
+ assert.match(message, /uniform scale/);
+});
+
+test('an emissive color above 1 passes scene_create and exports as color and emissive strength', { timeout: 120000 }, async () => {
+ const materials = [{ id: 'hot', color: [1, 0.5, 0.1], emission: 2, emissiveColor: [2, 1, 0.5] }];
+ const sessionId = await createScene(recipeOf([{ id: 'lamp', geometry: 'box', material: 'hot' }], materials));
+ const exported = await call('scene_export_glb', { sessionId });
+ assert.equal(exported.isError, undefined, exported.content?.[0]?.text);
+ const { json } = readGlb(await readFile(exported.structuredContent.path));
+ const [material] = json.materials;
+ assert.deepEqual(material.emissiveFactor, [1, 0.5, 0.25]);
+ assert.equal(material.extensions.KHR_materials_emissive_strength.emissiveStrength, 4);
+});