3D engine that AI agents drive
Ground bounce reads the mean albedo of a textured floor; terrain and foliage measured, not kept (part of #191)
Nguyen Xuan An53f8878f6aa9
diff --git a/bench/reference/README.md b/bench/reference/README.mdindex 1ba817c4..e20aed19 100644--- a/bench/reference/README.md+++ b/bench/reference/README.md@@ -1071,7 +1071,7 @@ Cause of the 10.7 percent gap on `brick-flat`, measured: light the ground bounceThe ground adds 0.0535 linear (22 percent of the wall's light) in Cycles. With bounces off, Cycles is 0.019 below 67js (display), so the sun units and colour, the sky irradiance on a vertical wall, Lambert against Principled diffuse and the tone map are not the cause: they leave 67js slightly bright. 67js lit the wall with the lower half of the sky HDRI, where Cycles has the floor.-Fix, derived from the scene and not set per scene: `groundBounceEnvironment(parts, environment)` (`src/ground-bounce.js`, `67js/addons/ground-bounce`) finds the floor (the lowest thin part that spans the scene, the same test as the automatic floor of agent scenes; a plain coloured, non-metal, opaque, untextured material gives its albedo; water and textured floors give none) and adds an `irradianceSource` to the environment map: a copy whose lower half is `albedo * (sun * max(l.y, 0) / pi + sky irradiance on a level surface)`. The renderer reads only the diffuse spherical harmonics from that copy (`environment.js`, two lines, plus the key of the prefilter cache in `renderer.js`), so the background, the reflections and the path tracer keep the real sky. The harness applies it to every scene; the agent preview applies it to every frame, with the colour of the automatic floor when no part forms one, and keeps the answer per parts array (`scripts/agent-preview-browser.js`; the browser preview itself was not driven here, only the stubbed page script in `tests/agent-preview.test.js`). It is skipped for a scene with a baked part (the light map already holds the bounce), a closed room (`closedRoomShare`, a bake or its own walls give that light), a point, spot or area light, no map, or `environment.groundBounce: false`; `--no-ground-bounce` draws the suite without it.+Fix, derived from the scene and not set per scene: `groundBounceEnvironment(parts, environment)` (`src/ground-bounce.js`, `67js/addons/ground-bounce`) finds the floor (the lowest thin part that spans the scene, the same test as the automatic floor of agent scenes; a plain coloured, non-metal, opaque, untextured material gives its albedo; water and a graph material give none; a textured floor gives its colour times the mean of its base-colour texture in linear space, found once per image) and adds an `irradianceSource` to the environment map: a copy whose lower half is `albedo * (sun * max(l.y, 0) / pi + sky irradiance on a level surface)`. The renderer reads only the diffuse spherical harmonics from that copy (`environment.js`, two lines, plus the key of the prefilter cache in `renderer.js`), so the background, the reflections and the path tracer keep the real sky. The harness applies it to every scene; the agent preview applies it to every frame, with the colour of the automatic floor when no part forms one, and keeps the answer per parts array (`scripts/agent-preview-browser.js`; the browser preview itself was not driven here, only the stubbed page script in `tests/agent-preview.test.js`). It is skipped for a scene with a baked part (the light map already holds the bounce), a closed room (`closedRoomShare`, a bake or its own walls give that light), a point, spot or area light, no map, or `environment.groundBounce: false`; `--no-ground-bounce` draws the suite without it.What the first version got wrong, kept for the next try: putting the bounced map in the sky itself (background and reflections too) made `brushed-film` 0.0739, `car-paint` 0.0688 and `metal` 0.0701 worse against Cycles, because the 40 m floor ends before the horizon and the band between the floor edge and the horizon showed the ground colour instead of the sky. A diffuse-only copy removes that. A scene lit by point, spot or area lights still got worse (`light-linking` +0.0059, `spot-area` +0.0056 with a 0.01 world): the term counts the sun and the sky only, so on a floor those lights brighten it takes light away from the lower half; those scenes are skipped now.@@ -1112,3 +1112,16 @@ Main reproduced `baseline.json` first on the stored arrays (`brick-flat` 0.1264,Cycles is 10.7% brighter than 67js and 9.8% brighter than EEVEE on the plain flat wall, with no texture at all, so most of the 0.524 against 0.466 on the brick faces (12.4%) is Cycles-only light, the same offset as in `brick-flat`'s score. Once the flat wall removes it, the face ratios are within 1.6% (0.852, 0.849, 0.838), which is the share the graph's colour path and noise statistics can own. Ramp stops and mix constants are linear on both sides (`element.color` in `render-blender.py` takes linear values and the bake writes `linearToSrgbByte`), the ramp is linear in both, and the Blender noise differs from the 67js one (stated in `render-blender.py`), so a 1.6% face offset cannot be traced further without a Blender run, which this pass did not have. Not changed.- Excess of the graph wall over its flat wall, the number #50 asks for: 67js 0.1518 - 0.1264 = 0.0254, EEVEE 0.0122, unchanged.++## Ground bounce on textured floors and terrain (2026-11-03, part of issue #191)++Main reproduced the GPU columns of `baseline.json` to four digits on the stored Cycles and EEVEE arrays first (GPU render and FLIP rescore of all 23 scenes; CPU renders were not redone, so the CPU columns are unchanged).++Which scenes the bounce skips (a temporary log of the reason in the harness, not kept): `local lights` for `temple-hall`, `lit-interior`, `metal-room`, `brick-room`, `spot-area`, `light-linking`; `closed room` for `dark-shaft`, `fog-room` and `foliage` (the leaf cards of the crown count as walls for the ray test); `no plain floor` for `mountain-valley` (a grid of terrain chunks, none spans the scene). No reference scene is skipped because its floor is textured, so that part is covered by unit tests only.++- Textured floor: the albedo is the material colour times the mean of the base-colour texture in linear space, found once per image. It changes no reference scene (the others are all re-scored equal to the baseline to four digits).+- `mountain-valley`, terrain with the mean vertex colour as albedo: 0.1769 to 0.1788 (worse by 0.0019). Scaled by the mean upward share of the normals (0.85 or so, a weaker bounce for sloped ground) it is 0.1871 (worse by 0.0102): the lower half gets darker, and the valley is darker than Cycles there already. Not kept; the terrain code was removed.+- `foliage`, bounce on by ignoring the cut-out leaf cards in the room test and by accepting a floor whose top sits in the lowest tenth of the scene (the roots reach 0.32 below it): 0.0979 to 0.0981, and the crown goes from 0.2000 to 0.2023 mean display luminance against Cycles 0.1763 (the same definition as above: green pixels in the top 62 percent of rows). The crown is already within 0.03 of Cycles, but the bounce moves it away. Not kept.++Nothing moved, so `baseline.json` is unchanged. `foliage` is still 0.0979 against EEVEE 0.0888, and the issue stays open.+Bundle size: `entry:ground-bounce` is 9451 bytes gzip (9318 before the texture mean, which adds 133 bytes), so its budget rose from 9330 to 9460.diff --git a/bench/size/budgets.json b/bench/size/budgets.jsonindex cbee5aa0..1d51c311 100644--- a/bench/size/budgets.json+++ b/bench/size/budgets.json@@ -31,7 +31,7 @@"entry:grass": 4400,"entry:clutter": 5300,"entry:light-bake": 28500,- "entry:ground-bounce": 9330,+ "entry:ground-bounce": 9460,"entry:path-tracer": 14600,"entry:texture-set": 900,"entry:agent-scene": 77810,diff --git a/changes/191-ground-bounce.md b/changes/191-ground-bounce.mdnew file mode 100644index 00000000..1eda98f3--- /dev/null+++ b/changes/191-ground-bounce.md@@ -0,0 +1 @@+- Ground bounce reads the mean of a floor's base-colour texture (linear space, once per image) instead of skipping textured floors (part of issue #191, which stays open): no reference scene has a textured floor, so no score moved; terrain and a bounce under the `foliage` crown were measured and worsened `mountain-valley` by 0.0019 and the crown by 0.002, so they are not kept (`bench/reference/README.md`).diff --git a/src/ground-bounce.js b/src/ground-bounce.jsindex cd9b7d97..b0c3f9bd 100644--- a/src/ground-bounce.js+++ b/src/ground-bounce.js@@ -8,6 +8,8 @@ const GROUND_SPAN_SHARE = 0.9const GROUND_THINNESS = 0.25const GROUND_LOWEST_TOLERANCE = 1e-3const GROUND_MAXIMUM_METALLIC = 0.5+// The display gamma stands for the sRGB curve: a mean albedo does not need its toe.+const DISPLAY_GAMMA = 2.2const EXCLUDED_TAGS = new Set(['liquid', 'foam', 'unlit', 'fire', 'smoke', 'floor'])function sceneBoundsOf(boundsList) {@@ -22,17 +24,44 @@ function sceneBoundsOf(boundsList) {return { minimum, maximum }}+// The mean of a base-colour texture in linear space, found once per image. Null for an image that is not raw RGBA bytes.+const textureMeans = new WeakMap()++function textureMeanAlbedo(map) {+ const image = map.image+ if (!image?.data || !(image.width > 0) || image.data.length < image.width * image.height * 4) {+ return null+ }+ if (!textureMeans.has(image)) {+ const exponent = map.colorSpace === 'linear' ? 1 : DISPLAY_GAMMA+ const sums = [0, 0, 0]+ const pixelCount = image.width * image.height+ for (let pixel = 0; pixel < pixelCount; pixel++) {+ for (let channel = 0; channel < 3; channel++) {+ sums[channel] += (image.data[pixel * 4 + channel] / 255) ** exponent+ }+ }+ textureMeans.set(image, sums.map(sum => sum / pixelCount))+ }+ return textureMeans.get(image)+}+function groundAlbedo(material) {- const tinted = !material.map && !material.graph && material.alphaMode !== 'blend' && !(material.transmission > 0) && !EXCLUDED_TAGS.has(material.tag)- if (!tinted || !Array.isArray(material.color) || (material.metallic ?? 0) > GROUND_MAXIMUM_METALLIC) {+ const surface = !material.graph && material.alphaMode !== 'blend' && !(material.transmission > 0) && !EXCLUDED_TAGS.has(material.tag)+ if (!surface || !Array.isArray(material.color) || (material.metallic ?? 0) > GROUND_MAXIMUM_METALLIC) {+ return null+ }+ const textureMean = material.map ? textureMeanAlbedo(material.map) : [1, 1, 1]+ if (!textureMean) {return null}- return material.color.slice(0, 3).map(channel => channel * (1 - (material.metallic ?? 0)))+ return material.color.slice(0, 3).map((channel, index) => channel * textureMean[index] * (1 - (material.metallic ?? 0)))}/**- * The floor of a scene as `{ albedo }`, or null: the lowest, thin part that spans the scene, when it is a plain- * coloured, non-metal, opaque surface. A textured floor, water and a scene without a floor give null.+ * The floor of a scene as `{ albedo }`, or null: the lowest, thin part that spans the scene, when its surface is a plain+ * or textured, non-metal, opaque colour. Water, a procedural graph material and a scene without a floor give null. A+ * texture's albedo is its mean in linear space times the material colour.*/export function findGroundSurface(parts) {if (parts.length < 2) {diff --git a/tests/ground-bounce.test.js b/tests/ground-bounce.test.jsindex 734d0f42..34abf761 100644--- a/tests/ground-bounce.test.js+++ b/tests/ground-bounce.test.js@@ -124,3 +124,22 @@ test('a point, spot or area light keeps the environment, as the term knows only}assert.ok(groundBounceEnvironment(openScene(), { ...environment, pointLights: [] }).map.irradianceSource);});++function textureOf(pixels, colorSpace = 'srgb') {+ return { image: { width: pixels.length, height: 1, data: new Uint8ClampedArray(pixels.flat()) }, colorSpace };+}++test('a textured floor gives its colour times the mean of the texture in linear space', () => {+ const checker = textureOf([[255, 255, 255, 255], [0, 0, 0, 255]]);+ const albedo = findGroundSurface(openScene({ ...GRASS, color: [1, 0.5, 0.25], map: checker })).albedo;+ [0.5, 0.25, 0.125].forEach((expected, index) => assert.ok(Math.abs(albedo[index] - expected) < 1e-6));+ const linearMiddle = textureOf([[128, 128, 128, 255]], 'linear');+ assert.ok(Math.abs(findGroundSurface(openScene({ ...GRASS, color: [1, 1, 1], map: linearMiddle })).albedo[0] - 128 / 255) < 1e-6);+});++test('the mean of a texture is found once per image', () => {+ const map = textureOf([[255, 255, 255, 255]]);+ findGroundSurface(openScene({ ...GRASS, map }));+ map.image.data.fill(0);+ assert.ok(findGroundSurface(openScene({ ...GRASS, map })).albedo[0] > 0.1);+});