3D engine that AI agents drive
Find the OIDN package in a source checkout and document the native job defaults (#970)
Nguyen Xuan An0eab8abe8499
diff --git a/bench/native-tracer/job.mjs b/bench/native-tracer/job.mjsindex df87c707..c47a3887 100644--- a/bench/native-tracer/job.mjs+++ b/bench/native-tracer/job.mjs@@ -1,6 +1,6 @@// One MCP image render job of a recipe with settings.renderer.backend set, timed from submit to completed. Run it through gpu-lock.// node bench/native-tracer/job.mjs <output directory> --backend native|gpu|cpu [--recipe tests/fixtures/demo-room.recipe.json]-// [--samples 64] [--width 1920] [--height 1080] [--label run1] [--denoise true]+// [--samples 64] [--width 1920] [--height 1080] [--label run1] [--denoise true] [--browser <chrome path>]// Writes job-<label>.png and job-<label>.json (seconds, the metrics.pathTracer report and the job state).import { copyFile, mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';import { constants, setPriority, tmpdir } from 'node:os';@@ -29,7 +29,7 @@ setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);await mkdir(outputDirectory, { recursive: true });const workDirectory = await mkdtemp(join(tmpdir(), '67js-native-job-'));const transport = new StdioClientTransport({ command: process.execPath,- args: [resolve('bin/67js-mcp.mjs'), '--backend', 'gpu', '--memory', '384', '--jobs', join(workDirectory, 'jobs')], cwd: workDirectory, stderr: 'pipe' });+ args: [resolve('bin/67js-mcp.mjs'), '--backend', 'gpu', '--memory', '384', '--jobs', join(workDirectory, 'jobs'), ...(valueAfter('--browser', '') ? ['--browser', valueAfter('--browser', '')] : [])], cwd: workDirectory, stderr: 'pipe', env: { ...process.env } });let diagnostics = '';transport.stderr.on('data', bytes => { diagnostics = (diagnostics + bytes).slice(-4096); });const client = new Client({ name: '67js-native-job-bench', version: '1' });@@ -41,7 +41,9 @@ async function call(name, toolArguments = {}, timeout = 600000) {try {await client.connect(transport);const recipe = JSON.parse(await readFile(recipePath, 'utf8'));- const created = (await call('scene_create', { recipe }, 600000)).structuredContent;+ const createResult = await call('scene_create', { recipe }, 600000);+ if (!createResult.structuredContent) throw new Error(createResult.content?.[0]?.text ?? 'scene_create returned no structured content');+ const created = createResult.structuredContent;const settings = { kind: 'image', width, height, renderer: { type: 'pathTracer', backend, samples, bounces: 8, denoise, maxSeconds: 600 } };const started = performance.now();const submitted = await call('scene_render_submit', { sessionId: created.sessionId, expectedRevision: 0, settings });diff --git a/changes/970-native-oidn-default.md b/changes/970-native-oidn-default.mdindex c708326c..a70431f2 100644--- a/changes/970-native-oidn-default.md+++ b/changes/970-native-oidn-default.md@@ -1 +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)+- 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); a source checkout now finds `packages/denoise-oidn` without an install, and `JS67_NATIVE_KERNEL=legacy` keeps the old kernel (#970)diff --git a/docs/agent-render-jobs.md b/docs/agent-render-jobs.mdindex c16efc5b..16aeeecf 100644--- a/docs/agent-render-jobs.md+++ b/docs/agent-render-jobs.md@@ -185,7 +185,7 @@ An `image`, `stills` or `video` job can ask for the offline [path tracer](https:"renderer": { "type": "pathTracer", "backend": "gpu", "samples": 64, "bounces": 8, "denoise": true, "seed": 0, "maxSeconds": 120 } }```-Every field after `type` is optional. `backend` is `cpu` (the default, byte-identical on SwiftShader smokes), `gpu`, which traces in a WebGL2 shader and needs a runtime started on the GPU backend (a `--backend cpu` runtime refuses it), or `native`, which traces on hardware ray queries (Vulkan) through the optional `@codepawlhq/67js-render-native` package. A native job exports the scene from the job page, traces it in the job runner, then denoises (wavelet or OIDN) and writes the PNG as the other backends do. It never fails for lack of the package: without it, without its built binary or without a Vulkan ray query adapter the job runs on `gpu` (`cpu` on a cpu runtime) and `metrics.pathTracer.backendNote` says why; `metrics.pathTracer.backend` always names what ran. The look up costs one import and is cached per process. Native traces volume fog and subsurface scattering with the same walk as the WebGPU megakernel, honours `maxSeconds`, and honours `noiseThreshold` on the GPU (after 16 samples, and then every 8, a converged pixel draws no more; `report.averageSamples` is the mean a pixel drew). The `gpu` fallback ignores `noiseThreshold`. The report in `metrics.pathTracer` names the `backend` that ran, the `gpu`, `gpuCompileSeconds` and `gpuKernelCompiles`. A `stills` or `video` job traces every frame with the same options: the kernel compiles once per job page and each frame reuses it, so a film shows `gpuKernelCompiles: 1`. A video of traced frames goes through the ffmpeg encoder (the browser H.264 encoder has no drawn frame to read), `maxSeconds` limits each frame, and the job deadline is `maxSeconds` times the frame count plus 60 seconds, up to the job ceiling. Limits: `samples` 1 to 1024, `bounces` 1 to 16, `seed` 0 to 2147483647, `maxSeconds` 1 to 600 (the job's deadline is `maxSeconds` plus 60 seconds; a 1920 by 1080 still of a 180,000 triangle room at 64 samples took 246 s, so give a large still `maxSeconds` 600). `passes` are refused with it. The tracer loads in the job page on demand, uses eight threads at below-normal priority, stops pixels that have converged (`report.averageSamples`), and writes `render.png`; `scene_render_result` metrics carry `pathTracer` with the samples, threads, seconds and what the scene asked for that was not drawn. The same recipe and seed give the same PNG. A job that passes `maxSeconds` fails and writes no image.+Every field after `type` is optional. `backend` is `cpu` (the default, byte-identical on SwiftShader smokes), `gpu`, which traces in a WebGL2 shader and needs a runtime started on the GPU backend (a `--backend cpu` runtime refuses it), or `native`, which traces on hardware ray queries (Vulkan) through the optional `@codepawlhq/67js-render-native` package. A native job exports the scene from the job page, traces it in the job runner with the Cycles-matching kernel (`JS67_NATIVE_KERNEL=legacy` keeps the older one), then denoises and writes the PNG as the other backends do: `denoise: true` means OIDN with the albedo and normal guides when `@codepawlhq/67js-denoise-oidn` and its binary are installed, else the wavelet filter with a note in `metrics.pathTracer.denoiserNote`. The report carries `kernel` and `averageSamples`. It never fails for lack of the package: without it, without its built binary or without a Vulkan ray query adapter the job runs on `gpu` (`cpu` on a cpu runtime) and `metrics.pathTracer.backendNote` says why; `metrics.pathTracer.backend` always names what ran. The look up costs one import and is cached per process. Native traces volume fog and subsurface scattering with the same walk as the WebGPU megakernel, honours `maxSeconds`, and honours `noiseThreshold` on the GPU (after 16 samples, and then every 8, a converged pixel draws no more; `report.averageSamples` is the mean a pixel drew). The `gpu` fallback ignores `noiseThreshold`. The report in `metrics.pathTracer` names the `backend` that ran, the `gpu`, `gpuCompileSeconds` and `gpuKernelCompiles`. A `stills` or `video` job traces every frame with the same options: the kernel compiles once per job page and each frame reuses it, so a film shows `gpuKernelCompiles: 1`. A video of traced frames goes through the ffmpeg encoder (the browser H.264 encoder has no drawn frame to read), `maxSeconds` limits each frame, and the job deadline is `maxSeconds` times the frame count plus 60 seconds, up to the job ceiling. Limits: `samples` 1 to 1024, `bounces` 1 to 16, `seed` 0 to 2147483647, `maxSeconds` 1 to 600 (the job's deadline is `maxSeconds` plus 60 seconds; a 1920 by 1080 still of a 180,000 triangle room at 64 samples took 246 s, so give a large still `maxSeconds` 600). `passes` are refused with it. The tracer loads in the job page on demand, uses eight threads at below-normal priority, stops pixels that have converged (`report.averageSamples`), and writes `render.png`; `scene_render_result` metrics carry `pathTracer` with the samples, threads, seconds and what the scene asked for that was not drawn. The same recipe and seed give the same PNG on the cpu and gpu backends; the native Cycles-matching kernel is not always byte-identical between runs (on the demo room at 960 by 540 and 256 samples two jobs differed in a few bytes; a 480 by 270 job with OIDN did not). A job that passes `maxSeconds` fails and writes no image.## Controller APIdiff --git a/docs/path-tracer.md b/docs/path-tracer.mdindex bf667775..d486adf1 100644--- a/docs/path-tracer.md+++ b/docs/path-tracer.md@@ -61,7 +61,7 @@ The same scene and options give the same bytes. Random numbers come from a hash`backend: "native"` is an agent render job setting, not a `renderPathTracedImage` option: [`packages/render-native`](../packages/render-native/README.md) runs the same kernel on Vulkan ray queries. On the demo room at 1920 by 1080 and 64 samples an MCP image job took 25 to 35 s with native against 58 s with gpu (trace alone 2.7 to 3.1 s against 38.8 s; the rest is the page export, the wavelet denoise and the PNG), FLIP 0.0047 between them. A missing package, binary or adapter falls back to gpu with a note in the job report. `maxSeconds` is honoured: past it the native trace stops and the job fails, as on the other backends, instead of rerunning on gpu; `noiseThreshold` is too (the kernel applies the CPU stop rule per pixel, so `averageSamples` falls below `samples`; the `gpu` and `webgpu` backends still draw every sample). Volume fog and subsurface scattering are in the native kernel, compiled in only for a scene that uses them; `bench/native-tracer/scenes.mjs` draws the reference scenes on native and on the WebGPU megakernel for a FLIP comparison. Alpha cutouts (`alphaMode: "mask"`) work: cutout triangles are their own geometry and the kernel confirms a hit only when the colour map alpha reaches the cutoff, with no step limit. In a dense cutout scene native is the more correct tracer: the CPU and WebGL2 shadow ray takes the first hit the traversal finds, not the nearest, and when that hit is a transparent texel it skips occluders it had not reached yet, so those backends leak light (300 leaf cards: native vs cpu FLIP 0.043, and 0.0002 once the CPU shadow ray takes the nearest hit; bench/native-tracer/cutout-bisect.mjs shows one card agrees exactly). The steps before: up to 8 layers deep (`bench/native-tracer/cutout.mjs`: 300 masked leaf cards trace in 0.1 s at 640 by 360 and 64 samples). See [agent-render-jobs.md](agent-render-jobs.md#path-tracer).-The native package has two kernels. The default `legacy` kernel is the one described above. Pass `kernel: 'cycles'` to `traceNative` (or set `JS67_NATIVE_KERNEL=cycles`) for the opt-in kernel that follows Blender Cycles 5.3: on six reference scenes at 4096 samples it matches Cycles within 1 percent of the mean and within 1.8 percent on every 8 by 8 tile, and its error at 256 samples on `lit-interior` is 0.0027 against 0.0198 for the legacy kernel (Cycles: 0.0031). Three options follow Cycles: `sampler` (`'sobol-burley'` blue-noise pattern by default, `'white'` for the hash sampler), `filterType` and `filterWidth` (`'box'` width 1 by default, `'gaussian'` and `'blackman-harris'` from the Cycles filter table) and `lightSampling` (`'auto'`, `'tree'` or `'uniform'`; the Cycles light tree is used from more than one emitter). It is 2.3 to 3.1 times slower per sample than the legacy kernel before the light tree (0.92 s against 2.86 s on `lit-interior`, 960 by 540, 256 samples), and the light tree adds 16 to 32 percent per sample on top; at equal error against Cycles 5.3 it is 1.2 times faster on `lit-interior` and 3 to 6 percent slower on `many-lights-500` on an RTX 3060, and 1.5 times faster and level (1.02 to 1.03 times) on an NVIDIA A10G. Tables, method and the equal-error caveat are in [cycles-parity.md](cycles-parity.md#selecting-the-kernel).+The native package has two kernels. `traceNative` keeps `legacy`, the kernel described above, as its own default, but a render job with `backend: "native"` (issue #970) traces with the `cycles` kernel and denoises with OIDN and the albedo and normal guides when `denoise` is `true` (the default); `JS67_NATIVE_KERNEL=legacy` makes the job runner use the legacy kernel again, and without OIDN installed the wavelet filter runs with a note in `denoiserNote`. The job report names the `kernel`, the `noiseThreshold` and the `averageSamples`. On the `metal` reference scene (960 by 540, 256 samples, NVIDIA A10, Vulkan, scored against Cycles 5.3 at 4096 samples with relMSE, the 100 worst pixels dropped, and FLIP): the default job frame step (`bench/native-tracer/metal-job.mjs`) took 1.64 s (1.22 s trace, 0.23 s OIDN) with relMSE 0.00007, against 5.57 s for the wavelet filter (relMSE 0.00014), 1.36 s for no filter (relMSE 0.00019, flat-area grain 0.0076 against 0.0024 filtered) and 1.23 s for the legacy kernel with OIDN (relMSE 0.00093, FLIP 0.039 against 0.009). `cycles` is the opt-in kernel that follows Blender Cycles 5.3: on six reference scenes at 4096 samples it matches Cycles within 1 percent of the mean and within 1.8 percent on every 8 by 8 tile, and its error at 256 samples on `lit-interior` is 0.0027 against 0.0198 for the legacy kernel (Cycles: 0.0031). Three options follow Cycles: `sampler` (`'sobol-burley'` blue-noise pattern by default, `'white'` for the hash sampler), `filterType` and `filterWidth` (`'box'` width 1 by default, `'gaussian'` and `'blackman-harris'` from the Cycles filter table) and `lightSampling` (`'auto'`, `'tree'` or `'uniform'`; the Cycles light tree is used from more than one emitter). It is 2.3 to 3.1 times slower per sample than the legacy kernel before the light tree (0.92 s against 2.86 s on `lit-interior`, 960 by 540, 256 samples), and the light tree adds 16 to 32 percent per sample on top; at equal error against Cycles 5.3 it is 1.2 times faster on `lit-interior` and 3 to 6 percent slower on `many-lights-500` on an RTX 3060, and 1.5 times faster and level (1.02 to 1.03 times) on an NVIDIA A10G. Tables, method and the equal-error caveat are in [cycles-parity.md](cycles-parity.md#selecting-the-kernel).`backend: 'cpu'` (the default) is the reference: it reuses `src/triangle-bvh.js` and `src/ray-query.js`, runs on workers in the job page next to the scene, needs no GPU, and gives the same bytes for the same scene and options. It measured 25 to 238 seconds for a 960 by 540 still at 32 samples on a Ryzen 5 5600X with four threads, while another session also loaded the machine (table in `bench/reference/README.md`).@@ -110,7 +110,7 @@ The 1920 by 1080 still of `tests/fixtures/demo-room.recipe.json` at `samples: 64## 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.+`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. A source checkout also finds the package in `packages/denoise-oidn`. On the native backend `denoise: true` means OIDN when it is installed. 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:diff --git a/scripts/agent-path-trace-denoise.mjs b/scripts/agent-path-trace-denoise.mjsindex adc5e642..4bba73b6 100644--- a/scripts/agent-path-trace-denoise.mjs+++ b/scripts/agent-path-trace-denoise.mjs@@ -1,14 +1,25 @@+import { existsSync } from 'node:fs';+import { fileURLToPath } from 'node:url';+// 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';+// A source checkout keeps the package in packages/, beside scripts/ or, from the bundled server, two folders above build/mcp.+const CHECKOUT_PACKAGE_URLS = ['../packages/denoise-oidn/index.mjs', '../../packages/denoise-oidn/index.mjs']+ .map(relative => new URL(/* @vite-ignore */ relative, import.meta.url));+async function loadOidnPackage() {- try {- const denoiser = await import(OIDN_PACKAGE);- return denoiser.findOidnBinary() ? denoiser : null;- } catch {- return null;+ const checkoutSpecifiers = CHECKOUT_PACKAGE_URLS.filter(packageUrl => existsSync(fileURLToPath(packageUrl))).map(packageUrl => packageUrl.href);+ for (const specifier of [OIDN_PACKAGE, ...checkoutSpecifiers]) {+ try {+ const denoiser = await import(/* @vite-ignore */ specifier);+ if (denoiser.findOidnBinary()) return denoiser;+ } catch {+ // Try the next place the package may live.+ }}+ return null;}/**diff --git a/tests/path-tracer-denoise-oidn.test.js b/tests/path-tracer-denoise-oidn.test.jsindex 1a22fbcb..ce4fea8a 100644--- a/tests/path-tracer-denoise-oidn.test.js+++ b/tests/path-tracer-denoise-oidn.test.js@@ -95,3 +95,9 @@ test('explicit denoise values keep their meaning on native and the other backendassert.deepEqual(await chooseDenoiser('none', { preferOidn: true, loadOidn }), { denoise: 'none' });assert.deepEqual(await chooseDenoiser(true, { loadOidn }), { denoise: true });});++test('a source checkout finds the fetched OIDN package without it being installed under node_modules', { skip: findOidnBinary() ? false : 'the oidnDenoise binary is not fetched' }, async () => {+ const choice = await chooseDenoiser('oidn');+ assert.equal(choice.denoise, 'oidn');+ assert.equal(typeof choice.denoiser.denoiseWithOidn, 'function');+});