Skip to content

3D engine that AI agents drive

Say a daylit interior traces brighter than the raster at one exposure (Part of #1334)

Nguyen Xuan Anf8de2e712550
diff --git a/bench/reference/interior-exposure.mjs b/bench/reference/interior-exposure.mjs
index 1c90c97d..a36872e5 100644
--- a/bench/reference/interior-exposure.mjs
+++ b/bench/reference/interior-exposure.mjs
@@ -1,7 +1,7 @@
// Draws one daylit room with the raster renderer and with the path tracer from the same recipe, and prints the mean luminance
// of each (issue #1334). The room is closed except for one window; the only light is the sun and a physical sky.
// node bench/reference/interior-exposure.mjs <output directory> [--samples 48] [--sun-bounce 2] [--exposure 3.6]
-// [--environment-intensity 0.3] [--backend gpu|cpu] [--key-intensity 1] [--sealed]
+// [--environment-intensity 0.3] [--backend gpu|cpu] [--key-intensity 1] [--sealed] [--width 960] [--height 540] [--denoise]
// Run it through gpu-lock.sh. Files are <output directory>/raster.png and path-traced.png; build the MCP server first
// (`npm run build && node scripts/build-mcp.mjs`).
import assert from 'node:assert/strict';
@@ -35,8 +35,10 @@ const tightShadow = argumentsGiven.includes('--tight-shadow');
// --raster-only skips the path tracer, for sweeps of the raster alone; --shadow-extent <metres> fits the sun's shadow view to that half width around the room.
const rasterOnly = argumentsGiven.includes('--raster-only');
const shadowExtent = numberAfter('--shadow-extent', 0);
-const WIDTH = 960;
-const HEIGHT = 540;
+const WIDTH = numberAfter('--width', 960);
+const HEIGHT = numberAfter('--height', 540);
+// --denoise runs the OIDN denoiser on the path traced frame (the default leaves it off so the mean is the raw estimate).
+const denoise = argumentsGiven.includes('--denoise') ? 'oidn' : false;
const ROOM = { halfWidth: 4, front: -3, back: 3.5, height: 3, wall: 0.2 };
const WINDOW = { halfWidth: 1.4, bottom: 0.9, top: 2.4 };
@@ -118,7 +120,7 @@ async function render(sessionId, name, renderer) {
async function traceAndReport(sessionId) {
const traced = await render(sessionId, 'path-traced', {
- type: 'pathTracer', backend, samples, bounces: 6, denoise: false, seed: 1, maxSeconds: 120,
+ type: 'pathTracer', backend, samples, bounces: 6, denoise, seed: 1, maxSeconds: 120,
});
console.log(JSON.stringify({ ignored: traced.metrics?.pathTracer?.ignored, diagnostics: traced.diagnostics }, null, 1));
console.log(`wrote ${outputDirectory}/raster.png and path-traced.png`);
diff --git a/changes/1334.md b/changes/1334.md
new file mode 100644
index 00000000..be3dca2d
--- /dev/null
+++ b/changes/1334.md
@@ -0,0 +1 @@
+- A path traced job's exposure advice says a daylit interior traces about 1 to 2 stops brighter than the raster frame at the same exposure, with the measured table in the path tracer guide (#1334).
diff --git a/docs/mcp.md b/docs/mcp.md
index c53fef64..68968f1b 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -206,7 +206,7 @@ Every tool schema is read on every turn, so `node scripts/measure-tool-cost.mjs`
| `coplanar-overlap` | `nodes`, `parts`, `area` or `reason` | Z-fighting: two parts draw the same plane (`area` in square metres), or the draw-time ranking could not settle a part (`reason`: `rank-overflow`, `double-sided-gap`, `unchecked` or `collapsed-node`). A scene by default ranks flush faces, so `scene_look` reports only what the ranking left over; a scene with `environment.resolveCoplanar: false` gets the pairs. The check is bounded by a work budget and says when it ran out. |
| `exposure-clipped`, `exposure-black` | `whitePercent`, `blackPercent`, and `lights` on a clipped frame | Share of a 64 by 64 copy of the frame that is clipped to white (35 percent or more) or black (98 percent or more) after tone mapping. A clipped frame also lists its three strongest lights (`{ field, intensity }`, such as `environment.pointLights[1].intensity`), and its fix names the strongest, so an over-exposed light can be found without opening the image. |
-The checks run on part bounds, material fields and that small copy of the frame, so they cost almost nothing. None of them reads an object ID pass: parts are named from the scene itself, so the findings are identical on the cpu and gpu backends. The object ID, depth and normal passes exist in every raster render job (`settings.passes`). A path traced job (`renderer.type` `pathTracer`) writes the lit image only: it has no passes, `passes` is refused with a message that says so, and the job's `metrics.diagnostics` carries the part findings of its first frame plus one `findings-unavailable` entry (severity `info`) saying that exposure findings and the passes are unavailable there and why. Check exposure with `scene_look` or a raster job before tracing. Scenes of over 256 parts get no floating or intersection findings. `src/frame-checks.js` holds them.
+The checks run on part bounds, material fields and that small copy of the frame, so they cost almost nothing. None of them reads an object ID pass: parts are named from the scene itself, so the findings are identical on the cpu and gpu backends. The object ID, depth and normal passes exist in every raster render job (`settings.passes`). A path traced job (`renderer.type` `pathTracer`) writes the lit image only: it has no passes, `passes` is refused with a message that says so, and the job's `metrics.diagnostics` carries the part findings of its first frame plus one `findings-unavailable` entry (severity `info`) saying that exposure findings and the passes are unavailable there and why. Check exposure with `scene_look` or a raster job before tracing. On a daylit interior the traced frame is about 1 to 2 stops brighter than the raster one at the same exposure (measured table in `docs/path-tracer.md`, Exposure), so lower the exposure for the trace. Scenes of over 256 parts get no floating or intersection findings. `src/frame-checks.js` holds them.
The recipe uses `format: 'crucible.scene'` and `schemaVersion: 1`.
Primitive sizes come from the node scale: a `box` is a unit cube, and `cylinder` and `sphere` have radius 1, so scale x and z (cylinder) or scale (sphere) is the radius, never the diameter. A 6-segment cylinder is a hexagonal prism with its corners on X (2 x scale apart) and its flats on Z (1.732 x scale apart); for a hex part W wide across the flats, scale x and z by W / 1.732.
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index 6632ae2c..c7072c6d 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -31,6 +31,15 @@ Unidirectional path tracing against the triangle BVH that the [light bake](light
![The same dim room corner lit only by the sky through a window, 64 samples a pixel in Cook: without a portal (left, grainy) and with one over the window (right, smooth), at the same brightness](cook-light-portals.jpg)
- Exposure (#1833): a render job's `effects.exposure` multiplies the traced linear picture before the view transform, on the CPU, WebGL and WebGPU backends and on a native frame; `renderPathTracedImage` and `toneMapToRgba8` take it as `exposure` (a number above 0, default 1), and the linear pixels it returns are not scaled. A scene with no sun, sky or lamp traces black. `ambientIntensity`, `fillIntensity`, `daylight` and `skyTop`/`skyBottom` are rasterizer terms: the tracer lights the scene with the environment map, so use `environmentIntensity` to scale the sky.
+
+Raster against tracer on a daylit interior (#1334, `bench/reference/interior-exposure.mjs`: an 8 x 6.5 m room with one window, physical sky, sun bounce 2, AgX, 960 x 540, GPU tracer, 48 samples, no denoiser). Before #1833 the tracer ignored `effects.exposure`, so the room looked about 3 stops darker than the raster at exposure 3.6. Now both apply it, and the tracer is the brighter one, because it carries the light that bounces around the room and the raster fill is lower (raising `sunBounce` to 8 lifts the raster mean only from 31.9 to 47.6 of 255):
+
+| `effects.exposure` | Raster mean (display, linear) | Tracer mean (display, linear) | Tracer over raster, linear |
+|---|---|---|---|
+| 1 | 16.7, 0.0143 | 33.5, 0.0278 | 1.9 |
+| 3.6 | 31.9, 0.0385 | 73.1, 0.1042 | 2.7 |
+
+The sunlit floor patch agrees to within a stop (158.8, 127.2, 82.1 against 134.2, 106.0, 74.2 at exposure 1); the gap sits on the walls and ceiling in shade (display 37 against 17 on the back wall at exposure 1). A sealed room still traces black (0.0006 linear), so the extra light is not leaking sky. To match a raster look with the tracer, lower `effects.exposure` (about 1 where the raster used 3.6 in this room) rather than raising it past its cap of 16.
- Volume fog: `environment.volumeFog` is traced as a homogeneous medium inside its box, with its `density`, `color` (the scattering albedo), `anisotropy` (Henyey-Greenstein) and `maxDistance`. The distance to each scattering event is drawn from the exact free-flight distribution, so there is no step count and no banding. Every event is lit by next-event estimation (sun, point, spot, area lights and the sky, with shadow rays) and light reaching a surface through the fog is dimmed by it. Fog events count as bounces. `noiseAmount`, `noiseScale`, `drift`, `steps` and the `ambient` glow are rasterizer tricks and are not used.
- Sky strength seen by the camera (native `cycles` kernel only, #1121): `environment.cameraIntensity` (a number of 0 or more, in the units of `map.intensity`; left out, the camera sees the sky at the lighting intensity and nothing changes) is the strength of the sky for a camera ray and for a ray that reaches it from the camera through a cutout, a transparent surface or smooth glass, while the sky keeps lighting the scene at `map.intensity`. It is what Cycles does with a Light Path 'Is Camera Ray' mix in the world, and it replaces a second trace with the opaque surfaces black. The strength applies until the path first bounces off a diffuse or glossy surface, reflects (also off glass), crosses rough glass or a translucent surface, or scatters in fog; sun disks and emissive surfaces are not scaled. The CPU, WebGL and WebGPU tracers ignore it and `report.ignored` says so.
diff --git a/src/frame-checks.js b/src/frame-checks.js
index 6ddc4f3f..83a2d153 100644
--- a/src/frame-checks.js
+++ b/src/frame-checks.js
@@ -335,7 +335,7 @@ export function pathTracerFindingsLimit() {
severity: 'info',
target: 'renderer',
message: 'This job is path traced. The tracer writes the lit image only, so exposure findings and the object ID, depth and normal passes are unavailable; the page draws no raster frame to read them from.',
- fix: 'Check exposure with scene_look or a raster job (leave renderer out), then trace. Part findings (framing, floating, intersecting, textures, z-fighting) are reported as usual.',
+ fix: 'Check exposure with scene_look or a raster job (leave renderer out), then trace. On a daylit interior the traced frame comes out about 1 to 2 stops brighter than the raster one at the same effects.exposure, because the tracer adds the light the room bounces around and the raster fill is lower (docs/path-tracer.md, Exposure): lower effects.exposure for the trace instead of raising it. Part findings (framing, floating, intersecting, textures, z-fighting) are reported as usual.',
};
}
diff --git a/tests/frame-checks.test.js b/tests/frame-checks.test.js
index 475e677b..e8eec3fb 100644
--- a/tests/frame-checks.test.js
+++ b/tests/frame-checks.test.js
@@ -290,6 +290,12 @@ test('a path traced job says why exposure findings and passes are unavailable',
assert.match(limit.fix, /scene_look/);
});
+test('the path traced exposure advice says a daylit interior traces brighter and to lower the exposure, not raise it', () => {
+ const { fix } = pathTracerFindingsLimit();
+ assert.match(fix, /brighter than the raster one/);
+ assert.match(fix, /lower effects\.exposure/);
+});
+
test('a scene reports the z-fighting its ranking left over, and none when it opted out', async () => {
const { loadAgentSceneModules } = await import('../src/agent-scene-modules.js');
await loadAgentSceneModules({ environment: { resolveCoplanar: 'offset' } });