3D engine that AI agents drive
Environment: derive the key light and shadow view from the HDRI sun (closes #555)
Nguyen Xuan An3021e556edd8
diff --git a/changes/555.md b/changes/555.mdnew file mode 100644index 00000000..2fdea95b--- /dev/null+++ b/changes/555.md@@ -0,0 +1 @@+- Add `sunFromEnvironmentMap(map)` and `keyLightFromHdri(map, bounds)` to the `@codepawlhq/67js/addons/hdri` addon (issue #555). They find the sun in an HDR map as a luminance-weighted centre, honour `rotation`, and return `lightDirection`, `keyColor`, `keyIntensity` and a `shadowBounds` view aimed along the sun over the scene bounds, or `null` for an overcast map. On Poly Haven san_giuseppe_bridge_4k with rotation pi the direction is within 0.05 degrees of the hand-tuned one. Core size does not change.diff --git a/docs/lighting.md b/docs/lighting.mdindex 5e2b12a5..70cb2c14 100644--- a/docs/lighting.md+++ b/docs/lighting.md@@ -49,6 +49,8 @@ const renderer = new Renderer67(canvas, parts, { hdr: true, environment: { map }`loadHdri(url, options)` fetches and parses a Radiance `.hdr` (RGBE, `-Y height +X width`, flat or run-length scanlines) and returns the descriptor. To build one from your own data, call `createEnvironmentMap({ width, height, data, intensity, rotation, showBackground, backgroundBlur })`, where `data` is a `Float32Array` of linear RGB or RGBA, top row first. The image centre looks toward -Z, `rotation` turns it about +Y in radians (0 to 1,000,000 as a finite number), `intensity` is 0 to 1000, `backgroundBlur` is 0 to 1.+`sunFromEnvironmentMap(map)` finds the sun in an outdoor map: the brightest 3 by 3 block, then the luminance-weighted centre of the pixels within 10 degrees of it that reach half its brightness. It returns `{ lightDirection, keyColor, keyIntensity }` with `rotation` applied, or `null` when the peak is under 20 times the mean luminance (overcast). `keyLightFromHdri(map, { min, max })` wraps it for a scene box and returns `{ environment: { lightDirection, keyColor, keyIntensity }, shadowBounds }`, so `new Renderer67(canvas, parts, { environment: { map, ...lit.environment }, shadowBounds: lit.shadowBounds })` gets sun shadows with no hand-tuned numbers. `keyIntensity` is an estimate (sun irradiance over pi); tune it by eye. On Poly Haven san_giuseppe_bridge_4k with `rotation` pi the direction is 0.04 degrees from the hand-tuned one.+Set `environment.map` in the constructor or in `frame.environment`. Maps spread from one created map, such as `{ ...map, rotation: time }`, reuse its GPU textures, so rotation animates for free. Passing a different map prefilters it on first use, and `map: null` returns to studio lighting. With no map the output is pixel-identical to before.When a map is set:diff --git a/src/hdri.js b/src/hdri.jsindex a065b380..9ff2310b 100644--- a/src/hdri.js+++ b/src/hdri.js@@ -105,3 +105,111 @@ export async function loadHdri(url, { intensity, rotation, showBackground, backg}export { createEnvironmentMap };++const SUN_PEAK_TO_MEAN_RATIO = 20;+const SUN_SEARCH_RADIUS = Math.PI / 18;++function luminanceAt(data, offset) {+ return 0.2126 * data[offset] + 0.7152 * data[offset + 1] + 0.0722 * data[offset + 2];+}++// Equirect pixel to a direction in the map's own frame (the inverse of the shader lookup, before `rotation`).+function mapDirection(column, row, width, height) {+ const azimuth = ((column + 0.5) / width - 0.5) * 2 * Math.PI;+ const polar = ((row + 0.5) / height) * Math.PI;+ return [Math.sin(polar) * Math.sin(azimuth), Math.cos(polar), -Math.sin(polar) * Math.cos(azimuth)];+}++// The shader turns a world direction into the map frame with a turn about +Y; this is the inverse.+function worldFromMapDirection([x, y, z], rotation) {+ const cosine = Math.cos(rotation);+ const sine = Math.sin(rotation);+ return [cosine * x + sine * z, y, -sine * x + cosine * z];+}++/**+ * Finds the sun in an HDR environment map: the brightest 3 by 3 block, then the luminance-weighted centre of the pixels+ * within 10 degrees of it that reach half its brightness, so a single hot pixel does not move it.+ * Returns `{ lightDirection, keyColor, keyIntensity }` (world direction toward the sun with `rotation` applied, colour+ * with its largest channel at 1, and `irradiance / PI` of the sun disc scaled by the map intensity), or `null` when the+ * peak is under 20 times the mean luminance, as on an overcast sky.+ */+export function sunFromEnvironmentMap(map) {+ const { width, height, channels, data } = map;+ const rowWeights = Float64Array.from({ length: height }, (_, row) => Math.sin(((row + 0.5) / height) * Math.PI));+ const luminance = new Float32Array(width * height);+ let weightedTotal = 0;+ for (let row = 0; row < height; row++) {+ for (let column = 0; column < width; column++) {+ const value = luminanceAt(data, (row * width + column) * channels);+ luminance[row * width + column] = value;+ weightedTotal += value * rowWeights[row];+ }+ }+ const meanLuminance = weightedTotal / (rowWeights.reduce((sum, weight) => sum + weight, 0) * width);++ let peakValue = 0;+ let peakColumn = 0;+ let peakRow = 0;+ for (let row = 1; row < height - 1; row++) {+ for (let column = 0; column < width; column++) {+ let blockSum = 0;+ for (let rowOffset = -1; rowOffset <= 1; rowOffset++) {+ for (let columnOffset = -1; columnOffset <= 1; columnOffset++) {+ blockSum += luminance[(row + rowOffset) * width + ((column + columnOffset + width) % width)];+ }+ }+ if (blockSum / 9 > peakValue) {+ peakValue = blockSum / 9;+ peakColumn = column;+ peakRow = row;+ }+ }+ }+ if (!(peakValue > SUN_PEAK_TO_MEAN_RATIO * meanLuminance)) return null;++ const peakDirection = mapDirection(peakColumn, peakRow, width, height);+ const minimumCosine = Math.cos(SUN_SEARCH_RADIUS);+ const pixelSolidAngle = ((2 * Math.PI) / width) * (Math.PI / height);+ const centre = [0, 0, 0];+ const colorSum = [0, 0, 0];+ let irradiance = 0;+ for (let row = 0; row < height; row++) {+ for (let column = 0; column < width; column++) {+ const value = luminance[row * width + column];+ if (value < peakValue * 0.5) continue;+ const direction = mapDirection(column, row, width, height);+ const cosine = direction[0] * peakDirection[0] + direction[1] * peakDirection[1] + direction[2] * peakDirection[2];+ if (cosine < minimumCosine) continue;+ const weight = value * rowWeights[row];+ for (let axis = 0; axis < 3; axis++) {+ centre[axis] += direction[axis] * weight;+ colorSum[axis] += data[(row * width + column) * channels + axis] * weight;+ }+ irradiance += value * rowWeights[row] * pixelSolidAngle * Math.max(cosine, 0);+ }+ }+ const length = Math.hypot(...centre);+ const brightest = Math.max(...colorSum);+ return {+ lightDirection: worldFromMapDirection(centre.map((component) => component / length), map.rotation),+ keyColor: colorSum.map((component) => component / brightest),+ keyIntensity: (irradiance * map.intensity) / Math.PI,+ };+}++/**+ * Lights a scene from the HDRI sun. Spread the result into the renderer's `environment` and pass its `shadowBounds`:+ * `{ environment: { lightDirection, keyColor, keyIntensity }, shadowBounds }`. The shadow view looks at the middle of+ * `bounds` ({ min, max }) from the sun side and covers its bounding sphere. Without a distinct sun it returns `null`,+ * so the caller keeps its defaults.+ */+export function keyLightFromHdri(map, bounds) {+ const sun = sunFromEnvironmentMap(map);+ if (!sun) return null;+ const target = bounds.min.map((minimum, axis) => (minimum + bounds.max[axis]) / 2);+ const extent = Math.max(Math.hypot(...bounds.max.map((maximum, axis) => maximum - bounds.min[axis])) / 2, 1e-3);+ const eye = target.map((component, axis) => component + sun.lightDirection[axis] * extent * 2);+ const { lightDirection, keyColor, keyIntensity } = sun;+ return { environment: { lightDirection, keyColor, keyIntensity }, shadowBounds: { target, eye, extent, near: extent * 0.5, far: extent * 3.5 } };+}diff --git a/tests/environment.test.js b/tests/environment.test.jsindex b051f463..b2fb5256 100644--- a/tests/environment.test.js+++ b/tests/environment.test.js@@ -134,3 +134,39 @@ test('direct light specular takes the same multiple scatter gain once per fragmeassert.equal(source.match(/directSpecularGain = multipleScatterGain/g).length, 1);assert.equal(source.match(/texture\(environmentBrdf/g).length, 2);});++test('sunFromEnvironmentMap finds a synthetic sun at a known direction with rotation applied', async () => {+ const { sunFromEnvironmentMap, keyLightFromHdri } = await import('../src/hdri.js');+ const width = 256;+ const height = 128;+ const sunRow = 40;+ const sunColumn = 70;+ const rotation = 1.1;+ const map = filledMap(width, height, (column, row) => {+ const nearSun = Math.abs(column - sunColumn) <= 2 && Math.abs(row - sunRow) <= 2;+ return nearSun ? [400, 320, 200] : [0.4, 0.5, 0.6];+ }, { rotation });+ const azimuth = ((sunColumn + 0.5) / width - 0.5) * 2 * Math.PI;+ const polar = ((sunRow + 0.5) / height) * Math.PI;+ const inMap = [Math.sin(polar) * Math.sin(azimuth), Math.cos(polar), -Math.sin(polar) * Math.cos(azimuth)];+ // The shader turns world into map by (cos x - sin z, y, sin x + cos z); the sun's world direction is the inverse turn.+ const expected = [Math.cos(rotation) * inMap[0] + Math.sin(rotation) * inMap[2], inMap[1], -Math.sin(rotation) * inMap[0] + Math.cos(rotation) * inMap[2]];+ const sun = sunFromEnvironmentMap(map);+ const dot = sun.lightDirection.reduce((sum, component, axis) => sum + component * expected[axis], 0);+ assert.ok(Math.acos(Math.min(1, dot)) < 0.01, 'within about half a degree');+ assert.equal(Math.max(...sun.keyColor), 1);+ assert.ok(sun.keyColor[2] < sun.keyColor[0]);+ assert.ok(sun.keyIntensity > 0);+ const lit = keyLightFromHdri(map, { min: [-1, 0, -1], max: [1, 2, 1] });+ assert.deepEqual(lit.shadowBounds.target, [0, 1, 0]);+ const toEye = lit.shadowBounds.eye.map((component, axis) => component - lit.shadowBounds.target[axis]);+ const eyeDot = toEye.reduce((sum, component, axis) => sum + component * sun.lightDirection[axis], 0) / Math.hypot(...toEye);+ assert.ok(eyeDot > 0.9999);+});++test('sunFromEnvironmentMap returns null for an overcast map', async () => {+ const { sunFromEnvironmentMap, keyLightFromHdri } = await import('../src/hdri.js');+ const map = filledMap(64, 32, (column, row) => [0.5 + row * 0.01, 0.5, 0.5]);+ assert.equal(sunFromEnvironmentMap(map), null);+ assert.equal(keyLightFromHdri(map, { min: [0, 0, 0], max: [1, 1, 1] }), null);+});