3D engine that AI agents drive
Document light intensity units and the three.js conversion (#262)
Nguyen Xuan An3f6917cd2c9b
diff --git a/changes/262.md b/changes/262.mdnew file mode 100644index 00000000..8a96d51d--- /dev/null+++ b/changes/262.md@@ -0,0 +1 @@+- Document light intensity units and the three.js conversion (issue #262). `docs/agent-look.md` states the unit of the key, point, spot and area light intensities with a conversion table from three.js r155 and later, and `tests/light-units.test.js` ports one light of each kind with the table and checks the irradiance within 2 percent.diff --git a/docs/agent-look.md b/docs/agent-look.mdindex b4867c70..a73b1b4e 100644--- a/docs/agent-look.md+++ b/docs/agent-look.md@@ -130,6 +130,24 @@ Direction magnitude remains in the canonical recipe.The shadow projector uses its normalized direction, so changing only magnitude does not change shadow placement.High radiance can clip at the renderer's half-float HDR target limit of `65504` before bloom and tone mapping.+## Light units and three.js conversion++Every intensity is a linear scene value, not a photometric unit with its own scale.+For a white diffuse surface facing a light, the outgoing radiance is `intensity * color / PI`, the same as three.js r155 and later (`useLegacyLights` removed, physical units).+So a three.js light copies over with the factor below, and a scene lit by one light matches without tuning.+Compare at the same `exposure` (three.js `toneMappingExposure`), and note that 67js tone maps with an ACES-style curve only when `hdr` is off.++| 67js field | Unit | three.js light | Value to use |+| --- | --- | --- | --- |+| `keyColor * keyIntensity` | Irradiance on a surface facing the light, lux-like | `DirectionalLight.color * intensity` | Same value. Put the intensity in `keyIntensity` and keep `keyColor` in `0` to `1` |+| `pointLights[].intensity` | Candela-like: irradiance at distance `d` is `intensity / d^2` | `PointLight.intensity` | Same value. `range` is `distance` (the same smooth cutoff). Set `radius: 0.1` to match three.js's clamp of `d^2` at `0.01` |+| `spotLights[].intensity` | Candela-like, as a point light, scaled by the cone | `SpotLight.intensity` | Same value. `angle` is the same half angle in radians. `penumbra` fades in cosine here and in angle in three.js; both agree at `0` and `1` |+| `areaLights[].intensity` | Candela-like: on axis, far from the light, irradiance is `intensity / d^2`, and `intensity / (d^2 + width * height / PI)` in general | `RectAreaLight.intensity` (nits) | `nits * width * height` |+| `fillIntensity`, `ambientIntensity`, `environmentIntensity` | Unitless multipliers on the fill rig, the sky ambient and the setup's environment map | `AmbientLight`, `HemisphereLight`, `scene.environmentIntensity` | No exact equivalent. |++A three.js scene built before r155 with the legacy light model multiplies each of those intensities by `PI` to get the 67js value.+`tests/light-units.test.js` ports a directional, point, spot and area light this way and checks the irradiance each produces against the three.js formula within 2 percent.+## Lighting setupsA recipe with no lighting settings uses `daylight` (and no occlusion): a small procedural sky map (128 by 64, generated in code, no files or URLs) lights every surface and shows in metal and glossy reflections, with a warm key light for shadows.diff --git a/tests/light-units.test.js b/tests/light-units.test.jsnew file mode 100644index 00000000..308debd9--- /dev/null+++ b/tests/light-units.test.js@@ -0,0 +1,55 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { createLightingState, updateLightingState } from '../src/lighting.js';++// The conversion table in docs/agent-look.md: a three.js r155+ light copies over with these values.+// Both sides give the irradiance on a surface facing the light, as a white diffuse surface shows it (radiance = irradiance / PI).+const TOLERANCE = 0.02;+const DISTANCE = 10;++function assertWithinTolerance(actual, expected, label) {+ const relativeError = Math.abs(actual - expected) / expected;+ assert.ok(relativeError <= TOLERANCE, `${label}: ${actual} against ${expected}, ${(relativeError * 100).toFixed(2)} percent off`);+}++// three.js: DirectionalLight irradiance is intensity; Point, Spot and Rect area lights follow intensity / d^2 on axis (area: nits * area).+const threeJsDirectional = { intensity: 3.1 };+const threeJsPoint = { intensity: 120 };+const threeJsSpot = { intensity: 80 };+const threeJsArea = { nits: 40, width: 2, height: 0.5 };++function portedState() {+ const state = createLightingState();+ updateLightingState(state, {+ keyColor: [1, 1, 1],+ keyIntensity: threeJsDirectional.intensity,+ pointLights: [{ position: [0, DISTANCE, 0], intensity: threeJsPoint.intensity, radius: 0.1 }],+ spotLights: [{ position: [0, DISTANCE, 0], direction: [0, -1, 0], intensity: threeJsSpot.intensity, radius: 0.1, angle: 0.8 }],+ areaLights: [{ position: [0, DISTANCE, 0], direction: [0, -1, 0], width: threeJsArea.width, height: threeJsArea.height, intensity: threeJsArea.nits * threeJsArea.width * threeJsArea.height }],+ });+ return state;+}++// The engine's own formulas from src/shaders.js, read from the uniforms the lighting state fills, for a point at the origin facing up.+test('a ported three.js directional light gives the same irradiance', () => {+ assertWithinTolerance(portedState().keyColor[0], threeJsDirectional.intensity, 'directional');+});++test('a ported three.js point light gives intensity / d^2 at distance d', () => {+ const state = portedState();+ const engineIrradiance = state.colors[0] * state.colors[3] / Math.max(DISTANCE ** 2, state.radii[0] ** 2);+ assertWithinTolerance(engineIrradiance, threeJsPoint.intensity / DISTANCE ** 2, 'point');+});++test('a ported three.js spot light gives intensity / d^2 on its axis', () => {+ const state = portedState();+ const engineIrradiance = state.spotColors[0] * state.spotColors[3] / Math.max(DISTANCE ** 2, 0.1 ** 2);+ assertWithinTolerance(engineIrradiance, threeJsSpot.intensity / DISTANCE ** 2, 'spot');+});++test('a ported three.js rect area light with nits * width * height matches far from the light', () => {+ const state = portedState();+ const area = state.areaNormals[3] * state.areaTangents[3];+ const engineIrradiance = state.areaColors[0] * state.areaColors[3] / (DISTANCE ** 2 + area / Math.PI);+ assertWithinTolerance(engineIrradiance, threeJsArea.nits * threeJsArea.width * threeJsArea.height / DISTANCE ** 2, 'area');+});