Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add a ground-truth flicker probe and a far panel trap (#751)

Nguyen Xuan Anca60db96562b
diff --git a/bench/flicker/ground-truth.js b/bench/flicker/ground-truth.js
new file mode 100644
index 00000000..dcf76a42
--- /dev/null
+++ b/bench/flicker/ground-truth.js
@@ -0,0 +1,178 @@
+// Ground truth for the flicker probe (issue #751). The jitter probe compares a render with a copy of itself, so it counts crease
+// anti-aliasing as flicker and misses speckle that sits next to a colour step. This module answers the question directly: for
+// every pixel it intersects the camera ray with every triangle in float64, which cannot z-fight, names the triangle that is
+// visible, and the probe then asks whether the raster render shows that triangle's colour there.
+//
+// A triangle's colour is looked up by a key (albedo, vertex colour and facing), not by its own pixels: a plaque flush on a wall
+// has no pixel of its own that the wall could not also claim, so the colour it should have is the median of the pixels where
+// the ray cast says it is visible. Pixels next to another key (silhouettes, creases, anti-aliased edges) are left out, so only
+// the interior of a face is judged.
+
+import { depthLayerOf, RANKS_PER_LAYER } from '../../src/depth-layer.js';
+import { castPixelOwners, crossProduct, normalized, subtract, NO_TRIANGLE, RIVALS_PER_PIXEL } from './pixel-cast.js';
+
+export { castPixelOwners, NO_TRIANGLE };
+
+const NORMAL_KEY_SCALE = 100;
+const COLOUR_KEY_SCALE = 255;
+export const DEFAULT_COLOUR_THRESHOLD = 40;
+const MINIMUM_REFERENCE_PIXELS = 3;
+
+function transformPoint(matrix, x, y, z, target, offset) {
+ target[offset] = matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12];
+ target[offset + 1] = matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13];
+ target[offset + 2] = matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14];
+}
+
+// The triangles of a part as it is drawn: the cut geometry and the rank of each triangle when the flush pass made an order.
+function drawnTriangles(part, flushOrder) {
+ if (!flushOrder) return { geometry: part.geometry, indices: part.geometry.indices, ranks: null };
+ const geometry = flushOrder.geometry ?? part.geometry;
+ const ranks = new Uint8Array(flushOrder.indices.length / 3);
+ for (const range of flushOrder.ranges) ranks.fill(range.rank, range.start / 3, (range.start + range.count) / 3);
+ return { geometry, indices: flushOrder.indices, ranks };
+}
+
+function colourKey(part, geometry, firstVertex, vertexCount, facing) {
+ const material = part.material?.color ?? [1, 1, 1];
+ const stride = geometry.colors ? geometry.colors.length / vertexCount : 0;
+ const vertexColour = stride >= 3 ? [0, 1, 2].map(channel => geometry.colors[firstVertex * stride + channel]) : [1, 1, 1];
+ const colour = [0, 1, 2].map(channel => Math.round(material[channel] * vertexColour[channel] * COLOUR_KEY_SCALE));
+ const normal = facing.map(value => Math.round(value * NORMAL_KEY_SCALE));
+ return `${colour.join(',')}|${normal.join(',')}`;
+}
+
+/**
+ * Every opaque triangle of the parts in world space, in float64.
+ * Returns `{ corners, keys, keyOf, ranks, doubleSided, count }`: `corners` holds nine numbers per triangle, `keyOf` the colour key
+ * id of each triangle, `ranks` its flush rank (0 without an order). `flushOrderOf` is the lookup of depth-layer.js.
+ * Parts that blend or cut out alpha are skipped: their visible colour is a mix the key cannot name.
+ */
+export function collectWorldTriangles(parts, flushOrderOf) {
+ const cornerChunks = [];
+ const keyIds = new Map();
+ const keyOf = [];
+ const rankList = [];
+ const doubleSidedList = [];
+ for (const part of parts) {
+ if ((part.material?.alphaMode ?? 'opaque') !== 'opaque') continue;
+ const { geometry, indices, ranks } = drawnTriangles(part, flushOrderOf(part));
+ const vertexCount = geometry.positions.length / 3;
+ const triangleCount = indices.length / 3;
+ const corners = new Float64Array(triangleCount * 9);
+ for (let triangle = 0; triangle < triangleCount; triangle++) {
+ for (let corner = 0; corner < 3; corner++) {
+ const vertex = indices[triangle * 3 + corner] * 3;
+ transformPoint(part.matrix, geometry.positions[vertex], geometry.positions[vertex + 1], geometry.positions[vertex + 2], corners, triangle * 9 + corner * 3);
+ }
+ const base = triangle * 9;
+ const first = [corners[base], corners[base + 1], corners[base + 2]];
+ const edgeOne = subtract([corners[base + 3], corners[base + 4], corners[base + 5]], first);
+ const edgeTwo = subtract([corners[base + 6], corners[base + 7], corners[base + 8]], first);
+ const key = colourKey(part, geometry, indices[triangle * 3], vertexCount, normalized(crossProduct(edgeOne, edgeTwo)));
+ if (!keyIds.has(key)) keyIds.set(key, keyIds.size);
+ keyOf.push(keyIds.get(key));
+ rankList.push(depthLayerOf(part) * RANKS_PER_LAYER + (ranks ? ranks[triangle] : 0));
+ doubleSidedList.push(part.material?.doubleSided === true ? 1 : 0);
+ }
+ cornerChunks.push(corners);
+ }
+ const total = cornerChunks.reduce((sum, chunk) => sum + chunk.length, 0);
+ const corners = new Float64Array(total);
+ let offset = 0;
+ for (const chunk of cornerChunks) {
+ corners.set(chunk, offset);
+ offset += chunk.length;
+ }
+ return { corners, keyOf: Int32Array.from(keyOf), ranks: Uint8Array.from(rankList), doubleSided: Uint8Array.from(doubleSidedList), keyCount: keyIds.size, count: keyOf.length };
+}
+
+function channelDistance(pixels, index, reference) {
+ return Math.max(Math.abs(pixels[index] - reference[0]), Math.abs(pixels[index + 1] - reference[1]), Math.abs(pixels[index + 2] - reference[2]));
+}
+
+function median(values) {
+ const sorted = Float64Array.from(values).sort();
+ return sorted[Math.floor(sorted.length / 2)];
+}
+
+// A pixel is judged only when it and its eight neighbours see one colour key: edges, creases and silhouettes are left out.
+function hasUniformSurroundings(keyAt, width, height, x, y) {
+ if (x < 1 || y < 1 || x >= width - 1 || y >= height - 1) return false;
+ const own = keyAt[y * width + x];
+ if (own < 0) return false;
+ for (let row = -1; row <= 1; row++) {
+ for (let column = -1; column <= 1; column++) {
+ if (keyAt[(y + row) * width + x + column] !== own) return false;
+ }
+ }
+ return true;
+}
+
+/**
+ * Compares a rendered frame (RGBA bytes, rows from the top) with the ray cast of `castPixelOwners`.
+ * Returns `{ contested, wrong, swapped, tied, unjudged, edge }`:
+ * - `contested`: interior pixels where another colour lies behind the visible one, the only place depth can fight;
+ * - `wrong`: contested pixels whose colour is further than `threshold` (0 to 255, largest channel) from the visible face's colour;
+ * - `swapped`: wrong pixels that sit within `threshold` of the colour of a face behind, a fight and not shading;
+ * - `tied`: contested pixels where the scene itself does not say which face is in front (the flush pass off, or a seam); left out of the other counts;
+ * - `unjudged`: contested pixels whose face has too few clean pixels to know its colour;
+ * - `edge`: pixels left out for having another colour next to them.
+ * `mismatchMask` marks the wrong pixels for a picture.
+ */
+export function compareWithGroundTruth({ pixels, world, cast, width, height, threshold = DEFAULT_COLOUR_THRESHOLD }) {
+ const keyAt = new Int32Array(width * height);
+ for (let pixel = 0; pixel < keyAt.length; pixel++) keyAt[pixel] = cast.owner[pixel] === NO_TRIANGLE ? -1 : world.keyOf[cast.owner[pixel]];
+ const references = new Array(world.keyCount);
+ const samples = Array.from({ length: world.keyCount }, () => ({ clean: [[], [], []], any: [[], [], []], cleanCount: 0 }));
+ for (let y = 1; y < height - 1; y++) {
+ for (let x = 1; x < width - 1; x++) {
+ if (!hasUniformSurroundings(keyAt, width, height, x, y)) continue;
+ const pixel = y * width + x;
+ const bucket = samples[keyAt[pixel]];
+ const contested = cast.rivals[pixel * RIVALS_PER_PIXEL] >= 0;
+ for (let channel = 0; channel < 3; channel++) {
+ bucket.any[channel].push(pixels[pixel * 4 + channel]);
+ if (!contested) bucket.clean[channel].push(pixels[pixel * 4 + channel]);
+ }
+ if (!contested) bucket.cleanCount++;
+ }
+ }
+ samples.forEach((bucket, key) => {
+ const source = bucket.cleanCount >= MINIMUM_REFERENCE_PIXELS ? bucket.clean : bucket.any;
+ if (source[0].length >= MINIMUM_REFERENCE_PIXELS) references[key] = source.map(median);
+ });
+ const result = { contested: 0, wrong: 0, swapped: 0, tied: 0, unjudged: 0, edge: 0 };
+ const mismatchMask = new Uint8Array(width * height);
+ for (let y = 0; y < height; y++) {
+ for (let x = 0; x < width; x++) {
+ const pixel = y * width + x;
+ if (keyAt[pixel] < 0 || cast.rivals[pixel * RIVALS_PER_PIXEL] < 0) continue;
+ if (!hasUniformSurroundings(keyAt, width, height, x, y)) {
+ result.edge++;
+ continue;
+ }
+ result.contested++;
+ if (cast.tied[pixel]) {
+ result.tied++;
+ continue;
+ }
+ const reference = references[keyAt[pixel]];
+ if (!reference) {
+ result.unjudged++;
+ continue;
+ }
+ if (channelDistance(pixels, pixel * 4, reference) <= threshold) continue;
+ result.wrong++;
+ mismatchMask[pixel] = 1;
+ for (let slot = 0; slot < RIVALS_PER_PIXEL; slot++) {
+ const rival = references[cast.rivals[pixel * RIVALS_PER_PIXEL + slot]];
+ if (rival && channelDistance(pixels, pixel * 4, rival) <= threshold) {
+ result.swapped++;
+ break;
+ }
+ }
+ }
+ }
+ return { ...result, mismatchMask };
+}
diff --git a/bench/flicker/pixel-cast.js b/bench/flicker/pixel-cast.js
new file mode 100644
index 00000000..dcb9382f
--- /dev/null
+++ b/bench/flicker/pixel-cast.js
@@ -0,0 +1,167 @@
+// The float64 ray cast behind ground-truth.js (issue #751): which triangle is visible at each pixel centre. It scan-converts every
+// triangle into a small per-pixel list of the nearest hits, in double precision with perspective-correct depth, so no depth
+// buffer rounding can pick the wrong face. Cost follows the area the triangles cover, not triangles times pixels.
+
+export const NO_TRIANGLE = -1;
+export const RIVALS_PER_PIXEL = 2;
+const TIE_RELATIVE_DISTANCE = 1e-9;
+const HITS_PER_PIXEL = 6;
+const NEAR_DEPTH = 1e-4;
+// A pixel centre exactly on an edge shared by two triangles must not fall between them through rounding.
+const EDGE_SLACK = 1e-9;
+
+export function subtract(first, second) {
+ return [first[0] - second[0], first[1] - second[1], first[2] - second[2]];
+}
+
+export function dot(first, second) {
+ return first[0] * second[0] + first[1] * second[1] + first[2] * second[2];
+}
+
+export function crossProduct(first, second) {
+ return [first[1] * second[2] - first[2] * second[1], first[2] * second[0] - first[0] * second[2], first[0] * second[1] - first[1] * second[0]];
+}
+
+export function normalized(vector) {
+ const length = Math.hypot(...vector) || 1;
+ return vector.map(value => value / length);
+}
+
+function cameraBasis({ eye, target, up = [0, 1, 0], fov = 45 }, width, height) {
+ const forward = normalized(subtract(target, eye));
+ const right = normalized(crossProduct(forward, up));
+ const upward = crossProduct(right, forward);
+ return { eye, forward, right, upward, tangent: Math.tan(fov * Math.PI / 360), aspect: width / height };
+}
+
+// A world point as [sideways, up, depth] from the camera.
+function toCameraSpace(basis, x, y, z) {
+ const relative = [x - basis.eye[0], y - basis.eye[1], z - basis.eye[2]];
+ return [dot(relative, basis.right), dot(relative, basis.upward), dot(relative, basis.forward)];
+}
+
+// The part of a camera-space triangle in front of the near depth, as a polygon of up to four points.
+function clipToNear(points) {
+ const kept = [];
+ for (let index = 0; index < points.length; index++) {
+ const current = points[index];
+ const next = points[(index + 1) % points.length];
+ const currentInside = current[2] >= NEAR_DEPTH;
+ if (currentInside) kept.push(current);
+ if (currentInside !== (next[2] >= NEAR_DEPTH)) {
+ const share = (NEAR_DEPTH - current[2]) / (next[2] - current[2]);
+ kept.push([0, 1, 2].map(axis => current[axis] + (next[axis] - current[axis]) * share));
+ }
+ }
+ return kept;
+}
+
+// Whether the first hit is nearer than the second; hits at one distance (to 1e-9) go to the higher rank, then the later triangle.
+function isNearer(world, firstDistance, firstTriangle, secondDistance, secondTriangle) {
+ const gap = firstDistance - secondDistance;
+ if (Math.abs(gap) > TIE_RELATIVE_DISTANCE * firstDistance) return gap < 0;
+ return world.ranks[firstTriangle] !== world.ranks[secondTriangle] ? world.ranks[firstTriangle] > world.ranks[secondTriangle] : firstTriangle > secondTriangle;
+}
+
+function recordHit(world, hitDistances, hitTriangles, pixel, distance, triangle) {
+ const base = pixel * HITS_PER_PIXEL;
+ let slot = 0;
+ while (slot < HITS_PER_PIXEL - 1 && hitTriangles[base + slot] !== NO_TRIANGLE) slot++;
+ const full = hitTriangles[base + slot] !== NO_TRIANGLE;
+ if (full && !isNearer(world, distance, triangle, hitDistances[base + slot], hitTriangles[base + slot])) return;
+ while (slot > 0 && isNearer(world, distance, triangle, hitDistances[base + slot - 1], hitTriangles[base + slot - 1])) {
+ hitDistances[base + slot] = hitDistances[base + slot - 1];
+ hitTriangles[base + slot] = hitTriangles[base + slot - 1];
+ slot--;
+ }
+ hitDistances[base + slot] = distance;
+ hitTriangles[base + slot] = triangle;
+}
+
+// Scan-converts one camera-space triangle: pixel centres inside it, with depth interpolated as 1/depth in screen space.
+function rasterize(world, basis, triangle, points, width, height, hitDistances, hitTriangles) {
+ const screen = points.map(([sideways, upward, depth]) => [
+ (sideways / depth / (basis.aspect * basis.tangent) * 0.5 + 0.5) * width,
+ (0.5 - upward / depth / basis.tangent * 0.5) * height,
+ 1 / depth,
+ ]);
+ const [first, second, third] = screen;
+ const area = (second[0] - first[0]) * (third[1] - first[1]) - (second[1] - first[1]) * (third[0] - first[0]);
+ if (area === 0) return;
+ const minimumX = Math.max(0, Math.floor(Math.min(first[0], second[0], third[0]) - 0.5));
+ const maximumX = Math.min(width - 1, Math.ceil(Math.max(first[0], second[0], third[0]) - 0.5));
+ const minimumY = Math.max(0, Math.floor(Math.min(first[1], second[1], third[1]) - 0.5));
+ const maximumY = Math.min(height - 1, Math.ceil(Math.max(first[1], second[1], third[1]) - 0.5));
+ for (let y = minimumY; y <= maximumY; y++) {
+ for (let x = minimumX; x <= maximumX; x++) {
+ const centreX = x + 0.5;
+ const centreY = y + 0.5;
+ const weightFirst = ((second[0] - centreX) * (third[1] - centreY) - (second[1] - centreY) * (third[0] - centreX)) / area;
+ const weightSecond = ((third[0] - centreX) * (first[1] - centreY) - (third[1] - centreY) * (first[0] - centreX)) / area;
+ const weightThird = 1 - weightFirst - weightSecond;
+ if (weightFirst < -EDGE_SLACK || weightSecond < -EDGE_SLACK || weightThird < -EDGE_SLACK) continue;
+ const inverseDepth = weightFirst * first[2] + weightSecond * second[2] + weightThird * third[2];
+ recordHit(world, hitDistances, hitTriangles, y * width + x, 1 / inverseDepth, triangle);
+ }
+ }
+}
+
+// Whether the triangle faces the eye (counter-clockwise seen from it); double-sided triangles always count.
+function facesEye(world, basis, triangle) {
+ if (world.doubleSided[triangle] === 1) return true;
+ const base = triangle * 9;
+ const corners = world.corners;
+ const edgeOne = [corners[base + 3] - corners[base], corners[base + 4] - corners[base + 1], corners[base + 5] - corners[base + 2]];
+ const edgeTwo = [corners[base + 6] - corners[base], corners[base + 7] - corners[base + 1], corners[base + 8] - corners[base + 2]];
+ return dot(crossProduct(edgeOne, edgeTwo), subtract(basis.eye, [corners[base], corners[base + 1], corners[base + 2]])) > 0;
+}
+
+// Two faces of different colour at one distance with one rank: nothing in the scene says which is in front, so no render is wrong.
+function isTie(world, distances, triangles, base) {
+ const nearestTriangle = triangles[base];
+ for (let slot = 1; slot < HITS_PER_PIXEL && triangles[base + slot] !== NO_TRIANGLE; slot++) {
+ if (Math.abs(distances[base + slot] - distances[base]) > TIE_RELATIVE_DISTANCE * distances[base]) return false;
+ const other = triangles[base + slot];
+ if (world.keyOf[nearestTriangle] !== world.keyOf[other] && world.ranks[nearestTriangle] === world.ranks[other]) return true;
+ }
+ return false;
+}
+
+/**
+ * Casts one ray through every pixel centre of a `width` x `height` image. `world` is the result of `collectWorldTriangles`,
+ * `camera` the `{ eye, target, up, fov }` of the frame. Returns `{ owner, rivals, tied }`: `owner` is the visible triangle of
+ * each pixel (`NO_TRIANGLE` for the background), `rivals` holds up to two colour keys of other triangles on the same ray, or
+ * -1, and `tied` marks pixels where two faces of different colour lie at one distance with one rank. Only the six nearest
+ * faces of a ray are kept, which is enough to name its visible face and the faces right behind it.
+ */
+export function castPixelOwners(world, camera, width, height) {
+ const basis = cameraBasis(camera, width, height);
+ const hitDistances = new Float64Array(width * height * HITS_PER_PIXEL);
+ const hitTriangles = new Int32Array(width * height * HITS_PER_PIXEL).fill(NO_TRIANGLE);
+ for (let triangle = 0; triangle < world.count; triangle++) {
+ if (!facesEye(world, basis, triangle)) continue;
+ const base = triangle * 9;
+ const points = [0, 1, 2].map(corner => toCameraSpace(basis, world.corners[base + corner * 3], world.corners[base + corner * 3 + 1], world.corners[base + corner * 3 + 2]));
+ const polygon = points.every(point => point[2] >= NEAR_DEPTH) ? points : clipToNear(points);
+ for (let corner = 1; corner + 1 < polygon.length; corner++) {
+ rasterize(world, basis, triangle, [polygon[0], polygon[corner], polygon[corner + 1]], width, height, hitDistances, hitTriangles);
+ }
+ }
+ const owner = new Int32Array(width * height).fill(NO_TRIANGLE);
+ const rivals = new Int32Array(width * height * RIVALS_PER_PIXEL).fill(-1);
+ const tied = new Uint8Array(width * height);
+ for (let pixel = 0; pixel < width * height; pixel++) {
+ const base = pixel * HITS_PER_PIXEL;
+ if (hitTriangles[base] === NO_TRIANGLE) continue;
+ owner[pixel] = hitTriangles[base];
+ tied[pixel] = isTie(world, hitDistances, hitTriangles, base) ? 1 : 0;
+ const ownKey = world.keyOf[hitTriangles[base]];
+ let stored = 0;
+ for (let slot = 1; slot < HITS_PER_PIXEL && hitTriangles[base + slot] !== NO_TRIANGLE && stored < RIVALS_PER_PIXEL; slot++) {
+ const key = world.keyOf[hitTriangles[base + slot]];
+ const known = key === ownKey || (stored > 0 && rivals[pixel * RIVALS_PER_PIXEL] === key);
+ if (!known) rivals[pixel * RIVALS_PER_PIXEL + stored++] = key;
+ }
+ }
+ return { owner, rivals, tied };
+}
diff --git a/bench/flicker/probe.mjs b/bench/flicker/probe.mjs
index f9bea085..42c82e5d 100644
--- a/bench/flicker/probe.mjs
+++ b/bench/flicker/probe.mjs
@@ -3,6 +3,10 @@
// --spots spots.json --configs "reversed=1,nearFit=1;reversed=0,nearFit=0"
// spots.json: [{ "name": "roofs", "eye": [x, y, z], "target": [x, y, z] }]. Without --spots it prints the scene bounds and exits.
// node bench/flicker/probe.mjs --traps --configs "reversed=1;reversed=0" runs every trap scene of traps.js with its own camera.
+// Each result also carries `truth`, the ground-truth probe of ground-truth.js: the render compared with a float64 ray cast that
+// cannot z-fight. `swapped` is the count that matters (a pixel showing the colour of a face behind the visible one), `tied` the
+// pixels where the scene itself names no winner (exact coplanar faces with the flush pass off, `offset=0`), and `wrong` also holds
+// shading steps within a face. A glTF needs `ids=1` (flat colour per part) or `facets=1` (per triangle) for the truth to read colours.
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import path from 'node:path';
import { chromium } from 'playwright';
@@ -44,9 +48,9 @@ async function probeTraps() {
for (const trap of await page.evaluate(() => window.flicker.traps)) {
await open(configuration, trap);
await page.waitForTimeout(300);
- const outcome = await page.evaluate(async () => ({ probe: await window.flicker.probe(), info: window.flicker.info }));
+ const outcome = await page.evaluate(async () => ({ probe: await window.flicker.probe(), info: window.flicker.info, truth: await window.flicker.truth() }));
await page.screenshot({ path: path.join(outputFolder, `${prefix}-${trap}-${label}.png`) });
- results.push({ trap, configuration: label, clear: outcome.probe.clearOfEdges, changed: outcome.probe.changed, moved: outcome.probe.totalChanged, ...(outcome.probe.open === undefined ? {} : { open: outcome.probe.open }), depth: outcome.info.depthMode });
+ results.push({ trap, configuration: label, clear: outcome.probe.clearOfEdges, changed: outcome.probe.changed, moved: outcome.probe.totalChanged, truth: outcome.truth, ...(outcome.probe.open === undefined ? {} : { open: outcome.probe.open }), depth: outcome.info.depthMode });
console.log(JSON.stringify(results.at(-1)));
}
}
@@ -71,10 +75,11 @@ try {
window.flicker.setCamera({ eye, target });
window.flicker.render();
const probe = await window.flicker.probe();
- return { probe, info: window.flicker.info };
+ const truth = await window.flicker.truth();
+ return { probe, truth, info: window.flicker.info };
}, spot);
await page.screenshot({ path: path.join(outputFolder, `${prefix}-${spot.name}-${label}.png`) });
- results.push({ spot: spot.name, moved: outcome.probe.totalChanged, configuration: label, clear: outcome.probe.clearOfEdges, changed: outcome.probe.changed, fraction: outcome.probe.fraction, depth: outcome.info.depthMode, near: outcome.info.near, far: outcome.info.far });
+ results.push({ spot: spot.name, moved: outcome.probe.totalChanged, configuration: label, truth: outcome.truth, clear: outcome.probe.clearOfEdges, changed: outcome.probe.changed, fraction: outcome.probe.fraction, depth: outcome.info.depthMode, near: outcome.info.near, far: outcome.info.far });
console.log(JSON.stringify(results.at(-1)));
}
}
diff --git a/bench/flicker/traps.js b/bench/flicker/traps.js
index 10bf78f3..cd27aa6b 100644
--- a/bench/flicker/traps.js
+++ b/bench/flicker/traps.js
@@ -120,6 +120,17 @@ function gappedWalls() {
};
}
+// A panel 1.5 cm in front of a wall, seen from 176 m: past the 1 cm a cut may open, so the panel is ranked, not cut. The case of
+// the glass reported in #751 (there as an unconfirmed `rank-overflow`), with an opaque panel so the probe can read its colour.
+function panelOnWallFar() {
+ const distance = 176;
+ return {
+ parts: [part('wall', [wallQuad([0, 30, 0], 120, 60, faceColour(0))]), part('panel', [wallQuad([0, 30, 0.015], 50, 30, faceColour(1))])],
+ eye: [distance * 0.3, 30 + distance * 0.1, distance],
+ target: [0, 30, 0],
+ };
+}
+
// 30 quads on exactly one plane in one mesh, each a little smaller than the one before, so every one shows as a ring.
function exactStack() {
return {
@@ -175,6 +186,7 @@ export const TRAPS = {
'kitbash-duplicates': kitbashedDuplicates,
'decal-grazing-2deg': grazingDecal,
'walls-16mm-1km-5deg': gappedWalls,
+ 'panel-15mm-176m': panelOnWallFar,
'stack-30-exact': exactStack,
'instanced-flush': instancedFlush,
'plaque-closeup-0.5m': plaqueCloseUp,
diff --git a/bench/flicker/viewer.js b/bench/flicker/viewer.js
index 81fa9df7..1298321c 100644
--- a/bench/flicker/viewer.js
+++ b/bench/flicker/viewer.js
@@ -6,6 +6,7 @@ import { parseGltf } from '../../src/gltf.js';
import { resolveFlushParts } from '../../src/coplanar-overlap.js';
import { flushOrderOf } from '../../src/depth-layer.js';
import { TRAPS } from './traps.js';
+import { collectWorldTriangles, castPixelOwners, compareWithGroundTruth } from './ground-truth.js';
// One flat colour per part, no textures, so a pixel's colour says which part owns it and a changed colour is a changed owner.
function paintPartsByOwner(parts) {
@@ -237,6 +238,26 @@ function readFrame(context) {
// `totalChanged` counts every pixel whose owner changed, edges included. `clearOfEdges` is stricter than `changed`: an anti-aliased
// edge blends two owners into a colour that is close to both, which the four-neighbour test reads as no edge, so this count also
// leaves out pixels with a colour step anywhere within two pixels.
+// The ground-truth probe (ground-truth.js): one frame, compared with a float64 ray cast that cannot z-fight. Needs flat colours
+// per part (ids=1) or per triangle (facets=1); the trap scenes bring their own. Returns the counts of compareWithGroundTruth
+// and the milliseconds the ray cast took.
+async function truth() {
+ if (!renderer) return null;
+ const { width, height } = canvas;
+ const scratch = document.createElement('canvas');
+ scratch.width = width;
+ scratch.height = height;
+ const context = scratch.getContext('2d', { willReadFrequently: true });
+ renderer.render(frameFor(0));
+ const pixels = new Uint8ClampedArray(readFrame(context));
+ const started = performance.now();
+ const world = collectWorldTriangles(window.flickerParts, flushOrderOf);
+ const cast = castPixelOwners(world, frameFor(0), width, height);
+ const { mismatchMask, ...counts } = compareWithGroundTruth({ pixels, world, cast, width, height });
+ renderer.render(frameFor(0));
+ return { ...counts, triangles: world.count, castMilliseconds: Math.round(performance.now() - started), width, height };
+}
+
async function probe() {
if (!renderer) return null;
if (!options.ids) {
@@ -451,7 +472,7 @@ bindControls();
requestAnimationFrame(tick);
document.querySelector('#speedValue').textContent = '';
window.flicker = {
- setCamera, probe, build, options, frameWholeScene,
+ setCamera, probe, truth, build, options, frameWholeScene,
get info() { return { depthMode: depthModeLabel(), ...(renderer ? nearAndFar() : {}), extent, bounds, canvas: [canvas.width, canvas.height], memory: renderer?.memoryReport?.(), flush: flushReport }; },
render: () => { markDirty(); renderer?.render(frameFor(0)); },
traps: Object.keys(TRAPS),
diff --git a/tests/flicker-ground-truth.test.js b/tests/flicker-ground-truth.test.js
new file mode 100644
index 00000000..a9ad4887
--- /dev/null
+++ b/tests/flicker-ground-truth.test.js
@@ -0,0 +1,172 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { collectWorldTriangles, castPixelOwners, compareWithGroundTruth, NO_TRIANGLE } from '../bench/flicker/ground-truth.js';
+import { resolveFlushParts } from '../src/coplanar-overlap.js';
+import { flushOrderOf } from '../src/depth-layer.js';
+
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+const WIDTH = 64;
+const HEIGHT = 48;
+const CENTRE = (HEIGHT / 2) * WIDTH + WIDTH / 2;
+const CAMERA = { eye: [0, 0, 10], target: [0, 0, 0], up: [0, 1, 0], fov: 45 };
+const RED = [1, 0, 0];
+const BLUE = [0, 0, 1];
+const WALL_PIXEL = [200, 20, 20];
+const PLAQUE_PIXEL = [20, 20, 200];
+
+// A quad in the plane z = depth, facing +z, with one flat colour.
+function wallPart(name, width, height, depth, colour, material = {}) {
+ const corners = [[-1, -1], [1, -1], [1, 1], [-1, 1]].map(([x, y]) => [x * width / 2, y * height / 2, depth]);
+ return {
+ name,
+ geometry: {
+ positions: new Float32Array(corners.flat()),
+ normals: new Float32Array(corners.flatMap(() => [0, 0, 1])),
+ colors: new Float32Array(corners.flatMap(() => colour)),
+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+ },
+ matrix: new Float32Array(IDENTITY),
+ material: { color: [1, 1, 1], ...material },
+ };
+}
+
+// A 12 m wall (triangles 0 and 1) and a 4 m plaque (triangles 2 and 3) `frontDepth` in front of it.
+function wallWithPlaque(frontDepth) {
+ return [wallPart('wall', 12, 12, 0, RED), wallPart('plaque', 4, 4, frontDepth, BLUE)];
+}
+
+// A frame in which every pixel shows the face the ray cast names, except where `override` gives another colour.
+function paintFrame(cast, override = () => null) {
+ const pixels = new Uint8ClampedArray(WIDTH * HEIGHT * 4);
+ for (let pixel = 0; pixel < WIDTH * HEIGHT; pixel++) {
+ const owner = cast.owner[pixel];
+ const truth = owner === NO_TRIANGLE ? [0, 0, 0] : owner >= 2 ? PLAQUE_PIXEL : WALL_PIXEL;
+ pixels.set([...(override(pixel) ?? truth), 255], pixel * 4);
+ }
+ return pixels;
+}
+
+function castWallWithPlaque(frontDepth) {
+ const world = collectWorldTriangles(wallWithPlaque(frontDepth), () => null);
+ return { world, cast: castPixelOwners(world, CAMERA, WIDTH, HEIGHT) };
+}
+
+test('the ray cast names the plaque in front of the wall, with the wall as its rival', () => {
+ const { world, cast } = castWallWithPlaque(0.01);
+ assert.equal(world.count, 4);
+ assert.ok(cast.owner[CENTRE] >= 2);
+ assert.equal(cast.rivals[CENTRE * 2], world.keyOf[0]);
+ assert.ok(cast.owner[0] >= 0 && cast.owner[0] < 2, 'the corner of the frame sees the wall');
+});
+
+test('a frame that shows the visible face everywhere has no wrong pixel', () => {
+ const { world, cast } = castWallWithPlaque(0.01);
+ const outcome = compareWithGroundTruth({ pixels: paintFrame(cast), world, cast, width: WIDTH, height: HEIGHT });
+ assert.ok(outcome.contested > 100, `contested ${outcome.contested}`);
+ assert.equal(outcome.wrong, 0);
+ assert.equal(outcome.swapped, 0);
+});
+
+test('plaque pixels that show the wall colour are swapped pixels, even beside a colour step', () => {
+ const { world, cast } = castWallWithPlaque(0.01);
+ const speckled = [CENTRE, CENTRE + 1, CENTRE + 2 * WIDTH];
+ const pixels = paintFrame(cast, pixel => (speckled.includes(pixel) ? WALL_PIXEL : null));
+ const outcome = compareWithGroundTruth({ pixels, world, cast, width: WIDTH, height: HEIGHT });
+ assert.equal(outcome.wrong, 3);
+ assert.equal(outcome.swapped, 3);
+});
+
+test('a pixel with another colour next to it is an edge, not a judged pixel', () => {
+ const { world, cast } = castWallWithPlaque(0.01);
+ const outcome = compareWithGroundTruth({ pixels: paintFrame(cast), world, cast, width: WIDTH, height: HEIGHT });
+ assert.ok(outcome.edge > 0);
+});
+
+test('a plaque exactly on the wall leaves the plaque alone at its place once the flush pass ran', () => {
+ const parts = wallWithPlaque(0);
+ resolveFlushParts(parts);
+ const world = collectWorldTriangles(parts, flushOrderOf);
+ const cast = castPixelOwners(world, CAMERA, WIDTH, HEIGHT);
+ assert.equal(world.keyOf[cast.owner[CENTRE]], world.keyOf[world.count - 1], 'the plaque is the visible face');
+ assert.equal(cast.rivals[CENTRE * 2], -1, 'nothing lies behind it once the wall is cut away');
+});
+
+test('the same plaque without the flush pass is a tie: counted as tied, never as a wrong pixel', () => {
+ const { world, cast } = castWallWithPlaque(0);
+ assert.equal(cast.tied[CENTRE], 1);
+ const pixels = paintFrame(cast, pixel => (pixel % 2 === 0 ? WALL_PIXEL : PLAQUE_PIXEL));
+ const outcome = compareWithGroundTruth({ pixels, world, cast, width: WIDTH, height: HEIGHT });
+ assert.ok(outcome.tied > 100, `tied ${outcome.tied}`);
+ assert.equal(outcome.wrong, 0);
+});
+
+// The case of the issue: glass 1 cm in front of a wall. It cannot be cut (it is not opaque), so it takes rank 1 above the wall;
+// two triangles in a chain of two never come near the 15 ranks.
+test('glass 1 cm in front of a large wall is ranked above it and is not a leftover', () => {
+ const parts = [wallPart('wall', 200, 200, 0, RED), wallPart('glass', 20, 20, 0.01, BLUE, { alphaMode: 'blend' })];
+ const resolved = resolveFlushParts(parts);
+ assert.deepEqual(resolved.leftovers, []);
+ assert.equal(resolved.ranked, 1);
+ assert.deepEqual(Array.from(flushOrderOf(parts[1]).triangleRanks), [1, 1]);
+ const world = collectWorldTriangles(parts, flushOrderOf);
+ assert.equal(world.count, 2, 'the blended glass is not collected');
+});
+
+test('a wall behind the eye is not hit, and one that crosses the eye plane still is', () => {
+ const behind = collectWorldTriangles([wallPart('behind', 12, 12, 20, RED)], () => null);
+ assert.ok(castPixelOwners(behind, CAMERA, WIDTH, HEIGHT).owner.every(owner => owner === NO_TRIANGLE));
+ const floor = wallPart('floor', 40, 40, 0, RED);
+ floor.geometry.positions = new Float32Array([-20, -2, 30, 20, -2, 30, 20, -2, -30, -20, -2, -30]);
+ floor.geometry.normals = new Float32Array(12).map((unused, index) => (index % 3 === 1 ? 1 : 0));
+ const crossing = collectWorldTriangles([floor], () => null);
+ const cast = castPixelOwners(crossing, CAMERA, WIDTH, HEIGHT);
+ assert.notEqual(cast.owner[(HEIGHT - 2) * WIDTH + WIDTH / 2], NO_TRIANGLE, 'the floor shows below the horizon');
+});
+
+// Moller-Trumbore for one ray, the slow way: the nearest triangle that faces the eye. Two triangles of one quad that meet on the
+// diagonal through a pixel centre tie, so the test compares quads (two triangles each), not triangles.
+function bruteForceOwner(world, origin, direction) {
+ let best = NO_TRIANGLE;
+ let bestDistance = Infinity;
+ for (let triangle = 0; triangle < world.count; triangle++) {
+ const c = world.corners.subarray(triangle * 9, triangle * 9 + 9);
+ const edgeOne = [c[3] - c[0], c[4] - c[1], c[5] - c[2]];
+ const edgeTwo = [c[6] - c[0], c[7] - c[1], c[8] - c[2]];
+ const pivot = [direction[1] * edgeTwo[2] - direction[2] * edgeTwo[1], direction[2] * edgeTwo[0] - direction[0] * edgeTwo[2], direction[0] * edgeTwo[1] - direction[1] * edgeTwo[0]];
+ const determinant = edgeOne[0] * pivot[0] + edgeOne[1] * pivot[1] + edgeOne[2] * pivot[2];
+ if (determinant <= 0) continue;
+ const toOrigin = [origin[0] - c[0], origin[1] - c[1], origin[2] - c[2]];
+ const u = (toOrigin[0] * pivot[0] + toOrigin[1] * pivot[1] + toOrigin[2] * pivot[2]) / determinant;
+ const cross = [toOrigin[1] * edgeOne[2] - toOrigin[2] * edgeOne[1], toOrigin[2] * edgeOne[0] - toOrigin[0] * edgeOne[2], toOrigin[0] * edgeOne[1] - toOrigin[1] * edgeOne[0]];
+ const v = (direction[0] * cross[0] + direction[1] * cross[1] + direction[2] * cross[2]) / determinant;
+ const distance = (edgeTwo[0] * cross[0] + edgeTwo[1] * cross[1] + edgeTwo[2] * cross[2]) / determinant;
+ if (u < 0 || v < 0 || u + v > 1 || distance <= 0 || distance >= bestDistance) continue;
+ best = triangle;
+ bestDistance = distance;
+ }
+ return best;
+}
+
+test('the scan-converted cast names the same face as a ray per pixel centre, on tilted overlapping quads', () => {
+ const parts = [wallPart('back', 14, 14, -3, RED), wallPart('middle', 6, 8, 0, BLUE), wallPart('front', 3, 3, 2, RED)];
+ parts[1].matrix = new Float32Array([0.9, 0, -0.4, 0, 0, 1, 0, 0, 0.4, 0, 0.9, 0, 1, 0.5, 0, 1]);
+ const world = collectWorldTriangles(parts, () => null);
+ const cast = castPixelOwners(world, CAMERA, WIDTH, HEIGHT);
+ const tangent = Math.tan(CAMERA.fov * Math.PI / 360);
+ let different = 0;
+ for (let y = 0; y < HEIGHT; y++) {
+ for (let x = 0; x < WIDTH; x++) {
+ const direction = [((x + 0.5) / WIDTH * 2 - 1) * (WIDTH / HEIGHT) * tangent, (1 - (y + 0.5) / HEIGHT * 2) * tangent, -1];
+ const expected = bruteForceOwner(world, CAMERA.eye, direction);
+ const found = cast.owner[y * WIDTH + x];
+ if (Math.floor(expected / 2) !== Math.floor(found / 2)) different++;
+ }
+ }
+ assert.ok(different <= 2, `${different} pixels differ`);
+});
+
+test('a one-sided face seen from behind is not hit', () => {
+ const world = collectWorldTriangles(wallWithPlaque(0.5), () => null);
+ const behind = castPixelOwners(world, { ...CAMERA, eye: [0, 0, -10] }, WIDTH, HEIGHT);
+ assert.ok(behind.owner.every(owner => owner === NO_TRIANGLE));
+});