Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Skip enclosure overlaps and keep part-outside-frame out of render jobs (#905)

Nguyen Xuan Ane283f05cafac
diff --git a/docs/mcp.md b/docs/mcp.md
index a16bc2c0..30991f4d 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -171,8 +171,8 @@ Every tool schema is read on every turn, so `node scripts/measure-tool-cost.mjs`
| kind | fields | meaning |
| --- | --- | --- |
| `floating-node` | `nodes`, `gapMeters`, `nearest` | The part is more than 2 cm from every other part and from the floor level (the lowest point of the scene). `nearest` is the closest part or `floor`. |
-| `intersecting-nodes` | `nodes`, `penetrationMeters` | The bounds of two parts overlap by 2 cm or more on every axis. Bounds are axis aligned, so a rotated part can report an overlap its surface does not have; a part sunk into the ground is reported too. |
-| `part-outside-frame` | `nodes`, `outsideCount`, `partCount` | Parts whose bounding sphere is outside the camera frustum or behind the camera. When more than half are outside, `subject-out-of-frame` is returned with the same fields instead. |
+| `intersecting-nodes` | `nodes`, `penetrationMeters` | The bounds of two parts overlap by 2 cm or more on every axis. Bounds are axis aligned, so a rotated part can report an overlap its surface does not have; a part sunk into a small ground is reported too. A pair is skipped when one box covers the other's footprint and is 20 times its volume and 10 times its longest side (a terrain, room or bowl whose bounds enclose what rests in it). |
+| `part-outside-frame` | `nodes`, `outsideCount`, `partCount` | Parts whose bounding sphere is outside the camera frustum or behind the camera. When more than half are outside, `subject-out-of-frame` is returned with the same fields instead. Only `scene_look` reports `part-outside-frame` and the two placement kinds; render jobs keep one `subject-out-of-frame` entry however the count changes. |
| `exposure-clipped`, `exposure-black` | `whitePercent`, `blackPercent` | Share of a 64 by 64 copy of the frame that is clipped to white (35 percent or more) or black (98 percent or more) after tone mapping. |
The checks run on part bounds and on that small copy of the frame, so they cost almost nothing. Scenes of over 256 parts get no floating or intersection findings. `src/frame-checks.js` holds them.
diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.js
index 34fea5db..197b4468 100644
--- a/scripts/agent-preview-browser.js
+++ b/scripts/agent-preview-browser.js
@@ -191,7 +191,7 @@ function viewProblems(record, camera, exposure, { placement = false } = {}) {
const problems = [];
const boxes = record.scene.worldBounds?.();
if (boxes) {
- problems.push(...framingProblems({ camera, aspect: canvas.width / canvas.height, boxes }));
+ problems.push(...framingProblems({ camera, aspect: canvas.width / canvas.height, boxes, reportPartsOutside: placement }));
if (placement) problems.push(...placementProblems({ boxes }));
}
if (record.scene.bakeStaleness) problems.push(...record.scene.bakeStaleness());
diff --git a/src/frame-checks.js b/src/frame-checks.js
index ea51d588..5808b5b5 100644
--- a/src/frame-checks.js
+++ b/src/frame-checks.js
@@ -80,10 +80,10 @@ function framingSuggestion(camera, boxes, tangent) {
}
/**
- * Warnings for where the camera points. `boxes` are world bounds ({ min, max }) of the visible parts; a camera that is
+ * Warnings for where the camera points. `reportPartsOutside` adds `part-outside-frame`, which only scene_look reports. `boxes` are world bounds ({ min, max }) of the visible parts; a camera that is
* orthographic or shifted gets none, because the frustum test below assumes a centered perspective view.
*/
-export function framingProblems({ camera, aspect, boxes }) {
+export function framingProblems({ camera, aspect, boxes, reportPartsOutside = true }) {
const tangent = halfHeightTangent(camera, aspect);
if (!tangent) return [];
if (boxes.length === 0) {
@@ -125,7 +125,7 @@ export function framingProblems({ camera, aspect, boxes }) {
`${framingSuggestion(camera, visibleBoxes, tangent)} to fill the frame, or lower camera.fov.`,
{ heightPercent: Math.round(radius / (depth * tangent) * 100) })];
}
- if (outside.length > 0) {
+ if (reportPartsOutside && outside.length > 0) {
return [warning('part-outside-frame', 'camera',
`${outside.length} of ${boxes.length} parts are outside the camera frustum, so the picture does not show them.`,
`Move them into view with scene_apply set-node, or ${framingSuggestion(camera, boxes, tangent)} to put every part in view.`,
@@ -169,6 +169,8 @@ export function exposureProblems({ shares, exposure }) {
const FLOATING_GAP = 0.02;
const MINIMUM_PENETRATION = 0.02;
const MAXIMUM_PAIR_PARTS = 256;
+const ENCLOSURE_VOLUME_RATIO = 20;
+const ENCLOSURE_SIDE_RATIO = 10;
const MAXIMUM_PLACEMENT_FINDINGS = 8;
/** Distance between two boxes along each axis; 0 where they touch or overlap on that axis. */
@@ -182,6 +184,29 @@ function axisPenetrations(first, second) {
return depths.every(depth => depth > 0) ? depths : null;
}
+function volumeOf(box) {
+ return [0, 1, 2].reduce((volume, axis) => volume * (box.max[axis] - box.min[axis]), 1);
+}
+
+function coversFootprint(outer, inner) {
+ return [0, 2].every(axis => outer.min[axis] <= inner.min[axis] && outer.max[axis] >= inner.max[axis]);
+}
+
+function longestSide(box) {
+ return Math.max(...[0, 1, 2].map(axis => box.max[axis] - box.min[axis]));
+}
+
+/**
+ * One box covers the other's footprint and is 20 times its volume and 10 times its longest side or more: a terrain, a
+ * hollow room or a bowl whose bounds enclose what rests in it, even where a tree pokes through the top. Two crates sunk into each other, or a cup half inside a table, are not enclosures.
+ */
+function isEnclosure(first, second) {
+ const [larger, smaller] = volumeOf(first) >= volumeOf(second) ? [first, second] : [second, first];
+ return coversFootprint(larger, smaller)
+ && volumeOf(larger) >= ENCLOSURE_VOLUME_RATIO * volumeOf(smaller)
+ && longestSide(larger) >= ENCLOSURE_SIDE_RATIO * longestSide(smaller);
+}
+
function droppedCount(total) {
return total > MAXIMUM_PLACEMENT_FINDINGS ? { droppedCount: total - MAXIMUM_PLACEMENT_FINDINGS } : {};
}
@@ -206,7 +231,7 @@ export function placementProblems({ boxes }) {
const gap = Math.hypot(...axisGaps(box, other));
if (gap < nearest.gap) nearest = { gap, name: other.name };
const penetrations = otherIndex > index ? axisPenetrations(box, other) : null;
- if (penetrations && Math.min(...penetrations) >= MINIMUM_PENETRATION) {
+ if (penetrations && Math.min(...penetrations) >= MINIMUM_PENETRATION && !isEnclosure(box, other)) {
intersecting.push({ nodes: [box.name, other.name], penetrationMeters: round(Math.min(...penetrations)) });
}
}
@@ -235,7 +260,7 @@ export function mergeFrameDiagnostics(metrics, frameDiagnostics) {
if (!frameDiagnostics?.length) return;
metrics.diagnostics ??= [];
for (const problem of frameDiagnostics) {
- const known = metrics.diagnostics.some(entry => entry.kind === problem.kind && entry.target === problem.target && entry.message === problem.message);
+ const known = metrics.diagnostics.some(entry => entry.kind === problem.kind && entry.target === problem.target && (problem.outsideCount !== undefined || entry.message === problem.message));
if (!known && metrics.diagnostics.length < MAXIMUM_JOB_DIAGNOSTICS) metrics.diagnostics.push(problem);
}
}
diff --git a/tests/frame-checks.test.js b/tests/frame-checks.test.js
index 8dd354e9..04970f74 100644
--- a/tests/frame-checks.test.js
+++ b/tests/frame-checks.test.js
@@ -176,6 +176,43 @@ test('placement findings are capped and say how many were left out', () => {
assert.equal(problems[0].droppedCount, 4);
});
+test('parts resting inside a large terrain box do not intersect it, but a real clash beside them does', () => {
+ const trees = Array.from({ length: 10 }, (_, index) => ({ id: `tree-${index}`, scale: [0.5, 2, 0.5], translation: [index * 4 - 18, 3.9, 0] }));
+ const terrain = { id: 'terrain', scale: [100, 4, 100], translation: [0, 2, 0] };
+ assert.deepEqual(placementOf([terrain, ...trees]), []);
+ const clash = placementOf([
+ terrain, ...trees,
+ { id: 'crate-a', translation: [30, 4.5, 0] },
+ { id: 'crate-b', translation: [30.4, 4.5, 0] },
+ ]);
+ assert.deepEqual(kinds(clash), ['intersecting-nodes']);
+ assert.deepEqual(clash[0].nodes, ['crate-a', 'crate-b']);
+});
+
+test('a cup half inside a table still intersects it', () => {
+ const problems = placementOf([
+ { id: 'table', scale: [2, 0.1, 2], translation: [0, 1, 0] },
+ { id: 'cup', scale: [0.2, 0.3, 0.2], translation: [0, 1.1, 0] },
+ ]);
+ assert.deepEqual(kinds(problems), ['intersecting-nodes']);
+});
+
+test('parts outside the frame are left out of per-frame job checks and repeats collapse in job metrics', () => {
+ const scene = createAgentScene(boxScene([{ id: 'a', translation: [0, 0, 0] }, { id: 'b', translation: [1, 0, 0] }, { id: 'c', translation: [-1, 0, 0] }, { id: 'd', translation: [0, 0, 0.5] }]));
+ const boxes = scene.worldBounds();
+ const metrics = {};
+ for (let frame = 0; frame < 6; frame++) {
+ const camera = { ...scene.camera, eye: [frame * 0.8, 3, 8], target: [frame * 0.8, 0.5, 0] };
+ const jobFrame = framingProblems({ camera, aspect: 1.5, boxes, reportPartsOutside: false });
+ assert.equal(jobFrame.filter(problem => problem.kind === 'part-outside-frame').length, 0);
+ mergeFrameDiagnostics(metrics, framingProblems({ camera, aspect: 1.5, boxes }));
+ }
+ assert.ok((metrics.diagnostics ?? []).filter(problem => problem.kind === 'part-outside-frame').length <= 1);
+ mergeFrameDiagnostics(metrics, [{ kind: 'subject-out-of-frame', target: 'camera', message: 'x', outsideCount: 3 }]);
+ mergeFrameDiagnostics(metrics, [{ kind: 'subject-out-of-frame', target: 'camera', message: 'y', outsideCount: 4 }]);
+ assert.equal(metrics.diagnostics.filter(problem => problem.kind === 'subject-out-of-frame').length, 1);
+});
+
test('a blown-out frame reports how much is clipped', () => {
const [finding] = exposureProblems({ shares: lumaShares(frameOf(255)), exposure: 1 });
assert.equal(finding.kind, 'exposure-clipped');