3D engine that AI agents drive
Merge origin/main into feat/652-review-diagnostics
Nguyen Xuan An0dd977b1a676
diff --cc changes/652.mdindex a8a12554,00000000..78e2fd7fmode 100644,000000..100644--- a/changes/652.md+++ b/changes/652.md@@@ -1,1 -1,0 +1,1 @@@- - scene_review, scene_look and the render result warn, with a field and a value to try, on an empty frame (`empty-frame`), a subject out of frame or too small (`subject-out-of-frame`, `subject-too-small`), a black or clipped frame (`exposure-black`, `exposure-clipped`) and a bake that no longer matches the lights or parts drawn (`bake-stale`, after a motion seek moves a light or a part). They arrive in the frame's `diagnostics`, and a render job keeps one entry per warning in its result metrics (#652, #603)++- scene_review, scene_look and the render result warn, with a field and a value to try, on an empty frame (`empty-frame`), a subject out of frame or too small (`subject-out-of-frame`, `subject-too-small`) and a black or clipped frame (`exposure-black`, `exposure-clipped`). The `bake-stale` warning of #603 now also arrives in a look, a review shot and a render job's metrics, not only in scene_inspect. They are in the frame's `diagnostics`, and a render job keeps one entry per warning (#652)diff --cc changes/652.size.mdindex db544436,00000000..29afeaacmode 100644,000000..100644--- a/changes/652.size.md+++ b/changes/652.size.md@@@ -1,3 -1,0 +1,3 @@@- - scene:agent-scene: worldBounds and bakeStaleness (277 bytes gzip) let the preview tell an agent that a frame is empty, framed wrong or lit by a stale bake, which it otherwise finds only by reading the image.- - scene:agent-scene+lazy: the checks, the fingerprint and the stale-bake comparison (742 bytes gzip in all, most of it in the lazy bake module) are the same agent-facing diagnostics.- - goal:agent-scene: 277 bytes for two small scene reads that frame, stale-bake and empty-frame warnings need; the sphere and luminance math sits outside the scene bundle.++- scene:agent-scene: worldBounds and a bakeStaleness alias (183 bytes gzip) let the preview tell an agent that a frame is empty or framed wrong, which it otherwise finds only by reading the image.++- goal:agent-scene: 183 bytes for one small scene read that the empty-frame and out-of-frame warnings need; the sphere and luminance math sits outside the scene bundle.++- scene:agent-scene+lazy: the measured growth against the recorded base (3556 bytes gzip) is mostly the merged main work of #603 and #543; this change adds the framing and exposure checks (about 1.1 KB, outside the scene bundle) and the 183 bytes above.diff --cc src/agent-scene.jsindex b6884c4c,7dda81a6..4921eecd--- a/src/agent-scene.js+++ b/src/agent-scene.js@@@ -1531,29 -1542,6 +1542,25 @@@ export function createAgentScene(inputconst environment = structuredClone(state.recipe.environment);return state.movedLook ?agentSceneModule('motion').motionEnvironment(environment, state.movedLook) : environment;},+ /** World bounds ({ name, min, max }) of the visible mesh parts in the current pose; parts with no known bounds are left out. */+ worldBounds() {+ const bounds = [];+ // A bake or a skin replaces a drawn part's geometry, so the bounds come from the part as built, in the drawn pose.+ const drawnParts = new Map(state.restParts.map(part => [part.name, part]));+ for (const sourcePart of state.sourceRestParts) {+ const part = drawnParts.get(sourcePart.name);+ const local = state.localBounds.get(sourcePart.geometry);+ if (!part || !local || part.visibility?.visible === false) continue;+ const positions = [];+ for (let corner = 0; corner < 8; corner++) {+ positions.push(corner & 1 ? local.max[0] : local.min[0], corner & 2 ? local.max[1] : local.min[1], corner & 4 ? local.max[2] : local.min[2]);+ }+ bounds.push({ name: part.name, ...boundsFor({ positions }, part.matrix) });+ }+ return bounds;+ },- /** Warnings when the sampled lights or part poses no longer match what the last bake lit; empty without a bake. */- bakeStaleness() {- if (!state.bakeInputs) return [];- const matrices = new Map(state.restParts.map(part => [part.name, part.matrix]));- return agentSceneModule('bake').staleBakeProblems({ baked: state.bakeInputs, current: { environment: this.environment, matrices } });- },++ /** The bake-stale warning, or none: see `staleBakeProblems` in `agent-bake.js`. */++ bakeStaleness: staleBakeProblems,get postPasses() {return structuredClone(state.recipe.postPasses ?? []);},diff --cc tests/frame-checks.test.jsindex c240d329,00000000..6200cbc4mode 100644,000000..100644--- a/tests/frame-checks.test.js+++ b/tests/frame-checks.test.js@@@ -1,114 -1,0 +1,113 @@@+import './support/load-agent-scene-modules.mjs';+import assert from 'node:assert/strict';+import test from 'node:test';+import { createAgentScene } from '../src/agent-scene.js';+import { exposureProblems, framingProblems, lumaShares, mergeFrameDiagnostics } from '../src/frame-checks.js';+import { closedRoom, closedRoomWithoutBake } from './support/agent-bake-rooms.mjs';++function sceneWithCamera(camera) {+ return {+ format: '67js.scene', schemaVersion: 1,+ geometries: [{ id: 'box', type: 'box' }],+ materials: [{ id: 'red', color: [0.8, 0.2, 0.2] }],+ nodes: [{ id: 'cube', geometry: 'box', material: 'red' }],+ camera,+ };+}++function framingOf(recipe) {+ const scene = createAgentScene(recipe);+ return framingProblems({ camera: scene.camera, aspect: 1, boxes: scene.worldBounds() });+}++function kinds(problems) {+ return problems.map(problem => problem.kind);+}++test('a subject in view gives no framing warning', () => {+ assert.deepEqual(framingOf(sceneWithCamera({ eye: [3, 2, 4], target: [0, 0, 0], fov: 45 })), []);+ assert.deepEqual(framingOf(closedRoom()), []);+});++test('a scene with no parts is an empty frame and says what to add', () => {+ const problems = framingOf({ ...sceneWithCamera({}), nodes: [] });+ assert.deepEqual(kinds(problems), ['empty-frame']);+ assert.match(problems[0].fix, /add-node/);+});++test('a camera that looks away from the subject names a camera.target and camera.eye that frame it', () => {+ const problems = framingOf(sceneWithCamera({ eye: [3, 2, 4], target: [30, 2, -40], fov: 45 }));+ assert.deepEqual(kinds(problems), ['subject-out-of-frame']);+ assert.match(problems[0].fix, /camera\.target to \[0,0,0\].*camera\.eye to \[/);+});++test('a subject far away fills so little of the frame that it is called too small', () => {+ const problems = framingOf(sceneWithCamera({ eye: [0, 0, 400], target: [0, 0, 0], fov: 45, far: 2000 }));+ assert.deepEqual(kinds(problems), ['subject-too-small']);+});++test('hidden parts do not count and orthographic cameras are not judged', () => {+ const hidden = sceneWithCamera({ eye: [3, 2, 4], target: [0, 0, 0] });+ hidden.nodes[0].visible = false;+ assert.deepEqual(kinds(framingOf(hidden)), ['empty-frame']);+ assert.deepEqual(framingOf(sceneWithCamera({ eye: [3, 2, 4], target: [30, 2, -40], projection: 'orthographic' })), []);+});++function frameOf(luma, count = 100) {+ return new Uint8Array(count * 4).fill(luma);+}++test('exposure warns on a black or clipped frame and not on a normal one', () => {+ const black = exposureProblems({ shares: lumaShares(frameOf(0)), exposure: 1 });+ assert.deepEqual(kinds(black), ['exposure-black']);+ assert.match(black[0].fix, /effects\.exposure from 1 to 4/);+ const white = exposureProblems({ shares: lumaShares(frameOf(255)), exposure: 1 });+ assert.deepEqual(kinds(white), ['exposure-clipped']);+ assert.match(white[0].fix, /effects\.exposure from 1 to 0\.5/);+ assert.deepEqual(exposureProblems({ shares: lumaShares(frameOf(120)), exposure: 1 }), []);+ const mostlyMid = frameOf(120);+ mostlyMid.fill(255, 0, 40);+ assert.deepEqual(exposureProblems({ shares: lumaShares(mostlyMid), exposure: 1 }), []);+});++function lightMoves() {+ return closedRoom({ motion: { duration: 2, loop: false, tracks: [+ { kind: 'light', id: 'point:0', property: 'position', keyframes: [{ time: 0, value: [0, 2.7, 0] }, { time: 2, value: [1, 2.7, 0] }] },+ ] } });+}++test('an unchanged baked scene gives no stale warning at the rest pose', () => {+ assert.deepEqual(createAgentScene(closedRoom()).bakeStaleness(), []);+ const scene = createAgentScene(lightMoves());+ scene.sampleMotion(0);+ assert.deepEqual(scene.bakeStaleness(), []);+ assert.deepEqual(createAgentScene(closedRoomWithoutBake()).bakeStaleness(), []);+});++test('moving a light after a bake gives bake-stale with the fix', () => {+ const scene = createAgentScene(lightMoves());+ scene.sampleMotion(2);+ const problems = scene.bakeStaleness();+ assert.deepEqual(kinds(problems), ['bake-stale']);- assert.match(problems[0].fix, /motionTime to null/);++ assert.match(problems[0].fix, /bake.rebake/);+ scene.sampleMotion(null);+ assert.deepEqual(scene.bakeStaleness(), []);+});+- test('moving a part after a bake names the part', () => {++test('moving a part after a bake gives bake-stale', () => {+ const scene = createAgentScene(closedRoom({ motion: { duration: 2, loop: false, tracks: [+ { kind: 'node', id: 'block', property: 'translation', keyframes: [{ time: 0, value: [-0.7, 0.6, -0.4] }, { time: 2, value: [0.5, 0.6, -0.4] }] },+ ] } }));+ scene.sampleMotion(2);+ const problems = scene.bakeStaleness();+ assert.deepEqual(kinds(problems), ['bake-stale']);- assert.match(problems[0].message, /block moved/);+});++test('job metrics keep one entry per warning across frames', () => {+ const metrics = {};+ const warning = { kind: 'exposure-black', target: 'effects.exposure', message: 'm', fix: 'f' };+ mergeFrameDiagnostics(metrics, [warning]);+ mergeFrameDiagnostics(metrics, [{ ...warning }]);+ mergeFrameDiagnostics(metrics, undefined);+ assert.equal(metrics.diagnostics.length, 1);+});