Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Cut near-flush faces too, so nested facades stop overflowing the ranks

Nguyen Xuan An56fcce5de797
diff --git a/changes/751.md b/changes/751.md
index e97ecedf..1865b5b8 100644
--- a/changes/751.md
+++ b/changes/751.md
@@ -1,3 +1,4 @@
- Depth precision by default (#751, phase 1 of 2): the colour pass draws with reversed-Z and a 32-bit float depth buffer wherever `EXT_clip_control` exists, at any far / near ratio, from the first frame; the 16-bit depth buffer is gone; without the extension the depth buffer is 24-bit and the near plane fits the visible bounds when the camera left near unset; `reversedDepth: false` opts out; `installDepthPrecision`, `hasFarOverlap` and `requestReversedDepth` are removed (use `installCoplanarDiagnostics` for the warning); `bench/flicker/index.html` is a viewer with a flicker probe
- Flush faces stop flickering by default (#751, phase 2, step 1 of 2): faces that lie on one plane or a few millimetres apart, inside one mesh or across parts, are ranked per triangle and drawn with a small view-space depth bias, so the face in front wins at every distance and on every depth format; agent scenes do it unless `environment.resolveCoplanar` is `false`, a renderer does it with `resolveCoplanar: resolveFlushParts`; `decal` and `depthLayer` use the same bias; what cannot be ranked (more than 15 faces stacked on one plane, double-sided faces a gap apart) comes back as a `coplanar-overlap` warning with a `reason`; `coplanarLayers`, `resolveCoplanarParts` and `EXACT_FLUSH_DISTANCE` are removed; `bench/flicker` has trap scenes (`?trap=`, `probe.mjs --traps`)
- Hidden flush faces are cut away (#751, phase 2, step 2 of 2): where an opaque face covers another on exactly the same plane (1 cm2 or more), the covered part is cut out of the copy the hidden face draws with, every vertex array interpolated, so a stack of any depth on one plane stops flickering and no longer reports `rank-overflow`; parts and their geometry stay as they are (`flushOrderOf(part).geometry` holds the cut copy), instances of one geometry share a cut, and the path tracer traces the cut geometry; a face under a blended or masked face, or a double-sided face under a one-sided one, is still ranked; `bench/flicker` gains the `plaque-closeup-0.5m` trap with an open-pixel count
+- Near-flush faces are cut too (#751): an opaque face in front of another by at most a thousandth of the side of their shared area (from 1 mm to 1 cm) cuts the face behind it, as a flush face does, instead of taking a rank; the Melbourne city model, whose stacked blocks nest facades 5 to 17 mm apart up to 17 deep, now reports no `rank-overflow`
diff --git a/docs/agent-look.md b/docs/agent-look.md
index 40fa31e3..36684252 100644
--- a/docs/agent-look.md
+++ b/docs/agent-look.md
@@ -121,7 +121,7 @@ Sky colors use display RGB, matching the renderer's existing environment contrac
| `world` | `false` | Boolean world presentation flag. With `true` the setup environment is also the background |
| `hdri` | absent | A shipped HDRI (`sky-clouds`, `studio-softbox`) or the 64-character ID of a `.hdr` file in `scene_asset_catalog`. It lights, reflects and (with `world: true`) forms the background instead of the setup sky; `environmentIntensity` is its strength and `environmentRotation` turns it about the vertical axis. The setup still gives the key light, so set `keyIntensity: 0` when the HDRI has its own sun. `null` clears. See [Catalog HDRIs and looks](#catalog-hdris-and-looks) |
| `ground` | on | Absent unless set. `false` removes the preview's automatic floor and contact shadow |
-| `resolveCoplanar` | `'offset'` | Flush and near-flush faces, inside one mesh or across parts, are ranked per triangle and drawn with a small depth-only bias, so the face in front wins at every distance and nothing flickers. Geometry never moves. `false` opts out, and `scene_inspect` then lists each pair as a `coplanar-overlap` warning. Parts that set `decal` or `depthLayer` keep their own layer. Where an opaque face covers another on exactly the same plane, the covered part is cut out of the drawn copy of the hidden face (the part and its geometry stay as you made them), so a stack of any depth on one plane is settled and the path tracer sees one face. What cannot be settled comes back as a `coplanar-overlap` warning with a `reason`: `rank-overflow` (more than 16 faces a small gap apart), `double-sided-gap`, `unchecked` or `collapsed-node` |
+| `resolveCoplanar` | `'offset'` | Flush and near-flush faces, inside one mesh or across parts, are ranked per triangle and drawn with a small depth-only bias, so the face in front wins at every distance and nothing flickers. Geometry never moves. `false` opts out, and `scene_inspect` then lists each pair as a `coplanar-overlap` warning. Parts that set `decal` or `depthLayer` keep their own layer. Where an opaque face covers another on the same plane, or in front of it by at most a thousandth of the shared face (between a millimetre and a centimetre), the covered part is cut out of the drawn copy of the hidden face (the part and its geometry stay as you made them), so a stack of any depth is settled and the path tracer sees one face. What cannot be settled comes back as a `coplanar-overlap` warning with a `reason`: `rank-overflow` (more than 16 faces a wider gap apart), `double-sided-gap`, `unchecked` or `collapsed-node` |
| `objectReflections` | on | Absent unless set. Each smooth metal part (`metallic` 0.5 or more, `roughness` 0.6 or less; at most 8 such parts, in a scene with at most 256 other parts) gets a reflection probe of the scene around it, so a chrome sphere shows the floor and its neighbours. `false` turns it off. Probes are traced at rest, so a part that moves reflects the scene as it started. `scene_inspect` names them in `reflections` |
| `sky` | absent | Absent unless set. `{ type: 'physical', sunElevation, sunRotation, turbidity, groundAlbedo, aerialPerspective, ozone, sunDisc }`: one time-of-day control. `sunElevation` -90 to 90 degrees (default 45), `sunRotation` degrees clockwise from -Z seen from above (0), `turbidity` 1 to 10 haze (3), `groundAlbedo` 0 to 1 (0.3), `aerialPerspective` 0 to 4 scales the distance haze (1; 0 for none), `ozone` 0 to 10 Chappuis-band absorption (1), `sunDisc` boolean (true). The sky sets `lightDirection`, `keyColor` (the sun reddens and dims with air mass and sets below the horizon), `skyTop`, `skyBottom`, `fogColor` and `fogDensity`, and replaces the setup's environment map with the sky, so those fields no longer take your values while a sky is set. `environment` motion tracks can animate `sunElevation`, `sunRotation`, `turbidity`, `groundAlbedo`, `aerialPerspective` and `ozone` for time-of-day arcs. A `set-environment` patch changes the fields it names and keeps the rest; `sky: null` in a patch keeps the last derived values as plain fields. It is an analytic single-scattering approximation (Rayleigh, aerosol and ozone, Kasten-Young air mass), not Blender's Nishita integration: no clouds. Raster first: the path tracer backends read the same environment map and key light, but are not yet checked against it. |
| `floorSkyTrace` | on | Absent unless set. A closed room a sun lights gets the sky each floor texel sees traced into its floor (`applyFloorSkyVisibility`, strength 0.2), so shadowed floors under a roof or between walls get less world and sky light; it makes the dark end of halls closer to Cycles. Open scenes and rooms lit by lamps alone are left as they are. `false` turns it off; a value that is not a boolean is refused. It loads lazily with a recipe that names its sun (`keyColor` or `keyIntensity`), costs about 1 s of trace when the scene is built and adds triangles to the floor (0.1 to 0.4 ms per frame in the reference halls). |
diff --git a/docs/learn/contact-detection.md b/docs/learn/contact-detection.md
index 7ca10b86..e57182f9 100644
--- a/docs/learn/contact-detection.md
+++ b/docs/learn/contact-detection.md
@@ -186,7 +186,7 @@ Both parts draw the plane `y = 0.1`, so the patch flickers against the slab. The
Use a real offset along the normal when the gap should be visible in exports or the path tracer.
-The coplanar code is not in the core bundle. Call `installCoplanarDiagnostics(renderer)` from `67js/addons/coplanar-overlap` to add the warning to `renderer.diagnostics` (checked once per layout). To fix the flicker instead of naming it, pass `resolveCoplanar: resolveFlushParts` (same addon) to `new Renderer67`: it ranks flush and near-flush triangles, inside one part and across parts, and draws each rank with a small depth-only bias, so the face in front wins at every distance; ranked pairs leave the warning. Where an opaque face covers another on exactly the same plane (shared area of 1 cm2 or more), the covered part is cut away instead: the part keeps its geometry, and the cut copy it draws with sits beside it (`flushOrderOf(part).geometry` in `depth-layer.js`), which the path tracer reads too. A face under a blended or masked face, and a double-sided face under a one-sided one, is ranked and not cut. Agent scenes do this by default wherever the code is loaded (the MCP preview always has it; elsewhere call `loadAllAgentSceneModules()`), and `environment.resolveCoplanar: false` opts out.
+The coplanar code is not in the core bundle. Call `installCoplanarDiagnostics(renderer)` from `67js/addons/coplanar-overlap` to add the warning to `renderer.diagnostics` (checked once per layout). To fix the flicker instead of naming it, pass `resolveCoplanar: resolveFlushParts` (same addon) to `new Renderer67`: it ranks flush and near-flush triangles, inside one part and across parts, and draws each rank with a small depth-only bias, so the face in front wins at every distance; ranked pairs leave the warning. Where an opaque face covers another on the same plane, or in front of it by at most a thousandth of the side of the shared area (never less than a millimetre or more than a centimetre), and they share 1 cm2 or more, the covered part is cut away instead. Seen at a grazing angle, that cut can open a strip no wider than the gap, which does not show, and it settles city models that nest facades of stacked blocks a few millimetres apart deeper than the ranks go: the part keeps its geometry, and the cut copy it draws with sits beside it (`flushOrderOf(part).geometry` in `depth-layer.js`), which the path tracer reads too. A face under a blended or masked face, and a double-sided face under a one-sided one, is ranked and not cut. Agent scenes do this by default wherever the code is loaded (the MCP preview always has it; elsewhere call `loadAllAgentSceneModules()`), and `environment.resolveCoplanar: false` opts out.
### Depth precision far from the camera
diff --git a/skills/build-67js-scene/references/light.md b/skills/build-67js-scene/references/light.md
index 19642e3d..8cd771a3 100644
--- a/skills/build-67js-scene/references/light.md
+++ b/skills/build-67js-scene/references/light.md
@@ -89,8 +89,8 @@ The fix is automatic. Depth precision needs no setting, and faces that lie flush
one mesh or across parts, are ranked per triangle at draw time so the face in front always wins; geometry never moves.
`scene_inspect` returns `flush.ranked`, the number of parts that got ranks. You only act on what is left:
-- A `coplanar-overlap` diagnostic with `reason: "rank-overflow"` means more than 15 faces are stacked on one plane:
- remove the duplicate faces. The other reasons (`double-sided-gap`, `unchecked`, `collapsed-node`) carry their own `fix`.
+- A `coplanar-overlap` diagnostic with `reason: "rank-overflow"` means more than 15 faces are stacked a small gap apart,
+ wider than the gap that is cut away: remove the duplicate faces. The other reasons (`double-sided-gap`, `unchecked`, `collapsed-node`) carry their own `fix`.
- To choose which of two flush nodes wins, set `decal: true` on the one on top (a sticker on a surface) or `depthLayer`
(1 to 4) to stack several.
- `environment.resolveCoplanar: false` opts out; `scene_inspect` then lists each flush pair as `coplanar-overlap`.
diff --git a/src/flush-resolve.js b/src/flush-resolve.js
index 10422d71..0203b720 100644
--- a/src/flush-resolve.js
+++ b/src/flush-resolve.js
@@ -10,6 +10,19 @@ import { invertAffine } from './path-tracer-reprojection.js';
const COLLAPSED_AXIS_SHARE = 1e-3;
const CACHED_ORDERS_PER_GEOMETRY = 8;
+// A face this close in front of another, facing the same way, is cut like a flush one. Seen at a grazing angle, the cut
+// can open a strip no wider than the gap at the front face's edge: a thousandth of the shared face, never less than a
+// millimetre and never more than a centimetre, does not show. A wider gap, such as a sign standing off a wall, is ranked
+// instead. Without the cut, assets built as stacked blocks nest facades a few millimetres apart deeper than the 15 ranks
+// (the Melbourne city model nests 17).
+const NEAR_FLUSH_CUT_GAP_SHARE = 1e-3;
+const NEAR_FLUSH_CUT_MINIMUM_GAP = 1e-3;
+const NEAR_FLUSH_CUT_MAXIMUM_GAP = 1e-2;
+
+function nearFlushCutGap(sharedArea) {
+ const relative = NEAR_FLUSH_CUT_GAP_SHARE * Math.sqrt(sharedArea);
+ return Math.min(NEAR_FLUSH_CUT_MAXIMUM_GAP, Math.max(NEAR_FLUSH_CUT_MINIMUM_GAP, relative));
+}
// Kept between runs, so a part whose ranks and cuts did not change keeps its order object and the renderer keeps its batch.
const ordersByGeometry = new WeakMap();
@@ -54,10 +67,12 @@ function rankTriangles(count, edges, seamEdges) {
return { ranks, overflow };
}
-// Whether the back triangle of a pair can be cut away under the front one: they lie on one plane and face the same way, the
-// front one hides what is under it, and no side of the back one stays in view where the front one is culled.
+// Whether the back triangle of a pair can be cut away under the front one: they lie on one plane, or within
+// nearFlushCutGap of it, and face the same way, the front one hides what is under it, and no side of the back one stays
+// in view where the front one is culled.
function canCut(pair, frontPart, backPart) {
- if (!pair.flush || pair.opposite || pair.area < FLUSH_CUT_MINIMUM_AREA) return false;
+ if (pair.opposite || pair.area < FLUSH_CUT_MINIMUM_AREA) return false;
+ if (!pair.flush && !(Math.abs(pair.gap) <= nearFlushCutGap(pair.area))) return false;
if ((frontPart.material?.alphaMode ?? 'opaque') !== 'opaque') return false;
return backPart.material?.doubleSided !== true || frontPart.material?.doubleSided === true;
}
diff --git a/tests/coplanar-overlap.test.js b/tests/coplanar-overlap.test.js
index 0c3e320e..2909da7b 100644
--- a/tests/coplanar-overlap.test.js
+++ b/tests/coplanar-overlap.test.js
@@ -253,19 +253,23 @@ test('resolveFlushParts settles exactly flush pairs too, on every depth format',
});
test('ranks settle in chains, and a stack deeper than the ranks is reported instead of piled on the top rank', () => {
- const big = gridPart('chainBig', 10, 1, 0);
- const middle = gridPart('chainMiddle', 5, 1, 0.0002);
- const small = gridPart('chainSmall', 2, 1, 0.0004);
- assert.equal(findCoplanarOverlaps([small, middle, big]).overlaps.length, 3);
+ // Faces under a metre, 1.2 mm apart: wider than the near-flush cut, which cuts anything findCoplanarOverlaps reports, and
+ // inside the 2 mm the flush search reaches on a scene this small. So each pair is ranked, and only neighbours pair up.
+ const step = 0.0012;
+ const big = gridPart('chainBig', 1, 1, 0);
+ const middle = gridPart('chainMiddle', 0.5, 1, step);
+ const small = gridPart('chainSmall', 0.2, 1, step * 2);
+ assert.equal(findCoplanarOverlaps([small, middle, big]).overlaps.length, 0, 'wider apart than the overlap check looks');
const rankOf = part => flushOrderOf(part)?.ranges.at(-1).rank ?? 0;
assert.deepEqual(resolveFlushParts([small, middle, big]), { ranked: 2, leftovers: [] });
assert.deepEqual([big, middle, small].map(rankOf), [0, 1, 2]);
- const stack = Array.from({ length: 8 }, (unused, index) => gridPart(`stack${index}`, 10 - index, 1, index * 0.0005));
+ const stack = Array.from({ length: 8 }, (unused, index) => gridPart(`stack${index}`, (10 - index) / 10, 1, index * step));
assert.deepEqual(resolveFlushParts(stack).leftovers, []);
assert.deepEqual(stack.map(rankOf), [0, 1, 2, 3, 4, 5, 6, 7], 'every face of the stack has a rank of its own');
- const deep = Array.from({ length: 20 }, (unused, index) => gridPart(`deep${index}`, 20 - index, 1, index * 0.0005));
+ const deep = Array.from({ length: 20 }, (unused, index) => gridPart(`deep${index}`, (20 - index) / 20, 1, index * step));
const { leftovers } = resolveFlushParts(deep);
- assert.deepEqual(leftovers.map(leftover => leftover.reason), ['rank-overflow', 'rank-overflow', 'rank-overflow', 'rank-overflow']);
+ // Face 16 would need rank 16; the faces past it only reach face 16, so their chain starts again below the top rank.
+ assert.deepEqual(leftovers, [{ reason: 'rank-overflow', part: 'deep16', triangles: 2 }]);
assert.ok(deep.every(part => rankOf(part) <= 15));
const onOnePlane = Array.from({ length: 20 }, (unused, index) => gridPart(`plane${index}`, 20 - index, 1, 0));
assert.deepEqual(resolveFlushParts(onOnePlane).leftovers, [], 'on one plane the hidden faces are cut away, however deep the stack');
diff --git a/tests/flush-resolve.test.js b/tests/flush-resolve.test.js
index 925cd73d..a5d26fc1 100644
--- a/tests/flush-resolve.test.js
+++ b/tests/flush-resolve.test.js
@@ -106,7 +106,8 @@ test('a part hidden whole keeps its geometry and is ranked under what hides it',
});
test('the ranked order holds every triangle once, sorted by rank, and leaves the geometry alone', () => {
- const kitbash = partOf('kitbash', [quadCorners(0, 0, 2, 1, 0.002), quadCorners(0, 0, 10, 1, 0), quadCorners(0, 0, 5, 1, 0.001)]);
+ // Strips 1.5 mm apart: wider than the near-flush cut allows on strips this small, so they are ranked, not cut.
+ const kitbash = partOf('kitbash', [quadCorners(0, 0, 2, 0.1, 0.003), quadCorners(0, 0, 10, 0.1, 0), quadCorners(0, 0, 5, 0.1, 0.0015)]);
const original = Array.from(kitbash.geometry.indices);
const geometry = kitbash.geometry;
resolveFlush([kitbash]);
@@ -128,15 +129,29 @@ test('a stack of 20 or 30 faces on one plane is cut down to what shows and repor
}
});
-test('a stack of 20 faces half a millimetre apart fills the 16 ranks and reports the rest as rank-overflow', () => {
+test('faces stacked within the near-flush gap are cut like flush ones, however deep the stack', () => {
const stack = partOf('stack', Array.from({ length: 20 }, (unused, index) => quadCorners(0, 0, 20 - index, 1, index * 0.0005)));
+ assert.deepEqual(resolveFlush([stack]), { ranked: 1, leftovers: [] });
+ assert.ok(Math.abs(drawnArea(stack) - 20) < 1e-2, 'only the union of the faces is drawn');
+ // Facades of blocks stacked from the ground, each a few millimetres out from the one before, as city models build towers.
+ const tower = partOf('tower', Array.from({ length: 17 }, (unused, index) => {
+ const height = 40 + index * 5;
+ return [0, 0, index * 0.005, 30, 0, index * 0.005, 30, height, index * 0.005, 0, height, index * 0.005];
+ }));
+ assert.deepEqual(resolveFlush([tower]), { ranked: 1, leftovers: [] });
+ assert.ok(Math.abs(drawnArea(tower) - 30 * 120) < 1);
+});
+
+test('a stack of 20 faces wider apart than the near-flush cut fills the 16 ranks and reports the rest as rank-overflow', () => {
+ const stack = partOf('stack', Array.from({ length: 20 }, (unused, index) => quadCorners(0, 0, 20 - index, 0.1, index * 0.0015)));
const { ranked, leftovers } = resolveFlush([stack]);
assert.equal(ranked, 1);
- assert.deepEqual(leftovers, [{ reason: 'rank-overflow', part: 'stack', triangles: 8 }]);
+ // The last strips sit beyond the search reach of the rank-15 strip, so their chain starts again and only the first is cut off.
+ assert.deepEqual(leftovers, [{ reason: 'rank-overflow', part: 'stack', triangles: 6 }]);
const ranks = ranksOf(stack);
assert.equal(Math.max(...ranks), MAXIMUM_FLUSH_RANK);
assert.deepEqual(ranks.slice(0, 32), Array.from({ length: 32 }, (unused, index) => index >> 1));
- const shallow = partOf('shallow', Array.from({ length: 16 }, (unused, index) => quadCorners(0, 0, 20 - index, 1, index * 0.0005)));
+ const shallow = partOf('shallow', Array.from({ length: 16 }, (unused, index) => quadCorners(0, 0, 20 - index, 0.1, index * 0.0015)));
assert.deepEqual(resolveFlush([shallow]).leftovers, []);
});