Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add an optional Open Image Denoise for path traced stills (issue #303)

Nguyen Xuan An65505d53bd9f
diff --git a/.gitignore b/.gitignore
index fca31ce9..a9780623 100644
--- a/.gitignore
+++ b/.gitignore
@@ -58,3 +58,6 @@ public/agent-review.md
.claude/worktrees/
bench/gaussian-splats/data/
public/gaussian-splats.md
+
+# Optional denoiser binaries fetched by packages/denoise-oidn/fetch-oidn.mjs
+packages/denoise-oidn/vendor/
diff --git a/bench/reference/denoise-1080.mjs b/bench/reference/denoise-1080.mjs
new file mode 100644
index 00000000..53263cae
--- /dev/null
+++ b/bench/reference/denoise-1080.mjs
@@ -0,0 +1,53 @@
+// Times a 1920 by 1080 path traced still of the demo room through the real MCP image job, for each denoiser:
+// node bench/reference/denoise-1080.mjs [--samples 16] [--denoisers oidn,wavelet] [--out artifacts/denoise-1080.json]
+// Needs `npm run build`. Prints the job wall time, the tracer's own seconds, the denoise seconds and what actually ran.
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir, constants, setPriority } from 'node:os';
+import { join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+
+function optionValue(name, fallback) {
+ const index = process.argv.indexOf(name);
+ return index >= 0 ? process.argv[index + 1] : fallback;
+}
+
+const samples = Number(optionValue('--samples', '16'));
+const denoisers = optionValue('--denoisers', 'oidn,wavelet').split(',');
+const outputPath = optionValue('--out', 'artifacts/denoise-1080.json');
+
+setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);
+const directory = await mkdtemp(join(tmpdir(), '67js-denoise-1080-'));
+const transport = new StdioClientTransport({ command: process.execPath, args: [resolve('bin/67js-mcp.mjs'), '--backend', 'cpu', '--memory', '256', '--jobs', join(directory, 'jobs')], cwd: resolve('.'), stderr: 'pipe' });
+const client = new Client({ name: '67js-denoise-1080', version: '1' });
+const call = (name, argumentsValue) => client.callTool({ name, arguments: argumentsValue }, { timeout: 900000 });
+
+async function finished(jobId) {
+ for (;;) {
+ const record = (await call('scene_render_status', { jobId })).structuredContent;
+ if (['completed', 'cancelled', 'failed'].includes(record.state)) return record;
+ await delay(500);
+ }
+}
+
+const results = {};
+try {
+ await client.connect(transport);
+ const recipe = JSON.parse(await readFile('tests/fixtures/demo-room.recipe.json', 'utf8'));
+ const sessionId = (await call('scene_create', { recipe })).structuredContent.sessionId;
+ for (const denoise of denoisers) {
+ const started = performance.now();
+ const submitted = await call('scene_render_submit', { sessionId, expectedRevision: 0, settings: { kind: 'image', width: 1920, height: 1080, renderer: { type: 'pathTracer', samples, denoise } } });
+ const record = await finished(submitted.structuredContent.jobId);
+ const wallSeconds = (performance.now() - started) / 1000;
+ const metrics = (await call('scene_render_result', { jobId: submitted.structuredContent.jobId })).structuredContent.metrics ?? record.metrics;
+ const report = metrics.pathTracer;
+ results[denoise] = { state: record.state, samples, wallSeconds: Number(wallSeconds.toFixed(1)), tracedSeconds: Number(report.tracedSeconds.toFixed(1)), reportSeconds: Number(report.seconds.toFixed(1)), denoiseSeconds: report.denoiseSeconds === undefined ? null : Number(report.denoiseSeconds.toFixed(1)), ranDenoiser: report.denoiser, note: report.denoiserNote ?? null };
+ console.log(denoise, JSON.stringify(results[denoise]));
+ await call('scene_render_release', { jobId: submitted.structuredContent.jobId });
+ }
+} finally {
+ await client.close();
+}
+await writeFile(outputPath, JSON.stringify(results, null, 1));
diff --git a/bench/reference/denoise-browser.mjs b/bench/reference/denoise-browser.mjs
new file mode 100644
index 00000000..1b824ac8
--- /dev/null
+++ b/bench/reference/denoise-browser.mjs
@@ -0,0 +1,64 @@
+// Runs the OIDN network of the `denoiser` npm package (tensorflow.js) in Chrome on the captures of denoise-capture.mjs and writes
+// tfjs.f32 beside them. It uses the GPU, so start it through the shared GPU lock:
+// (cd artifacts/tfjs-denoiser && npm install denoiser) # not a dependency of 67js: a scratch install
+// bash ~/.agents/tools/gpu-lock.sh node bench/reference/denoise-browser.mjs [--backend webgl|webgpu] [--samples 8,16] [--scenes a,b]
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { chromium } from 'playwright';
+import { createServer } from 'vite';
+
+const WIDTH = 960;
+const HEIGHT = 540;
+const CHROME = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';
+
+function optionValue(name, fallback) {
+ const index = process.argv.indexOf(name);
+ return index >= 0 ? process.argv[index + 1] : fallback;
+}
+
+const rootDirectory = resolve(optionValue('--directory', 'artifacts/denoise'));
+const packageDirectory = resolve(optionValue('--package', 'artifacts/tfjs-denoiser/node_modules/denoiser'));
+const backend = optionValue('--backend', 'webgl');
+const quality = optionValue('--quality', 'high');
+const sampleFilter = optionValue('--samples', '').split(',').filter(Boolean);
+const sceneFilter = optionValue('--scenes', '').split(',').filter(Boolean);
+
+const server = await createServer({
+ root: resolve('bench/reference/denoise-browser'),
+ publicDir: packageDirectory,
+ resolve: { alias: { denoiser: `${packageDirectory}/dist/index.mjs` } },
+ server: { host: '127.0.0.1', port: 0, fs: { strict: false } },
+ logLevel: 'warn',
+});
+await server.listen();
+const browser = await chromium.launch({
+ executablePath: CHROME, headless: true,
+ args: ['--enable-webgl', '--ignore-gpu-blocklist', '--enable-unsafe-webgpu', '--enable-features=Vulkan,WebGPU', '--use-angle=d3d11'],
+});
+const timings = {};
+try {
+ const page = await browser.newPage();
+ page.setDefaultTimeout(0);
+ page.on('console', message => console.log('PAGE', message.text().slice(0, 200)));
+ page.on('pageerror', error => console.log('PAGE ERROR', error.message));
+ await page.goto(`http://127.0.0.1:${server.httpServer.address().port}/index.html`);
+ await page.waitForFunction(() => window.denoiseReady);
+ for (const scene of await readdir(rootDirectory, { withFileTypes: true })) {
+ if (!scene.isDirectory() || (sceneFilter.length && !sceneFilter.includes(scene.name))) continue;
+ for (const sample of await readdir(`${rootDirectory}/${scene.name}`, { withFileTypes: true })) {
+ if (!sample.isDirectory() || (sampleFilter.length && !sampleFilter.includes(sample.name))) continue;
+ const directory = `${rootDirectory}/${scene.name}/${sample.name}`;
+ const [color, albedo, normal] = await Promise.all(['color', 'albedo', 'normal'].map(async name => (await readFile(`${directory}/${name}.f32`)).toString('base64')));
+ const result = await page.evaluate(input => window.denoiseInBrowser(input), { width: WIDTH, height: HEIGHT, color, albedo, normal, backend, quality, tiling: false });
+ await writeFile(`${directory}/tfjs.f32`, Buffer.from(result.output, 'base64'));
+ const { output, ...metrics } = result;
+ timings[`${scene.name}/${sample.name}`] = metrics;
+ console.log(scene.name, sample.name, JSON.stringify(metrics));
+ }
+ }
+} finally {
+ await browser.close();
+ await server.close();
+}
+await mkdir(rootDirectory, { recursive: true });
+await writeFile(`${rootDirectory}/timings-tfjs-${backend}.json`, JSON.stringify(timings, null, 1));
diff --git a/bench/reference/denoise-browser/index.html b/bench/reference/denoise-browser/index.html
new file mode 100644
index 00000000..6715e453
--- /dev/null
+++ b/bench/reference/denoise-browser/index.html
@@ -0,0 +1,4 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>OIDN network in the browser</title>
+<script type="module" src="./main.js"></script>
diff --git a/bench/reference/denoise-browser/main.js b/bench/reference/denoise-browser/main.js
new file mode 100644
index 00000000..e1aeaa6a
--- /dev/null
+++ b/bench/reference/denoise-browser/main.js
@@ -0,0 +1,50 @@
+// Runs the OIDN network from the `denoiser` npm package (tensorflow.js) on one capture. denoise-browser.mjs drives this page.
+import { Denoiser } from 'denoiser';
+
+function base64ToFloats(base64) {
+ const binary = atob(base64);
+ const bytes = new Uint8Array(binary.length);
+ for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+ return new Float32Array(bytes.buffer);
+}
+
+function floatsToBase64(values) {
+ const bytes = new Uint8Array(values.buffer, values.byteOffset, values.byteLength);
+ let binary = '';
+ for (let start = 0; start < bytes.length; start += 0x8000) binary += String.fromCharCode(...bytes.subarray(start, start + 0x8000));
+ return btoa(binary);
+}
+
+// The network reads normals as colours, so they are mapped from [-1, 1] to [0, 1] first.
+function normalsAsColors(normal) {
+ const mapped = new Float32Array(normal.length);
+ for (let index = 0; index < normal.length; index++) mapped[index] = normal[index] * 0.5 + 0.5;
+ return mapped;
+}
+
+window.denoiseInBrowser = async ({ width, height, color, albedo, normal, backend, quality, tiling }) => {
+ const denoiser = new Denoiser(backend);
+ denoiser.weightsUrl = '/tzas';
+ denoiser.width = width;
+ denoiser.height = height;
+ denoiser.hdr = true;
+ denoiser.quality = quality;
+ denoiser.useTiling = tiling;
+ const started = performance.now();
+ await denoiser.build();
+ const buildSeconds = (performance.now() - started) / 1000;
+ denoiser.setInputData('color', base64ToFloats(color), { channels: 3 });
+ denoiser.setInputData('albedo', base64ToFloats(albedo), { channels: 3 });
+ denoiser.setInputData('normal', normalsAsColors(base64ToFloats(normal)), { channels: 3 });
+ const executeStarted = performance.now();
+ const output = await new Promise((resolve, reject) => {
+ denoiser.onExecute(result => resolve(result), 'float32');
+ denoiser.execute().catch(reject);
+ });
+ const executeSeconds = (performance.now() - executeStarted) / 1000;
+ const floats = output instanceof Float32Array ? output : output.data ?? output;
+ const result = { executeSeconds, buildSeconds, floatCount: floats.length, backend: denoiser.backend?.constructor?.name ?? null };
+ denoiser.dispose();
+ return { ...result, output: floatsToBase64(floats) };
+};
+window.denoiseReady = true;
diff --git a/bench/reference/denoise-capture.mjs b/bench/reference/denoise-capture.mjs
new file mode 100644
index 00000000..732ce05d
--- /dev/null
+++ b/bench/reference/denoise-capture.mjs
@@ -0,0 +1,49 @@
+// Draws reference scenes with the path tracer and keeps the untouched noisy output with its feature images, so every
+// denoiser in denoise-compare.mjs sees the same pixels:
+// node bench/reference/denoise-capture.mjs [--scenes a,b] [--samples 8,16,32,64] [--threads 6] [--directory artifacts/denoise]
+// Needs Chrome (CHROME_PATH) and writes <directory>/<scene>/<samples>/{color,albedo,normal,depth,variance}.f32 plus report.json.
+import { mkdir, writeFile } from 'node:fs/promises';
+import { constants, setPriority } from 'node:os';
+import { resolve } from 'node:path';
+import { chromium } from 'playwright';
+import { createServer } from 'vite';
+
+const WIDTH = 960;
+const HEIGHT = 540;
+const CHROME = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';
+const PAGE_LOAD_TIMEOUT = 180000;
+
+function optionValue(name, fallback) {
+ const index = process.argv.indexOf(name);
+ return index >= 0 ? process.argv[index + 1] : fallback;
+}
+
+const sceneIds = optionValue('--scenes', 'brick-graph,character,material-spheres,outdoor-hdri,metal,glass').split(',');
+const sampleCounts = optionValue('--samples', '8,16,32,64').split(',').map(Number);
+const threads = Number(optionValue('--threads', '6'));
+const outputDirectory = resolve(optionValue('--directory', 'artifacts/denoise'));
+
+setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);
+const server = await createServer({ server: { host: '127.0.0.1', port: 0 }, logLevel: 'silent' });
+await server.listen();
+const browser = await chromium.launch({ executablePath: CHROME, headless: true, args: ['--enable-webgl', '--use-angle=swiftshader', '--enable-unsafe-swiftshader'] });
+try {
+ const page = await browser.newPage({ viewport: { width: WIDTH, height: HEIGHT } });
+ page.setDefaultTimeout(0);
+ await page.goto(`http://127.0.0.1:${server.httpServer.address().port}/bench/reference/harness.html`, { timeout: PAGE_LOAD_TIMEOUT });
+ await page.waitForFunction(() => window.renderReferencePathTracedFeatures, null, { timeout: PAGE_LOAD_TIMEOUT });
+ for (const sceneId of sceneIds) {
+ for (const samples of sampleCounts) {
+ const options = { width: WIDTH, height: HEIGHT, samples, threads, maxSeconds: 1800 };
+ const result = await page.evaluate(([id, tracerOptions]) => window.renderReferencePathTracedFeatures(id, tracerOptions), [sceneId, options]);
+ const directory = `${outputDirectory}/${sceneId}/${samples}`;
+ await mkdir(directory, { recursive: true });
+ for (const [name, base64] of Object.entries(result.features)) await writeFile(`${directory}/${name}.f32`, Buffer.from(base64, 'base64'));
+ await writeFile(`${directory}/report.json`, JSON.stringify(result.report, null, 1));
+ console.log(`${sceneId} at ${samples} samples: ${result.report.seconds.toFixed(1)} s traced`);
+ }
+ }
+} finally {
+ await browser.close();
+ await server.close();
+}
diff --git a/bench/reference/denoise-compare.mjs b/bench/reference/denoise-compare.mjs
new file mode 100644
index 00000000..33a6228e
--- /dev/null
+++ b/bench/reference/denoise-compare.mjs
@@ -0,0 +1,67 @@
+// Runs the denoisers on the captures of denoise-capture.mjs and writes <method>.f32 beside them:
+// node bench/reference/denoise-compare.mjs [--directory artifacts/denoise] [--oidn-device cpu]
+// Methods: none (the traced colour), wavelet (src/path-tracer-denoise.js) and oidn (packages/denoise-oidn, native
+// Open Image Denoise). OIDN runs twice per capture and the two outputs are compared byte for byte.
+// denoise-score.py then scores every method against Cycles.
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { constants, setPriority } from 'node:os';
+import { resolve } from 'node:path';
+import { denoiseWithOidn, findOidnBinary } from '../../packages/denoise-oidn/index.mjs';
+import { denoiseRadiance } from '../../src/path-tracer-denoise.js';
+
+const WIDTH = 960;
+const HEIGHT = 540;
+const FEATURE_NAMES = ['color', 'albedo', 'normal', 'depth', 'variance'];
+
+function optionValue(name, fallback) {
+ const index = process.argv.indexOf(name);
+ return index >= 0 ? process.argv[index + 1] : fallback;
+}
+
+const rootDirectory = resolve(optionValue('--directory', 'artifacts/denoise'));
+const oidnDevice = optionValue('--oidn-device', 'cpu');
+
+async function readFloats(path) {
+ const bytes = await readFile(path);
+ return new Float32Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+}
+
+function writeFloats(path, values) {
+ return writeFile(path, Buffer.from(values.buffer, values.byteOffset, values.byteLength));
+}
+
+async function timed(work) {
+ const started = performance.now();
+ const value = await work();
+ return { value, seconds: (performance.now() - started) / 1000 };
+}
+
+function sameBytes(first, second) {
+ return Buffer.compare(Buffer.from(first.buffer), Buffer.from(second.buffer)) === 0;
+}
+
+setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);
+if (!findOidnBinary()) throw new Error('Run `npm run fetch` in packages/denoise-oidn first.');
+const timings = {};
+for (const sceneEntry of await readdir(rootDirectory, { withFileTypes: true })) {
+ if (!sceneEntry.isDirectory()) continue;
+ for (const sampleEntry of await readdir(`${rootDirectory}/${sceneEntry.name}`, { withFileTypes: true })) {
+ if (!sampleEntry.isDirectory()) continue;
+ const directory = `${rootDirectory}/${sceneEntry.name}/${sampleEntry.name}`;
+ const features = {};
+ for (const name of FEATURE_NAMES) features[name] = await readFloats(`${directory}/${name}.f32`);
+ const inputs = { width: WIDTH, height: HEIGHT, ...features };
+ const wavelet = await timed(() => denoiseRadiance(inputs));
+ const oidn = await timed(() => denoiseWithOidn({ ...inputs, device: oidnDevice }));
+ const oidnAgain = await denoiseWithOidn({ ...inputs, device: oidnDevice });
+ const oidnClean = await timed(() => denoiseWithOidn({ ...inputs, device: oidnDevice, cleanAux: true }));
+ await writeFloats(`${directory}/oidn-clean-aux.f32`, oidnClean.value);
+ await writeFloats(`${directory}/none.f32`, features.color);
+ await writeFloats(`${directory}/wavelet.f32`, wavelet.value);
+ await writeFloats(`${directory}/oidn.f32`, oidn.value);
+ const key = `${sceneEntry.name}/${sampleEntry.name}`;
+ timings[key] = { waveletSeconds: Number(wavelet.seconds.toFixed(2)), oidnSeconds: Number(oidn.seconds.toFixed(2)), oidnDevice, oidnSameBytesTwice: sameBytes(oidn.value, oidnAgain) };
+ console.log(key, JSON.stringify(timings[key]));
+ }
+}
+await writeFile(`${rootDirectory}/timings.json`, JSON.stringify(timings, null, 1));
diff --git a/bench/reference/denoise-score.py b/bench/reference/denoise-score.py
new file mode 100644
index 00000000..a6fdad2f
--- /dev/null
+++ b/bench/reference/denoise-score.py
@@ -0,0 +1,86 @@
+# Scores every denoiser output of denoise-compare.mjs against the Cycles render of the same scene with FLIP, and writes denoise.json:
+# uv run --no-project --python 3.12 --with flip-evaluator --with pillow --with numpy python -I bench/reference/denoise-score.py <capture directory> <cycles directory> <output json>
+# Each <capture directory>/<scene>/<samples>/<method>.f32 is linear RGB, 960 by 540. Like score.py, the image is tone mapped as 67js does
+# and rounded to 8 bits before FLIP, because a path traced still is written as an 8-bit PNG.
+import json
+import sys
+from pathlib import Path
+
+import flip_evaluator
+import numpy as np
+
+WIDTH = 960
+HEIGHT = 540
+GAMMA = 2.2
+MIN_SCENES_BETTER = 4
+
+
+def tone_map_like_67js(linear):
+ color = np.maximum(linear, 0)
+ mapped = np.clip((color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14), 0, 1)
+ return mapped ** (1 / GAMMA)
+
+
+def quantise_to_8_bit(display):
+ return np.round(np.clip(display, 0, 1) * 255).astype(np.float32) / 255
+
+
+def flip_score(reference, test):
+ _, mean_error, _ = flip_evaluator.evaluate(reference.astype(np.float32), test.astype(np.float32), "LDR", inputsRGB=True)
+ return round(float(mean_error), 4)
+
+
+def main():
+ capture_directory = Path(sys.argv[1])
+ cycles_directory = Path(sys.argv[2])
+ output_path = Path(sys.argv[3])
+ timings_path = capture_directory / "timings.json"
+ timings = json.loads(timings_path.read_text(encoding="utf-8")) if timings_path.exists() else {}
+ # With a fourth argument the reference is not Cycles but the tracer's own 512 sample capture without a filter in that
+ # directory (denoise-capture.mjs --samples 512), which takes the difference between the tracer and Cycles out of the
+ # score and leaves the noise and the blur the denoiser adds.
+ truth_directory = Path(sys.argv[4]) if len(sys.argv) > 4 else None
+ scores = {}
+ for scene_directory in sorted(path for path in capture_directory.iterdir() if path.is_dir()):
+ if truth_directory is not None:
+ truth_path = truth_directory / scene_directory.name / "512" / "color.f32"
+ if not truth_path.exists():
+ continue
+ cycles = quantise_to_8_bit(tone_map_like_67js(np.fromfile(truth_path, dtype=np.float32).reshape(HEIGHT, WIDTH, 3)))
+ else:
+ cycles_path = cycles_directory / f"{scene_directory.name}-cycles.npy"
+ if not cycles_path.exists():
+ continue
+ cycles = tone_map_like_67js(np.load(cycles_path))
+ scores[scene_directory.name] = {}
+ for sample_directory in sorted((path for path in scene_directory.iterdir() if path.is_dir()), key=lambda path: int(path.name)):
+ entry = {}
+ for method_path in sorted(sample_directory.glob("*.f32")):
+ if method_path.stem in ("color", "albedo", "normal", "depth", "variance"):
+ continue
+ linear = np.fromfile(method_path, dtype=np.float32).reshape(HEIGHT, WIDTH, 3)
+ entry[method_path.stem] = flip_score(cycles, quantise_to_8_bit(tone_map_like_67js(linear)))
+ scores[scene_directory.name][sample_directory.name] = entry
+ verdict = {}
+ for scene_id, by_samples in scores.items():
+ wavelet_at_64 = by_samples.get("64", {}).get("wavelet")
+ for method in sorted({name for entry in by_samples.values() for name in entry}):
+ if method in ("none", "wavelet"):
+ continue
+ beats = [samples for samples in ("8", "16") if wavelet_at_64 is not None and by_samples.get(samples, {}).get(method, 9) <= wavelet_at_64]
+ verdict.setdefault(method, {})[scene_id] = beats
+ report = {
+ "metric": "FLIP (LDR), mean error against Cycles, lower is better; 960 by 540, tone mapped and rounded to 8 bits",
+ "scores": scores,
+ "timings": timings,
+ "scenesWhereMethodAtOrBelow16BeatsWaveletAt64": {method: [scene for scene, beats in per_scene.items() if beats] for method, per_scene in verdict.items()},
+ "samplesThatBeatWaveletAt64": verdict,
+ }
+ output_path.write_text(json.dumps(report, indent=1) + "\n", encoding="utf-8")
+ for scene_id, by_samples in scores.items():
+ print(scene_id)
+ for samples, entry in by_samples.items():
+ print(" " + samples.rjust(3) + " spp " + " ".join(f"{name} {value:.4f}" for name, value in entry.items()))
+
+
+main()
diff --git a/bench/reference/denoise.json b/bench/reference/denoise.json
new file mode 100644
index 00000000..ac3df92b
--- /dev/null
+++ b/bench/reference/denoise.json
@@ -0,0 +1,333 @@
+{
+ "metric": "FLIP (LDR), mean error against Cycles, lower is better; 960 by 540, tone mapped and rounded to 8 bits",
+ "scores": {
+ "brick-graph": {
+ "8": {
+ "none": 0.0878,
+ "oidn-clean-aux": 0.0822,
+ "oidn": 0.0818,
+ "wavelet": 0.0821
+ },
+ "16": {
+ "none": 0.0844,
+ "oidn-clean-aux": 0.0819,
+ "oidn": 0.0812,
+ "wavelet": 0.0812
+ },
+ "32": {
+ "none": 0.0824,
+ "oidn-clean-aux": 0.0814,
+ "oidn": 0.0806,
+ "wavelet": 0.0807
+ },
+ "64": {
+ "none": 0.0811,
+ "oidn-clean-aux": 0.0811,
+ "oidn": 0.0804,
+ "wavelet": 0.0805
+ }
+ },
+ "character": {
+ "8": {
+ "none": 0.0425,
+ "oidn-clean-aux": 0.0322,
+ "oidn": 0.0324,
+ "wavelet": 0.0316
+ },
+ "16": {
+ "none": 0.036,
+ "oidn-clean-aux": 0.0311,
+ "oidn": 0.0308,
+ "wavelet": 0.0297
+ },
+ "32": {
+ "none": 0.0319,
+ "oidn-clean-aux": 0.03,
+ "oidn": 0.0295,
+ "wavelet": 0.0289
+ },
+ "64": {
+ "none": 0.0294,
+ "oidn-clean-aux": 0.0293,
+ "oidn": 0.0289,
+ "wavelet": 0.0287
+ }
+ },
+ "glass": {
+ "8": {
+ "none": 0.0522,
+ "oidn-clean-aux": 0.0408,
+ "oidn": 0.0407,
+ "wavelet": 0.0413
+ },
+ "16": {
+ "none": 0.0456,
+ "oidn-clean-aux": 0.0401,
+ "oidn": 0.0395,
+ "wavelet": 0.0399
+ },
+ "32": {
+ "none": 0.0416,
+ "oidn-clean-aux": 0.0391,
+ "oidn": 0.0385,
+ "wavelet": 0.0391
+ },
+ "64": {
+ "none": 0.0392,
+ "oidn-clean-aux": 0.0382,
+ "oidn": 0.0376,
+ "wavelet": 0.0385
+ }
+ },
+ "material-spheres": {
+ "8": {
+ "none": 0.0675,
+ "oidn-clean-aux": 0.0484,
+ "oidn": 0.0487,
+ "wavelet": 0.0488
+ },
+ "16": {
+ "none": 0.0578,
+ "oidn-clean-aux": 0.0474,
+ "oidn": 0.0471,
+ "wavelet": 0.0465
+ },
+ "32": {
+ "none": 0.0514,
+ "oidn-clean-aux": 0.0459,
+ "oidn": 0.0457,
+ "wavelet": 0.0454
+ },
+ "64": {
+ "none": 0.0474,
+ "oidn-clean-aux": 0.0452,
+ "oidn": 0.0449,
+ "wavelet": 0.0449
+ }
+ },
+ "metal": {
+ "8": {
+ "none": 0.0687,
+ "oidn-clean-aux": 0.0447,
+ "oidn": 0.0457,
+ "wavelet": 0.0513
+ },
+ "16": {
+ "none": 0.0594,
+ "oidn-clean-aux": 0.0432,
+ "oidn": 0.0444,
+ "wavelet": 0.0474
+ },
+ "32": {
+ "none": 0.0529,
+ "oidn-clean-aux": 0.0427,
+ "oidn": 0.044,
+ "wavelet": 0.0451
+ },
+ "64": {
+ "none": 0.0486,
+ "oidn-clean-aux": 0.0427,
+ "oidn": 0.0437,
+ "wavelet": 0.0439
+ }
+ },
+ "outdoor-hdri": {
+ "8": {
+ "none": 0.0351,
+ "oidn-clean-aux": 0.0258,
+ "oidn": 0.025,
+ "wavelet": 0.0241
+ },
+ "16": {
+ "none": 0.0302,
+ "oidn-clean-aux": 0.0258,
+ "oidn": 0.0239,
+ "wavelet": 0.0231
+ },
+ "32": {
+ "none": 0.0271,
+ "oidn-clean-aux": 0.025,
+ "oidn": 0.023,
+ "wavelet": 0.0227
+ },
+ "64": {
+ "none": 0.0249,
+ "oidn-clean-aux": 0.0248,
+ "oidn": 0.0226,
+ "wavelet": 0.0226
+ }
+ }
+ },
+ "timings": {
+ "brick-graph/16": {
+ "waveletSeconds": 3.41,
+ "oidnSeconds": 0.73,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "brick-graph/32": {
+ "waveletSeconds": 3.47,
+ "oidnSeconds": 0.67,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "brick-graph/64": {
+ "waveletSeconds": 3.99,
+ "oidnSeconds": 0.53,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "brick-graph/8": {
+ "waveletSeconds": 22.47,
+ "oidnSeconds": 1.74,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "character/16": {
+ "waveletSeconds": 3.94,
+ "oidnSeconds": 0.59,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "character/32": {
+ "waveletSeconds": 3.79,
+ "oidnSeconds": 0.53,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "character/64": {
+ "waveletSeconds": 4.07,
+ "oidnSeconds": 0.61,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "character/8": {
+ "waveletSeconds": 3.49,
+ "oidnSeconds": 0.62,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "glass/16": {
+ "waveletSeconds": 3.71,
+ "oidnSeconds": 0.51,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "glass/32": {
+ "waveletSeconds": 4.05,
+ "oidnSeconds": 0.68,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "glass/64": {
+ "waveletSeconds": 3.44,
+ "oidnSeconds": 0.75,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "glass/8": {
+ "waveletSeconds": 3.74,
+ "oidnSeconds": 0.61,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "material-spheres/16": {
+ "waveletSeconds": 3.92,
+ "oidnSeconds": 0.55,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "material-spheres/32": {
+ "waveletSeconds": 3.9,
+ "oidnSeconds": 0.53,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "material-spheres/64": {
+ "waveletSeconds": 3.47,
+ "oidnSeconds": 0.6,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "material-spheres/8": {
+ "waveletSeconds": 3.7,
+ "oidnSeconds": 0.52,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "metal/16": {
+ "waveletSeconds": 3.88,
+ "oidnSeconds": 0.7,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "metal/32": {
+ "waveletSeconds": 3.49,
+ "oidnSeconds": 0.61,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "metal/64": {
+ "waveletSeconds": 3.41,
+ "oidnSeconds": 0.5,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "metal/8": {
+ "waveletSeconds": 4.01,
+ "oidnSeconds": 0.6,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "outdoor-hdri/16": {
+ "waveletSeconds": 3.54,
+ "oidnSeconds": 0.65,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "outdoor-hdri/32": {
+ "waveletSeconds": 3.59,
+ "oidnSeconds": 0.52,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "outdoor-hdri/64": {
+ "waveletSeconds": 2.2,
+ "oidnSeconds": 0.46,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ },
+ "outdoor-hdri/8": {
+ "waveletSeconds": 2.82,
+ "oidnSeconds": 0.45,
+ "oidnDevice": "cpu",
+ "oidnSameBytesTwice": true
+ }
+ },
+ "scenesWhereMethodAtOrBelow16BeatsWaveletAt64": {
+ "oidn": [],
+ "oidn-clean-aux": [
+ "metal"
+ ]
+ },
+ "samplesThatBeatWaveletAt64": {
+ "oidn": {
+ "brick-graph": [],
+ "character": [],
+ "glass": [],
+ "material-spheres": [],
+ "metal": [],
+ "outdoor-hdri": []
+ },
+ "oidn-clean-aux": {
+ "brick-graph": [],
+ "character": [],
+ "glass": [],
+ "material-spheres": [],
+ "metal": [
+ "16"
+ ],
+ "outdoor-hdri": []
+ }
+ }
+}
diff --git a/bench/reference/harness.js b/bench/reference/harness.js
index ba3cb561..24d967c6 100644
--- a/bench/reference/harness.js
+++ b/bench/reference/harness.js
@@ -252,6 +252,24 @@ async function renderReferencePathTraced(id, options) {
return { image: canvas.toDataURL('image/png').split(',')[1], report: result.report };
}
+function floatsToBase64(values) {
+ const bytes = new Uint8Array(values.buffer, values.byteOffset, values.byteLength);
+ let binary = '';
+ for (let start = 0; start < bytes.length; start += 0x8000) binary += String.fromCharCode(...bytes.subarray(start, start + 0x8000));
+ return btoa(binary);
+}
+
+// The untouched tracer output (no denoiser) with its feature images, so denoisers can be compared on the same noisy pixels.
+async function renderReferencePathTracedFeatures(id, options) {
+ const scene = await REFERENCE_SCENES[id]();
+ const { renderPathTracedImage } = await import('/src/path-tracer.js');
+ const result = await renderPathTracedImage({ parts: applyLightLinks(scene.parts, scene.environment), environment: scene.environment, camera: scene.camera }, { ...options, denoise: false });
+ const features = {};
+ for (const [name, values] of Object.entries(result.features)) features[name] = floatsToBase64(values);
+ return { features, report: result.report };
+}
+
+window.renderReferencePathTracedFeatures = renderReferencePathTracedFeatures;
window.renderReferenceScene = renderReferenceScene;
window.renderReferencePathTraced = renderReferencePathTraced;
window.referenceSceneIds = Object.keys(SCENES);
diff --git a/bench/reference/render-blender.py b/bench/reference/render-blender.py
index 053f18e7..57db7cde 100644
--- a/bench/reference/render-blender.py
+++ b/bench/reference/render-blender.py
@@ -822,12 +822,16 @@ def configure_output(scene):
def configure_cycles(scene):
scene.render.engine = "CYCLES"
- preferences = bpy.context.preferences.addons["cycles"].preferences
- preferences.compute_device_type = "OPTIX"
- preferences.get_devices()
- for device in preferences.devices:
- device.use = device.type == "OPTIX"
- scene.cycles.device = "GPU"
+ if os.environ.get("CYCLES_DEVICE") == "CPU":
+ # --no-gpu in run.mjs: the same renderer on the CPU, for when another job holds the GPU.
+ scene.cycles.device = "CPU"
+ else:
+ preferences = bpy.context.preferences.addons["cycles"].preferences
+ preferences.compute_device_type = "OPTIX"
+ preferences.get_devices()
+ for device in preferences.devices:
+ device.use = device.type == "OPTIX"
+ scene.cycles.device = "GPU"
scene.cycles.samples = CYCLES_SAMPLES
scene.cycles.use_denoising = True
scene.cycles.volume_step_rate = 1
diff --git a/bench/reference/run.mjs b/bench/reference/run.mjs
index e113687f..3871a0f2 100644
--- a/bench/reference/run.mjs
+++ b/bench/reference/run.mjs
@@ -34,8 +34,11 @@ const HEIGHT = 540;
// This process runs below normal priority, so a busy machine takes the page load past Playwright's 30 second default
// (measured 22 s, against 5 s when idle). Load time does not affect any score.
const PAGE_LOAD_TIMEOUT = 180000;
+// --no-gpu keeps the whole run off the GPU: the "gpu" render uses SwiftShader and Cycles runs on the CPU. The scene
+// descriptions and the Cycles images are what the path tracer comparison needs; the rasterizer scores of such a run are not comparable.
+const noGpu = process.argv.includes('--no-gpu');
const BACKEND_ARGUMENTS = {
- gpu: ['--enable-webgl', '--ignore-gpu-blocklist', '--disable-renderer-backgrounding'],
+ gpu: noGpu ? ['--enable-webgl', '--ignore-gpu-blocklist', '--use-angle=swiftshader', '--enable-unsafe-swiftshader'] : ['--enable-webgl', '--ignore-gpu-blocklist', '--disable-renderer-backgrounding'],
cpu: ['--enable-webgl', '--ignore-gpu-blocklist', '--use-angle=swiftshader', '--enable-unsafe-swiftshader'],
};
@@ -159,7 +162,7 @@ async function renderPathTracerScenes(serverUrl) {
}
function runChecked(command, commandArguments) {
- const result = spawnSync(command, commandArguments, { stdio: ['ignore', 'pipe', 'inherit'], encoding: 'utf8', maxBuffer: 1 << 28 });
+ const result = spawnSync(command, commandArguments, { stdio: ['ignore', 'pipe', 'inherit'], encoding: 'utf8', maxBuffer: 1 << 28, env: { ...process.env, ...(noGpu ? { CYCLES_DEVICE: 'CPU' } : {}) } });
const lines = result.stdout.split('\n').filter(line => !/^(Fra:|Saved:|Time:|\s*$)/.test(line));
console.log(lines.slice(-30).join('\n'));
if (result.status !== 0) throw new Error(`${command} exited with ${result.status}.`);
diff --git a/bench/size/budgets.json b/bench/size/budgets.json
index 1ee09f27..459b421b 100644
--- a/bench/size/budgets.json
+++ b/bench/size/budgets.json
@@ -32,7 +32,7 @@
"entry:clutter": 5300,
"entry:light-bake": 28500,
"entry:ground-bounce": 9460,
- "entry:path-tracer": 15844,
+ "entry:path-tracer": 15960,
"entry:texture-set": 900,
"entry:agent-scene": 80770,
"entry:agent-scene+lazy": 263350,
diff --git a/bench/tool-cost-budgets.json b/bench/tool-cost-budgets.json
index ec9c791d..0ff57b3c 100644
--- a/bench/tool-cost-budgets.json
+++ b/bench/tool-cost-budgets.json
@@ -1,6 +1,6 @@
{
"measured": "2026-10-31, from scripts/measure-tool-cost.mjs; raised by 800 total and 150 for scene_apply for branch and labels fields (no new tool); raised by 650 total and 80 for scene_apply for clip layers, bone masks and retargeting through MCP; raised by 20 for scene_create and 20 for the scene_capabilities result after merging the expression language with the material graph; was 373388 schema bytes before shared IDs and recipe references; trimmed after the render-passes merge: material graph, depth of field, motion blur and passes details moved to scene_capabilities, budgets set to the measured value plus 0.5% (total 188267, scene_capabilities result 5167); raised by 95 for scene_apply and 690 for the scene_capabilities result for node relations; curve and text geometry entries shortened to a pointer at scene_capabilities curveText, budgets set to the measured value plus 0.5% (total 189468, scene_capabilities result 6399); then six modifier ops (weld, triangulate, edge_split, smooth, simple_deform, cast) added as one compact schema entry with details in scene_capabilities meshModifiers, entry and mesh_stack description shortened: total 190382 (budget unchanged at 190420), mesh_edit 34216 (budget 34220), scene_capabilities result 7042 (budget 7050); mesh_stack 11682 (budget 11690); after merging imported mesh topology with the modifier ops: raised the total to 190480 (measured 190471), mesh_edit to 34300 (measured 34293) and the scene_capabilities result to 7520 (measured 7512) for imported mesh edits; then cloth (recipe cloth, set-cloth, grid geometry) added with the total unchanged at 190480 (measured 189159): physics descriptions shortened and set-physics now takes the same record reference as set-motion, scene_create raised to 62150 and scene_apply lowered to 44130, scene_capabilities result raised to 8190 (measured 8176) for the cloth details; then particles and hair (recipe `particles`, set-particles) added with the total unchanged at 190480 (measured 189642, scene_create raised to 62350 and scene_apply to 44370 for the recipe particles reference and set-particles): the section is one record reference described in scene_capabilities, so the scene_capabilities result rose to 9570 (measured 9523) for the particle and hair fields; after merging the film timeline (recipe timeline, set-timeline) with particles: total 190719 (budget 190730), scene_create 62464, scene_apply 44620, scene_capabilities result 9902; then the path tracer renderer setting (drop z.int bounds, integers still checked by the job validator): total raised to 190830 (measured 190818); after merging the render limits and light bake with the path tracer: measured total 190013, scene_create raised to 62680 (measured 62667), scene_apply to 44860 (measured 44852) and the scene_capabilities result to 10620 (measured 10613) for the bake section and job size limits; then material layers anisotropy and iridescence (issue #51): the 16 layer fields take one short line each in the schema and their ranges and notes moved to scene_capabilities scene.materialLayers, so the scene_capabilities result rose to 12230 (measured 12168); then the worker bake limit added workerMaxSeconds to the bake limits (result 13361, budget raised to 13370); then the sculpt and shrinkwrap mesh edits (issue #47) with the total unchanged at 190830 (measured 190612): the face rule and tag prefix descriptions shortened (the face rule text repeats in every select field), so mesh_edit rose to 33980 (measured 33960) and mesh_stack fell to 11030 (measured 11014), and the scene_capabilities result rose to 13350 (measured 13338) for the meshSculpt notes; then recipe light links and shadow cascades (issue #52): environment fields added to the shared environment schema with the total unchanged at 190830 (measured 190507) by shortening its descriptions, and the scene_capabilities result raised to 13870 (measured 13865) for lightLinking and shadowCascades; then the nine remaining modifiers (issue #42: screw, skin, wireframe, lattice, curve, hook, wave, weighted_normal, smooth_by_angle) added their notes to meshModifiers and a free modifier record replaced the modifier schema entry, so the schemas shrank and the scene_capabilities result rose to 15900 (measured 15814); path query of scene_inspect (issue #64): one record field of 205 bytes in the scene_inspect schema (total 190732, within its budget) and the navigation notes in scene_capabilities, so the result rose to 14500 (measured 14494); reflection probes (issue #55): the bake.probes line, and the scene_capabilities result raised to 16600 (measured 16541) after merging with main; volumeFog shadowAmbient (issue #165): scene_create raised to 62945 (measured 62940) and scene_apply to 45040 (measured 45037); keyframe easing (issue #286): one easing string field in each of the motion track schemas, scene_create raised to 63450 (measured 63444) and the total to 191000 (measured 190994); glTF import line gltfImport (issue #280): the scene_capabilities result raised to 16701 (measured 16681)",
- "schemaTotalBytes": 191000,
+ "schemaTotalBytes": 191040,
"schemaToolBytes": {
"scene_create": 63450,
"scene_apply": 45040,
diff --git a/changes/303.md b/changes/303.md
new file mode 100644
index 00000000..40db4e27
--- /dev/null
+++ b/changes/303.md
@@ -0,0 +1 @@
+- Add `settings.renderer.denoise: "oidn"` for path traced render jobs (issue #303): Intel Open Image Denoise from the optional package `@codepawlhq/67js-denoise-oidn`, outside the core archive. `denoise` also takes `"wavelet"` (the old `true`) and `"none"`; `oidn` defaults to 16 samples, and a job without the package or its binary falls back to the wavelet filter and says so in `metrics.pathTracer.denoiserNote`. At 1920 by 1080 the denoise step took 1.6 s against about 9 s for the wavelet filter (measured). `bench/reference/denoise-*.mjs` compare the denoisers.
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index 356f7b70..2a4f5fae 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -44,7 +44,7 @@ Unidirectional path tracing against the triangle BVH that the [light bake](light
| `threads` | 4 | 1 to 8 | Module workers; the pixels are the same for any count. Without `Worker` it runs on one thread. |
| `noiseThreshold` | 0 | 0 to 1 (render jobs: 0 to 0.1) | 0 draws every sample. Above 0, a pixel stops once the standard error of its mean luminance, relative to that mean plus 0.05, is under this, checked from 16 samples on and after every 8 more. It costs quality on some scenes (see the table below). It reads only the pixel's own samples, so the result is the same on any thread count and band split. `report.averageSamples` says how many paths a pixel took. |
| `maxSeconds` | 300 | 1 to 1800 | Wall-clock limit. Passing it throws; there is never a partial image. |
-| `denoise` | true | boolean | Filters the light with normal, depth and noise guides. |
+| `denoise` | true | boolean, `"wavelet"`, `"oidn"`, `"none"` | `true` or `"wavelet"` filters the light with normal, depth and noise guides; `false` or `"none"` does not filter. `"oidn"` is [Open Image Denoise](#open-image-denoise-optional): a render job with it defaults to 16 samples. |
| `fireflyClamp` | 20 | 1 to 1000 | Largest radiance one bounce may add to a sample. |
Also checked before any ray is traced: samples times pixels times bounces at most 4 billion, 400,000 triangles, 1,024 parts, 32 lights, and finite numbers and in-range indices in every part. A render job limits `maxSeconds` to 600: the job runs on workers without blocking the page, and its deadline is `maxSeconds` plus 60 seconds for the page and the PNG, so a trace that reaches its limit still ends before the job does.
@@ -92,6 +92,27 @@ Fewer samples with the denoiser lose little on some scenes: 24 samples scored wi
The 1920 by 1080 still of `tests/fixtures/demo-room.recipe.json` at `samples: 64`, through an MCP image job with 8 threads: 246.4 s in the tracer (229.4 s tracing, the rest the filter), 30.7 samples per pixel on average, 257 s for the whole job (measured, once, with `noiseThreshold` 0.03, the setting at that time). With the default of 0 every pixel draws all 64, so the same still takes 585.9 s in the tracer and 596.1 s for the job (measured 2026-11-01 on 8 threads, machine at 100 percent CPU), inside the 600 s limit with almost no room: lower `samples` or pass a `noiseThreshold` for a larger room. That is 6 seconds over the old 240 s job limit, so the limit is now 600. The hair strands were not the cost by themselves: the time was per ray, and every ray was slow.
+## Open Image Denoise (optional)
+
+`settings.renderer.denoise: "oidn"` filters the still with [Intel Open Image Denoise](https://github.com/RenderKit/oidn) 2.5.1 (Apache-2.0), the denoiser Cycles uses, fed the colour, albedo and normal images the tracer writes. It is the package `@codepawlhq/67js-denoise-oidn` (`packages/denoise-oidn`), not part of the core archive: install it beside `67js` and run its `fetch` script, which downloads the official release binary for the platform after a SHA-256 check. The job runner calls the `oidnDenoise` tool on the CPU. Without the package or the binary the job runs the wavelet filter and says why in `metrics.pathTracer.denoiserNote`; `metrics.pathTracer.denoiser` always names the filter that ran. Only the native build is shipped. The browser port (`denoiser` 0.0.11 on tensorflow.js) is a 134 MB install; its scores are not in the table because the GPU it needs was not free for this comparison (`bench/reference/denoise-browser.mjs` is the script to run it), and the job runner already has Node.
+
+Compared on 960 by 540 captures of six reference scenes, FLIP against Cycles, lower is better (`bench/reference/denoise.json`, made by `denoise-capture.mjs`, `denoise-compare.mjs` and `denoise-score.py`). The unfiltered tracer, the wavelet filter and OIDN all land within 0.01 of each other on every scene except `metal`, because most of the score is the difference between the tracer and Cycles, not noise:
+
+| Scene | Wavelet, 64 samples | Wavelet, 16 | OIDN, 16 | OIDN, 8 | OIDN, 32 |
+| --- | --- | --- | --- | --- | --- |
+| `brick-graph` | 0.0805 | 0.0812 | 0.0812 | 0.0818 | 0.0806 |
+| `character` | 0.0287 | 0.0297 | 0.0308 | 0.0324 | 0.0295 |
+| `glass` | 0.0385 | 0.0399 | 0.0395 | 0.0407 | 0.0385 |
+| `material-spheres` | 0.0449 | 0.0465 | 0.0471 | 0.0487 | 0.0457 |
+| `metal` | 0.0439 | 0.0474 | 0.0444 | 0.0457 | 0.0440 |
+| `outdoor-hdri` | 0.0226 | 0.0231 | 0.0239 | 0.0250 | 0.0230 |
+
+OIDN at 16 samples does not score at or below the wavelet filter at 64 on any of the six scenes: it is 0.0005 to 0.0022 higher. At 32 samples it equals it on `glass` and is 0.0001 to 0.0008 higher on the other five. Issue #303's goal (no worse than the wavelet filter at 64 on four scenes with 16 samples or fewer) is therefore not met by this measure. At equal samples OIDN is clearly better only on `metal` (0.0444 against 0.0474 at 16); on the other scenes the two are within 0.0013 of each other, the wavelet filter ahead on `character`, `material-spheres` and `outdoor-hdri`. So 16 samples is the default for `oidn` because it costs a quarter of the tracing time for a score about 0.001 to 0.002 higher, not because it matches 64.
+
+Time of the denoise step alone, 1920 by 1080 demo room: 1.6 s for OIDN against about 9 s for the wavelet filter (measured once each, machine loaded by other jobs; the 960 by 540 captures took 0.45 to 0.67 s against 2.1 to 3.2 s). The whole still at 16 samples took 138 s with OIDN (113 s tracing) and 105 s with the wavelet filter (85 s tracing); the tracing times differ because of load, not of the filters. A 64 sample wavelet still of that room took 586 s (above), so 16 samples with OIDN is about four times faster at a FLIP score 0.001 to 0.002 higher on these scenes.
+
+OIDN's output is the same bytes run to run on one machine (the CPU device, two runs on each of the 24 captures, and two identical PNGs from an MCP job); it was not compared across machines or CPU generations, where OIDN does not promise it.
+
## Measured
`npm run reference -- --path-tracer [--samples 32]` draws each reference scene with the tracer and scores it against the Cycles render of the same scene with FLIP (`bench/reference/path-tracer.json`). It leaves `baseline.json` and `images/` alone, and it needs the Cycles renders of an earlier `npm run reference`.
diff --git a/package-lock.json b/package-lock.json
index 23f2a0c8..d1b94cb3 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -15,6 +15,7 @@
"67js-mcp": "bin/67js-mcp.mjs"
},
"devDependencies": {
+ "@codepawlhq/67js-denoise-oidn": "file:packages/denoise-oidn",
"@dimforge/rapier3d-compat": "0.21.0",
"@modelcontextprotocol/client": "2.4.0",
"@modelcontextprotocol/server": "2.4.0",
@@ -158,6 +159,10 @@
"node": ">=16"
}
},
+ "node_modules/@codepawlhq/67js-denoise-oidn": {
+ "resolved": "packages/denoise-oidn",
+ "link": true
+ },
"node_modules/@cspotcode/source-map-support": {
"version": "0.8.1",
"resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
@@ -3091,6 +3096,15 @@
"funding": {
"url": "https://github.com/sponsors/colinhacks"
}
+ },
+ "packages/denoise-oidn": {
+ "name": "@codepawlhq/67js-denoise-oidn",
+ "version": "0.1.0",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=22"
+ }
}
}
}
diff --git a/package.json b/package.json
index 342bbed1..2ed1dd62 100644
--- a/package.json
+++ b/package.json
@@ -164,6 +164,7 @@
}
},
"devDependencies": {
+ "@codepawlhq/67js-denoise-oidn": "file:packages/denoise-oidn",
"@dimforge/rapier3d-compat": "0.21.0",
"@modelcontextprotocol/client": "2.4.0",
"@modelcontextprotocol/server": "2.4.0",
diff --git a/packages/denoise-oidn/README.md b/packages/denoise-oidn/README.md
new file mode 100644
index 00000000..35227902
--- /dev/null
+++ b/packages/denoise-oidn/README.md
@@ -0,0 +1,12 @@
+# @codepawlhq/67js-denoise-oidn
+
+Optional native denoiser for 67js path traced stills: [Intel Open Image Denoise](https://github.com/RenderKit/oidn) (Apache-2.0) 2.5.1, called through its official `oidnDenoise` tool with the colour, albedo and normal images the tracer already writes. It is not part of the core `67js` archive.
+
+```sh
+npm install @codepawlhq/67js-denoise-oidn
+npm run fetch --prefix node_modules/@codepawlhq/67js-denoise-oidn # downloads the release for this platform into ./vendor after a SHA-256 check
+```
+
+Then ask a render job for it: `settings.renderer: { type: "pathTracer", denoise: "oidn" }`. Samples default to 16 for `oidn`. If the package or its binary is missing, the job uses the wavelet filter and says so in `metrics.pathTracer.denoiserNote`. `OIDN_DENOISE_PATH` points at an `oidnDenoise` you installed yourself.
+
+`denoiseWithOidn({ width, height, color, albedo, normal })` takes row-major `Float32Array`s with three floats per pixel and returns the filtered colour. It runs on the CPU by default, so the GPU stays free and the result does not depend on a graphics driver. On one machine the same input gave the same bytes twice (measured).
diff --git a/packages/denoise-oidn/fetch-oidn.mjs b/packages/denoise-oidn/fetch-oidn.mjs
new file mode 100644
index 00000000..df3c461c
--- /dev/null
+++ b/packages/denoise-oidn/fetch-oidn.mjs
@@ -0,0 +1,53 @@
+// Downloads the official Open Image Denoise release for this platform into ./vendor (ignored by git), after checking
+// its SHA-256. Run it with `npm run fetch` in this package. The downloaded archive is only unpacked, never run as a script.
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { OIDN_VERSION } from './index.mjs';
+
+const RELEASE_ASSETS = {
+ 'win32-x64': { name: `oidn-${OIDN_VERSION}.x64.windows.zip`, sha256: 'f11f91bc072a5e3a564515724cb72ab8fcfbc445c84a84c197ff9b16cc01396f' },
+ 'linux-x64': { name: `oidn-${OIDN_VERSION}.x86_64.linux.tar.gz`, sha256: '743c3e2aff8c220d5d70fe6cb970fb3d36f2702d2693c61d1d148e404cf37cd6' },
+ 'darwin-x64': { name: `oidn-${OIDN_VERSION}.x86_64.macos.tar.gz`, sha256: 'a4341639005a33ce0d944bd7c771ce34de1465be7eb3189b7c3b5b0064429832' },
+ 'darwin-arm64': { name: `oidn-${OIDN_VERSION}.arm64.macos.tar.gz`, sha256: '98e0aca8e7ab69e9f4f0191582a500fd8b0d9085d68662f18ab6469e934a6efd' },
+};
+
+const VENDOR_DIRECTORY = join(dirname(fileURLToPath(import.meta.url)), 'vendor');
+
+function extract(archivePath, destination) {
+ // Windows ships bsdtar, which reads zip files; GNU tar from Git for Windows does not.
+ const tarCommand = process.platform === 'win32' ? join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'tar.exe') : 'tar';
+ const result = spawnSync(tarCommand, ['-xf', archivePath, '-C', destination], { stdio: 'inherit' });
+ if (result.status !== 0) throw new Error('Unpacking the Open Image Denoise archive failed.');
+}
+
+export async function fetchOidn() {
+ const asset = RELEASE_ASSETS[`${process.platform}-${process.arch}`];
+ if (!asset) throw new Error(`There is no official Open Image Denoise build for ${process.platform} ${process.arch}.`);
+ const installDirectory = join(VENDOR_DIRECTORY, `oidn-${OIDN_VERSION}`);
+ if (existsSync(installDirectory)) return installDirectory;
+ const response = await fetch(`https://github.com/RenderKit/oidn/releases/download/v${OIDN_VERSION}/${asset.name}`);
+ if (!response.ok) throw new Error(`Downloading ${asset.name} failed with HTTP ${response.status}.`);
+ const archiveBytes = Buffer.from(await response.arrayBuffer());
+ const digest = createHash('sha256').update(archiveBytes).digest('hex');
+ if (digest !== asset.sha256) throw new Error(`${asset.name} has SHA-256 ${digest}, not the pinned ${asset.sha256}.`);
+ const staging = join(VENDOR_DIRECTORY, `staging-${process.pid}`);
+ await mkdir(staging, { recursive: true });
+ try {
+ const archivePath = join(staging, asset.name);
+ await writeFile(archivePath, archiveBytes);
+ extract(archivePath, staging);
+ const unpackedName = asset.name.replace(/\.(zip|tar\.gz)$/, '');
+ await rename(join(staging, unpackedName), installDirectory);
+ } finally {
+ await rm(staging, { recursive: true, force: true });
+ }
+ return installDirectory;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+ console.log(`Open Image Denoise ${OIDN_VERSION} is in ${await fetchOidn()}`);
+}
diff --git a/packages/denoise-oidn/index.mjs b/packages/denoise-oidn/index.mjs
new file mode 100644
index 00000000..7bc51136
--- /dev/null
+++ b/packages/denoise-oidn/index.mjs
@@ -0,0 +1,93 @@
+// Calls Intel Open Image Denoise (OIDN, Apache-2.0) through its official `oidnDenoise` command line tool, with
+// the colour, albedo and normal images the 67js path tracer already writes. The binary is not in this package:
+// `npm run fetch` (fetch-oidn.mjs) downloads the official release into ./vendor, and OIDN_DENOISE_PATH points
+// at another copy.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const EXECUTABLE_NAME = process.platform === 'win32' ? 'oidnDenoise.exe' : 'oidnDenoise';
+
+export const OIDN_VERSION = '2.5.1';
+
+/** The path of the `oidnDenoise` tool, or null when none is installed. */
+export function findOidnBinary() {
+ const configured = process.env.OIDN_DENOISE_PATH;
+ if (configured) return existsSync(configured) ? configured : null;
+ const vendored = join(PACKAGE_DIRECTORY, 'vendor', `oidn-${OIDN_VERSION}`, 'bin', EXECUTABLE_NAME);
+ return existsSync(vendored) ? vendored : null;
+}
+
+/** Writes three-channel float pixels as a little-endian PFM, which stores its rows bottom to top. */
+export function encodePfm(pixels, width, height) {
+ const header = Buffer.from(`PF\n${width} ${height}\n-1.0\n`, 'latin1');
+ const body = Buffer.alloc(width * height * 12);
+ const rowFloats = width * 3;
+ for (let row = 0; row < height; row++) {
+ const source = pixels.subarray((height - 1 - row) * rowFloats, (height - row) * rowFloats);
+ Buffer.from(source.buffer, source.byteOffset, source.byteLength).copy(body, row * rowFloats * 4);
+ }
+ return Buffer.concat([header, body]);
+}
+
+export function decodePfm(bytes, width, height) {
+ let cursor = 0;
+ const fields = [];
+ while (fields.length < 4) {
+ let end = cursor;
+ while (bytes[end] > 32) end++;
+ fields.push(bytes.toString('latin1', cursor, end));
+ cursor = end + 1;
+ }
+ if (fields[0] !== 'PF' || Number(fields[1]) !== width || Number(fields[2]) !== height || Number(fields[3]) >= 0) {
+ throw new Error('OIDN wrote a PFM that is not the expected little-endian colour image.');
+ }
+ const rowFloats = width * 3;
+ const pixels = new Float32Array(rowFloats * height);
+ for (let row = 0; row < height; row++) {
+ const start = bytes.byteOffset + cursor + row * rowFloats * 4;
+ const rowPixels = new Float32Array(bytes.buffer.slice(start, start + rowFloats * 4));
+ pixels.set(rowPixels, (height - 1 - row) * rowFloats);
+ }
+ return pixels;
+}
+
+function runTool(binary, toolArguments) {
+ return new Promise((resolve, reject) => {
+ const child = spawn(binary, toolArguments, { stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+ let errorText = '';
+ child.stderr.on('data', chunk => { errorText += chunk; });
+ child.on('error', reject);
+ child.on('close', code => (code === 0 ? resolve() : reject(new Error(`oidnDenoise exited with ${code}: ${errorText.trim().slice(0, 400)}`))));
+ });
+}
+
+/**
+ * Denoises one HDR image. `color`, `albedo` and `normal` are row-major Float32Arrays with three floats per pixel: the
+ * linear radiance, the first-hit albedo and the unit first-hit normal. Resolves with a new Float32Array of the same
+ * shape. `device` is "cpu" (the default: the result does not depend on a GPU, and the GPU stays free) or any name
+ * `oidnDenoise --device` takes. Rejects when the tool is missing, so a caller can fall back.
+ */
+export async function denoiseWithOidn({ width, height, color, albedo, normal, device = 'cpu', quality = 'high', threads = 0, cleanAux = false }) {
+ const binary = findOidnBinary();
+ if (!binary) throw new Error('The oidnDenoise tool is not installed: run `npm run fetch` in the denoise package, or set OIDN_DENOISE_PATH.');
+ const directory = await mkdtemp(join(tmpdir(), '67js-oidn-'));
+ try {
+ await Promise.all([
+ writeFile(join(directory, 'color.pfm'), encodePfm(color, width, height)),
+ writeFile(join(directory, 'albedo.pfm'), encodePfm(albedo, width, height)),
+ writeFile(join(directory, 'normal.pfm'), encodePfm(normal, width, height)),
+ ]);
+ await runTool(binary, [
+ '--device', device, '--quality', quality, '--hdr', join(directory, 'color.pfm'), '--alb', join(directory, 'albedo.pfm'),
+ '--nrm', join(directory, 'normal.pfm'), '--output', join(directory, 'out.pfm'), ...(cleanAux ? ['--clean_aux'] : []), ...(threads > 0 ? ['--threads', String(threads)] : []),
+ ]);
+ return decodePfm(await readFile(join(directory, 'out.pfm')), width, height);
+ } finally {
+ await rm(directory, { recursive: true, force: true });
+ }
+}
diff --git a/packages/denoise-oidn/package.json b/packages/denoise-oidn/package.json
new file mode 100644
index 00000000..82d7f9bf
--- /dev/null
+++ b/packages/denoise-oidn/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "@codepawlhq/67js-denoise-oidn",
+ "version": "0.1.0",
+ "description": "Optional native Intel Open Image Denoise for 67js path traced stills. Not part of the core archive.",
+ "type": "module",
+ "main": "./index.mjs",
+ "exports": {
+ ".": "./index.mjs",
+ "./fetch": "./fetch-oidn.mjs"
+ },
+ "files": [
+ "index.mjs",
+ "fetch-oidn.mjs",
+ "README.md"
+ ],
+ "scripts": {
+ "fetch": "node fetch-oidn.mjs"
+ },
+ "license": "MIT",
+ "engines": {
+ "node": ">=22"
+ }
+}
diff --git a/scripts/agent-path-trace-denoise.mjs b/scripts/agent-path-trace-denoise.mjs
new file mode 100644
index 00000000..93ff2cc0
--- /dev/null
+++ b/scripts/agent-path-trace-denoise.mjs
@@ -0,0 +1,49 @@
+// The optional native denoiser is its own npm package, so the server never carries it. The name sits in a variable so the
+// bundler leaves the import alone and it resolves from the user's node_modules when a job asks for it.
+const OIDN_PACKAGE = '@codepawlhq/67js-denoise-oidn';
+
+async function loadOidnPackage() {
+ try {
+ const denoiser = await import(OIDN_PACKAGE);
+ return denoiser.findOidnBinary() ? denoiser : null;
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * What a job's `settings.renderer.denoise` becomes. "oidn" needs the optional package and its binary; without them the
+ * wavelet filter runs instead and `note` says so, so the job result never claims a denoiser that did not run.
+ */
+export async function chooseDenoiser(requested) {
+ if (requested !== 'oidn') return { denoise: requested };
+ const denoiser = await loadOidnPackage();
+ if (denoiser) return { denoise: 'oidn', denoiser };
+ return { denoise: 'wavelet', note: `denoise "oidn" needs ${OIDN_PACKAGE} and its binary (npm run fetch in that package, or OIDN_DENOISE_PATH): the wavelet filter ran instead.` };
+}
+
+function floatsFromBase64(base64) {
+ const bytes = Buffer.from(base64, 'base64');
+ return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / 4);
+}
+
+/**
+ * Filters the features a page returned for denoise "oidn" and gives the result back to the page to draw. If the tool fails,
+ * the page filters the same pixels with the wavelet filter and the report says so. Returns the PNG as base64 and the report.
+ */
+export async function finishWithOidn({ traced, denoiser, drawLinear }) {
+ const { width, height } = traced.report;
+ const features = Object.fromEntries(['color', 'albedo', 'normal'].map(name => [name, floatsFromBase64(traced.features[name])]));
+ const started = performance.now();
+ let linear;
+ let failure;
+ try {
+ linear = await denoiser.denoiseWithOidn({ width, height, ...features });
+ } catch (error) {
+ failure = error.message;
+ }
+ const denoiseSeconds = (performance.now() - started) / 1000;
+ const drawn = await drawLinear({ width, height, ...(linear ? { linear: Buffer.from(linear.buffer, linear.byteOffset, linear.byteLength).toString('base64') } : {}) });
+ const report = { ...traced.report, denoised: true, denoiser: linear ? 'oidn' : 'wavelet', denoiseSeconds, ...(linear ? { oidnVersion: denoiser.OIDN_VERSION } : { denoiserNote: `OIDN failed (${failure}): the wavelet filter ran instead.` }) };
+ return { data: drawn.data, report };
+}
diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.js
index eb985371..9006d5ad 100644
--- a/scripts/agent-preview-browser.js
+++ b/scripts/agent-preview-browser.js
@@ -411,6 +411,17 @@ function bytesToBase64(bytes) {
return btoa(binary);
}
+// The feature images of the last denoise "oidn" trace, kept until finishPathTrace draws it.
+let tracedFeatures;
+
+function encodeTracedPng(rgba, width, height) {
+ const canvas = document.createElement('canvas');
+ canvas.width = width;
+ canvas.height = height;
+ canvas.getContext('2d').putImageData(new ImageData(rgba, width, height), 0, 0);
+ return canvas.toDataURL('image/png').split(',')[1];
+}
+
// The review grid outlives the private scenes drawn into it, because each branch in a review is its own scene.
let reviewGrid;
@@ -591,11 +602,34 @@ window.__agentPreview = {
environment: { ...environment, map: agentEnvironmentMap(environment) },
camera: record.scene.camera,
}, options);
- const traced = document.createElement('canvas');
- traced.width = result.width;
- traced.height = result.height;
- traced.getContext('2d').putImageData(new ImageData(result.rgba, result.width, result.height), 0, 0);
- return { data: traced.toDataURL('image/png').split(',')[1], report: result.report };
+ // An external denoiser (denoise "oidn") works on the traced features outside the page; finishPathTrace then draws its result.
+ if (result.report.denoiser === 'oidn') {
+ tracedFeatures = result.features;
+ const features = {};
+ for (const name of ['color', 'albedo', 'normal']) {
+ const values = result.features[name];
+ features[name] = bytesToBase64(new Uint8Array(values.buffer, values.byteOffset, values.byteLength));
+ }
+ return { features, report: result.report };
+ }
+ return { data: encodeTracedPng(result.rgba, result.width, result.height), report: result.report };
+ },
+ // The PNG of linear pixels (three floats each, base64) that a denoiser outside the page returned, or of the wavelet
+ // filter over the kept features when none came back.
+ async finishPathTrace({ width, height, linear }) {
+ const { toneMapToRgba8 } = await import('../src/path-tracer.js');
+ let pixels;
+ if (linear) {
+ const binary = atob(linear);
+ const bytes = new Uint8Array(binary.length);
+ for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+ pixels = new Float32Array(bytes.buffer);
+ } else {
+ const { denoiseRadiance } = await import('../src/path-tracer-denoise.js');
+ pixels = denoiseRadiance({ width, height, ...tracedFeatures });
+ }
+ tracedFeatures = undefined;
+ return { data: encodeTracedPng(toneMapToRgba8(pixels, width, height), width, height) };
},
create(input) {
if (active) throw new Error('Dispose the current scene before creating another.');
diff --git a/scripts/agent-render-jobs.mjs b/scripts/agent-render-jobs.mjs
index 4bf6b85e..42e963f4 100644
--- a/scripts/agent-render-jobs.mjs
+++ b/scripts/agent-render-jobs.mjs
@@ -4,7 +4,7 @@ import { isAbsolute, join, resolve } from 'node:path';
import { RENDER_PASS_NAMES, VIDEO_ENCODERS, AUDIO_FILE_PATTERN, MAXIMUM_VIDEO_SECONDS, MAXIMUM_JOB_SIDE, MAXIMUM_JOB_PIXELS } from '../src/agent-scene-capabilities.js';
import { normalizeFilmTimeline, filmTimelineDuration } from '../src/film-timeline.js';
-import { PATH_TRACER_JOB_LIMITS } from '../src/path-tracer-capabilities.js';
+import { OIDN_DEFAULT_SAMPLES, PATH_TRACER_DENOISERS, PATH_TRACER_JOB_LIMITS } from '../src/path-tracer-capabilities.js';
const UUID =/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
const STATES = ['queued', 'running', 'finalizing', 'completed', 'cancelling', 'cancelled', 'failed', 'interrupted'];
@@ -146,11 +146,13 @@ function rendererFrom(renderer, kind, passes) {
if (renderer.type !== 'pathTracer') throw new TypeError('renderer.type must be pathTracer.');
if (kind !== 'image') throw new RangeError('The path tracer renders one image: use kind image.');
if (passes !== undefined) throw new RangeError('The path tracer writes the lit image only: leave passes out.');
- if (renderer.denoise !== undefined && typeof renderer.denoise !== 'boolean') throw new TypeError('renderer.denoise must be a boolean.');
- const result = { type: 'pathTracer', denoise: renderer.denoise ?? true };
+ const denoise = renderer.denoise ?? true;
+ if (typeof denoise !== 'boolean' && !PATH_TRACER_DENOISERS.includes(denoise)) throw new TypeError(`renderer.denoise must be a boolean or one of ${PATH_TRACER_DENOISERS.join(', ')}.`);
+ const result = { type: 'pathTracer', denoise };
for (const name of Object.keys(PATH_TRACER_JOB_LIMITS)) {
const { minimum, maximum, default: fallback } = PATH_TRACER_JOB_LIMITS[name];
- result[name] = boundedNumber(renderer[name] ?? fallback, minimum, maximum, `renderer ${name}`, !FRACTIONAL_RENDERER_FIELDS.has(name));
+ const defaultValue = name === 'samples' && denoise === 'oidn' ? OIDN_DEFAULT_SAMPLES : fallback;
+ result[name] = boundedNumber(renderer[name] ?? defaultValue, minimum, maximum, `renderer ${name}`, !FRACTIONAL_RENDERER_FIELDS.has(name));
}
return result;
}
diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjs
index 0701dbba..c057a035 100644
--- a/scripts/agent-runtime.mjs
+++ b/scripts/agent-runtime.mjs
@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
import packageMetadata from '../package.json' with { type: 'json' };
import { AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, RENDER_PASS_NAMES, RENDER_PASS_DEPTH_RANGE, VIDEO_ENCODERS, MAXIMUM_VIDEO_SECONDS, MAXIMUM_JOB_SIDE, MAXIMUM_JOB_PIXELS, MAXIMUM_MEMORY_MIB, BAKE_WORKER_MAXIMUM_SECONDS } from '../src/agent-scene-capabilities.js';
import { PATH_TRACER_CAPABILITIES } from '../src/path-tracer-capabilities.js';
+import { chooseDenoiser, finishWithOidn } from './agent-path-trace-denoise.mjs';
import { createAgentAssetCatalog } from './agent-asset-catalog.mjs';
import { createAgentRenderJobs, EXPORT_DIRECTORY_NAME } from './agent-render-jobs.mjs';
import { createFrameEncoder } from './frame-encoder.mjs';
@@ -370,7 +371,12 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', brow
...(settings.animation ? { animation: { clip: settings.animation.clip, time: settings.animation.start + elapsed } } : {}) };
const renderStarted = performance.now();
if (settings.renderer) {
- const traced = await jobPage.evaluate(input => window.__agentPreview.pathTrace(input), { ...frameInput, options: { width, height, ...settings.renderer, threads: PATH_TRACER_THREADS } });
+ const choice = await chooseDenoiser(settings.renderer.denoise);
+ let traced = await jobPage.evaluate(input => window.__agentPreview.pathTrace(input), { ...frameInput, options: { width, height, ...settings.renderer, denoise: choice.denoise, threads: PATH_TRACER_THREADS } });
+ if (traced.features) {
+ traced = await finishWithOidn({ traced, denoiser: choice.denoiser, drawLinear: input => jobPage.evaluate(drawInput => window.__agentPreview.finishPathTrace(drawInput), input) });
+ }
+ if (choice.note) traced.report.denoiserNote = choice.note;
metrics.renderSeconds += (performance.now() - renderStarted) / 1000;
metrics.width = width;
metrics.height = height;
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index 6547b0ec..71659f8d 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -620,7 +620,7 @@ const renderSettings = z.strictObject({
animation: z.strictObject({ clip: z.number().int().min(0), start: z.number().min(0).max(3600).optional() }).optional(),
motion: z.strictObject({ start: z.number().min(0).max(3600).optional() }).optional(),
rendererTime: z.strictObject({ start: z.number().min(0).max(3600).optional(), rate: z.number().min(-16).max(16).optional() }).optional(),
- renderer: z.strictObject({ type: z.literal('pathTracer'), samples: z.number().optional(), bounces: z.number().optional(), denoise: z.boolean().optional(), seed: z.number().optional(), maxSeconds: z.number().optional(), noiseThreshold: z.number().optional() }).optional().describe('image only: offline path tracer; limits and skips in scene_capabilities pathTracer.'),
+ renderer: z.strictObject({ type: z.literal('pathTracer'), samples: z.number().optional(), bounces: z.number().optional(), denoise: z.union([z.boolean(), z.enum(['wavelet', 'oidn', 'none'])]).optional(), seed: z.number().optional(), maxSeconds: z.number().optional(), noiseThreshold: z.number().optional() }).optional().describe('image only: path tracer; see scene_capabilities pathTracer.'),
timeline: z.strictObject({ start: z.number().min(0).max(60).optional() }).optional().describe('Play the recipe timeline from start (default 0); duration defaults to the rest of it. It owns the motion clock, so leave motion and animation out.'),
audio: z.strictObject({ file: z.string().max(68), offset: z.number().min(0).max(3600).optional() }).optional().describe('Video only: a file name in the --audio folder (.wav, .mp3, .ogg, .flac) mixed in from offset seconds.'),
encoder: z.enum(VIDEO_ENCODERS).optional().describe('Video only: cpu (default) or nvenc.'),
diff --git a/scripts/smoke-path-tracer.mjs b/scripts/smoke-path-tracer.mjs
index 2c2beb85..b5325a2d 100644
--- a/scripts/smoke-path-tracer.mjs
+++ b/scripts/smoke-path-tracer.mjs
@@ -82,6 +82,18 @@ try {
const rasterized = await renderedBytes(sessionId, base);
assert.notDeepEqual(rasterized.bytes, first.bytes, 'The path tracer must not return the rasterizer image.');
+ // denoise "oidn" runs the native tool of the optional package when it is installed; without it the job says it used the wavelet filter.
+ const { findOidnBinary } = await import('@codepawlhq/67js-denoise-oidn').catch(() => ({ findOidnBinary: () => null }));
+ const external = await renderedBytes(sessionId, { ...base, renderer: { ...tracer, denoise: 'oidn' } });
+ if (findOidnBinary()) {
+ assert.equal(external.metrics.pathTracer.denoiser, 'oidn');
+ assert.ok(external.metrics.pathTracer.denoiseSeconds > 0);
+ const again = await renderedBytes(sessionId, { ...base, renderer: { ...tracer, denoise: 'oidn' } });
+ assert.deepEqual(again.bytes, external.bytes, 'The same recipe, seed and OIDN must give the same PNG on one machine.');
+ } else {
+ assert.equal(external.metrics.pathTracer.denoiser, 'wavelet');
+ assert.match(external.metrics.pathTracer.denoiserNote, /wavelet filter ran instead/);
+ }
for (const [settings, message] of [
[{ ...base, renderer: { ...tracer, samples: 99999 } }, /samples/],
[{ ...base, renderer: { ...tracer, extra: 1 } }, /extra|Unrecognized|Unknown/],
diff --git a/src/path-tracer-capabilities.js b/src/path-tracer-capabilities.js
index 183a9d68..d41ca2d2 100644
--- a/src/path-tracer-capabilities.js
+++ b/src/path-tracer-capabilities.js
@@ -10,8 +10,13 @@ export const PATH_TRACER_JOB_LIMITS = Object.freeze({
noiseThreshold: Object.freeze({ minimum: 0, maximum: 0.1, default: 0 }),
});
+// "wavelet" is the built-in filter (true), "none" is no filter (false), and "oidn" is Intel Open Image Denoise from the optional
+// package @codepawlhq/67js-denoise-oidn. A job that asks for "oidn" and leaves samples out gets OIDN_DEFAULT_SAMPLES.
+export const PATH_TRACER_DENOISERS = Object.freeze(['wavelet', 'oidn', 'none']);
+export const OIDN_DEFAULT_SAMPLES = 16;
+
export const PATH_TRACER_CAPABILITIES = Object.freeze({
- setting: 'settings.renderer { type: "pathTracer", samples, bounces, denoise, seed, maxSeconds, noiseThreshold }; image jobs only, no passes. Past maxSeconds the job fails.',
+ setting: 'settings.renderer { type: "pathTracer", samples, bounces, denoise (true | false | "wavelet" | "oidn" | "none"), seed, maxSeconds, noiseThreshold }; image jobs only, no passes. Past maxSeconds the job fails.',
noiseThreshold: 'Default 0 draws every sample. Above 0 a pixel stops once its standard error relative to its mean is under the value, checked from 16 samples on: faster and noisier, and it cost quality on spot-area (score 0.0658 at 0, 0.0900 at 0.03). docs/path-tracer.md has the table.',
traces: 'emissive maps and strength; volume fog as a uniform medium (density, colour, anisotropy, box; noise, drift and ambient are not used).',
skips: 'occlusion maps, translucent leaves, liquids, anisotropy, iridescence, sheen, caustics, depth of field, bloom; metrics.pathTracer.ignored in the job result lists what the scene asked for.',
diff --git a/src/path-tracer.js b/src/path-tracer.js
index 34d00358..968ca817 100644
--- a/src/path-tracer.js
+++ b/src/path-tracer.js
@@ -64,6 +64,22 @@ function boundedNumber(options, name) {
return value;
}
+// Kept equal to PATH_TRACER_DENOISERS in path-tracer-capabilities.js by tests/path-tracer-denoise-oidn.test.js; the
+// capabilities file stays out of this bundle.
+export const PATH_TRACER_DENOISERS = Object.freeze(['wavelet', 'oidn', 'none']);
+
+/**
+ * `denoise` is true (the wavelet filter) or false (none), or a name: "wavelet", "oidn" or "none". "oidn" is the optional
+ * native Open Image Denoise (packages/denoise-oidn): the tracer then leaves the colour as traced and returns the feature
+ * images, and the caller that has the package filters them.
+ */
+function denoiserNamed(value) {
+ if (value === true) return 'wavelet';
+ if (value === false) return 'none';
+ if (PATH_TRACER_DENOISERS.includes(value)) return value;
+ throw new TypeError(`Path tracer denoise must be a boolean or one of ${PATH_TRACER_DENOISERS.join(', ')}.`);
+}
+
export function normalizePathTracerOptions(options = {}) {
if (options === null || typeof options !== 'object') throw new TypeError('Path tracer options must be an object.');
const result = {
@@ -76,9 +92,9 @@ export function normalizePathTracerOptions(options = {}) {
maxSeconds: boundedNumber(options, 'maxSeconds'),
fireflyClamp: boundedNumber(options, 'fireflyClamp'),
noiseThreshold: boundedNumber(options, 'noiseThreshold'),
- denoise: options.denoise ?? true,
+ denoiser: denoiserNamed(options.denoise ?? true),
};
- if (typeof result.denoise !== 'boolean') throw new TypeError('Path tracer denoise must be a boolean.');
+ result.denoise = result.denoiser !== 'none';
if (result.width * result.height > MAX_TRACE_PIXELS) throw new RangeError(`A path trace takes at most ${MAX_TRACE_PIXELS} pixels.`);
if (result.width * result.height * result.samples * (result.bounces + 1) > MAX_TRACE_RAY_WORK) throw new RangeError('This path trace would need too much ray work: lower the size, samples or bounces.');
return result;
@@ -984,11 +1000,12 @@ export async function renderPathTracedImage({ parts, environment = {}, camera },
const tracedSeconds = (performance.now() - started) / 1000;
normalizeNormals(buffers.normal, pixelCount);
const { samplesTaken, ...denoiseInputs } = buffers;
- const linear = options.denoise ? denoiseRadiance({ width, height, ...denoiseInputs }) : buffers.color;
+ const linear = options.denoiser === 'wavelet' ? denoiseRadiance({ width, height, ...denoiseInputs }) : buffers.color;
return {
- width, height, linear, rgba: toneMapToRgba8(linear, width, height),
+ width, height, linear, rgba: toneMapToRgba8(linear, width, height), features: denoiseInputs,
report: {
- width, height, samples: options.samples, bounces: options.bounces, seed: options.seed, denoised: options.denoise, threads,
+ width, height, samples: options.samples, bounces: options.bounces, seed: options.seed, denoised: options.denoiser === 'wavelet',
+ denoiser: options.denoiser, threads,
averageSamples: totalSamples(samplesTaken) / pixelCount, noiseThreshold: options.noiseThreshold,
triangles: scene.indices.length / 3, tracedSeconds, seconds: (performance.now() - started) / 1000,
ignored: describeIgnoredFeatures(parts, environment),
diff --git a/tests/agent-render-jobs.test.js b/tests/agent-render-jobs.test.js
index 48f9beef..d55e05d1 100644
--- a/tests/agent-render-jobs.test.js
+++ b/tests/agent-render-jobs.test.js
@@ -361,6 +361,28 @@ test('asset digests bind immutable bytes and still/video settings produce only t
await controller.close();
});
+test('a path tracer job names its denoiser, and oidn defaults to 16 samples instead of 64', async context => {
+ const root = await temporary(context);
+ const assetBytes = Buffer.from('bounded embedded GLB fixture');
+ const assetId = createHash('sha256').update(assetBytes).digest('hex');
+ const snapshot = { recipe: { format: '67js.asset', assetId }, assetBytes, clips: [{ duration: 5 }] };
+ const controller = await createAgentRenderJobs({ root, limits, async run({ directory }) {
+ await writeFile(join(directory, 'render.png.partial'), Buffer.alloc(32, 1));
+ return { artifacts: [{ temporary: 'render.png.partial', filename: 'render.png', mimeType: 'image/png' }], metrics: {} };
+ } });
+ const submitWith = renderer => controller.submit({ sourceRevision: 1, snapshot, settings: { kind: 'image', width: 64, height: 64, renderer: { type: 'pathTracer', ...renderer } } });
+ const expectations = [[{}, true, 64], [{ denoise: 'oidn' }, 'oidn', 16], [{ denoise: 'oidn', samples: 8 }, 'oidn', 8], [{ denoise: 'wavelet' }, 'wavelet', 64], [{ denoise: false }, false, 64]];
+ for (const [renderer, denoise, samples] of expectations) {
+ const job = await submitWith(renderer);
+ await terminal(controller, job.jobId);
+ const settings = controller.status(job.jobId).settings.renderer;
+ assert.equal(settings.denoise, denoise);
+ assert.equal(settings.samples, samples);
+ }
+ await assert.rejects(submitWith({ denoise: 'bm3d' }), /denoise must be/);
+ await controller.close();
+});
+
test('a path tracer job draws every sample unless it passes a noise threshold, which stays within 0 to 0.1', async context => {
const root = await temporary(context);
const assetBytes = Buffer.from('bounded embedded GLB fixture');
diff --git a/tests/path-tracer-denoise-oidn.test.js b/tests/path-tracer-denoise-oidn.test.js
new file mode 100644
index 00000000..3e18570a
--- /dev/null
+++ b/tests/path-tracer-denoise-oidn.test.js
@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import test from 'node:test';
+
+import { decodePfm, denoiseWithOidn, encodePfm, findOidnBinary } from '../packages/denoise-oidn/index.mjs';
+import { PATH_TRACER_DENOISERS as JOB_DENOISERS } from '../src/path-tracer-capabilities.js';
+import { normalizePathTracerOptions, PATH_TRACER_DENOISERS, renderPathTracedImage } from '../src/path-tracer.js';
+import { chooseDenoiser } from '../scripts/agent-path-trace-denoise.mjs';
+
+test('denoise takes a boolean or a name and keeps the boolean the tracer reports', () => {
+ assert.equal(normalizePathTracerOptions({}).denoiser, 'wavelet');
+ assert.equal(normalizePathTracerOptions({ denoise: false }).denoiser, 'none');
+ for (const name of PATH_TRACER_DENOISERS) {
+ const options = normalizePathTracerOptions({ denoise: name });
+ assert.equal(options.denoiser, name);
+ assert.equal(options.denoise, name !== 'none');
+ }
+ assert.deepEqual([...JOB_DENOISERS], [...PATH_TRACER_DENOISERS]);
+ assert.throws(() => normalizePathTracerOptions({ denoise: 'bm3d' }), /denoise must be/);
+ assert.throws(() => normalizePathTracerOptions({ denoise: 1 }), /denoise must be/);
+});
+
+test('denoise "oidn" leaves the colour as traced and returns the feature images for the caller', async () => {
+ const quad = { name: 'floor', geometry: { positions: new Float32Array([-4, 0, -4, 4, 0, -4, 4, 0, 4, -4, 0, 4]), normals: new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]), indices: new Uint32Array([0, 2, 1, 0, 3, 2]) },
+ matrix: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]), material: { tag: 'surface', color: [0.8, 0.8, 0.8], metallic: 0, roughness: 0.5 } };
+ const scene = { parts: [quad], environment: { skyColor: [0.5, 0.6, 0.8] }, camera: { eye: [0, 3, 0], target: [0, 0, 0], up: [0, 0, -1], fov: 40 } };
+ const options = { width: 16, height: 16, samples: 4, bounces: 1, threads: 1 };
+ const external = await renderPathTracedImage(scene, { ...options, denoise: 'oidn' });
+ const none = await renderPathTracedImage(scene, { ...options, denoise: false });
+ assert.deepEqual(external.linear, none.linear);
+ assert.equal(external.report.denoiser, 'oidn');
+ assert.equal(external.report.denoised, false);
+ assert.equal(external.features.albedo.length, 16 * 16 * 3);
+ assert.equal(external.features.normal.length, 16 * 16 * 3);
+});
+
+test('a job that asks for oidn without the binary runs the wavelet filter and says why', async context => {
+ const saved = process.env.OIDN_DENOISE_PATH;
+ process.env.OIDN_DENOISE_PATH = 'does-not-exist/oidnDenoise';
+ context.after(() => {
+ if (saved === undefined) delete process.env.OIDN_DENOISE_PATH;
+ else process.env.OIDN_DENOISE_PATH = saved;
+ });
+ const choice = await chooseDenoiser('oidn');
+ assert.equal(choice.denoise, 'wavelet');
+ assert.match(choice.note, /oidn.*wavelet filter ran instead/s);
+ assert.deepEqual(await chooseDenoiser(true), { denoise: true });
+ await assert.rejects(denoiseWithOidn({ width: 1, height: 1, color: new Float32Array(3), albedo: new Float32Array(3), normal: new Float32Array(3) }), /not installed/);
+});
+
+test('PFM files keep the pixels and store rows bottom to top', () => {
+ const pixels = Float32Array.from({ length: 4 * 3 * 3 }, (_, index) => index / 7);
+ const bytes = encodePfm(pixels, 4, 3);
+ assert.equal(bytes.toString('latin1', 0, 12), 'PF\n4 3\n-1.0\n');
+ const firstStoredRow = new Float32Array(bytes.buffer.slice(bytes.byteOffset + 12, bytes.byteOffset + 12 + 48));
+ assert.deepEqual(firstStoredRow, pixels.subarray(24, 36));
+ assert.deepEqual(decodePfm(bytes, 4, 3), pixels);
+ assert.throws(() => decodePfm(bytes, 5, 3), /not the expected/);
+});
+
+test('the installed OIDN removes noise from a flat image and gives the same bytes twice', { skip: findOidnBinary() ? false : 'the oidnDenoise binary is not fetched' }, async () => {
+ assert.ok(existsSync(findOidnBinary()));
+ const width = 64;
+ const height = 64;
+ let state = 12345;
+ const random = () => {
+ state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+ return state / 2 ** 32;
+ };
+ const color = Float32Array.from({ length: width * height * 3 }, () => 0.5 + (random() - 0.5) * 0.4);
+ const albedo = new Float32Array(width * height * 3).fill(0.8);
+ const normal = Float32Array.from({ length: width * height * 3 }, (_, index) => (index % 3 === 1 ? 1 : 0));
+ const spread = values => Math.max(...values) - Math.min(...values);
+ const first = await denoiseWithOidn({ width, height, color, albedo, normal });
+ const second = await denoiseWithOidn({ width, height, color, albedo, normal });
+ assert.ok(spread(first) < spread(color), `spread ${spread(first)} against ${spread(color)}`);
+ assert.deepEqual(first, second);
+});