3D engine that AI agents drive
Default sunBounce to 3 and keep bounce lights off nearby surfaces (part of #462)
Nguyen Xuan Anff821121ec0c
diff --git a/changes/462.md b/changes/462.mdindex dc52b0da..ebd54ff2 100644--- a/changes/462.md+++ b/changes/462.md@@ -1 +1 @@-- Fix `environment.sunBounce` doing nothing in a sunlit room with a window opening and a garden outside it (issue #462). The room test started its rays from the middle of the scene's bounds, which a lawn and a hedge beside the window moved out of the room (share 0.50 against the 0.90 needed), so no patch lights were found and `sunBounce` 1 and 2 drew the same picture. `fittedClosedRoomShare` (`src/fitted-closed-room.js`, lazy) starts again from the middle of the parts near the rest and leaves out the heaviest parts when the scene is over 150,000 triangles, so scanned props no longer switch the test off; the core `closedRoomShare` and the inspect diagnostic are unchanged, and open scenes still do not count as rooms. The patch search now samples only the triangles a coarse first pass found sunlit and inside the room (a lawn took nearly all 20,000 samples before, leaving 149 in the room), and a patch's light stands at most half the free distance in front of it, so it cannot end up behind a wall. On the five reference halls `sunBounce` 1 moves the FLIP score against Cycles by -0.0027 to +0.0018 compared with no bounce (the first version: -0.0043 to +0.0022) and the picture around the lit patch toward Cycles; `sunBounce: 0` draws the same pixels as before the bounce existed and open scenes do not change. Numbers in `docs/lighting.md`.+- Fix `environment.sunBounce` doing nothing in a sunlit room with a window opening and a garden outside it (issue #462). The room test started its rays from the middle of the scene's bounds, which a lawn and a hedge beside the window moved out of the room (share 0.50 against the 0.90 needed), so no patch lights were found and `sunBounce` 1 and 2 drew the same picture. `fittedClosedRoomShare` (`src/fitted-closed-room.js`, lazy) starts again from the middle of the parts near the rest and leaves out the heaviest parts when the scene is over 150,000 triangles, so scanned props no longer switch the test off; the core `closedRoomShare` and the inspect diagnostic are unchanged, and open scenes still do not count as rooms. The patch search now samples only the triangles a coarse first pass found sunlit and inside the room (a lawn took nearly all 20,000 samples before, leaving 149 in the room), and a patch's light stands at most half the free distance in front of it, so it cannot end up behind a wall. On the five reference halls `sunBounce` 1 moves the FLIP score against Cycles by -0.0027 to +0.0018 compared with no bounce (the first version: -0.0043 to +0.0022) and the picture around the lit patch toward Cycles; `sunBounce: 0` draws the same pixels as before the bounce existed and open scenes do not change. The default is now 3 (it was 1; the value multiplies the fitted gain, 0 is off), a stronger look for a sun-lit room that sets no `environment.sunBounce`; a patch with less than 3 percent of the scene size of free space in front of it is left out, so no light stands close enough to a surface to draw a hard speck. Numbers in `docs/lighting.md`.diff --git a/changes/462.size.md b/changes/462.size.mdindex bc6ee2b1..6304fa4c 100644--- a/changes/462.size.md+++ b/changes/462.size.md@@ -1,2 +1,2 @@-- entry:floor-sky-visibility: +490 bytes gzip against main (17320 to 17810) for the closed-room test that ignores a garden and heavy props (`src/fitted-closed-room.js`) and the two-pass sampling in `src/sun-bounce.js`. The code loads only with the floor sky trace, in the same lazy chunk as the sun bounce. It is what makes `sunBounce` work in a sunlit room with a window and a lawn outside, which gave no lights at all before (`sunBounce` 1 and 2 drew the same picture).-- scene:agent-scene+lazy: +453 bytes gzip against main (371528 to 371981), the same lazy code; the core `scene:agent-scene` shrinks by 1 byte (103907 to 103906) and `scene:lit-box` and `scene:gltf-box` do not change.+- entry:floor-sky-visibility: +528 bytes gzip against main (17320 to 17848) for the closed-room test that ignores a garden and heavy props (`src/fitted-closed-room.js`) and the two-pass sampling in `src/sun-bounce.js`. The code loads only with the floor sky trace, in the same lazy chunk as the sun bounce. It is what makes `sunBounce` work in a sunlit room with a window and a lawn outside, which gave no lights at all before (`sunBounce` 1 and 2 drew the same picture).+- scene:agent-scene+lazy: about +490 bytes gzip against main (re-measured at the final commit), the same lazy code; the core `scene:agent-scene` shrinks by 1 byte (103907 to 103906) and `scene:lit-box` and `scene:gltf-box` do not change.diff --git a/docs/agent-look.md b/docs/agent-look.mdindex 32feeb55..0b164cb8 100644--- a/docs/agent-look.md+++ b/docs/agent-look.md@@ -110,7 +110,7 @@ Sky colors use display RGB, matching the renderer's existing environment contrac| `resolveCoplanar` | off | `'offset'` puts the smaller part of each coplanar pair (see the `coplanar-overlap` warning) on the next depth layer, drawn with a polygon offset; `false` or absent leaves parts as authored. Geometry never moves. Parts that set `decal` or `depthLayer` keep their own || `objectReflections` | on | Absent unless set. Each smooth metal part (`metallic` 0.5 or more, `roughness` 0.6 or less; at most 8 such parts) gets a reflection probe of the scene around it, so a chrome sphere shows the floor and its neighbours. `false` turns it off. Probes are traced at rest, so a part that moves reflects the scene as it started. `scene_inspect` names them in `reflections` || `floorSkyTrace` | on | Absent unless set. A closed room a sun lights gets the sky each floor texel sees traced into its floor (`applyFloorSkyVisibility`, strength 0.2), so shadowed floors under a roof or between walls get less world and sky light; it makes the dark end of halls closer to Cycles. Open scenes and rooms lit by lamps alone are left as they are. `false` turns it off; a value that is not a boolean is refused. It loads lazily with a recipe that names its sun (`keyColor` or `keyIntensity`), costs about 1 s of trace when the scene is built and adds triangles to the floor (0.1 to 0.4 ms per frame in the reference halls). |-| `sunBounce` | `1` | Absent unless set. A number of 0 or more. A closed room a sun lights gets a few point lights at its sunlit patches (`withSunBounce`, found when the scene is prepared), so the floor, walls and pillars around a patch are lit by the light it bounces and the far end of the room less. `0` turns it off and gives the look without it; `1` is fitted to Cycles; above `1` is stronger. A value that is not a number of 0 or more is refused. Open scenes and rooms with no sun are left as they are. It loads lazily with the sun, and the lights take up to 6 of the 16 point light slots. |+| `sunBounce` | `3` | Absent unless set. A number of 0 or more. A closed room a sun lights gets a few point lights at its sunlit patches (`withSunBounce`, found when the scene is prepared), so the floor, walls and pillars around a patch are lit by the light it bounces and the far end of the room less. `0` turns it off and gives the look without it; `3` is the default and `1` the gain fitted to the reference halls; above is stronger. A value that is not a number of 0 or more is refused. Open scenes and rooms with no sun are left as they are. It loads lazily with the sun, and the lights take up to 6 of the 16 point light slots. || `setup` | `daylight` | `daylight`, `overcast`, `sunset` or `studio`. See Lighting setups || `environmentIntensity` | `1` | `0` to `100`. Scales the setup's environment light and reflections || `environmentRotation` | `0` | `-100` to `100` radians around the vertical axis |diff --git a/docs/lighting.md b/docs/lighting.mdindex aeeb889b..9d7c1270 100644--- a/docs/lighting.md+++ b/docs/lighting.md@@ -136,7 +136,7 @@ A closed room a sun lights gets the light its sunlit patches send on, so the floThe room test is `fittedClosedRoomShare` (`src/fitted-closed-room.js`), not the core `closedRoomShare`: the core test shoots its rays from the middle of the scene's bounds, and a lawn and a hedge outside a window moved that point out of a reading-corner room (share 0.50, 0.90 needed), so no patch was found and `sunBounce` 1 and 2 drew the same picture. The fitted test also tries the middle of the parts near the rest (share 0.98 there), leaves out the heaviest parts when the scene has more than 150 000 triangles (scanned props no longer switch the test off), and still calls open ground and a lone solid open. The inspect diagnostic `closed-room-without-bake` keeps the core test.-`environment.sunBounce` is a number of 0 or more: 0 is off (the look before sun bounce existed, byte for byte: the pixels of all 6 scenes below match a tree without it), 1 is the default, above 1 is stronger. The 0.3 is fitted: at 0.6 `dark-shaft` came out brighter than Cycles around its patch (mean 1.19 times) and FLIP got worse by 0.01.+`environment.sunBounce` is a number of 0 or more: 0 is off (the look before sun bounce existed, byte for byte: the pixels of all 6 scenes below match a tree without it), 3 is the default, 1 is the gain fitted to Cycles on the reference halls (the tables below), above is stronger. The 0.3 is fitted: at 0.6 `dark-shaft` came out brighter than Cycles around its patch (mean 1.19 times) and FLIP got worse by 0.01.Luminance of the 67js picture over Cycles in the ring around the lit patch (mean and 20th percentile, linear, 480 x 270 panels of the committed Cycles sheets, patch = Cycles pixels above 0.35 of its 99.5th percentile, ring from 3 to 25 pixels away), and FLIP of the whole panel against Cycles (RTX 3060, `bench/reference/render-gpu.mjs --sun-bounce <n>`, scored on the 960 x 540 draws scaled to the panel):diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 483c8eb3..5f93c4cb 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -230,7 +230,7 @@ const environment = z.strictObject({lines: lines.nullable().optional(),objectReflections: z.boolean().optional().describe("false turns off reflection probes on smooth metal parts."),floorSkyTrace: z.boolean().optional().describe('false turns off the sky traced into floors of sun-lit closed rooms.'),- sunBounce: z.number().min(0).optional().describe('Sun bounce in a closed room: 0 off, 1 default.'),+ sunBounce: z.number().min(0).optional().describe('Sun bounce in a closed room: 0 off, 3 default.'),resolveCoplanar: z.union([z.literal('offset'), z.literal(false)]).optional().describe("'offset' biases the smaller part of each coplanar pair at draw time; false clears."),viewTransform: z.enum(VIEW_TRANSFORM_NAMES).optional().describe('Display transform, for example agx to compare with Blender.'),look: z.enum(LOOK_NAMES).nullable().optional().describe('Named look preset; null clears.'),diff --git a/src/sun-bounce.js b/src/sun-bounce.jsindex 5497e054..1eb5aaa8 100644--- a/src/sun-bounce.js+++ b/src/sun-bounce.js@@ -26,7 +26,10 @@ const CLUSTER_PASSES = 6;const LIFT_IN_RADII = 1;// Fitted against Cycles on the reference halls (docs/lighting.md); environment.sunBounce multiplies it.export const SUN_BOUNCE_GAIN = 0.3;-const MINIMUM_LIFT = 0.02;+// The strength a scene gets when it sets no `environment.sunBounce`.+export const DEFAULT_SUN_BOUNCE = 3;+// A light closer than this share of the scene to a surface blows up as 1/d^2 into a hard speck, so a patch with less free space in front is left out.+const MINIMUM_LIFT_SHARE = 0.03;const KEY_THRESHOLD = 1e-3;const EXCLUDED_TAGS = new Set(['liquid', 'foam', 'unlit', 'fire', 'smoke']);@@ -155,7 +158,7 @@ function clusterSamples(samples, count, scale) {return centres.map((centre, index) => samples.filter((sample, sampleIndex) => assignment[sampleIndex] === index)).filter(group => group.length > 0);}-function lightOfPatch(group, strength, tracer, probeOffset) {+function lightOfPatch(group, strength, tracer, probeOffset, sceneSize) {const flux = [0, 0, 0];const centre = [0, 0, 0];const facing = [0, 0, 0];@@ -174,7 +177,9 @@ function lightOfPatch(group, strength, tracer, probeOffset) {const middle = centre.map(component => component / weight);const radius = Math.sqrt(group.reduce((total, sample) => total + luminanceOf(sample.flux) * sample.point.reduce((sum, value, axis) => sum + (value - middle[axis]) ** 2, 0), 0) / weight);const freeDistance = probeOffset + tracer.trace(middle[0] + normal[0] * probeOffset, middle[1] + normal[1] * probeOffset, middle[2] + normal[2] * probeOffset, normal[0], normal[1], normal[2], Infinity, false).nearestDistance;- const lift = Math.max(Math.min(radius * LIFT_IN_RADII, freeDistance / 2), MINIMUM_LIFT);+ const minimumLift = sceneSize * MINIMUM_LIFT_SHARE;+ if (freeDistance / 2 < minimumLift) return null;+ const lift = Math.max(Math.min(radius * LIFT_IN_RADII, freeDistance / 2), minimumLift);// Spread over the half space in front of the patch: intensity = flux / (2 pi).const intensity = flux.map(channel => (strength * SUN_BOUNCE_GAIN * channel) / (2 * Math.PI));const peak = Math.max(...intensity, 1e-9);@@ -201,17 +206,17 @@ export function findSunBounceLights(parts, environment, { strength = 1, maximumLconst { samples, tracer } = sampled;if (samples.length === 0) return [];const sceneSize = Math.max(...[0, 1, 2].map(axis => Math.max(...samples.map(sample => sample.point[axis])) - Math.min(...samples.map(sample => sample.point[axis]))), 1e-3);- return clusterSamples(samples, maximumLights, sceneSize).map(group => lightOfPatch(group, strength, tracer, sceneSize * 1e-3));+ return clusterSamples(samples, maximumLights, sceneSize).map(group => lightOfPatch(group, strength, tracer, sceneSize * 1e-3, sceneSize)).filter(Boolean);}const lightsOfParts = new WeakMap();/**- * The environment with the sunlit patches' lights added to its point lights. `environment.sunBounce` (default 1) scales+ * The environment with the sunlit patches' lights added to its point lights. `environment.sunBounce` (default 3) scales* them; 0 returns the environment itself. The patches are found once for these parts and this sun and kept.*/export function withSunBounce(parts, environment) {- const strength = environment.sunBounce ?? 1;+ const strength = environment.sunBounce ?? DEFAULT_SUN_BOUNCE;if (strength <= 0 || !hasSun(environment)) return environment;const existing = environment.pointLights ?? [];const room = Math.min(SUN_BOUNCE_PATCH_LIGHTS, MAX_POINT_LIGHTS - existing.length);