Skip to content

3D engine that AI agents drive

Pose the glTF clip before the native scene-file trace (#2310)

Nguyen Xuan Anda7bb70962f2
diff --git a/changes/2310.md b/changes/2310.md
new file mode 100644
index 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.md
index 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 freeze
diff --git a/scripts/render-file-native-options.mjs b/scripts/render-file-native-options.mjs
index 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, maxim
return 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.mjs
index 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.js
index 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, rende
const 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.js
index 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.js
index 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.js
index 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 stack
assert.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/);
+});