3D engine that AI agents drive
Document the lamp-lit room bounce, add the luminance and preview scripts and the size note (#351)
Nguyen Xuan Anc149239868bc
diff --git a/bench/reference/before-after-sheet.py b/bench/reference/before-after-sheet.pynew file mode 100644index 00000000..256a3c2f--- /dev/null+++ b/bench/reference/before-after-sheet.py@@ -0,0 +1,38 @@+# Writes a 960 px wide preview per scene: Cycles (top left), 67js before (top right) and 67js after (bottom left), with captions.+# uv run --no-project --python 3.12 --with pillow --with numpy python -I bench/reference/before-after-sheet.py <renders directory> <output directory> <scene id> [...]+# "Before" is the 67js panel of the committed sheet images/<scene id>.jpg; "after" is <renders directory>/<scene id>-gpu.png.+import os+import sys++from PIL import Image, ImageDraw++HEADER_HEIGHT = 22+PANEL_WIDTH = 480+PANEL_HEIGHT = 270+++def sheet_panels(scene_id):+ sheet = Image.open(os.path.join(os.path.dirname(os.path.abspath(__file__)), "images", f"{scene_id}.jpg")).convert("RGB")+ row_height = sheet.height // 2+ cycles = sheet.crop((0, HEADER_HEIGHT, PANEL_WIDTH, row_height))+ before = sheet.crop((0, row_height + HEADER_HEIGHT, PANEL_WIDTH, sheet.height))+ return cycles, before+++def captioned(picture, caption):+ panel = picture.resize((PANEL_WIDTH, PANEL_HEIGHT), Image.LANCZOS)+ ImageDraw.Draw(panel).text((8, 6), caption, fill=(255, 255, 255))+ return panel+++if __name__ == "__main__":+ renders, output, scene_ids = sys.argv[1], sys.argv[2], sys.argv[3:]+ os.makedirs(output, exist_ok=True)+ for scene_id in scene_ids:+ cycles, before = sheet_panels(scene_id)+ after = Image.open(os.path.join(renders, f"{scene_id}-gpu.png")).convert("RGB")+ sheet = Image.new("RGB", (PANEL_WIDTH * 2, PANEL_HEIGHT * 2), (20, 20, 20))+ sheet.paste(captioned(cycles, "Cycles"), (0, 0))+ sheet.paste(captioned(before, "67js before"), (PANEL_WIDTH, 0))+ sheet.paste(captioned(after, "67js after"), (0, PANEL_HEIGHT))+ sheet.save(os.path.join(output, f"{scene_id}.png"), optimize=True)diff --git a/changes/351.size.md b/changes/351.size.mdnew file mode 100644index 00000000..54344434--- /dev/null+++ b/changes/351.size.md@@ -0,0 +1,7 @@+- entry:core: the renderer adds a map's `bounce` colour to the first irradiance coefficient (one small method), which is what lets a lamp-lit room get its bounced light with no shader change and no cost per frame.+- entry:ground-bounce: the closed-room bounce estimate (exposed wall area, mean albedo, lamp flux) lives in the ground-bounce add-on, where the floor's bounce already is; it lifts lamp-lit rooms from about half to about the brightness of Cycles.+- scene:lit-box: carries the renderer method above.+- scene:gltf-box: carries the renderer method above.+- scene:gltf-box+lazy: carries the renderer method above.+- scene:agent-scene: carries the renderer method above and the second `scene_inspect` message for a closed room lit by lamps only, which names the bake preset.+- scene:agent-scene+lazy: same as scene:agent-scene.diff --git a/docs/lighting.md b/docs/lighting.mdindex d55f4d7f..eaec7d7d 100644--- a/docs/lighting.md+++ b/docs/lighting.md@@ -111,6 +111,23 @@ A point light costs about 0.04 to 0.05 ms and an area light about 0.04 ms at thi`node bench/lighting/frame-time.mjs gpu --each-light` draws the hall with 12 point and 7 area lights and again without each light in turn; every removal changes the picture (checked on the software rasterizer).+## Bounced light in a lamp-lit room++A closed room lit by point, spot or area lights gets the light its walls bounce without a bake and at no cost per frame. `groundBounceEnvironment(parts, environment)` (`67js/addons/ground-bounce`, the same call that adds the floor's bounce) finds the room with the closed-room ray test, measures the area of the faces that look at the middle of the scene and their mean albedo (colour times texture mean, per channel), and sets `bounce` on the environment map. With lamp flux `F` (point `4 pi I`, spot `2 pi (1 - cos angle) I`, area `pi I`, summed over the lamps inside the room), area `A` and albedo `rho`, the bounce is `0.8 * F / pi * rho / (A * (1 - rho))` in each colour channel, so red walls bounce red light. The renderer adds it to the diffuse light: it is one constant in the first irradiance coefficient, the map's data is shared, and a lamp that changes every frame rebuilds nothing. The 0.8 is fitted: at 1.0 `lit-interior` came out 10 percent brighter than Cycles.++It is left out when the scene has a bake (its light map holds the bounce), a sun (`keyColor` above zero or unset, as in `temple-hall` and `dark-shaft`, which already read lighter than Cycles in their shadows), no map, or `environment.roomBounce` is `false`. It is one average colour for the whole room, with no brighter corner beside a lamp and no colour bleeding next to a wall; a bake gives those, and `scene_inspect` names it (`closed-room-without-bake`, with the `standard` preset) for a closed room lit by lamps only.++Luminance of the 67js picture over Cycles (linear, whole frame and 20th percentile, `bench/reference/luminance-ratio.py`, GPU renders against the committed Cycles panels):++| Scene | Mean before | Mean after | p20 before | p20 after |+| --- | --- | --- | --- | --- |+| `lit-interior` | 0.51 | 0.98 | 0.33 | 1.00 |+| `metal-room` | 0.49 | 0.88 | 0.32 | 0.85 |+| `brick-room` | 0.57 | 0.86 | 0.37 | 0.95 |+| `temple-hall` | 0.97 | 0.97 | 1.62 | 1.64 |++The two `temple-hall` p20 values differ only by the rescaling of the picture (the scene has a sun, so no bounce is added). The outdoor shadow fill of the issue is not done.+## Local shadows`castShadow: true` on a point or spot light draws that light's depth into one shared atlas of 2048 x 3072 texels: 24 tiles of 512 x 512, a 24 MiB depth texture allocated on first use. A spot light takes one tile with a perspective view of `2 * angle + 4` degrees (170 at most). A point light takes six tiles, one per cube face, each 92 degrees wide. Lights are given tiles in order: point lights, then spot lights. A request for more than 24 tiles, for example five shadowed point lights, throws `RangeError` and changes nothing. So the most is four shadowed point lights, or for example two point lights and eight spot lights.