3D engine that AI agents drive
Warn when the shadow view and the light direction disagree (#264)
Nguyen Xuan An1e736b628af1
diff --git a/changes/264.md b/changes/264.mdnew file mode 100644index 00000000..94905142--- /dev/null+++ b/changes/264.md@@ -0,0 +1 @@+- Warn when the shadow view and the light direction disagree (issue #264). A renderer whose `shadowBounds.eye` points 10 degrees or more away from `environment.lightDirection` now lists a `shadow-light-direction-mismatch` warning in `renderer.diagnostics`. `docs/agent-look.md` says the eye wins.diff --git a/docs/agent-look.md b/docs/agent-look.mdindex 5cc01249..b4867c70 100644--- a/docs/agent-look.md+++ b/docs/agent-look.md@@ -237,6 +237,8 @@ View, projection, and combined matrices must remain finite and nonsingular at FlLarge targets and short distances can fail these combined checks even when each field fits its individual range.Derived projectors do not automatically fit scene or fog bounds.+Recipes always derive the eye from `lightDirection`, so shadows follow the light. A custom adapter that passes its own `shadowBounds.eye` to the renderer overrides that: the eye decides where shadows fall, and `lightDirection` only moves the shading. When the two differ by 10 degrees or more, the renderer lists a `shadow-light-direction-mismatch` warning in `renderer.diagnostics`. Leave `eye` out of `shadowBounds` to make the shadow follow the light.+## Validation boundaryEvery object rejects unknown keys.diff --git a/src/frame-diagnostics.js b/src/frame-diagnostics.jsindex 907c4c70..03871236 100644--- a/src/frame-diagnostics.js+++ b/src/frame-diagnostics.js@@ -1,10 +1,32 @@+import { resolveShadowLight } from './shadow-light.js';+/*** Diagnostics for a frame that renders without error but not as asked. They use the shape of `agent-diagnostics.js`* (kind, severity, target, message, fix) and are read from `renderer.diagnostics`.*/+const SHADOW_DISAGREEMENT_DEGREES = 10;const NO_DIAGNOSTICS = Object.freeze([]);-export function frameDiagnostics({ depth, effects }) {+function angleBetweenDegrees(first, second) {+ const dot = first[0] * second[0] + first[1] * second[1] + first[2] * second[2];+ const lengths = Math.hypot(...first) * Math.hypot(...second);+ if (!(lengths > 1e-6)) return 0;+ return Math.acos(Math.max(-1, Math.min(1, dot / lengths))) * 180 / Math.PI;+}++function shadowDirectionProblem(world, lightDirection, shadowBounds) {+ const light = resolveShadowLight(world, lightDirection, shadowBounds);+ const towardShadowEye = light.eye.map((value, axis) => value - light.target[axis]);+ const degrees = angleBetweenDegrees(towardShadowEye, lightDirection);+ if (degrees < SHADOW_DISAGREEMENT_DEGREES) return null;+ return {+ kind: 'shadow-light-direction-mismatch', severity: 'warning', target: 'shadowBounds.eye',+ message: `shadowBounds.eye points ${Math.round(degrees)} degrees away from environment.lightDirection. The eye decides where shadows fall; lightDirection only moves the shading.`,+ fix: 'Remove shadowBounds.eye so the shadow follows lightDirection, or set lightDirection to the direction from shadowBounds.target to shadowBounds.eye.',+ };+}++export function frameDiagnostics({ world, depth, effects, lightDirection, shadowBounds }) {const problems = [];if (effects.ambientOcclusion > 0 && !depth) {problems.push({@@ -13,5 +35,9 @@ export function frameDiagnostics({ depth, effects }) {fix: 'Construct the renderer with depth: true, or set effects.ambientOcclusion to 0.',});}+ if (shadowBounds?.eye && lightDirection) {+ const problem = shadowDirectionProblem(world, lightDirection, shadowBounds);+ if (problem) problems.push(problem);+ }return problems.length ? problems : NO_DIAGNOSTICS;}diff --git a/src/renderer.js b/src/renderer.jsindex a6596908..1303eb0c 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -2028,7 +2028,7 @@ export class Renderer67 {// The shadow view follows the sun, so a moved sun redraws the map.const lightChanged = String(this.activeLightDirection) !== String(environment.lightDirection);this.activeLightDirection = environment.lightDirection;- this.diagnostics = frameDiagnostics({ depth: this.depth, effects });+ this.diagnostics = frameDiagnostics({ world: this.world, depth: this.depth, effects, lightDirection: environment.lightDirection, shadowBounds: this.shadowBounds });const start = performance.now();const context = this.context;this.beginGpuTiming();diff --git a/tests/frame-diagnostics.test.js b/tests/frame-diagnostics.test.jsindex eed686f0..7007412d 100644--- a/tests/frame-diagnostics.test.js+++ b/tests/frame-diagnostics.test.js@@ -11,6 +11,25 @@ test('ambient occlusion on a renderer without depth gets a named warning', () =>assert.match(problems[0].fix, /depth: true/);});+const quietEffects = resolveEffects({});++test('a shadow eye 10 degrees or more off the light direction gets a named warning', () => {+ const lightDirection = [0, 1, 0];+ const twelveDegrees = 12 * Math.PI / 180;+ const shadowBounds = { target: [0, 0, 0], eye: [0, 50 * Math.cos(twelveDegrees), 50 * Math.sin(twelveDegrees)] };+ const problems = frameDiagnostics({ world: false, depth: true, effects: quietEffects, lightDirection, shadowBounds });+ assert.equal(problems.length, 1);+ assert.equal(problems[0].kind, 'shadow-light-direction-mismatch');+ assert.match(problems[0].message, /12 degrees/);+});++test('a shadow eye that follows the light, or no eye at all, is silent', () => {+ const lightDirection = [-3, 6, 4];+ const aligned = { target: [0, 0, 0], eye: [-6, 12, 8] };+ assert.deepEqual(frameDiagnostics({ world: false, depth: true, effects: quietEffects, lightDirection, shadowBounds: aligned }), []);+ assert.deepEqual(frameDiagnostics({ world: false, depth: true, effects: quietEffects, lightDirection, shadowBounds: { extent: 5 } }), []);+});+test('ambient occlusion with depth, or switched off, is silent', () => {assert.deepEqual(frameDiagnostics({ depth: true, effects: resolveEffects({ ambientOcclusion: 0.6 }) }), []);assert.deepEqual(frameDiagnostics({ depth: false, effects: resolveEffects({ ambientOcclusion: 0 }) }), []);