Skip to content

armgit / 67.js

Public Imported from GitHub
0

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