3D engine that AI agents drive
Add a bounced-light estimate for lamp-lit closed rooms (#351)
Nguyen Xuan An2567765715b3
diff --git a/bench/reference/luminance-ratio.py b/bench/reference/luminance-ratio.pynew file mode 100644index 00000000..aec2b532--- /dev/null+++ b/bench/reference/luminance-ratio.py@@ -0,0 +1,58 @@+# Mean and 20th percentile of linear luminance of the 67js panel divided by the Cycles panel, read from reference sheets.+# uv run --no-project --python 3.12 --with pillow --with numpy python -I bench/reference/luminance-ratio.py <sheet.jpg> [<sheet.jpg> ...]+# uv run --no-project --python 3.12 --with pillow --with numpy python -I bench/reference/luminance-ratio.py --renders <directory> <scene id> [...]+# The second form takes the Cycles panel from images/<scene id>.jpg and the 67js picture from <directory>/<scene id>-gpu.png+# (what render-gpu.mjs writes), scaled to the panel's size.+# A sheet is two columns by two rows of panels under 22 px headers: Cycles top left, the 67js panel bottom left.+import os+import sys++import numpy as np+from PIL import Image++HEADER_HEIGHT = 22+LUMINANCE_WEIGHTS = np.array([0.2126, 0.7152, 0.0722])+++def linear_luminance(pixels):+ normalized = pixels.astype(np.float64) / 255.0+ linear = np.where(normalized <= 0.04045, normalized / 12.92, ((normalized + 0.055) / 1.055) ** 2.4)+ return linear @ LUMINANCE_WEIGHTS+++def panels(path):+ sheet = np.asarray(Image.open(path).convert("RGB"))+ height, width = sheet.shape[:2]+ column_width = width // 2+ row_height = height // 2+ cycles = sheet[HEADER_HEIGHT:row_height, :column_width]+ gpu = sheet[row_height + HEADER_HEIGHT:, :column_width]+ return cycles, gpu+++def ratios(cycles, gpu):+ cycles_luminance = linear_luminance(cycles)+ gpu_luminance = linear_luminance(gpu)+ return (+ gpu_luminance.mean() / cycles_luminance.mean(),+ np.percentile(gpu_luminance, 20) / np.percentile(cycles_luminance, 20),+ )+++def rendered_pair(directory, scene_id):+ cycles, _ = panels(os.path.join(os.path.dirname(os.path.abspath(__file__)), "images", f"{scene_id}.jpg"))+ picture = Image.open(os.path.join(directory, f"{scene_id}-gpu.png")).convert("RGB")+ gpu = np.asarray(picture.resize((cycles.shape[1], cycles.shape[0]), Image.LANCZOS))+ return cycles, gpu+++if __name__ == "__main__":+ arguments = sys.argv[1:]+ if arguments and arguments[0] == "--renders":+ directory, scene_ids = arguments[1], arguments[2:]+ pairs = [(scene_id, rendered_pair(directory, scene_id)) for scene_id in scene_ids]+ else:+ pairs = [(os.path.basename(path), panels(path)) for path in arguments]+ for name, (cycles, gpu) in pairs:+ mean_ratio, p20_ratio = ratios(cycles, gpu)+ print(f"{name}\tmean {mean_ratio:.2f}\tp20 {p20_ratio:.2f}")diff --git a/changes/351.md b/changes/351.mdnew file mode 100644index 00000000..d8cdd481--- /dev/null+++ b/changes/351.md@@ -0,0 +1 @@+- Add a bounced-light estimate for a closed room lit by point, spot or area lights without a bake (issue #351). `groundBounceEnvironment` gives the environment map a `bounce` colour, flux * rho / (pi * area * (1 - rho)) per colour channel, which the renderer adds to the diffuse light at no cost per frame; `environment.roomBounce: false` turns it off. A room with a sun is left alone. `scene_inspect` says so when a closed room is lit by lamps only and names the bake preset.diff --git a/src/agent-diagnostics.js b/src/agent-diagnostics.jsindex 2bb2796e..fc7c98ba 100644--- a/src/agent-diagnostics.js+++ b/src/agent-diagnostics.js@@ -79,7 +79,12 @@ export function recipeDiagnostics(recipe) {* The scene looks like a closed room and asks for no bake, so the world's light reaches it through the walls and the room* renders lifted and flat. `share` is the share of rays from the middle of the scene that hit an inner face.*/-export function closedRoomDiagnostic(share) {+export function closedRoomDiagnostic(share, litByLampsOnly = false) {+ if (litByLampsOnly) {+ return diagnostic('closed-room-without-bake', 'warning', 'bake',+ `${Math.round(share * 100)} percent of rays from the middle of the scene hit a wall, so this is a closed room lit only by its point, spot or area lights. Without a bake the walls bounce light only as one average colour over the whole room: no brighter corner beside a lamp, no colour bleeding off a red wall onto the floor next to it.`,+ 'Add "bake": { "preset": "standard" } (scene_apply set-bake) for bounced light that follows the lamps and the wall colours.');+ }return diagnostic('closed-room-without-bake', 'warning', 'bake',`${Math.round(share * 100)} percent of rays from the middle of the scene hit a wall, so this is a closed room, and without a bake the world's light still reaches it: the room renders lifted and grey, with weak contact shadows.`,'Add "bake": { "preset": "standard" } (scene_apply set-bake). It darkens what the sky cannot see and adds bounced light; measured against Cycles it halves the error of a closed room.');diff --git a/src/agent-scene.js b/src/agent-scene.jsindex ccea5b29..a905fb7f 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -1155,6 +1155,13 @@ export function createAgentScene(input, inputLimits = {}) {// A scene that asks for no bake and looks like a closed room gets one diagnostic naming the bake. The ray test costs a// few milliseconds, so it runs for scene_inspect only and is kept until the scene changes.+ function isLitByLampsOnly(environment) {+ const lampCount = (environment.pointLights?.length ?? 0) + (environment.spotLights?.length ?? 0) + (environment.areaLights?.length ?? 0);+ const keyColor = environment.keyColor ?? [1, 1, 1];+ const keyLight = (environment.keyIntensity ?? 1) * (keyColor[0] + keyColor[1] + keyColor[2]);+ return lampCount > 0 && keyLight === 0;+ }+let closedRoomCache = null;function closedRoomProblems() {if (state.recipe.bake) {@@ -1165,7 +1172,7 @@ export function createAgentScene(input, inputLimits = {}) {closedRoomCache = { revision, share: closedRoomShare(state.parts, worldMatrices) };}const { share } = closedRoomCache;- return share !== null && share >= CLOSED_ROOM_SHARE ? [closedRoomDiagnostic(share)] : [];+ return share !== null && share >= CLOSED_ROOM_SHARE ? [closedRoomDiagnostic(share, isLitByLampsOnly(state.recipe.environment))] : [];}// environment.resolveCoplanar 'offset' puts the smaller part of each coplanar pair on the next depth layer, so thediff --git a/src/ground-bounce.js b/src/ground-bounce.jsindex b0c3f9bd..a4db1654 100644--- a/src/ground-bounce.js+++ b/src/ground-bounce.js@@ -142,6 +142,155 @@ function groundOf(parts, automaticAlbedo) {return ground}+// A closed room lit by lamps. A wall a lamp lights becomes a dim lamp itself, and the walls light each other again. With a+// lamp of intensity I (flux 4 pi I), exposed wall area A and mean albedo rho, the light that reaches an average point after+// all the bounces is E = flux * rho / (A * (1 - rho)); a white surface sends back E / pi, the unit of an environment map's+// diffuse light. Each colour channel uses its own albedo, so a room of red walls bounces red light.+const ROOM_UNKNOWN_ALBEDO = 0.5+const ROOM_MAXIMUM_ALBEDO = 0.95+const FULL_SPHERE = 4 * Math.PI+// What the estimate keeps of the average bounce: furniture and open sides take some of it, and a flat fill has no gradient to+// make up for it. Fitted on `lit-interior`, `metal-room` and `brick-room` against Cycles (see docs/lighting.md).+const ROOM_BOUNCE_GAIN = 0.8+const KEY_LIGHT_THRESHOLD = 1e-3++function transformPoint(matrix, positions, vertexIndex, out) {+ for (let axis = 0; axis < 3; axis++) {+ out[axis] = matrix[axis] * positions[vertexIndex * 3] + matrix[4 + axis] * positions[vertexIndex * 3 + 1] + matrix[8 + axis] * positions[vertexIndex * 3 + 2] + matrix[12 + axis]+ }+ return out+}++// The area of a part's triangles whose front face looks at `viewpoint`: the walls of a room face its middle, and the outer+// side of a wall, which no light reaches, does not count.+function areaFacing(part, viewpoint) {+ const { positions, indices } = part.geometry+ const first = [0, 0, 0]+ const second = [0, 0, 0]+ const third = [0, 0, 0]+ let area = 0+ for (let corner = 0; corner < indices.length; corner += 3) {+ transformPoint(part.matrix, positions, indices[corner], first)+ transformPoint(part.matrix, positions, indices[corner + 1], second)+ transformPoint(part.matrix, positions, indices[corner + 2], third)+ const normalX = (second[1] - first[1]) * (third[2] - first[2]) - (second[2] - first[2]) * (third[1] - first[1])+ const normalY = (second[2] - first[2]) * (third[0] - first[0]) - (second[0] - first[0]) * (third[2] - first[2])+ const normalZ = (second[0] - first[0]) * (third[1] - first[1]) - (second[1] - first[1]) * (third[0] - first[0])+ const facing = normalX * (viewpoint[0] - first[0]) + normalY * (viewpoint[1] - first[1]) + normalZ * (viewpoint[2] - first[2])+ if (facing > 0) {+ area += 0.5 * Math.hypot(normalX, normalY, normalZ)+ }+ }+ return area+}++function partDiffuseAlbedo(material) {+ const known = groundAlbedo(material)+ if (known) {+ return known+ }+ return (material.metallic ?? 0) > GROUND_MAXIMUM_METALLIC ? [0, 0, 0] : [ROOM_UNKNOWN_ALBEDO, ROOM_UNKNOWN_ALBEDO, ROOM_UNKNOWN_ALBEDO]+}++/**+ * The surfaces of a closed room as `{ minimum, maximum, area, albedo }`: the scene's bounds, the area of the faces that look+ * at its middle and their area-weighted mean linear albedo. Null when the scene is not a closed room, or is drawn with a+ * bake (its light map holds the bounce).+ */+export function findRoomSurface(parts) {+ if (parts.length === 0 || isDrawnWithBakedLight(parts) || !isClosedRoom(parts)) {+ return null+ }+ const { minimum, maximum } = sceneBoundsOf(parts.map(part => worldBounds(part)))+ const middle = minimum.map((low, axis) => (low + maximum[axis]) / 2)+ let area = 0+ const albedoSum = [0, 0, 0]+ for (const part of parts) {+ if (part.material?.alphaMode === 'blend') {+ continue+ }+ const partArea = areaFacing(part, middle)+ const albedo = partDiffuseAlbedo(part.material ?? {})+ area += partArea+ for (let channel = 0; channel < 3; channel++) {+ albedoSum[channel] += partArea * albedo[channel]+ }+ }+ return area > 0 ? { minimum, maximum, area, albedo: albedoSum.map(sum => sum / area) } : null+}++function isInside(position, { minimum, maximum }) {+ return position.every((value, axis) => value >= minimum[axis] && value <= maximum[axis])+}++// The flux of each local light inside the room, per colour channel, in intensity times steradians: a point light spreads over+// the whole sphere, a spot light over its cone, an area light over one side as a Lambert emitter (pi).+function lightFlux(environment, room) {+ const flux = [0, 0, 0]+ const add = (light, steradians) => {+ if (!isInside(light.position, room)) {+ return+ }+ const color = light.color ?? [1, 1, 1]+ for (let channel = 0; channel < 3; channel++) {+ flux[channel] += color[channel] * (light.intensity ?? 1) * steradians+ }+ }+ for (const light of environment.pointLights ?? []) add(light, FULL_SPHERE)+ for (const light of environment.spotLights ?? []) add(light, 2 * Math.PI * (1 - Math.cos(light.angle ?? Math.PI / 4)))+ for (const light of environment.areaLights ?? []) add(light, Math.PI)+ return flux+}++/**+ * The diffuse light the walls of `room` bounce back at an average point, linear RGB in the unit of an environment map's+ * diffuse light (what `environmentDiffuse` returns): the flux of the local lights in `environment`, the room's area and its+ * mean albedo give flux / pi * rho / (area * (1 - rho)) in each channel.+ */+export function roomBounceRadiance(room, environment) {+ return lightFlux(environment, room).map((flux, channel) => {+ const albedo = Math.min(room.albedo[channel], ROOM_MAXIMUM_ALBEDO)+ return ROOM_BOUNCE_GAIN * (flux / Math.PI) * albedo / (room.area * (1 - albedo))+ })+}++// A sun that reaches the room (a window, a skylight) is light the estimate does not count, and such a scene already reads as+// light as Cycles in its shadows (`temple-hall`, `dark-shaft`): only a room lit by its lamps alone gets the bounce.+function hasKeyLight(environment) {+ const keyColor = environment.keyColor+ if (!keyColor) {+ return true+ }+ return (environment.keyIntensity ?? 1) * (keyColor[0] + keyColor[1] + keyColor[2]) > KEY_LIGHT_THRESHOLD+}++const roomOfParts = new WeakMap()++function roomOf(parts) {+ const remembered = roomOfParts.get(parts)+ if (remembered?.length === parts.length) {+ return remembered.room+ }+ const room = findRoomSurface(parts)+ roomOfParts.set(parts, { length: parts.length, room })+ return room+}++// The map gets a `bounce` colour that the renderer adds to its diffuse light. The map's data stays shared, so a lamp whose+// power changes every frame costs no new prefilter.+function roomBounceEnvironment(parts, environment) {+ if (environment.roomBounce === false || hasKeyLight(environment)) {+ return environment+ }+ const room = roomOf(parts)+ if (!room) {+ return environment+ }+ const bounce = roomBounceRadiance(room, environment)+ return bounce.some(channel => channel > 0) ? { ...environment, map: { ...environment.map, bounce } } : environment+}++// The term knows the sun and the sky only. A scene lit by point, spot or area lights has a floor those lights brighten, which// it would not count, so it would take the sky's own light away from the lower half and darken the scene (measured on// `light-linking` and `spot-area`).@@ -152,11 +301,18 @@ function hasLocalLights(environment) {/*** The environment with the ground's bounce in its map, found from the parts: the same environment when the scene has no* plain floor, a baked part (its light map already holds the bounce), a closed room (a bake or the room's own walls- * give that light), a point, spot or area light, or no map. `automaticAlbedo` is the colour of a floor the preview adds when no part forms one.+ * give that light), a point, spot or area light, or no map. A closed room lit by point, spot or area lights gets its walls'+ * bounced light instead, as a `bounce` colour on the map (`environment.roomBounce: false` turns that off). `automaticAlbedo` is the colour of a floor the preview adds when no part forms one.* `environment.groundBounce: false` turns it off.*/export function groundBounceEnvironment(parts, environment, { automaticAlbedo = null } = {}) {- if (!environment.map || environment.groundBounce === false || hasLocalLights(environment)) {+ if (!environment.map) {+ return environment+ }+ if (hasLocalLights(environment)) {+ return roomBounceEnvironment(parts, environment)+ }+ if (environment.groundBounce === false) {return environment}const ground = groundOf(parts, automaticAlbedo)diff --git a/src/renderer.js b/src/renderer.jsindex 7a62f43c..d45703b5 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -1616,11 +1616,22 @@ export class Renderer67 {return map;}+ // A map's `bounce` (the light a lit room's walls send back, ground-bounce.js) is a constant diffuse light: it adds to the+ // first irradiance coefficient, which the map's intensity scales again in the shader.+ irradianceWithBounce(map) {+ const irradiance = this.environmentResources.irradiance;+ if (!map.bounce) return irradiance;+ this.bouncedIrradiance ??= new Float32Array(irradiance.length);+ this.bouncedIrradiance.set(irradiance);+ for (let channel = 0; channel < 3; channel++) this.bouncedIrradiance[channel] += map.bounce[channel] / Math.max(map.intensity, 1e-6);+ return this.bouncedIrradiance;+ }+applyEnvironmentUniforms(map, uniforms = this.uniforms) {const context = this.context;context.uniform1f(uniforms.environmentEnabled, map ? 1 : 0);if (!map) return;- if (uniforms['environmentIrradiance[0]']) context.uniform3fv(uniforms['environmentIrradiance[0]'], this.environmentResources.irradiance);+ if (uniforms['environmentIrradiance[0]']) context.uniform3fv(uniforms['environmentIrradiance[0]'], this.irradianceWithBounce(map));context.uniform1f(uniforms.environmentIntensity, map.intensity);context.uniform2f(uniforms.environmentRotation, Math.cos(map.rotation), Math.sin(map.rotation));context.uniform1f(uniforms.environmentLevelMax, this.environmentResources.levelCount - 1);diff --git a/tests/room-bounce.test.js b/tests/room-bounce.test.jsnew file mode 100644index 00000000..d1c38747--- /dev/null+++ b/tests/room-bounce.test.js@@ -0,0 +1,117 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { createAgentScene } from '../src/agent-scene.js';+import { createEnvironmentMap } from '../src/environment.js';+import { findRoomSurface, groundBounceEnvironment, roomBounceRadiance } from '../src/ground-bounce.js';++const WALL = 0.2;+const ROOM_SIZE = 10;+const ROOM_HEIGHT = 6;++function slab(id, translation, scale, material) {+ return { id, geometry: 'box', material, translation, scale };+}++// A 10 x 6 x 10 room from six slabs; `roof: false` leaves the top open and `redLeft` paints the west wall red.+function roomParts({ roof = true, redLeft = false } = {}) {+ const slabs = [+ slab('floor', [0, -3, 0], [ROOM_SIZE, WALL, ROOM_SIZE], 'grey'),+ slab('north', [0, 0, -5], [ROOM_SIZE, ROOM_HEIGHT, WALL], 'grey'),+ slab('south', [0, 0, 5], [ROOM_SIZE, ROOM_HEIGHT, WALL], 'grey'),+ slab('west', [-5, 0, 0], [WALL, ROOM_HEIGHT, ROOM_SIZE], redLeft ? 'red' : 'grey'),+ slab('east', [5, 0, 0], [WALL, ROOM_HEIGHT, ROOM_SIZE], 'grey'),+ ];+ if (roof) {+ slabs.push(slab('roof', [0, 3, 0], [ROOM_SIZE, WALL, ROOM_SIZE], 'grey'));+ }+ const recipe = {+ format: '67js.scene', schemaVersion: 1,+ geometries: [{ id: 'box', type: 'box', bevel: 0 }],+ materials: [{ id: 'grey', color: [0.5, 0.5, 0.5] }, { id: 'red', color: [0.8, 0.1, 0.1] }],+ nodes: slabs,+ };+ return createAgentScene(recipe).parts;+}++function dimWorld() {+ return createEnvironmentMap({ width: 8, height: 4, data: new Float32Array(8 * 4 * 3).fill(0.02) });+}++function lampEnvironment(overrides = {}) {+ return {+ map: dimWorld(),+ keyColor: [0, 0, 0],+ pointLights: [{ position: [0, 1, 0], color: [1, 1, 1], intensity: 10 }],+ ...overrides,+ };+}++test('a closed room lit by a lamp gets flux * rho / (pi * area * (1 - rho)) as its bounce, scaled by the fitted gain', () => {+ const parts = roomParts();+ const room = findRoomSurface(parts);+ assert.ok(room, 'the six slabs form a room');+ const innerArea = 2 * ROOM_SIZE * ROOM_SIZE + 4 * ROOM_SIZE * ROOM_HEIGHT;+ assert.ok(Math.abs(room.area - innerArea) / innerArea < 0.05, `inner area ${room.area} against ${innerArea}`);+ const bounced = groundBounceEnvironment(parts, lampEnvironment());+ const albedo = 0.5;+ const unscaled = (4 * 10) * albedo / (room.area * (1 - albedo));+ const ratio = bounced.map.bounce[0] / unscaled;+ assert.ok(ratio > 0.5 && ratio < 1, `the fitted gain is below one: ${ratio}`);+ assert.deepEqual(roomBounceRadiance(room, lampEnvironment()), Array.from(bounced.map.bounce));+});++test('the bounce takes the colour of the walls', () => {+ const bounced = groundBounceEnvironment(roomParts({ redLeft: true }), lampEnvironment());+ const [red, green, blue] = bounced.map.bounce;+ assert.ok(red > green && green === blue || red > blue, `red ${red}, green ${green}, blue ${blue}`);+ const plain = groundBounceEnvironment(roomParts(), lampEnvironment()).map.bounce;+ assert.ok(Math.abs(plain[0] - plain[2]) < 1e-9, 'grey walls and a white lamp give a grey bounce');+});++test('the map keeps its data, so a lamp that changes every frame never rebuilds the environment textures', () => {+ const parts = roomParts();+ const environment = lampEnvironment();+ const bounced = groundBounceEnvironment(parts, environment);+ assert.equal(bounced.map.data, environment.map.data);+ const brighter = groundBounceEnvironment(parts, lampEnvironment({ map: environment.map, pointLights: [{ position: [0, 1, 0], intensity: 20 }] }));+ assert.ok(Math.abs(brighter.map.bounce[0] / bounced.map.bounce[0] - 2) < 1e-9);+});++test('no bounce is added with a sun, with roomBounce off, in an open room or from a lamp outside the room', () => {+ const parts = roomParts();+ const withSun = lampEnvironment({ keyColor: [3, 3, 3] });+ assert.equal(groundBounceEnvironment(parts, withSun), withSun);+ const switchedOff = lampEnvironment({ roomBounce: false });+ assert.equal(groundBounceEnvironment(parts, switchedOff), switchedOff);+ const openRoom = lampEnvironment();+ assert.equal(groundBounceEnvironment(roomParts({ roof: false }), openRoom), openRoom);+ const outside = lampEnvironment({ pointLights: [{ position: [0, 20, 0], intensity: 10 }] });+ assert.equal(groundBounceEnvironment(parts, outside), outside);+});++test('a scene without a map or without lamps is left alone', () => {+ const parts = roomParts();+ const noMap = { keyColor: [0, 0, 0], pointLights: [{ position: [0, 1, 0], intensity: 10 }] };+ assert.equal(groundBounceEnvironment(parts, noMap), noMap);+});++test('scene_inspect names the bake for a closed room lit by lamps only', () => {+ const recipe = {+ format: '67js.scene', schemaVersion: 1,+ geometries: [{ id: 'box', type: 'box', bevel: 0 }],+ materials: [{ id: 'grey', color: [0.5, 0.5, 0.5] }],+ nodes: [+ slab('floor', [0, -3, 0], [ROOM_SIZE, WALL, ROOM_SIZE], 'grey'),+ slab('north', [0, 0, -5], [ROOM_SIZE, ROOM_HEIGHT, WALL], 'grey'),+ slab('south', [0, 0, 5], [ROOM_SIZE, ROOM_HEIGHT, WALL], 'grey'),+ slab('west', [-5, 0, 0], [WALL, ROOM_HEIGHT, ROOM_SIZE], 'grey'),+ slab('east', [5, 0, 0], [WALL, ROOM_HEIGHT, ROOM_SIZE], 'grey'),+ slab('roof', [0, 3, 0], [ROOM_SIZE, WALL, ROOM_SIZE], 'grey'),+ ],+ environment: { keyIntensity: 0, pointLights: [{ position: [0, 1, 0], intensity: 10 }] },+ };+ const found = createAgentScene(recipe).inspect().diagnostics.find(entry => entry.kind === 'closed-room-without-bake');+ assert.ok(found);+ assert.match(found.message, /lit only by its point, spot or area lights/);+ assert.match(found.fix, /"preset": "standard"/);+});