3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Keep child transforms under rotated, unevenly scaled parents in GLB export (#2127)
Nguyen Xuan Anf78277a8d23f
diff --git a/changes/2127.md b/changes/2127.mdnew file mode 100644index 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.mdnew file mode 100644index 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 changediff --git a/docs/export-glb.md b/docs/export-glb.mdindex 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 expoA 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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 additiassert.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.jsnew file mode 100644index 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);+});