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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.mjsindex 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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));+});