Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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 setups
A 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.js
new file mode 100644
index 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');
+});