3D Wood Lighting Scorecard

3D Wood Lighting Scorecard

Wood only looks like wood under one directional key raking across a dark room, so the grain, the shadow seam and the light shafts are lit by the same window, tone-mapped once at the end, and each is measured on the finished frame instead of judged by mood.

Verified stack: Three.js r169 (unpkg), WebGL2, GLSL patched into MeshPhysicalMaterial.onBeforeCompile, a half-float MSAA target and a hand-written ACES pass. The demo is demo.html; the numbers are references/.

Boundaries. This is the lighting-and-material layer for one lit interior. For sun shafts that must be cut by real trees and rooflines use 3d-sky-rays (screen-space occlusion); here the shafts are authored planes. For scanned or painted PBR maps, texel budgets and delivery use 3d-high-resolution-textures; here the wood is procedural from one shared 1024 noise field. For a bright rim on dark metal use 3d-specular-rim-glow; for glass use the studio-box ladder, not this. For the scoring habit alone use workflow-score-to-target; this skill supplies the wood rubric and the machine that measures it.

Extracted from Kibori (木彫), a scroll-driven WebGL woodworking page: its woodMat, buildEnvironment, key rig, shaft planes, dust and final pass are ported, with the window moved to where the shafts need it.

Build order

1. Renderer: NoToneMapping, LinearSRGBColorSpace, HalfFloatType target with samples: 4, autoClear = false. Draw everything, additive shafts and dust included, into that target. Tone-map once in a last full-screen pass.
2. One window. Put the emissive paper, the key light's direction, the shaft planes, and the window card in the PMREM environment on the same line. Nothing else.
3. Key DirectionalLight 0xfff2df, intensity 2.0, 4096 shadow map (2048 under 820 px), normalBias 0.0045 (0.0085 at 2048), bias -0.00025, shadowMap.autoUpdate = false for a static room. Let a real wall with a real opening cast: the pool of light on the bench is then the window's shape.
4. Fill 0xaec7df 0.60-0.76 from the camera side, rim 0xffdeb4 0.72 from behind, hemisphere 0xb5c5d7 / 0x35281c 0.19. These only keep the shaded flank alive; they are not the look.
5. Wood: MeshPhysicalMaterial ior 1.43, specularIntensity 0.72, roughness clamp(base * W.rough, 0.35, 1), procedural albedo/roughness/bump from one periodic noise field baked once (1024x1024 RGBA8, 64 cells, three octaves, mipmapped, repeat).
6. Shafts, then dust, then the last pass, then run references/scorecard.mjs.

Rules, each with the failure it prevents

Grain vanishes under flat light. A hemisphere or environment that is bright enough to see the room fills every pore and the board reads as painted. Keep the key at 2.0 and the ambient terms low; measured here, turning the studio reflections off raised the total score by 0.14 because they lifted the shadows. Per-material envMapIntensity 0.25 for the bench, 0.45 for the carved board, 0.40 default.

envMapIntensity does nothing and tuning "works" on paper. With three r163+ the material value is only read when material.envMap is set; scene.environment alone ignores it. Set mat.envMap = env on every wood material, and toggle a layer through the intensity, not by nulling the map (that recompiles).

The sheen mirrors a window that is not there. Kibori hung its environment window at front-left; a scene whose window is behind-left reflects a light that does not exist. Place the environment window pane group where the real window is (here (-2.3, 4.3, -3.2), scale 0.5, 12 panes 1.24x1.38 at radiance 3.8/3.55/3.05). Tilt the board so the mirror direction lands a little off the window (0.27 rad here; at exactly the mirror angle the whole board turns milky).

Volumetrics wash the blacks and the grain. Additive planes add light to everything behind them, including the top of the timber they cross. Fade each shaft by world height (smoothstep(0.02, 0.34, y)), keep the gain at 0.13 (Kibori 0.12) and the brightness above the reference strip under 35 levels, and read the black point: p1 must stay under 7. Before the height fade, gain 0.14 laid a milky haze across the plaque and the grain went with it.

A hard wedge where a shaft plane cuts a solid. The plane intersects the bench or the post and draws a bright line. Kibori kept planes behind the benches; the height fade above does it without moving them. Also clamp before pow: pow(1.0 - across, 2.2) with a hair-negative edge coordinate is NaN and NaN through additive blending is a black wedge.

God rays clip. If the renderer tone-maps, or the shaft pass is added after ACES, the beams either double-map or hit 1.0 flat. Sum them in linear HDR, then run ACES once (a=2.51 b=0.03 c=2.43 d=0.59 e=0.14). The window paper is toneMapped:false linear (1.15, 0.86, 0.52); at (3.9, 3.35, 2.55) it clipped to white paper.

Additive alpha. AdditiveBlending adds alpha too. On an opaque canvas it is invisible; if the scene is ever drawn into an alpha-composited layer, use CustomBlending with blendSrc One, blendDst One, blendSrcAlpha Zero, blendDstAlpha One.

Shadow acne on the bench, or a gap under the plaque. Acne comes from a small negative bias alone; use normalBias scaled to the map (0.0045 at 4096, 0.0085 at 2048). A gap between object and shadow (peter-panning) is normalBias too high. The scorecard reads it as contactGap. Add a baked contact pool under each object (radial alpha 0.78, r = 0.30..1.0 smoothstep, y 0.0012); the shadow map alone leaves the seam light.

A single-band texture shimmers at grazing angles. Fine bands (pores at 96/88 cycles per metre, fibres 230, rays 13/115) must fade with fwidth of their own coordinate, and the bump must give up before the colour does (1 - smoothstep(0.05, 0.18, vesselPx)), or dFdx(h) beats into moire. The scorecard's shimmer is a half-pixel view shift; 1.1 here, 3+ is aliasing.

A carved relief turns to noise. Grooves under 12 px per period alias in the bump and sparkle against a bright environment. The seigaiha carving here uses 0.15 m cells and two rings per circle (about 16 px at 1440 wide); at 0.062 m it was noise at 1x and fine at 2x. Size carving to the pixel budget, not the model.

Bricks in the grain. Medullary-ray flecks (rays) on a flat-sawn top face read as a tiled grid. Kibori's 0.8 default is for quartersawn faces; on the plaque it is 0, on others 0.15.

Banding in the dark wall. 8-bit steps in a vignetted gradient. A +-0.0015 hash dither ((hash - 0.5) * 0.003) after the sRGB encode removes it; the scorecard counts runs of 6+ identical pixels (flatRun 0.019).

The metric moves when the camera does. Freeze the sway and time (KiboriScore.freeze(true)), render and read the canvas in the same task (no preserveDrawingBuffer), capture at a fixed size and DPR, and use headless Chromium; the in-app pane backgrounds itself and shares the GPU.