3D engine that AI agents drive
Trace native render jobs with the cycles kernel and denoise with OIDN by default (#970)
Nguyen Xuan An58572a072de3
diff --git a/bench/native-tracer/metal-job.mjs b/bench/native-tracer/metal-job.mjsnew file mode 100644index 00000000..45c64c9d--- /dev/null+++ b/bench/native-tracer/metal-job.mjs@@ -0,0 +1,66 @@+// The frame step of a native render job on the `metal` reference scene: the same chooseDenoiser and traceFrameNative calls the+// job runner makes, fed with the tables the job page would export, so the kernel, noiseThreshold and denoiser defaults can be+// measured without a browser. Writes a PNG and a linear .npy per run for bench/cycles-parity score scripts.+// node bench/native-tracer/metal-job.mjs <output directory> [--samples 256] [--noise-threshold 0] [--kernel cycles|legacy] [--denoise true|false|oidn|wavelet|none]+import { mkdir, writeFile } from 'node:fs/promises';+import { resolve } from 'node:path';+import { createCamera } from '../../src/path-tracer.js';+import * as packModule from '../../src/path-tracer-gpu-pack.js';+import { buildTraceScene } from '../../src/path-tracer-scene.js';+import { buildNativeInput } from '../../packages/render-native/pack-input.mjs';+import * as renderNative from '../../packages/render-native/index.mjs';+import { encodeNativeTables } from '../../scripts/native-bake-page.js';+import { chooseDenoiser } from '../../scripts/agent-path-trace-denoise.mjs';+import { traceFrameNative } from '../../scripts/agent-native-trace.mjs';+import { loadReferenceScene } from '../cycles-parity/scene-bridge.mjs';+import { writeFloat32Npy } from '../cycles-parity/npy.mjs';++const WIDTH = 960;+const HEIGHT = 540;+const argumentsGiven = process.argv.slice(2);++function valueAfter(flag, fallback) {+ const index = argumentsGiven.indexOf(flag);+ return index >= 0 ? argumentsGiven[index + 1] : fallback;+}++const outputDirectory = resolve(argumentsGiven[0]);+const samples = Number(valueAfter('--samples', 256));+const noiseThreshold = Number(valueAfter('--noise-threshold', 0));+const kernel = valueAfter('--kernel', 'cycles');+const denoiseArgument = valueAfter('--denoise', 'true');+const requested = denoiseArgument === 'true' ? true : denoiseArgument === 'false' ? false : denoiseArgument;+const label = valueAfter('--label', `${kernel}-${samples}-${String(requested)}`);++const loaded = await loadReferenceScene('metal');+const source = loaded.traceSource;+const options = { width: WIDTH, height: HEIGHT, bounces: 8, seed: 1, fireflyClamp: 20, noiseThreshold };+const input = buildNativeInput(buildTraceScene(source.parts, source.environment), createCamera(source.camera, WIDTH, HEIGHT), options, packModule);+const exported = { tables: encodeNativeTables(input), triangleCount: input.triangleCount, triangles: input.triangleCount, ignored: [] };++let captured;+const tracer = { traceNative(tables, traceOptions) {+ captured = renderNative.traceNative(tables, traceOptions);+ return captured;+} };+const choice = await chooseDenoiser(requested, { preferOidn: true });+const denoise = choice.denoise === true ? 'wavelet' : choice.denoise === false ? 'none' : choice.denoise;+await traceFrameNative({ tracer, exported, width: WIDTH, height: HEIGHT, samples, bounces: 8, seed: 1, denoise, denoiser: choice.denoiser, maxSeconds: 600, noiseThreshold, kernel });+// Warm run above compiles the kernel; the measured run below is the one the report describes.+const measured = await traceFrameNative({ tracer, exported, width: WIDTH, height: HEIGHT, samples, bounces: 8, seed: 1, denoise, denoiser: choice.denoiser, maxSeconds: 600, noiseThreshold, kernel });+const features = { width: WIDTH, height: HEIGHT, color: new Float32Array(WIDTH * HEIGHT * 3), albedo: captured.albedo, normal: new Float32Array(captured.normal), depth: captured.depth, variance: captured.variance };+for (let pixel = 0; pixel < WIDTH * HEIGHT; pixel++) features.color.set(captured.rgba.subarray(pixel * 4, pixel * 4 + 3), pixel * 3);+for (let offset = 0; offset < features.normal.length; offset += 3) {+ const length = Math.hypot(features.normal[offset], features.normal[offset + 1], features.normal[offset + 2]);+ if (length > 1e-6) for (let axis = 0; axis < 3; axis++) features.normal[offset + axis] /= length;+}+let linear = features.color;+if (measured.report.denoiser === 'oidn') linear = await choice.denoiser.denoiseWithOidn(features);+else if (measured.report.denoiser === 'wavelet') linear = (await import('../../src/path-tracer-denoise.js')).denoiseRadiance(features);+await mkdir(outputDirectory, { recursive: true });+await writeFile(`${outputDirectory}/job-${label}.png`, Buffer.from(measured.data, 'base64'));+await writeFloat32Npy(`${outputDirectory}/job-${label}.npy`, linear, [HEIGHT, WIDTH, 3]);+const { gpu, nativeBackend, kernel: ranKernel, averageSamples, noiseThreshold: threshold, denoiser, denoised, tracedSeconds, denoiseSeconds, seconds } = measured.report;+const summary = { label, gpu, nativeBackend, kernel: ranKernel, samples, noiseThreshold: threshold, averageSamples, denoiser, denoised, denoiserNote: choice.note, tracedSeconds, denoiseSeconds, seconds };+await writeFile(`${outputDirectory}/job-${label}.json`, JSON.stringify(summary, null, 1));+console.log(JSON.stringify(summary));diff --git a/changes/970-native-oidn-default.md b/changes/970-native-oidn-default.mdnew file mode 100644index 00000000..c708326c--- /dev/null+++ b/changes/970-native-oidn-default.md@@ -0,0 +1 @@+- Render jobs with `backend: "native"` trace with the Cycles-matching kernel, pass `noiseThreshold` to it and denoise with OIDN and the albedo and normal guides by default (the wavelet filter with a note when OIDN is missing); `JS67_NATIVE_KERNEL=legacy` keeps the old kernel (#970)diff --git a/scripts/agent-native-trace.mjs b/scripts/agent-native-trace.mjsindex ff1f39a1..08434461 100644--- a/scripts/agent-native-trace.mjs+++ b/scripts/agent-native-trace.mjs@@ -98,13 +98,22 @@ function withoutAlpha(rgba, pixelCount) {return color;}+/**+ * The native kernel a job traces with: "cycles" (the Cycles-matching kernel) unless JS67_NATIVE_KERNEL=legacy asks for the+ * older one. Any other value is passed on so `traceNative` rejects it with its own message.+ */+export function chooseNativeKernel(environment = process.env) {+ const requested = environment.JS67_NATIVE_KERNEL;+ return requested === undefined || requested === '' ? 'cycles' : requested;+}+/*** Traces one frame the page exported and returns the PNG (base64) with the job report. `denoise` is "none", "wavelet" or* "oidn"; `denoiser` is the loaded OIDN package for "oidn". Throws when the tracer cannot run, so the caller can fall back.*/-export async function traceFrameNative({ tracer, exported, width, height, samples, bounces, seed, denoise, denoiser, maxSeconds, noiseThreshold = 0 }) {+export async function traceFrameNative({ tracer, exported, width, height, samples, bounces, seed, denoise, denoiser, maxSeconds, noiseThreshold = 0, kernel = chooseNativeKernel() }) {const started = performance.now();- const traced = tracer.traceNative(decodeTables(exported), { width, height, samples, maxSeconds });+ const traced = tracer.traceNative(decodeTables(exported), { width, height, samples, maxSeconds, kernel, noiseThreshold });const tracedSeconds = (performance.now() - started) / 1000;const pixelCount = width * height;const features = { color: withoutAlpha(traced.rgba, pixelCount), albedo: traced.albedo, normal: traced.normal,@@ -113,7 +122,7 @@ export async function traceFrameNative({ tracer, exported, width, height, sampleconst report = { width, height, samples, bounces, seed, denoised: false, denoiser: 'none', threads: 1, backend: 'native',gpu: traced.adapter, nativeBackend: traced.backend, nativeFeatures: traced.features, setupSeconds: traced.setupSeconds, compileSeconds: traced.compileSeconds,uploadSeconds: traced.uploadSeconds, accelerationBuildSeconds: traced.accelerationBuildSeconds,- averageSamples: traced.averageSamples ?? samples, noiseThreshold, triangles: exported.triangles, tracedSeconds, ignored: exported.ignored };+ kernel, averageSamples: traced.averageSamples ?? samples, noiseThreshold, triangles: exported.triangles, tracedSeconds, ignored: exported.ignored };let linear = features.color;const denoiseStarted = performance.now();if (denoise === 'oidn') {diff --git a/scripts/agent-path-trace-denoise.mjs b/scripts/agent-path-trace-denoise.mjsindex 93ff2cc0..adc5e642 100644--- a/scripts/agent-path-trace-denoise.mjs+++ b/scripts/agent-path-trace-denoise.mjs@@ -14,12 +14,22 @@ async function loadOidnPackage() {/*** 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.+ * `preferOidn` is set for the native backend: there the default (`true`) means OIDN with the albedo and normal guides when+ * it is installed, else the wavelet filter with the same guides, and the note says why. Explicit values keep their meaning.*/-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.` };+export async function chooseDenoiser(requested, { preferOidn = false, loadOidn = loadOidnPackage } = {}) {+ const defaultsToOidn = preferOidn && requested === true;+ if (requested !== 'oidn' && !defaultsToOidn) return { denoise: requested };+ const denoiser = await loadOidn();+ if (denoiser) {+ return defaultsToOidn+ ? { denoise: 'oidn', denoiser, note: 'The native backend denoises with OIDN and the albedo and normal guides by default.' }+ : { denoise: 'oidn', denoiser };+ }+ const reason = `needs ${OIDN_PACKAGE} and its binary (npm run fetch in that package, or OIDN_DENOISE_PATH)`;+ return { denoise: 'wavelet', note: defaultsToOidn+ ? `The native backend denoises with OIDN, which ${reason}: the wavelet filter ran instead.`+ : `denoise "oidn" ${reason}: the wavelet filter ran instead.` };}function floatsFromBase64(base64) {diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjsindex 01e7736b..c9977f0b 100644--- a/scripts/agent-runtime.mjs+++ b/scripts/agent-runtime.mjs@@ -556,9 +556,10 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', browif (settings.renderer) {const { type, ...tracerOptions } = settings.renderer;if (settings.renderer.backend === 'gpu' && backend === 'cpu') throw new Error('renderer.backend "gpu" needs a runtime on the GPU backend, and this one runs on SwiftShader.');- const choice = await chooseDenoiser(settings.renderer.denoise);nativeTracerLocator ??= createNativeTracerLocator();const trace = await chooseTraceBackend({ requested: settings.renderer.backend, runtimeBackend: backend, locator: nativeTracerLocator });+ // Only a job that really traces on native defaults to OIDN; the cpu, gpu and webgpu defaults do not change.+ let choice = await chooseDenoiser(settings.renderer.denoise, { preferOidn: trace.backend === 'native' });const traceOptions = { width, height, ...tracerOptions, backend: trace.backend === 'native' ? 'gpu' : trace.backend, denoise: choice.denoise, threads: PATH_TRACER_THREADS };let traced;let backendNote = trace.note;@@ -574,6 +575,8 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', brownativeTracerLocator.markUnusable(error.message);backendNote = (await nativeTracerLocator.find()).reason;traceOptions.backend = backend === 'cpu' ? 'cpu' : 'gpu';+ choice = await chooseDenoiser(settings.renderer.denoise);+ traceOptions.denoise = choice.denoise;backendNote += ' The ' + traceOptions.backend + ' backend ran instead.';}}diff --git a/tests/agent-native-trace.test.js b/tests/agent-native-trace.test.jsindex 3f25634d..0d863dc2 100644--- a/tests/agent-native-trace.test.js+++ b/tests/agent-native-trace.test.js@@ -1,6 +1,6 @@import assert from 'node:assert/strict';import test from 'node:test';-import { chooseTraceBackend, createNativeTracerLocator } from '../scripts/agent-native-trace.mjs';+import { chooseNativeKernel, chooseTraceBackend, createNativeTracerLocator, traceFrameNative } from '../scripts/agent-native-trace.mjs';const builtTracer = { findNativeAddon: () => '/build/render-native.node' };@@ -50,3 +50,57 @@ test('cpu and gpu requests never touch the native package', async () => {assert.deepEqual(await chooseTraceBackend({ requested: 'gpu', runtimeBackend: 'gpu', locator }), { backend: 'gpu' });assert.deepEqual(await chooseTraceBackend({ requested: 'cpu', runtimeBackend: 'cpu', locator }), { backend: 'cpu' });});++function tracerRecording(calls) {+ const pixels = 4 * 4;+ return {+ traceNative(tables, options) {+ calls.push(options);+ return { rgba: new Float32Array(pixels * 4).fill(0.5), albedo: new Float32Array(pixels * 3).fill(0.5),+ normal: new Float32Array(pixels * 3).fill(0.5), depth: new Float32Array(pixels), variance: new Float32Array(pixels),+ averageSamples: 11.5, adapter: 'test adapter', backend: 'test' };+ },+ };+}++const emptyExport = {+ triangleCount: 0, triangles: 0, ignored: [],+ tables: Object.fromEntries(['triangles', 'materials', 'lights', 'atlas', 'environmentColors', 'environmentTables', 'parameters'].map(name => [name, ''])),+};++test('a native frame traces with the cycles kernel unless JS67_NATIVE_KERNEL names another', async () => {+ assert.equal(chooseNativeKernel({}), 'cycles');+ assert.equal(chooseNativeKernel({ JS67_NATIVE_KERNEL: '' }), 'cycles');+ assert.equal(chooseNativeKernel({ JS67_NATIVE_KERNEL: 'legacy' }), 'legacy');+ const calls = [];+ const saved = process.env.JS67_NATIVE_KERNEL;+ delete process.env.JS67_NATIVE_KERNEL;+ try {+ const defaulted = await traceFrameNative({ tracer: tracerRecording(calls), exported: emptyExport, width: 4, height: 4, samples: 8, denoise: 'none' });+ assert.equal(calls[0].kernel, 'cycles');+ assert.equal(defaulted.report.kernel, 'cycles');+ await traceFrameNative({ tracer: tracerRecording(calls), exported: emptyExport, width: 4, height: 4, samples: 8, denoise: 'none', kernel: 'legacy' });+ assert.equal(calls[1].kernel, 'legacy');+ } finally {+ if (saved !== undefined) process.env.JS67_NATIVE_KERNEL = saved;+ }+});++test('noiseThreshold reaches the native trace and the report keeps averageSamples', async () => {+ const calls = [];+ const traced = await traceFrameNative({ tracer: tracerRecording(calls), exported: emptyExport, width: 4, height: 4, samples: 64, denoise: 'none', noiseThreshold: 0.02 });+ assert.equal(calls[0].noiseThreshold, 0.02);+ assert.equal(traced.report.noiseThreshold, 0.02);+ assert.equal(traced.report.averageSamples, 11.5);+});++test('the wavelet filter and OIDN both run on the native features', async () => {+ const calls = [];+ const guides = [];+ const denoiser = { OIDN_VERSION: 'test', async denoiseWithOidn(features) { guides.push(Object.keys(features).sort()); return features.color; } };+ const withOidn = await traceFrameNative({ tracer: tracerRecording(calls), exported: emptyExport, width: 4, height: 4, samples: 8, denoise: 'oidn', denoiser });+ assert.equal(withOidn.report.denoiser, 'oidn');+ assert.deepEqual(guides[0], ['albedo', 'color', 'height', 'normal', 'width']);+ const withWavelet = await traceFrameNative({ tracer: tracerRecording(calls), exported: emptyExport, width: 4, height: 4, samples: 8, denoise: 'wavelet' });+ assert.equal(withWavelet.report.denoiser, 'wavelet');+});diff --git a/tests/path-tracer-denoise-oidn.test.js b/tests/path-tracer-denoise-oidn.test.jsindex 3e18570a..1a22fbcb 100644--- a/tests/path-tracer-denoise-oidn.test.js+++ b/tests/path-tracer-denoise-oidn.test.js@@ -76,3 +76,22 @@ test('the installed OIDN removes noise from a flat image and gives the same byteassert.ok(spread(first) < spread(color), `spread ${spread(first)} against ${spread(color)}`);assert.deepEqual(first, second);});++test('the native default (denoise true) picks OIDN when it is installed and the wavelet filter with a note when it is not', async () => {+ const installed = { findOidnBinary: () => 'oidn' };+ const withOidn = await chooseDenoiser(true, { preferOidn: true, loadOidn: async () => installed });+ assert.equal(withOidn.denoise, 'oidn');+ assert.equal(withOidn.denoiser, installed);+ assert.match(withOidn.note, /OIDN and the albedo and normal guides by default/);+ const without = await chooseDenoiser(true, { preferOidn: true, loadOidn: async () => null });+ assert.equal(without.denoise, 'wavelet');+ assert.match(without.note, /native backend denoises with OIDN.*wavelet filter ran instead/s);+});++test('explicit denoise values keep their meaning on native and the other backends keep the plain default', async () => {+ const loadOidn = async () => { throw new Error('must not load OIDN'); };+ assert.deepEqual(await chooseDenoiser(false, { preferOidn: true, loadOidn }), { denoise: false });+ assert.deepEqual(await chooseDenoiser('wavelet', { preferOidn: true, loadOidn }), { denoise: 'wavelet' });+ assert.deepEqual(await chooseDenoiser('none', { preferOidn: true, loadOidn }), { denoise: 'none' });+ assert.deepEqual(await chooseDenoiser(true, { loadOidn }), { denoise: true });+});