3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Pose the glTF clip before the native scene-file trace (#2310)
Nguyen Xuan Anda7bb70962f2
diff --git a/changes/2310.md b/changes/2310.mdnew file mode 100644index 00000000..541b92b6--- /dev/null+++ b/changes/2310.md@@ -0,0 +1 @@+- `render-file-native.mjs` poses the glTF clip before the native trace, at the new `--time <seconds>`, instead of tracing the bind pose (#2310)diff --git a/docs/gltf.md b/docs/gltf.mdindex 5151fb02..8adc4b41 100644--- a/docs/gltf.md+++ b/docs/gltf.md@@ -110,7 +110,7 @@ A file over `maxBytes` (256 MiB by default) fails before decoding with an error`scripts/render-media.mjs --scene file` and `scripts/render-file-native.mjs` serve a GLB above 32 MiB from a local HTTP server that streams it from disk. Handing a file that size to the page through a Playwright route copies it through the browser protocol as one message and closed the whole browser tab (a 225 MB file did, with nothing else loading).-A scene file whose GLB has an animation clip plays the first clip on a loop in `scripts/render-media.mjs --scene file`, the way the showcase page does: the pose at a frame time is the clip at that time modulo the clip length. Staged files (`glbRest`) are not posed, and `scripts/render-file-native.mjs` still traces the bind pose. A GLB without a clip renders as before.+A scene file whose GLB has an animation clip plays the first clip on a loop in `scripts/render-media.mjs --scene file`, the way the showcase page does: the pose at a frame time is the clip at that time modulo the clip length. Staged files (`glbRest`) are not posed. `scripts/render-file-native.mjs` poses the same clip before it packs the scene, at `--time <seconds>` (default 0); render a video as one run per frame time. A GLB without a clip renders as before.## Loading a large scene without a long freezediff --git a/scripts/render-file-native-options.mjs b/scripts/render-file-native-options.mjsindex 27866b3d..91d2b828 100644--- a/scripts/render-file-native-options.mjs+++ b/scripts/render-file-native-options.mjs@@ -12,6 +12,7 @@ Usage: node scripts/render-file-native.mjs --config <scene.json> --out <prefix>--width <n>, --height <n> picture size in pixels, 16 to 8192 (default 800 x 450)--samples <n> paths per pixel, 1 to 100000 (default 128)--bounces <n> bounces per path, 1 to 16 (default 8)+ --time <seconds> pose the first glTF animation clip at this time (it loops; default 0); a video is one run per frame time--seed <n> noise seed, 0 to 2147483647 (default 1)--max-seconds <n> wall-clock limit of the trace, 1 to 86400 (default 600)--denoise oidn|atrous|none (default oidn, which falls back to atrous when OIDN is missing)@@ -27,7 +28,7 @@ Usage: node scripts/render-file-native.mjs --config <scene.json> --out <prefix>Exit code 2 means the native addon is not built; 1 is any other failure.`;-const VALUE_FLAGS = new Set(['--config', '--out', '--width', '--height', '--samples', '--bounces', '--seed', '--max-seconds', '--denoise',+const VALUE_FLAGS = new Set(['--config', '--out', '--width', '--height', '--samples', '--bounces', '--seed', '--time', '--max-seconds', '--denoise','--camera', '--chrome', '--list-parts', '--hide-parts', '--patch-materials']);const SWITCH_FLAGS = new Set(['--instancing', '--software-gl', '--write-raw', '--help', '-h']);const DENOISERS = ['oidn', 'atrous', 'none'];@@ -62,6 +63,15 @@ function readIntegerOption(argumentList, flagName, fallbackValue, minimum, maximreturn parsed;}+function readSecondsOption(argumentList, flagName, fallbackValue) {+ const text = readOption(argumentList, flagName, String(fallbackValue));+ const parsed = Number(text);+ if (!Number.isFinite(parsed) || parsed < 0) {+ throw new RangeError(`Option ${flagName} must be a number of seconds, 0 or more, got "${text}".`);+ }+ return parsed;+}+function assertKnownFlags(argumentList) {for (let index = 0; index < argumentList.length; index++) {const argument = argumentList[index];@@ -135,6 +145,7 @@ export function parseArguments(argumentList) {samples: readIntegerOption(argumentList, '--samples', 128, 1, 100000),bounces: readIntegerOption(argumentList, '--bounces', 8, 1, 16),seed: readIntegerOption(argumentList, '--seed', 1, 0, 2147483647),+ clipSeconds: readSecondsOption(argumentList, '--time', 0),maxSeconds: readIntegerOption(argumentList, '--max-seconds', 600, 1, 86400),denoise,writeRaw: argumentList.includes('--write-raw'),diff --git a/scripts/render-file-native.mjs b/scripts/render-file-native.mjsindex fe2fec6e..2297c2c7 100644--- a/scripts/render-file-native.mjs+++ b/scripts/render-file-native.mjs@@ -46,11 +46,13 @@ async function startViteServer(root) {}// Runs in the page: packs the loaded scene into the tables the native tracer reads, like the MCP render job does.-async function exportTablesInPage({ width, height, bounces, seed, instancing, camera, listParts, hideParts, patchMaterials, maximumTriangles }) {+async function exportTablesInPage({ width, height, bounces, seed, clipSeconds, instancing, camera, listParts, hideParts, patchMaterials, maximumTriangles }) {const [{ createCamera, describeIgnoredFeatures }, { buildTraceScene, resolveTexture }, pack, { buildNativeInput }, { buildJobNativeInput, buildFlattenedJobNativeInput }, { exportNativeSceneTables, splitExportForChunks }, gridVolumeInput] = await Promise.all([import('/src/path-tracer.js'), import('/src/path-tracer-scene.js'), import('/src/path-tracer-gpu-pack.js'),import('/node_modules/@codepawlhq/cook/pack-input.mjs'), import('/node_modules/@codepawlhq/cook/job-input.mjs'), import('/scripts/native-bake-page.js'), import('/node_modules/@codepawlhq/cook/grid-volume-input.mjs'),]);+ // The parts are packed as they stand, so pose the glTF clip first (a scene without a clip stays in its bind pose).+ window.__scene.poseClipAt?.(clipSeconds);const { environment } = window.__scene;const describePart = part => ({name: part.name,@@ -188,7 +190,7 @@ async function main() {const loadSeconds = (performance.now() - loadStarted) / 1000;const packStarted = performance.now();const capacityRead = readNativeCapacity(tracer);- const manifest = await page.evaluate(exportTablesInPage, { width: options.width, height: options.height, bounces: options.bounces, seed: options.seed, instancing: options.instancing, camera,+ const manifest = await page.evaluate(exportTablesInPage, { width: options.width, height: options.height, bounces: options.bounces, seed: options.seed, clipSeconds: options.clipSeconds, instancing: options.instancing, camera,listParts: options.listParts ?? null, hideParts: options.hideParts ?? null, patchMaterials: options.patchMaterials, maximumTriangles: chunkedTriangleBound(capacityRead.capacity?.maxUniqueTriangles) });const exported = await readHeldNativeExport(page, manifest, { blobExpression: 'window.__nativeExportBlob()', release: () => { window.__nativeExportBlob = null; }, capacity: capacityRead.capacity });const packSeconds = (performance.now() - packStarted) / 1000;diff --git a/src/file-scene-clip.js b/src/file-scene-clip.jsindex 0c94c29c..1c3e8332 100644--- a/src/file-scene-clip.js+++ b/src/file-scene-clip.js@@ -18,8 +18,13 @@ export function createFileSceneClipPlayer({ asset, posedParts, sceneParts, rendeconst partsToUpdate = rendererParts.filter((part, index) => posed.has(sceneParts[index]));return {clip,- poseAt(renderer, seconds) {+ // Poses the asset's parts without a renderer: the native path tracer packs the parts themselves (skinned vertices included),+ // so it needs the pose and no updateParts call.+ applyAt(seconds) {asset.applyAnimation(loopedClipTime(seconds, clip.duration), 0);+ },+ poseAt(renderer, seconds) {+ this.applyAt(seconds);renderer.updateParts(partsToUpdate, { shadows: true });},};diff --git a/src/file-scene.js b/src/file-scene.jsindex 13968932..51d19fa2 100644--- a/src/file-scene.js+++ b/src/file-scene.js@@ -78,7 +78,7 @@ async function start() {renderer.render({ ...frame, ...pose });};// `parts` and `environment` let scripts/render-file-native.mjs pack the same scene for the native path tracer.- window.__scene = { renderer, duration: camera?.duration, renderAt, pause() {}, parts: reflection.parts, environment: { ...(rendererOptions.environment ?? {}), map } };+ window.__scene = { renderer, duration: camera?.duration, renderAt, poseClipAt: seconds => clipPlayer?.applyAt(seconds), pause() {}, parts: reflection.parts, environment: { ...(rendererOptions.environment ?? {}), map } };}start().catch(error => {diff --git a/tests/file-scene-clip.test.js b/tests/file-scene-clip.test.jsindex d641b46c..16f2daa0 100644--- a/tests/file-scene-clip.test.js+++ b/tests/file-scene-clip.test.js@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';import { readFile } from 'node:fs/promises';import { parseGltf } from '../src/gltf.js';import { createFileSceneClipPlayer } from '../src/file-scene-clip.js';+import { skinnedGeometry } from '../src/path-tracer-scene.js';async function loadRobot() {const bytes = await readFile(new URL('fixtures/RobotExpressive.glb', import.meta.url));@@ -79,3 +80,29 @@ test('renderer parts that do not match the scene parts one for one are refused b/must match the scene parts/,);});++// What the native tracer reads from a part: the skinned vertices at the part's current pose (src/path-tracer-scene.js).+function tracedPositionsOf(parts) {+ return parts.filter(part => part.skin).map(part => [...skinnedGeometry(part).positions]);+}++test('applyAt poses the parts handed to the native tracer: the traced vertices differ between t=0 and half the clip', async () => {+ const { asset, player } = await playerForRobot();+ player.applyAt(0);+ const atStart = tracedPositionsOf(asset.parts);+ player.applyAt(player.clip.duration / 2);+ const atMiddle = tracedPositionsOf(asset.parts);+ assert.ok(atStart.length > 0, 'the robot must have skinned parts, or this test does not cover the tracer input');+ assert.notDeepEqual(atMiddle, atStart);+ player.applyAt(player.clip.duration / 2 + 2 * player.clip.duration);+ assert.deepEqual(tracedPositionsOf(asset.parts), atMiddle);+});++test('a scene without a clip has no player, so the traced parts stay as loaded', async () => {+ const asset = await loadRobot();+ asset.animations = [];+ const before = tracedPositionsOf(asset.parts);+ const player = createFileSceneClipPlayer({ asset, posedParts: asset.parts, sceneParts: asset.parts, rendererParts: rendererCopiesOf(asset.parts) });+ assert.equal(player, null);+ assert.deepEqual(tracedPositionsOf(asset.parts), before);+});diff --git a/tests/render-file-native-options.test.js b/tests/render-file-native-options.test.jsindex 18063817..3b74ca6a 100644--- a/tests/render-file-native-options.test.js+++ b/tests/render-file-native-options.test.js@@ -131,3 +131,10 @@ test('without the built addon the command exits 2 with one message and no stackassert.equal(result.stderr.trim(), missingAddonMessage());assert.doesNotMatch(result.stderr, /\n\s+at /);});++test('--time sets the clip time, defaults to 0 and refuses a negative or non-numeric value', () => {+ assert.equal(parseArguments(REQUIRED).clipSeconds, 0);+ assert.equal(parseArguments([...REQUIRED, '--time', '1.25']).clipSeconds, 1.25);+ assert.throws(() => parseArguments([...REQUIRED, '--time', '-1']), /Option --time must be a number of seconds/);+ assert.throws(() => parseArguments([...REQUIRED, '--time', 'soon']), /Option --time must be a number of seconds/);+});