3D engine that AI agents drive
Add a reproducible proof script for the #623 checks
Nguyen Xuan Anfa2ad79f7c2b
diff --git a/bench/reference/progressive-compare.mjs b/bench/reference/progressive-compare.mjsindex 321b47c8..b0c05e7d 100644--- a/bench/reference/progressive-compare.mjs+++ b/bench/reference/progressive-compare.mjs@@ -1,5 +1,5 @@// Draws reference scenes progressively (issue #623) and measures the time against the 64 sample still.-// node bench/reference/progressive-compare.mjs <output directory> <scene id or recipe.json>,... [--variant random|blue|importance|tree|both]+// node bench/reference/progressive-compare.mjs <output directory> <scene id or recipe.json>,... [--variant random|uniform|blue|importance|tree|both]// [--checkpoints 1,2,4,8,16,32,64] [--firefly-clamp 1e9] [--width 960] [--height 540] [--still] [--frames 200]// Files are <scene>@<variant>-<samples>.png, <scene>@still-64.png and timings.json; bench/reference/progressive-score.py scores them against Cycles.// With --frames the script also prints the median time of one full size sample (1 sample per pixel) for each scene.@@ -23,6 +23,7 @@ function valueAfter(flag, fallback) {const VARIANT_OPTIONS = {random: {},+ uniform: { lightSelection: 'uniform' },blue: { samplingPattern: 'blue-noise-first' },importance: { lightSelection: 'importance' },tree: { lightSelection: 'tree' },diff --git a/bench/reference/progressive-proof.mjs b/bench/reference/progressive-proof.mjsnew file mode 100644index 00000000..406da802--- /dev/null+++ b/bench/reference/progressive-proof.mjs@@ -0,0 +1,110 @@+// Prints the three "Done when" numbers of issue #623 in one table: progressive time to the 64 sample still's FLIP score,+// the median frame time at 1 sample per pixel, and the light choice score against uniform at equal samples.+// node bench/reference/progressive-proof.mjs <output directory> --cycles <directory with <scene>-cycles.npy> [--runs 3] [--frames 200]+// Behind the GPU lock: bash ~/.agents/tools/gpu-lock.sh node bench/reference/progressive-proof.mjs ...+// It runs progressive-compare.mjs and progressive-score.py (uv, flip-evaluator) once per run, so it needs Chrome, a GPU and uv.+// The scores do not change between runs; the times do, so every time is printed as a range over the runs.+import { spawnSync } from 'node:child_process';+import { createHash } from 'node:crypto';+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';+import { resolve } from 'node:path';++const argumentsGiven = process.argv.slice(2);+const valueAfter = (flag, fallback) => (argumentsGiven.includes(flag) ? argumentsGiven[argumentsGiven.indexOf(flag) + 1] : fallback);+const outputDirectory = resolve(argumentsGiven[0] ?? '');+const cyclesDirectory = resolve(valueAfter('--cycles', ''));+const runCount = Number(valueAfter('--runs', 3));+const frameCount = Number(valueAfter('--frames', 200));+if (!argumentsGiven[0] || !argumentsGiven.includes('--cycles')) {+ throw new Error('Usage: progressive-proof.mjs <output directory> --cycles <directory with <scene>-cycles.npy> [--runs 3] [--frames 200]');+}++const TIMED_SCENES = ['lit-interior', 'spot-area'];+const TIMED_VARIANTS = ['random', 'tree'];+const FRAME_SCENE = 'tests/fixtures/demo-room.recipe.json';+const CHECKPOINTS = '1,2,3,4,6,8,12,16,24,32,48,64';+const LIGHT_SCENE_SAMPLES = '16,64';+// --skip-light-choice leaves out item 3, which draws 17 scenes in four ways.+const lightSceneIds = argumentsGiven.includes('--skip-light-choice') ? [] : [...Object.keys(JSON.parse(readFileSync('bench/reference/path-tracer.json', 'utf8')).scores), 'many-lights'];++function run(command, commandArguments) {+ const result = spawnSync(command, commandArguments, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'], maxBuffer: 1 << 28 });+ if (result.status !== 0) throw new Error(`${command} ${commandArguments.slice(0, 3).join(' ')} failed with status ${result.status}`);+ return result.stdout;+}++function score(directory) {+ run('uv', ['run', '--no-project', '--python', '3.12', '--with', 'flip-evaluator', '--with', 'pillow', '--with', 'numpy',+ 'python', '-I', 'bench/reference/progressive-score.py', directory, '--cycles', cyclesDirectory]);+ return JSON.parse(readFileSync(`${directory}/progressive-score.json`, 'utf8'));+}++const range = values => (Math.min(...values) === Math.max(...values) ? `${Math.min(...values).toFixed(1)}` : `${Math.min(...values).toFixed(1)} to ${Math.max(...values).toFixed(1)}`);+const fileHash = path => createHash('sha256').update(readFileSync(path)).digest('hex');+const report = { timedScenes: {}, frameTime: {}, lightChoice: {} };++// 1. Time to the still's score, and 2. frame time.+for (let runIndex = 1; runIndex <= runCount; runIndex++) {+ const directory = `${outputDirectory}/run${runIndex}`;+ run(process.execPath, ['bench/reference/progressive-compare.mjs', directory, TIMED_SCENES.join(','), '--still', '--variant', TIMED_VARIANTS.join(','), '--checkpoints', CHECKPOINTS]);+ const scores = score(directory);+ const timings = JSON.parse(readFileSync(`${directory}/timings.json`, 'utf8'));+ for (const scene of TIMED_SCENES) {+ const stillScore = scores[`${scene}:still-64`];+ const still = timings[`${scene}:still-64`];+ for (const variant of TIMED_VARIANTS) {+ const reached = CHECKPOINTS.split(',').map(Number).find(samples => scores[`${scene}:${variant}-${samples}`] <= stillScore);+ const entry = (report.timedScenes[`${scene}:${variant}`] ??= { stillScore, stillSeconds: [], reachedSamples: [], progressiveSeconds: [], progressiveScore: null });+ entry.stillSeconds.push(still.seconds);+ if (reached === undefined) continue;+ const point = timings[`${scene}:${variant}:${reached}`];+ entry.reachedSamples.push(reached);+ entry.progressiveScore = scores[`${scene}:${variant}-${reached}`];+ entry.progressiveSeconds.push(point.setupSeconds + point.stepSeconds + point.snapshotSeconds);+ }+ }+ const frameDirectory = `${directory}/frame`;+ run(process.execPath, ['bench/reference/progressive-compare.mjs', frameDirectory, FRAME_SCENE, '--variant', 'random', '--checkpoints', '1', '--frames', String(frameCount)]);+ const frame = JSON.parse(readFileSync(`${frameDirectory}/timings.json`, 'utf8'))['demo-room:random:frame'];+ (report.frameTime.medianMilliseconds ??= []).push(frame.medianMilliseconds);+ (report.frameTime.minimumMilliseconds ??= []).push(frame.minimumMilliseconds);+ (report.frameTime.maximumMilliseconds ??= []).push(frame.maximumMilliseconds);+}++// 3. Default light choice against forced uniform. Scores do not vary between runs, so one pass.+const lightDirectory = `${outputDirectory}/light-choice`;+if (lightSceneIds.length) run(process.execPath, ['bench/reference/progressive-compare.mjs', lightDirectory, lightSceneIds.join(','), '--variant', 'uniform,tree,importance', '--checkpoints', LIGHT_SCENE_SAMPLES]);+if (lightSceneIds.length) run(process.execPath, ['bench/reference/progressive-compare.mjs', lightDirectory, lightSceneIds.join(','), '--variant', 'random', '--checkpoints', LIGHT_SCENE_SAMPLES]);+const lightScores = lightSceneIds.length ? score(lightDirectory) : {};+const files = lightSceneIds.length ? readdirSync(lightDirectory) : [];+for (const scene of lightSceneIds) {+ for (const samples of LIGHT_SCENE_SAMPLES.split(',')) {+ const defaultPath = `${lightDirectory}/${scene}@random-${samples}.png`;+ const uniformPath = `${lightDirectory}/${scene}@uniform-${samples}.png`;+ if (!files.includes(`${scene}@random-${samples}.png`)) continue;+ report.lightChoice[`${scene}:${samples}`] = {+ defaultScore: lightScores[`${scene}:random-${samples}`] ?? null,+ uniformScore: lightScores[`${scene}:uniform-${samples}`] ?? null,+ treeScore: lightScores[`${scene}:tree-${samples}`] ?? null,+ importanceScore: lightScores[`${scene}:importance-${samples}`] ?? null,+ defaultEqualsUniform: existsSync(uniformPath) ? fileHash(defaultPath) === fileHash(uniformPath) : null,+ };+ }+}+writeFileSync(`${outputDirectory}/progressive-proof.json`, JSON.stringify(report, null, 1));++console.log(`\nItem 1: progressive (default options) against the 64 sample still, 960 by 540, ${runCount} runs (seconds: setup, compile, steps and read back)`);+console.log('| Scene | Light choice | Still FLIP | Progressive FLIP | Samples reached | Progressive s | Still s |');+console.log('| --- | --- | --- | --- | --- | --- | --- |');+for (const [key, entry] of Object.entries(report.timedScenes)) {+ const progressive = entry.progressiveSeconds.length ? range(entry.progressiveSeconds) : 'not reached';+ console.log(`| ${key.split(':')[0]} | ${key.split(':')[1] === 'random' ? 'default (uniform)' : 'forced tree'} | ${entry.stillScore} | ${entry.progressiveScore ?? '-'} | ${[...new Set(entry.reachedSamples)].join(', ') || '-'} | ${progressive} | ${range(entry.stillSeconds)} |`);+}+console.log(`\nItem 2: median frame time at 1 sample per pixel, demo room, ${frameCount} frames, ${runCount} runs: median ${range(report.frameTime.medianMilliseconds)} ms (fastest frame ${range(report.frameTime.minimumMilliseconds)}, slowest ${range(report.frameTime.maximumMilliseconds)})`);+console.log('\nItem 3: default light choice (auto) against forced uniform, FLIP against Cycles (- means no Cycles render given)');+console.log('| Scene | Samples | Default | Uniform | Tree | Importance | Default pixels equal uniform |');+console.log('| --- | --- | --- | --- | --- | --- | --- |');+for (const [key, entry] of Object.entries(report.lightChoice)) {+ const [scene, samples] = key.split(':');+ console.log(`| ${scene} | ${samples} | ${entry.defaultScore ?? '-'} | ${entry.uniformScore ?? '-'} | ${entry.treeScore ?? '-'} | ${entry.importanceScore ?? '-'} | ${entry.defaultEqualsUniform} |`);+}diff --git a/docs/path-tracer.md b/docs/path-tracer.mdindex e9232dcf..f9a4ab81 100644--- a/docs/path-tracer.md+++ b/docs/path-tracer.md@@ -157,6 +157,19 @@ The light tree on the same 16 scenes (FLIP against Cycles, 16 and 64 samples, onThe scene that shows the gain is `many-lights` (`bench/reference/scenes.js`, issue #623): a 36 m corridor lit only by 24 ceiling lamps, 16 point and 8 spot. FLIP against Cycles at 960 by 540, 16 and 64 samples: uniform 0.1926 and 0.1471, importance 0.0594 and 0.0688, tree 0.0710 and 0.0617. One full size sample (median of 20 on the RTX 3060, shared machine) takes 72 ms with the uniform draw, 88 ms with importance (it sums every light at every hit) and 38 ms with the tree, because the first hit traces one shadow ray instead of 24; 64 steps took 15.7 s, 11.5 s and 12.4 s including the kernel compile and the read back of the checkpoints. Importance wins at 16 samples, the tree at 64, and the tree costs about half the time per sample.+Proof of the three checks of issue #623 on 2026-11-11 (`node bench/reference/progressive-proof.mjs <directory> --cycles <directory with the Cycles .npy files> [--runs 3]`, behind the GPU lock; it prints the tables below from `progressive-compare.mjs` and `progressive-score.py`). RTX 3060, 960 by 540, denoised, three runs, machine shared with other jobs, times are ranges. Progressive time is the setup, the steps and one read back; the still time is the whole `renderReferencePathTraced` call, kernel compile included.++| Scene | Light choice | Still FLIP | Progressive FLIP | Samples reached | Progressive s | Still s |+| --- | --- | --- | --- | --- | --- | --- |+| `lit-interior` | default (uniform) | 0.0769 | 0.0769 | 64 | 5.7 to 5.8 | 82.1 to 165.8 |+| `lit-interior` | forced tree | 0.0769 | 0.0724 | 24 | 80.0 to 134.0 | 82.1 to 165.8 |+| `spot-area` | default (uniform) | 0.0262 | 0.0262 | 64 | 4.0 to 4.4 | 3.9 to 4.3 |+| `spot-area` | forced tree | 0.0262 | 0.0239 | 48 | 3.8 to 4.2 | 3.9 to 4.3 |++- Reached sooner: `lit-interior` by a factor of 14 or more, and mostly because the still takes 82 to 166 s here. Not reached sooner: `spot-area` at the default options needs the same 64 samples as the still and takes the same time within the noise (the kernel was compiled before, so the still has no compile to hide). With the tree it needs 48, which is inside the noise too. The tree kernel compiles slowly (most of the 80 to 134 s on `lit-interior`).+- Frame time at 1 sample per pixel on the demo room (`tests/fixtures/demo-room.recipe.json`), median of 200 frames, three runs: 79.2 to 80.9 ms (fastest frame 75.8 to 77.0 ms, slowest 84.6 to 86.1 ms).+- Light choice at equal samples, FLIP against Cycles (one pass, 16 and 64 samples, all 17 path tracer scenes including `many-lights`). The default (`auto`) draws the same bytes as forced uniform on every scene but `many-lights`, which has 24 lamps (more than 8) and picks the tree: 0.0753 against 0.1926 at 16 and 0.0593 against 0.1471 at 64. With the tree forced, no scene with a Cycles render scores worse than uniform at either count: `brick-room` 0.1409 against 0.1699 and 0.0985 against 0.1166, `light-linking` 0.0220 against 0.0291 and 0.0212 against 0.0213, `lit-interior` 0.0854 against 0.1318 and 0.0569 against 0.0769, `spot-area` 0.0340 against 0.0415 and 0.0221 against 0.0262. The 12 other scenes have no Cycles render at hand; they have at most one local light, so uniform and tree draw the same pixels (the script prints whether the default image equals the uniform one). The earlier `brick-room` loss (0.2587 to 0.2692) no longer shows (the cause is not isolated; the Cycles file of this scene was taken at an earlier commit, so treat it as inferred that #813 fixed it).+## Real-time hybrid view (issue #624)`67js/addons/path-tracer-realtime` (`createRealtimeTracer(scene, { width, height, bounces, ... })`, then `frame(camera)` for every picture) draws the WebGL2 tracer fast enough to move the camera. It shares the WebGL2 context of the GPU still, so one render at a time owns it, and it draws to `canvas` (an `OffscreenCanvas` or a canvas element, 8 bit, ACES view transform). `readFrame()` returns the same picture as bytes. The pieces, each in its own module so they can move to the WebGPU backend: