3D engine that AI agents drive
Bake a graph's normal map at twice the colour resolution (part of #50)
Nguyen Xuan Anfc4a57540bff
diff --git a/bench/reference/README.md b/bench/reference/README.mdindex 07f91da6..32bb4e76 100644--- a/bench/reference/README.md+++ b/bench/reference/README.md@@ -1694,3 +1694,42 @@ Blended water (a `water` part with opacity below one) now draws its own backgrouThe dark band at the foot of a shadow in the first preview was not a doubled shadow: the bed point takes its sun visibility once and the surface lift applies only to water fragments. Along the shadow the bed is even (green channel 0.178 to 0.173 at 1 m, 0.157 to 0.152 at 4 m, seen from above), and a close render shows no band. The band was the shaded side of the submerged post, which got darker with depth and had no scattered light, so it joined the shadow. The scattered light fixes it.The new preview uses Poly Haven CC0 assets (boulder_01, rock_07, modular_wooden_pier and the gravel_ground_01 material) read from `out/assets`, which is ignored by Git.++## The bump edge of a graph wall: normal map resolution (2026-11-04, part of issue #50, RTX 3060 960 x 540)++Main reproduced the stored rows first: `brick-graph` 0.0734, `brick-flat` 0.0556 against Cycles, excess 0.0178 against EEVEE's 0.0120 (EEVEE against Cycles 0.1249 and 0.1129).++Node level, Blender 5.2.2 headless against 67js, on the unit square of the brick wall (a 6 by 4 plane, Bump Distance 0.15, strength 1):++- Height: the translated Math, Map Range and Wave nodes baked to a float array by Cycles (EMIT, 2048 x 2048) against the graph's `height` at the same pixel centres: max difference 0.00029, mean 0.000023. The brick factor and the joint profile are the same, so the Brick Texture candidates (mortar size, smoothing, offset) are ruled out; the graph does not use Blender's Brick node.+- Bump: Cycles bake of the NORMAL pass (tangent space, Diffuse BSDF; with a Principled BSDF the baked normal is the average of the closure normals and the specular one is clamped, so it is not the bump normal) at 2048 x 2048. Its slope `-n.xy / n.z`, divided by Distance over the world size of each UV axis, equals the analytic derivative of the height to float precision (peak 299.7 against 296.0 per UV unit across a course joint, the difference being the analytic gradient's own 2048 grid). Blender differentiates the height at each pixel, so a joint edge about 2.6 texels wide at 512 loses nothing.+- 67js bakes `normalMapFromHeightFunction` at the colour resolution (512), the slope read half a texel either side (the step is right). Sampled bilinearly at the 2048 grid and compared with Blender's normal (the 67js slope is `bump / 32` per UV unit, Blender's `0.15 / L`, so the scale differs by 1.25 along U and 0.83 along V and is left in both rows): mean angle 3.51 degrees, mean Lambert difference for the sun 0.0340. At 1024 texels: 2.14 degrees, 0.0186. At 2048: 1.36 degrees, 0.0097. The cause is the texel size: bilinear filtering blends the unit normals of two texels, and a joint edge is a few texels wide, so the tilt of its middle pixels reads weaker than the analytic one.++Whole frame, FLIP against the stored Cycles array, `brick-graph` only (every variant rendered in one session, `brick-flat` is 0.0556 throughout):++| Normal map | Texels | Mips | `brick-graph` | Excess over `brick-flat` |+| --- | --- | --- | --- | --- |+| Colour resolution (before) | 512 | yes | 0.0734 | 0.0178 |+| Twice (kept) | 1024 | yes | 0.0714 | 0.0158 |+| Four times | 2048 | yes | 0.0705 | 0.0149 |+| Twice, `LINEAR` only | 1024 | no | 0.0694 | 0.0138 |+| Four times, `LINEAR` only | 2048 | no | 0.0690 | 0.0134 |+| Colour resolution, `LINEAR` only | 512 | no | 0.0728 | 0.0172 |++Kept: twice the colour resolution, capped at 1024 texels, with the default trilinear filter. The map without mips scores 0.002 better, but a normal map with no mips shimmers where the wall is far away, and the shader samples it once per pixel, so it was not kept. Four times costs 16.8 MB for a 512 pattern. The bake reads the height four times per texel; the brick wall's height costs 20 work units, so the finer map is 84 million units (0.35 s in Node, 81 ms before) against a new allowance of four times the graph limit, and a graph whose height is too costly keeps the colour resolution.++Tried and not kept (all at 2048 texels with mips unless stated; against Cycles):++| Variant | `brick-graph` |+| --- | --- |+| Blender's world scale (0.8 along U, 1.2 along V) | 0.0732 (from 0.0705) |+| U only 0.8 / V only 1.2 | 0.0728 / 0.0709 |+| U 1.25 / V 0.8 (the opposite) | 0.0697 / 0.0700 |+| Map shifted by a quarter or half a texel along V or U | 0.0704 to 0.0733 (no offset: 0.0705) |+| Sky lobe moved towards the geometric normal (blend 0.5 / 1 / 2, 1024 texels) | 0.0705 / 0.0714 / 0.0725 (no blend 0.0714) |++The world scale is the exact match to Blender and scores worse, and there is no offset between the two renders (the wall's top and bottom edges sit within 0.1 pixel). So what remains is not the normal.++Where the rest is, measured from the 2048 texel render by the sign of the bump slope at each pixel centre (display luminance, 67js minus Cycles): ledges that tilt up towards the sun are +0.046 and +0.057 too bright, ledges that tilt down -0.078 (gentle) and -0.022 (steep) too dark, and the vertical joints are +0.03 too bright on both sides. EEVEE is 0.27 off Cycles on every wall pixel, flat or not, because its flat wall is darker; 67js is 0.057 on the flat wall and 0.146 to 0.196 on the pixels at or next to a bump edge (0.0705 render; 0.0576 for the same pixels of `brick-flat`), which is where its excess sits. Which side is "up-tilted" is read from the sign of the slope (inferred). Cause (inferred, not isolated): Cycles removes the part of the lobe that falls below the geometric plane, which for an up-tilted ledge is the bright upper sky and for a down-tilted one the dark lower half, while the shader scales the whole sky term by one share. Moving the sky lookup towards the geometric normal helped by 0.0009 at best (table) and moved the render away from EEVEE, so it was not kept; it would also add to `scene:lit-box`.++After the change: `brick-graph` 0.0714 on the GPU (CPU render not redone), `brick-flat` 0.0556, excess 0.0158 against EEVEE's 0.0120. The first Done-when box of #50 stays open by 0.0038. Only `brick-graph` reads a graph with a height output among the suite's scenes (no other scene has a normal map from a graph), so no other scene's pixels changed and the full suite was not run.diff --git a/changes/50-bump.md b/changes/50-bump.mdnew file mode 100644index 00000000..ae089cc4--- /dev/null+++ b/changes/50-bump.md@@ -0,0 +1 @@+- Bake the normal map of a graph material at twice the colour resolution, up to 1024 texels (issue #50). A joint edge a few texels wide lost tilt to the bilinear blend of unit normals, 3.5 degrees on average against Blender's Bump node; at 1024 texels it is 2.1. `brick-graph` goes from 0.0734 to 0.0714 against Cycles (FLIP, RTX 3060); a graph whose height is too costly to read four times per texel at that size keeps the colour resolution. The map holds 4 times the texels (5.6 MB with mips for a 512 pattern, 1.4 MB before) and the bake takes about 4 times longer (0.35 s for the reference brick wall).diff --git a/changes/50-bump.size.md b/changes/50-bump.size.mdnew file mode 100644index 00000000..5d03649a--- /dev/null+++ b/changes/50-bump.size.md@@ -0,0 +1 @@+- scene:agent-scene+lazy: the graph bake picks a finer normal map size (per-output cost, resolution and work allowance), 112 bytes in the lazy graph code; scene:lit-box and scene:agent-scene do not growdiff --git a/src/material-graph.js b/src/material-graph.jsindex 96b81a1e..ee70a2fe 100644--- a/src/material-graph.js+++ b/src/material-graph.js@@ -377,11 +377,14 @@ export function compileMaterialGraph(graph) {if (names.length === 0) throw graphError(`graph needs at least one output: ${MATERIAL_GRAPH_OUTPUTS.join(', ')}.`);const state = { nodeCount: 0, cost: 0 };const outputs = {};+ const outputCosts = {};for (const name of names) {+ const costBefore = state.cost;outputs[name] = compileNode(graph[name], state, 0);+ outputCosts[name] = state.cost - costBefore;if (SCALAR_OUTPUTS.includes(name) && outputs[name].kind !== 'scalar') throw graphError(`${name} needs a number, not a vector.`);}- return { outputs, nodeCount: state.nodeCount, cost: state.cost };+ return { outputs, outputCosts, nodeCount: state.nodeCount, cost: state.cost };}/** Throw when a graph is too costly to bake at this size. Called while normalizing, so a bad scene fails at once. */@@ -415,6 +418,31 @@ function writeColor(data, offset, channels) {data[offset + 3] = 255;}+// A joint edge is a few texels wide, and bilinear filtering blends the unit normals of its texels, which rounds the edge+// off where Blender's Bump node differentiates the height at every pixel. Measured against Cycles (bench/reference/README.md,+// 2026-11-04) a normal map at twice the colour resolution halves the mean angle error of the wall's normals.+const NORMAL_MAP_RESOLUTION_FACTOR = 2;+const NORMAL_MAP_RESOLUTION_LIMIT = 1024;+// Four height reads per texel: half a texel either side along each axis. The work limit counts one evaluation per pixel of+// every output, and a height read is cheaper than a full graph pixel, so the finer map may cost four times that limit+// (the brick wall of the reference suite: 84 million units, about 0.35 s in Node).+const HEIGHT_READS_PER_NORMAL_TEXEL = 4;+const NORMAL_MAP_WORK_LIMIT = 4 * MATERIAL_GRAPH_LIMITS.maxWork;++/** The size of the baked normal map: finer than the colour, unless the height is too costly to read that often. */+function normalMapResolution(heightCost, resolution) {+ const finer = Math.min(resolution * NORMAL_MAP_RESOLUTION_FACTOR, NORMAL_MAP_RESOLUTION_LIMIT);+ const work = heightCost * HEIGHT_READS_PER_NORMAL_TEXEL * finer * finer;+ return finer > resolution && work <= NORMAL_MAP_WORK_LIMIT ? finer : resolution;+}++function bakeNormalMap(heightOutput, heightCost, resolution, bump) {+ const normalResolution = normalMapResolution(heightCost, resolution);+ const heightAt = (u, v) => finiteOrZero(heightOutput.evaluate(u, v));+ const normalData = normalMapFromHeightFunction(heightAt, normalResolution, bump);+ return { image: createImage(normalData, normalResolution, normalResolution), colorSpace: 'linear' };+}+/** Bake a normalized graph into texture descriptors, one for each output the graph has. Deterministic. */export function bakeMaterialGraph(graph, { resolution, bump }) {const compiled = compileMaterialGraph(graph);@@ -445,6 +473,6 @@ export function bakeMaterialGraph(graph, { resolution, bump }) {map: descriptor(colorData, 'srgb'),emissiveMap: descriptor(emissionData, 'srgb'),metallicRoughnessMap: descriptor(surfaceData, 'linear'),- normalMap: descriptor(height ? normalMapFromHeightFunction((u, v) => finiteOrZero(height.evaluate(u, v)), resolution, bump) : null, 'linear'),+ normalMap: height ? bakeNormalMap(height, compiled.outputCosts.height, resolution, bump) : undefined,};}diff --git a/tests/material-graph.test.js b/tests/material-graph.test.jsindex 388c58e1..059bb71d 100644--- a/tests/material-graph.test.js+++ b/tests/material-graph.test.js@@ -75,10 +75,10 @@ test('height becomes a normal map: flat height is a flat normal, relief tilts ittest('a height ramp tilts the normal by bump / 32 per UV unit at any resolution, the sign pointing downhill', () => {for (const resolution of [256, 512]) {const ramp = bakeMaterialPattern(normalizeMaterialPattern({ type: 'graph', graph: { height: { uv: 'u' } }, resolution, bump: 4 }));- const { data } = ramp.normalMap.image;+ const { data, width } = ramp.normalMap.image;const slope = 4 / 32;const length = Math.hypot(slope, 1);- const offset = (Math.floor(resolution / 2) * resolution + Math.floor(resolution / 2)) * 4;+ const offset = (Math.floor(width / 2) * width + Math.floor(width / 2)) * 4;assert.equal(data[offset], Math.round((-slope / length * 0.5 + 0.5) * 255));assert.equal(data[offset + 1], 128);assert.equal(data[offset + 2], Math.round((1 / length * 0.5 + 0.5) * 255));@@ -89,8 +89,24 @@ test('the slope of a sharp joint edge stays within one texel of the edge insteadconst resolution = 256;const step = { smoothstep: [0.5, 0.5 + 1 / resolution, { uv: 'u' }] };const edge = bakeMaterialPattern(normalizeMaterialPattern({ type: 'graph', graph: { height: step }, resolution, bump: 1 }));- const tiltedColumns = Array.from({ length: resolution }, (_, column) => column).filter(column => edge.normalMap.image.data[(10 * resolution + column) * 4] !== 128);- assert.ok(tiltedColumns.length <= 2, `${tiltedColumns.length} texels are tilted`);+ const { data, width } = edge.normalMap.image;+ const tiltedColumns = Array.from({ length: width }, (_, column) => column).filter(column => data[(10 * width + column) * 4] !== 128);+ const tiltedColorTexels = tiltedColumns.length * resolution / width;+ assert.ok(tiltedColorTexels <= 2, `${tiltedColumns.length} normal texels are tilted`);+});++test('the normal map is baked at twice the colour resolution, and at the colour resolution when the height is too costly for that', () => {+ const brick = bakeMaterialPattern(normalizeMaterialPattern(graphPattern()));+ assert.equal(brick.map.image.width, 256);+ assert.equal(brick.normalMap.image.width, 512);+ assert.equal(brick.normalMap.image.height, 512);+ const costly = { height: { add: [{ noise: { scale: 6, octaves: 6 } }, { noise: { scale: 9, octaves: 6, seed: 1 } }] } };+ const small = bakeMaterialPattern(normalizeMaterialPattern({ type: 'graph', graph: costly, resolution: 256 }));+ const large = bakeMaterialPattern(normalizeMaterialPattern({ type: 'graph', graph: costly, resolution: 512 }));+ assert.equal(small.normalMap.image.width, 512);+ assert.equal(large.normalMap.image.width, 512, 'twice 512 texels would be over the work limit for two six octave noises');+ const largest = bakeMaterialPattern(normalizeMaterialPattern({ type: 'graph', graph: { height: { uv: 'u' } }, resolution: 1024 }));+ assert.equal(largest.normalMap.image.width, 1024);});test('every graph texture node tiles across the seam', () => {