3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Leave portal area lights out of the bake, probes and bounce estimate (#2153)
Nguyen Xuan An57eb5a58438a
diff --git a/changes/2153.md b/changes/2153.mdnew file mode 100644index 00000000..639df553--- /dev/null+++ b/changes/2153.md@@ -0,0 +1 @@+- A portal area light (`portal: true`) no longer lights the light bake, the object reflection probes or the room bounce estimate as if it were a panel, and is no longer named as the strongest light to turn down (#2153).diff --git a/docs/light-bake.md b/docs/light-bake.mdindex c992c65e..8080cfab 100644--- a/docs/light-bake.md+++ b/docs/light-bake.md@@ -52,7 +52,7 @@ const { parts: bakedParts, report } = await bakeLightmapsAsync(parts, lighting,The bake traces cosine-weighted paths from each texel through up to `bounces` reflections. Each hit adds its own emission and the direct light it receives from the point lights and the sun, with shadow rays. A texel stores that light times its own albedo. Direct light is not baked: it stays live, so shadows and moving lights keep working. The stored light is only what has bounced at least once, so a scene needs the same lights at run time that it gave the bake.-Spot lights take the cone and soft edge the renderer uses (`angle`, `penumbra`, default 0.15), with `range` and `radius` as for a point light. An area light is a rectangle that emits from its front side only, with the path tracer's `intensity * cosine / distance squared`. A hit is lit by one shadow ray per area light to a point of the rectangle that changes on every call; the sequence is a hash of the call count, so it repeats exactly, and the many paths of a texel average the soft shadow. At most 8 spot and 7 area lights. A scene without spot or area lights bakes the same bytes as before.+Spot lights take the cone and soft edge the renderer uses (`angle`, `penumbra`, default 0.15), with `range` and `radius` as for a point light. An area light is a rectangle that emits from its front side only, with the path tracer's `intensity * cosine / distance squared`. A hit is lit by one shadow ray per area light to a point of the rectangle that changes on every call; the sequence is a hash of the call count, so it repeats exactly, and the many paths of a texel average the soft shadow. At most 8 spot and 7 area lights. A scene without spot or area lights bakes the same bytes as before. An area light with `portal: true` is a window and emits nothing: the bake, the object reflection probes and the room bounce estimate leave it out, as the raster view does (it adds none of its own light).Not baked: the environment map (it already lights every surface at run time) and specular reflection. A metal part reflects no baked light. Fresnel and sheen are ignored.diff --git a/src/area-light-portal.js b/src/area-light-portal.jsnew file mode 100644index 00000000..2e3dbdbc--- /dev/null+++ b/src/area-light-portal.js@@ -0,0 +1,7 @@+// A portal area light (#1948) marks a window: it emits nothing and only lets sky light in. Everything that sums or traces the light a+// panel gives off (light bake, object reflection probes, the room bounce estimate, the strongest-light list) works on this list.++/** The area lights that give off light of their own: the list without its portals. Keeps the order. */+export function emittingAreaLights(areaLights) {+ return (areaLights ?? []).filter(light => light.portal !== true);+}diff --git a/src/frame-checks.js b/src/frame-checks.jsindex 83a2d153..3fbd694f 100644--- a/src/frame-checks.js+++ b/src/frame-checks.js@@ -162,6 +162,7 @@ export function strongestLights(environment) {const lights = [{ field: 'environment.keyIntensity', intensity: environment.keyIntensity ?? 1 }];for (const listName of ['pointLights', 'spotLights', 'areaLights']) {(environment[listName] ?? []).forEach((light, index) => {+ if (light.portal === true) return;lights.push({ field: `environment.${listName}[${index}].intensity`, intensity: light.intensity ?? 1 });});}diff --git a/src/ground-bounce.js b/src/ground-bounce.jsindex 0d6e4d0d..30edec6e 100644--- a/src/ground-bounce.js+++ b/src/ground-bounce.js@@ -1,6 +1,7 @@import { computeIrradianceCoefficients, createEnvironmentMap, evaluateIrradiance } from './environment.js'import { CLOSED_ROOM_SHARE, closedRoomShare, partMatrixLookup } from './closed-room.js'import { worldBounds } from './probe-trace.js'+import { emittingAreaLights } from './area-light-portal.js'// The ground of a scene is its floor: a part that spans the scene (the same test as the automatic floor of agent scenes),// is thin and is the lowest geometry. Its albedo comes from its material.@@ -238,7 +239,7 @@ function lightFlux(environment, room) {}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)+ for (const light of emittingAreaLights(environment.areaLights)) add(light, Math.PI)return flux}@@ -315,7 +316,7 @@ function roomBounceEnvironment(parts, environment) {// 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`).function hasLocalLights(environment) {- return [environment.pointLights, environment.spotLights, environment.areaLights].some(lights => lights?.length > 0)+ return [environment.pointLights, environment.spotLights, emittingAreaLights(environment.areaLights)].some(lights => lights?.length > 0)}// Under a low sun a shadow is lit by more than the sky and the level ground: slopes, walls and roofs that face the sun senddiff --git a/src/light-bake.js b/src/light-bake.jsindex 517be178..2e83fbe1 100644--- a/src/light-bake.js+++ b/src/light-bake.js@@ -1,4 +1,5 @@import { invalidField } from './field-error.js';+import { emittingAreaLights } from './area-light-portal.js';import { MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS } from './light-limits.js';import { buildTriangleBvh } from './triangle-bvh.js';import { readTriangle } from './triangle-math.js';@@ -168,7 +169,7 @@ export function normalizeLights(lighting) {return { position: Array.from(light.position), color: Array.from(light.color ?? [1, 1, 1]), intensity: light.intensity, range, radius };});const spotSources = lighting.spotLights ?? [];- const areaSources = lighting.areaLights ?? [];+ const areaSources = emittingAreaLights(lighting.areaLights);const spotLights = withAffects(normalizeSpotLights(spotSources), spotSources);const areaLights = withAffects(normalizeAreaLights(areaSources), areaSources);const keyColor = lighting.keyColor ?? [0, 0, 0];diff --git a/tests/area-light-portal-bake.test.js b/tests/area-light-portal-bake.test.jsnew file mode 100644index 00000000..d635a75f--- /dev/null+++ b/tests/area-light-portal-bake.test.js@@ -0,0 +1,82 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { box, sphere } from '../src/geometry.js';+import { createEnvironmentMap } from '../src/environment.js';+import { bakeLightmaps } from '../src/light-bake.js';+import { traceObjectProbes } from '../src/probe-trace.js';+import { groundBounceEnvironment } from '../src/ground-bounce.js';+import { strongestLights } from '../src/frame-checks.js';+import { emittingAreaLights } from '../src/area-light-portal.js';++const cube = box(0, 1);+const ball = sphere(16, 12);++function placed(name, geometry, translation, scale, material = {}) {+ const matrix = new Float32Array([scale[0], 0, 0, 0, 0, scale[1], 0, 0, 0, 0, scale[2], 0, translation[0], translation[1], translation[2], 1]);+ return { name, geometry, matrix, material: { tag: 'surface', color: [0.7, 0.7, 0.7], metallic: 0, roughness: 0.8, emission: 0, ...material } };+}++// A closed 6 m room; the mirror ball gives the probe test a reflective part.+function closedRoom() {+ return [+ placed('floor', cube, [0, -0.05, 0], [6, 0.1, 6]),+ placed('ceiling', cube, [0, 3.05, 0], [6, 0.1, 6]),+ placed('back', cube, [0, 1.5, -3.05], [6, 3.2, 0.1]),+ placed('left', cube, [-3.05, 1.5, 0], [0.1, 3.2, 6]),+ placed('right', cube, [3.05, 1.5, 0], [0.1, 3.2, 6]),+ placed('front', cube, [0, 1.5, 3.05], [6, 3.2, 0.1]),+ placed('mirror', ball, [1.5, 0.5, 0], [0.5, 0.5, 0.5], { metallic: 1, roughness: 0.05 }),+ ];+}++const window = { position: [0, 2.9, 0], direction: [0, -1, 0], up: [0, 0, 1], width: 1, height: 1, color: [1, 1, 1], intensity: 20 };+const bakeOptions = { samples: 8, bounces: 1, texelsPerUnit: 2, maxResolution: 32 };++function byteSum(bake) {+ return bake.parts.reduce((total, part) => total + (part.material.emissiveMap?.image.data.reduce((sum, byte) => sum + byte, 0) ?? 0), 0);+}++test('emittingAreaLights drops portals and keeps the order', () => {+ const lamp = { ...window, intensity: 3 };+ assert.deepEqual(emittingAreaLights([lamp, { ...window, portal: true }, lamp]), [lamp, lamp]);+ assert.deepEqual(emittingAreaLights(undefined), []);+});++test('a portal adds no light to a bake: a closed room with only a portal bakes like a room with no light', () => {+ const dark = byteSum(bakeLightmaps(closedRoom(), { keyColor: [0, 0, 0] }, bakeOptions));+ const portal = byteSum(bakeLightmaps(closedRoom(), { areaLights: [{ ...window, portal: true }], keyColor: [0, 0, 0] }, bakeOptions));+ const panel = byteSum(bakeLightmaps(closedRoom(), { areaLights: [window], keyColor: [0, 0, 0] }, bakeOptions));+ assert.equal(portal, dark);+ assert.ok(panel > portal * 2 + 1000, `a normal panel lights the room (${panel}) and a portal does not (${portal})`);+});++test('a portal beside a lamp leaves the lamp unchanged in the bake', () => {+ const lamp = { pointLights: [{ position: [-1.5, 2.5, 0], color: [1, 1, 1], intensity: 8, radius: 0.05 }], keyColor: [0, 0, 0] };+ const lampOnly = byteSum(bakeLightmaps(closedRoom(), lamp, bakeOptions));+ const withPortal = byteSum(bakeLightmaps(closedRoom(), { ...lamp, areaLights: [{ ...window, portal: true }] }, bakeOptions));+ assert.equal(withPortal, lampOnly);+});++test('object reflection probes do not see a portal as a lamp', () => {+ const trace = areaLights => traceObjectProbes(closedRoom(), { areaLights, keyColor: [0, 0, 0] }, { width: 32, samples: 8, bounces: 1 }).traced[0].data;+ const checksum = data => Array.from(data).reduce((sum, value) => sum + value, 0);+ const none = checksum(trace([]));+ assert.equal(checksum(trace([{ ...window, portal: true }])), none);+ assert.ok(checksum(trace([window])) > none, 'a normal panel brightens the probe');+});++test('the room bounce estimate counts a normal panel and not a portal', () => {+ const sky = createEnvironmentMap({ width: 8, height: 4, data: new Float32Array(8 * 4 * 3).fill(0.5) });+ const environment = areaLights => ({ map: sky, keyColor: [0, 0, 0], lightDirection: [0, 1, 0], areaLights });+ const room = closedRoom().slice(0, 6);+ const portalOnly = environment([{ ...window, portal: true }]);+ assert.equal(groundBounceEnvironment(room, portalOnly), portalOnly, 'a closed room with a portal has no light of its own to bounce');+ const lit = groundBounceEnvironment(room, environment([window]));+ assert.notEqual(lit, undefined);+ assert.ok(lit.map.bounce?.some(channel => channel > 0), 'a normal panel gives the walls a bounce colour');+});++test('strongestLights never names a portal as the light to turn down', () => {+ const lights = strongestLights({ keyIntensity: 1, areaLights: [{ intensity: 90, portal: true }, { intensity: 5 }] });+ assert.deepEqual(lights.map(light => light.field), ['environment.areaLights[1].intensity', 'environment.keyIntensity']);+});