Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.mjs
new file mode 100644
index 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.md
new file mode 100644
index 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.mjs
index 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, sample
const 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.mjs
index 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.mjs
index 01e7736b..c9977f0b 100644
--- a/scripts/agent-runtime.mjs
+++ b/scripts/agent-runtime.mjs
@@ -556,9 +556,10 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', brow
if (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', brow
nativeTracerLocator.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.js
index 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.js
index 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 byte
assert.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 });
+});