Skip to content

3D engine that AI agents drive

Trace ambientIntensity as environment strength and name the rasterizer-only terms (Part of #1833)

Nguyen Xuan An594c5f02799b
diff --git a/changes/1833.md b/changes/1833.md
new file mode 100644
index 00000000..6bfe2d3d
--- /dev/null
+++ b/changes/1833.md
@@ -0,0 +1 @@
+- The path tracer reads `ambientIntensity` as environment map strength, so a recipe with ambient 0 and dim lamps stays dark in Cook; `fillIntensity` and `world: true` are named as rasterizer only in the render report (Part of #1833).
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index 6632ae2c..a30b07ca 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -30,7 +30,7 @@ Unidirectional path tracing against the triangle BVH that the [light bake](light
A shading point behind the portal (outside) is lit by BSDF samples only, and a ray that reaches the sky by another way than a portal still counts in full. The CPU tracer samples the sky through the portals in the same way (`src/path-tracer-portal.js`: a portal chosen uniformly, a point uniform on it, the pdf summed over the portals the direction crosses), and its next-event light for the sky is drawn through them. The WebGPU tracer does the same in its megakernel and wavefront kernels (the portals sit at the end of the environment table buffer), and the real-time WebGPU tracer does not use them yet. The WebGL tracer draws no light from a portal and names it in `report.ignored`. The agent scene tools do not take `portal` yet.
![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.
+- 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` multiplies the environment map strength, as it scales the rasterizer's environment light (Cycles: the World Background strength; `src/path-trace-terms.js`); a camera ray still sees the sky at the unscaled strength on the native kernel. `fillIntensity` (two fixed unshadowed lights) and `world: true` (outdoor haze shading) are rasterizer only, and the render report says so when a recipe sets them. `daylight` and `skyTop`/`skyBottom` change nothing in the rasterizer while an environment map lights the scene, which every recipe has, so the trace agrees. `world: false` hides nothing from the trace: a camera ray sees the environment map, where the rasterizer draws a flat background. Light the shadow side with a point or area light or `environmentIntensity`.
- 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/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.js
index fba61aa2..4c2f6b45 100644
--- a/scripts/agent-preview-browser.js
+++ b/scripts/agent-preview-browser.js
@@ -15,6 +15,7 @@ import { applyProjection } from '../src/camera.js';
import { mat4 } from 'gl-matrix';
import { listAddedControllerKinds, listAddedCameraRigKinds, listControllerKinds, listCameraRigKinds, unregisterControllerKind, unregisterCameraRigKind } from '../src/player.js';
import { fitAgentShadow, resolveAgentShadow, agentEnvironmentMap } from '../src/agent-look.js';
+import { pathTraceEnvironment } from '../src/path-trace-terms.js';
import { agentSceneModule, agentSceneModuleLoaded } from '../src/agent-scene-modules.js';
import { agentGroundPlacement, createAgentGround, placeAgentGround, FLOOR_COLOR } from '../src/agent-ground.js';
import { groundBounceEnvironment } from '../src/ground-bounce.js';
@@ -1078,7 +1079,7 @@ window.__agentPreview = {
const result = await renderPathTracedImage({
parts: record.scene.parts,
// The scene's motion blur shutter also blurs a grid volume that carries velocity (#1759), in the trace as in the rasterizer.
- environment: { ...environment, map: agentEnvironmentMap(environment), ...(record.scene.effects.motionBlur.shutter > 0 ? { volumeShutter: record.scene.effects.motionBlur.shutter } : {}) },
+ environment: { ...pathTraceEnvironment(environment), ...(record.scene.effects.motionBlur.shutter > 0 ? { volumeShutter: record.scene.effects.motionBlur.shutter } : {}) },
camera: record.scene.camera,
}, { ...options, exposure: record.scene.effects.exposure });
tracedExposure = record.scene.effects.exposure;
@@ -1110,7 +1111,7 @@ window.__agentPreview = {
import('../src/path-tracer.js'), import('../src/path-tracer-scene.js'), import('../src/path-tracer-gpu-pack.js'),
import('@codepawlhq/cook/pack-input'), import('@codepawlhq/cook/job-input'), import('@codepawlhq/cook/grid-volume-input'),
]);
- const environment = { ...record.scene.environment, map: agentEnvironmentMap(record.scene.environment) };
+ const environment = pathTraceEnvironment(record.scene.environment);
// The "cycles" kernel gets FORMAT-v2 tables with whole materials, and copies of one geometry stay instances; the legacy kernel reads flattened v1 triangles.
const camera = createCamera(record.scene.camera, options.width, options.height);
heldNativeExportTables = null;
diff --git a/src/path-trace-terms.js b/src/path-trace-terms.js
new file mode 100644
index 00000000..a101f018
--- /dev/null
+++ b/src/path-trace-terms.js
@@ -0,0 +1,42 @@
+import { createEnvironmentMap } from './environment.js';
+import { agentEnvironmentMap } from './agent-look.js';
+
+// The environment a path trace reads from a recipe's environment fields (issue #1833). The tracer lights with the environment
+// map, so the rasterizer's ambient term has to arrive as map strength:
+// ambientIntensity multiplies the map, like the rasterizer, which scales its environment light by it. In Cycles this is the
+// World Background strength.
+// What stays out, and why (the render report names the ones a recipe sets, see describeIgnoredFeatures):
+// fillIntensity: two fixed, unshadowed directional lights with hand-picked colours; nothing in a Cycles scene matches them.
+// daylight, skyTop, skyBottom: measured to change nothing in the rasterizer while an environment map lights the scene, which
+// every recipe has, so the trace already agrees.
+// world: true: the rasterizer's outdoor haze shading; the tracer draws the map behind the picture either way.
+
+const scaledMaps = new WeakMap();
+
+/** The map at `ambientIntensity` times its own strength; the same object returns while the map and the factor hold. */
+function mapScaledByAmbient(map, ambientIntensity) {
+ let byFactor = scaledMaps.get(map);
+ if (!byFactor) {
+ byFactor = new Map();
+ scaledMaps.set(map, byFactor);
+ }
+ if (!byFactor.has(ambientIntensity)) {
+ byFactor.set(ambientIntensity, createEnvironmentMap({ ...map, intensity: map.intensity * ambientIntensity }));
+ }
+ return byFactor.get(ambientIntensity);
+}
+
+/**
+ * The recipe environment with the map a path trace lights with. A camera ray keeps seeing the sky at the map's own strength
+ * (`cameraIntensity`, read by the native kernel) so that turning the ambient light down does not blacken the view.
+ */
+export function pathTraceEnvironment(environment) {
+ const map = agentEnvironmentMap(environment);
+ const ambientIntensity = environment.ambientIntensity ?? 1;
+ if (ambientIntensity === 1) return { ...environment, map };
+ return {
+ ...environment,
+ map: mapScaledByAmbient(map, ambientIntensity),
+ cameraIntensity: environment.cameraIntensity ?? map.intensity,
+ };
+}
diff --git a/src/path-tracer.js b/src/path-tracer.js
index fa940988..27757705 100644
--- a/src/path-tracer.js
+++ b/src/path-tracer.js
@@ -1053,6 +1053,8 @@ export function describeIgnoredFeatures(parts, environment, backend = 'cpu', { k
const hasGridVolume = (environment?.localVolumes ?? []).some(volume => volume?.shape === 'grid');
if (hasGridVolume && kernelMaterials && environment.volumeShutter > 0) notes.add('environment.volumeShutter is ignored for a grid volume: Cook draws the grid as it is at the frame time, with no motion blur from its velocity channel. Use backend "cpu" or "webgpu" for a blurred blast.');
if (!environment?.map) notes.add('There is no environment map, so the sky is black and only the lights shine.');
+ if (environment?.fillIntensity > 0) notes.add('fillIntensity is ignored: the two fixed fill lights are rasterizer only. Add a point or area light, or raise environmentIntensity, to light the shadow side of a trace.');
+ if (environment?.world === true) notes.add('world: true is ignored: the outdoor haze shading is rasterizer only, and a trace draws the environment map behind the picture and lights with it whatever world says.');
if (environment?.cameraIntensity !== undefined && !kernelMaterials) notes.add('cameraIntensity is ignored: only the native cycles kernel draws the sky a camera ray sees at its own strength, the other tracers use the map intensity.');
for (const part of parts) {
const material = part.material ?? {};
diff --git a/tests/path-trace-terms.test.js b/tests/path-trace-terms.test.js
new file mode 100644
index 00000000..6bd08593
--- /dev/null
+++ b/tests/path-trace-terms.test.js
@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { box } from '../src/geometry.js';
+import { describeIgnoredFeatures, renderPathTracedImage } from '../src/path-tracer.js';
+import { pathTraceEnvironment } from '../src/path-trace-terms.js';
+
+// A recipe's ambientIntensity reaches the path tracer as environment map strength, like the rasterizer's ambient term (issue #1833).
+const FLOOR = [{
+ name: 'floor',
+ geometry: box(0, 1),
+ matrix: new Float32Array([8, 0, 0, 0, 0, 0.1, 0, 0, 0, 0, 8, 0, 0, -0.05, 0, 1]),
+ material: { tag: 'surface', metallic: 0, roughness: 1, emission: 0, color: [0.5, 0.5, 0.5] },
+}];
+const CAMERA = { eye: [0, 3, 0], target: [0, 0, 0], up: [0, 0, -1], fov: 40 };
+const OPTIONS = { width: 16, height: 16, samples: 16, bounces: 2, denoise: false, threads: 1 };
+const RECIPE = { setup: 'studio', environmentIntensity: 0.4, keyIntensity: 0, fillIntensity: 0 };
+
+async function meanLinear(recipeEnvironment) {
+ const environment = pathTraceEnvironment(recipeEnvironment);
+ const { linear } = await renderPathTracedImage({ parts: FLOOR, environment, camera: CAMERA }, OPTIONS);
+ return Array.from(linear).reduce((total, value) => total + value, 0) / linear.length;
+}
+
+test('ambientIntensity multiplies the map strength the trace lights with', () => {
+ const plain = pathTraceEnvironment(RECIPE);
+ assert.equal(plain.map.intensity, 0.4);
+ assert.equal(plain.cameraIntensity, undefined);
+ assert.equal(pathTraceEnvironment({ ...RECIPE, ambientIntensity: 0.5 }).map.intensity, 0.2);
+ assert.equal(pathTraceEnvironment({ ...RECIPE, ambientIntensity: 0 }).map.intensity, 0);
+ assert.equal(pathTraceEnvironment({ ...RECIPE, ambientIntensity: 2 }).map.intensity, 0.8);
+});
+
+test('the map object is reused while the recipe holds, and a camera ray still sees the sky at its own strength', () => {
+ const first = pathTraceEnvironment({ ...RECIPE, ambientIntensity: 0.5 });
+ assert.equal(pathTraceEnvironment({ ...RECIPE, ambientIntensity: 0.5 }).map, first.map);
+ assert.equal(first.cameraIntensity, 0.4, 'the view keeps the sky at the unscaled map strength');
+ assert.equal(pathTraceEnvironment({ ...RECIPE, ambientIntensity: 0.5, cameraIntensity: 0.1 }).cameraIntensity, 0.1, 'a recipe cameraIntensity wins');
+});
+
+test('the traced light follows ambientIntensity: half gives half, 0 gives black', async () => {
+ const full = await meanLinear(RECIPE);
+ const half = await meanLinear({ ...RECIPE, ambientIntensity: 0.5 });
+ assert.ok(full > 0.05, `the studio map lights the floor (mean ${full})`);
+ assert.ok(Math.abs(half / full - 0.5) < 0.02, `half the ambient light gives half the traced light (${half} against ${full})`);
+ assert.equal(await meanLinear({ ...RECIPE, ambientIntensity: 0 }), 0);
+});
+
+test('daylight and the sky colours leave the traced map alone, as they leave the rasterizer lit by a map alone', () => {
+ const plain = pathTraceEnvironment(RECIPE);
+ const changed = pathTraceEnvironment({ ...RECIPE, daylight: 0, skyTop: [1, 0, 0], skyBottom: [0, 0, 1] });
+ assert.equal(changed.map, plain.map);
+});
+
+test('the render report names the rasterizer-only terms a recipe sets', () => {
+ const notesFor = environment => describeIgnoredFeatures(FLOOR, pathTraceEnvironment({ ...RECIPE, ...environment }));
+ assert.deepEqual(notesFor({}), []);
+ assert.match(notesFor({ fillIntensity: 1 }).join('\n'), /fillIntensity is ignored/);
+ assert.match(notesFor({ world: true }).join('\n'), /world: true is ignored/);
+ assert.deepEqual(notesFor({ world: false }), []);
+});