3D engine that AI agents drive
Split offRay pixels by edge and bound true flips from above (part of #751)
Nguyen Xuan Anf847156cf698
diff --git a/bench/flicker/ground-truth.js b/bench/flicker/ground-truth.jsindex bcab9e63..60a21285 100644--- a/bench/flicker/ground-truth.js+++ b/bench/flicker/ground-truth.js@@ -124,11 +124,23 @@ function shownRank(world, cast, pixel, key) {return -1;}+// Whether any of the eight neighbours of a pixel has another visible triangle (or none): the pixel then sits within a pixel of an+// edge, silhouette or crease of the ray cast, where the rasteriser and the cast may disagree about which side the centre is on.+function touchesOwnerChange(owner, width, pixel) {+ const own = owner[pixel];+ for (let row = -1; row <= 1; row++) {+ for (let column = -1; column <= 1; column++) {+ if (owner[pixel + row * width + column] !== own) return true;+ }+ }+ return false;+}+// Says what a wrong pixel of an exact frame shows. The colour names a face: when that face lies on the ray (one of its six nearest// hits) the pixel is swapped, and it is flipped when the face has no higher rank than the one the ray cast puts in front. A face// that is not on the ray is the rasteriser and the ray cast disagreeing about a pixel centre (offRay), and a colour that names no// face is a blend of two (blended). Neither is depth fighting.-function classifyExactMismatch(result, mismatchMask, { pixels, pixel, world, cast, keyByColour }) {+function classifyExactMismatch(result, mismatchMask, { pixels, pixel, width, world, cast, keyByColour }) {const shownKey = keyByColour.get(`${pixels[pixel * 4]},${pixels[pixel * 4 + 1]},${pixels[pixel * 4 + 2]}`);if (shownKey === undefined) {result.blended++;@@ -137,6 +149,8 @@ function classifyExactMismatch(result, mismatchMask, { pixels, pixel, world, casconst rank = shownRank(world, cast, pixel, shownKey);if (rank < 0) {result.offRay++;+ if (touchesOwnerChange(cast.owner, width, pixel)) result.offRayEdge++;+ else result.offRayInterior++;return;}result.swapped++;@@ -154,6 +168,10 @@ function classifyExactMismatch(result, mismatchMask, { pixels, pixel, world, cas* - `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;* - `offRay` and `blended`: with `exact`, wrong pixels that show a face not on the ray, or no single face (see classifyExactMismatch);+ * - `offRayEdge` and `offRayInterior`: `offRay` split by whether the pixel touches an owner change of the ray cast in its 3x3+ * neighbourhood. Edge pixels are the rasteriser and the cast disagreeing about a pixel centre. An interior pixel has no such excuse:+ * its face may be one deeper than `hitsPerPixel` of the cast, which would be a real flip, so `flipped + offRayInterior` is the+ * upper bound of true flips (see `flipUpperBound`);* - `flipped`: with `exact`, the swapped pixels where the face shown has no higher rank than the face the ray cast puts in front, so* a face behind covers one in front and nothing in the scene asked for it: a true visibility flip. The rest of `swapped` is* `ranked`, a face that the flush pass deliberately lifts over the nearer one inside its bias, which is stable and not flicker;@@ -187,7 +205,7 @@ export function compareWithGroundTruth({ pixels, world, cast, width, height, exaconst 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, flipped: 0, ranked: 0, offRay: 0, blended: 0 };+ const result = { contested: 0, wrong: 0, swapped: 0, tied: 0, unjudged: 0, edge: 0, flipped: 0, ranked: 0, offRay: 0, offRayEdge: 0, offRayInterior: 0, blended: 0 };const keyByColour = new Map();references.forEach((reference, key) => { if (exact) keyByColour.set(reference.join(','), key); });const mismatchMask = new Uint8Array(width * height);@@ -213,7 +231,7 @@ export function compareWithGroundTruth({ pixels, world, cast, width, height, exaresult.wrong++;mismatchMask[pixel] = 1;if (exact) {- classifyExactMismatch(result, mismatchMask, { pixels, pixel, world, cast, keyByColour });+ classifyExactMismatch(result, mismatchMask, { pixels, pixel, width, world, cast, keyByColour });continue;}for (let slot = 0; slot < RIVALS_PER_PIXEL; slot++) {@@ -226,5 +244,5 @@ export function compareWithGroundTruth({ pixels, world, cast, width, height, exa}}}- return { ...result, mismatchMask };+ return { ...result, flipUpperBound: result.flipped + result.offRayInterior, mismatchMask };}diff --git a/bench/flicker/pixel-cast.js b/bench/flicker/pixel-cast.jsindex 70e8dd4e..f04b1993 100644--- a/bench/flicker/pixel-cast.js+++ b/bench/flicker/pixel-cast.js@@ -5,7 +5,7 @@export const NO_TRIANGLE = -1;export const RIVALS_PER_PIXEL = 2;const TIE_RELATIVE_DISTANCE = 1e-9;-const HITS_PER_PIXEL = 6;+export const DEFAULT_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;@@ -63,10 +63,11 @@ function isNearer(world, firstDistance, firstTriangle, secondDistance, secondTrireturn 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;+function recordHit(world, hits, pixel, distance, triangle) {+ const { hitDistances, hitTriangles, hitsPerPixel } = hits;+ const base = pixel * hitsPerPixel;let slot = 0;- while (slot < HITS_PER_PIXEL - 1 && hitTriangles[base + slot] !== NO_TRIANGLE) slot++;+ while (slot < hitsPerPixel - 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])) {@@ -79,7 +80,7 @@ function recordHit(world, hitDistances, hitTriangles, pixel, distance, 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) {+function rasterize(world, basis, triangle, points, width, height, hits) {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,@@ -101,7 +102,7 @@ function rasterize(world, basis, triangle, points, width, height, hitDistances,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);+ recordHit(world, hits, y * width + x, 1 / inverseDepth, triangle);}}}@@ -117,9 +118,9 @@ function facesEye(world, basis, triangle) {}// 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) {+function isTie(world, distances, triangles, base, hitsPerPixel) {const nearestTriangle = triangles[base];- for (let slot = 1; slot < HITS_PER_PIXEL && triangles[base + slot] !== NO_TRIANGLE; slot++) {+ for (let slot = 1; slot < hitsPerPixel && 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;@@ -131,20 +132,21 @@ function isTie(world, distances, triangles, base) {* 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, distance }`: `distance` is the depth of the visible face in front of the camera (0 for the background); `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+ * -1, and `tied` marks pixels where two faces of different colour lie at one distance with one rank. Only the `hitsPerPixel` (default 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) {+export function castPixelOwners(world, camera, width, height, hitsPerPixel = DEFAULT_HITS_PER_PIXEL) {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);+ const hitDistances = new Float64Array(width * height * hitsPerPixel);+ const hitTriangles = new Int32Array(width * height * hitsPerPixel).fill(NO_TRIANGLE);+ const hits = { hitDistances, hitTriangles, hitsPerPixel };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);+ rasterize(world, basis, triangle, [polygon[0], polygon[corner], polygon[corner + 1]], width, height, hits);}}const owner = new Int32Array(width * height).fill(NO_TRIANGLE);@@ -152,18 +154,18 @@ export function castPixelOwners(world, camera, width, height) {const tied = new Uint8Array(width * height);const distance = new Float64Array(width * height);for (let pixel = 0; pixel < width * height; pixel++) {- const base = pixel * HITS_PER_PIXEL;+ const base = pixel * hitsPerPixel;if (hitTriangles[base] === NO_TRIANGLE) continue;owner[pixel] = hitTriangles[base];distance[pixel] = hitDistances[base];- tied[pixel] = isTie(world, hitDistances, hitTriangles, base) ? 1 : 0;+ tied[pixel] = isTie(world, hitDistances, hitTriangles, base, hitsPerPixel) ? 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++) {+ for (let slot = 1; slot < hitsPerPixel && 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, distance, hitTriangles, hitDistances, hitsPerPixel: HITS_PER_PIXEL };+ return { owner, rivals, tied, distance, hitTriangles, hitDistances, hitsPerPixel };}diff --git a/bench/flicker/probe.mjs b/bench/flicker/probe.mjsindex 86b5968b..b67da119 100644--- a/bench/flicker/probe.mjs+++ b/bench/flicker/probe.mjs@@ -12,6 +12,8 @@// each pixel and no shading can pass for a swap. Then `flipped` is the count of true visibility flips (a face behind covers one in// front that is not ranked below it), `ranked` the swaps the flush pass asked for, `offRay` pixels showing a face the ray through the// pixel centre misses (the rasteriser and the ray cast disagree on an edge) and `blended` pixels no face explains.+// `offRayEdge` / `offRayInterior` split offRay by whether the pixel touches an owner change of the ray cast in its 3x3 neighbourhood;+// `flipUpperBound` = flipped + offRayInterior bounds the true flips from above. hits=N (viewer config) keeps N hits per ray, default 6.// --timeout <ms> sets the wait for a page step (default 240000).import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';import path from 'node:path';diff --git a/bench/flicker/viewer.js b/bench/flicker/viewer.jsindex ba8eac7e..559ab73c 100644--- a/bench/flicker/viewer.js+++ b/bench/flicker/viewer.js@@ -7,6 +7,7 @@ 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';+import { DEFAULT_HITS_PER_PIXEL } from './pixel-cast.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) {@@ -96,6 +97,8 @@ const options = {facets: parameters.get('facets') === '1' || parameters.get('facets') === '2',// facets=2: the colour of every triangle is its own number, drawn unlit, so the frame tells exactly which face is shown at a pixel.triangleIds: parameters.get('facets') === '2',+ // hits=N keeps the N nearest faces per ray in the ray cast (default 6, at most 64): a deeper stack than that shows up as offRay.+ hitsPerPixel: Math.min(64, Math.max(1, Number(parameters.get('hits')) || DEFAULT_HITS_PER_PIXEL)),};const trapName = parameters.get('trap');@@ -264,7 +267,7 @@ async function truth() {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 cast = castPixelOwners(world, frameFor(0), width, height, options.hitsPerPixel);const { mismatchMask, ...counts } = compareWithGroundTruth({ pixels, world, cast, width, height, exact: options.triangleIds ? shownByte : null });renderer.render(frameFor(0));return { ...counts, triangles: world.count, castMilliseconds: Math.round(performance.now() - started), width, height };@@ -318,7 +321,7 @@ function swapDetails(limit = 12) {renderer.render(frameFor(0));const pixels = new Uint8ClampedArray(readFrame(context));const world = collectWorldTriangles(window.flickerParts, flushOrderOf);- const cast = castPixelOwners(world, frameFor(0), width, height);+ const cast = castPixelOwners(world, frameFor(0), width, height, options.hitsPerPixel);const { mismatchMask } = compareWithGroundTruth({ pixels, world, cast, width, height, exact: options.triangleIds ? shownByte : null });const groups = new Map();for (let pixel = 0; pixel < mismatchMask.length; pixel++) {diff --git a/changes/751-offray-edges.md b/changes/751-offray-edges.mdnew file mode 100644index 00000000..1722f030--- /dev/null+++ b/changes/751-offray-edges.md@@ -0,0 +1 @@+- The flicker probe splits offRay pixels into edge and interior ones, reports an upper bound of true flips, and keeps a configurable number of ray hits (#751)diff --git a/tests/flicker-ground-truth.test.js b/tests/flicker-ground-truth.test.jsindex 2026a2ba..58bcf6c8 100644--- a/tests/flicker-ground-truth.test.js+++ b/tests/flicker-ground-truth.test.js@@ -261,7 +261,51 @@ test('an exact frame showing a face off the ray, or a colour no face has, is notconst outcome = compareExact(paintExactFrame(cast, pixel => (pixel === CENTRE ? [0, 255, 0] : pixel === CENTRE + 1 ? [7, 7, 7] : null)), world, cast);assert.equal(outcome.wrong, 2);assert.equal(outcome.offRay, 1);+ assert.equal(outcome.offRayEdge, 1, 'the middle of the plaque sits on its diagonal, a seam of the ray cast');+ assert.equal(outcome.offRayInterior, 0);+ assert.equal(outcome.flipUpperBound, 0);assert.equal(outcome.blended, 1);assert.equal(outcome.swapped, 0);assert.equal(outcome.flipped, 0);});++test('an offRay pixel on a triangle edge of the ray cast is split off from one in the interior of a face', () => {+ const parts = [...wallWithPlaque(0.01), wallPart('far-side', 2, 2, 0, [0, 1, 0])];+ parts[2].matrix = new Float32Array([...IDENTITY.slice(0, 12), 500, 0, 0, 1]);+ const world = collectWorldTriangles(parts, () => null);+ const cast = castPixelOwners(world, CAMERA, WIDTH, HEIGHT);+ const seam = [...cast.owner.keys()].find(pixel => cast.owner[pixel] >= 2 && cast.owner[pixel + 1] >= 2 && cast.owner[pixel] !== cast.owner[pixel + 1]+ && cast.owner[pixel - WIDTH] >= 2 && cast.owner[pixel + WIDTH] >= 2);+ assert.ok(seam > 0, 'the plaque diagonal has a pixel whose neighbours are all plaque');+ const outcome = compareExact(paintExactFrame(cast, pixel => (pixel === seam ? [0, 255, 0] : pixel === CENTRE - 5 * WIDTH ? [0, 255, 0] : null)), world, cast);+ assert.equal(outcome.offRay, 2);+ assert.equal(outcome.offRayEdge, 1);+ assert.equal(outcome.offRayInterior, 1);+ assert.equal(outcome.flipUpperBound, 1);+});++// A wall under seven more faces, each 1 cm in front of the last: the wall is the eighth hit of every ray through the middle.+function deepStack() {+ const parts = [wallPart('wall', 12, 12, 0, RED)];+ for (let layer = 1; layer <= 7; layer++) {+ parts.push(wallPart(`layer-${layer}`, 4, 4, layer * 0.01, layer === 7 ? BLUE : [0, layer / 10, 0]));+ }+ const world = collectWorldTriangles(parts, () => null);+ return { world, cast: (hitsPerPixel) => castPixelOwners(world, CAMERA, WIDTH, HEIGHT, hitsPerPixel) };+}++test('a face deeper than the hits kept per ray is offRay, and a flip once the cast keeps enough hits', () => {+ const { world, cast: castWith } = deepStack();+ const showWall = pixel => (pixel === CENTRE + 4 ? [255, 0, 0] : null);+ const shallow = castWith(6);+ const shallowOutcome = compareExact(paintExactFrame(shallow, showWall), world, shallow);+ assert.equal(shallowOutcome.offRayInterior, 1);+ assert.equal(shallowOutcome.flipped, 0);+ assert.equal(shallowOutcome.flipUpperBound, 1);+ const deep = castWith(8);+ assert.equal(deep.hitsPerPixel, 8);+ const deepOutcome = compareExact(paintExactFrame(deep, showWall), world, deep);+ assert.equal(deepOutcome.offRay, 0);+ assert.equal(deepOutcome.flipped, 1);+ assert.equal(deepOutcome.flipUpperBound, 1);+});