@woosh/meep-engine 3.2.0 → 3.4.0

package/src/shade/playground/skinned_blas_refit/diff_traced_against_rasterized.js

@@ -0,0 +1,745 @@
+import { use_flat_environment } from "./flat_environment.js";
+
+/**
+ * Render the current view both ways and show, pixel by pixel, where they disagree.
+ *
+ * "A piece looks missing under the tracer" is hard to judge by eye and easy to judge by counting.
+ * The two paths read the same deformed vertices — rasterization directly, the tracer through the
+ * BLAS — so wherever one covers a pixel and the other does not, exactly one of them is wrong about
+ * the geometry.
+ *
+ * What separates the two explanations is the *shape* of the disagreement, not its size:
+ *
+ *   - **Edge antialiasing.** Hundreds of components, most of them one pixel, scattered along
+ *     silhouettes, and roughly as many traced-only as raster-only. A mesh made of long thin slivers
+ *     has an enormous amount of silhouette, so this can run to a percent or two of covered pixels
+ *     and still mean nothing is missing.
+ *   - **Missing geometry.** One or a few large connected components, one-directional. A subtree the
+ *     tracer never reaches, or a set of triangles whose boxes do not contain them, comes out as a
+ *     blob rather than a rim.
+ *
+ * Two masks, because one of them has a blind spot. **Silhouette** disagreement is per-pixel
+ * covered-or-not, which says nothing about a sliver so thin that it only tints a pixel it shares
+ * with the sky — that pixel reads as background in both renderings. **Delta** disagreement catches
+ * those: any pixel whose two renderings differ by more than lighting plausibly explains. Delta is
+ * the noisier of the two and lights up on specular highlights; silhouette is the one that means
+ * geometry.
+ *
+ * Leaves the overlay on screen and returns the numbers. Call {@link clear_diff_overlay} to drop it.
+ */
+
+/**
+ * Sum of absolute channel differences above which two renderings of one pixel are saying different
+ * things about what is there. Lighting between a rasterized and a traced image differs everywhere,
+ * so this sits well above the ambient disagreement and below "one has sky, the other has a limb".
+ *
+ * @type {number}
+ */
+const DELTA_THRESHOLD = 90;
+
+/**
+ * A blob at least this big, and mostly one-directional, is geometry rather than a rim.
+ *
+ * @type {number}
+ */
+const BLOB_PIXELS = 400;
+
+/**
+ * Samples per pixel the comparison runs at by default.
+ *
+ * The tracer resolves primary visibility stochastically, so a triangle covering a few percent of a
+ * pixel needs tens of samples before one is likely to land on it. Below that it is simply absent,
+ * and the comparison reads that absence as missing geometry — which is the single most misleading
+ * thing this tool can do, because it is indistinguishable by shape from a real fault.
+ *
+ * @type {number}
+ */
+const DEFAULT_SAMPLES_PER_PIXEL = 24;
+
+/**
+ * How many frames one sample per pixel costs.
+ *
+ * The accumulator advances one tile per frame, so a frame is *not* a sample — at 1080x816 with
+ * 256-pixel tiles a single sample over the whole image takes twenty of them. Counting in frames is
+ * what made an earlier reading of this look like convergence had finished when it had barely
+ * started.
+ *
+ * @param {Renderer} renderer
+ * @returns {number}
+ */
+function frames_per_sample(renderer) {
+    const tile = renderer.path_tracer.render_tile_size;
+
+    const resolution = renderer.output_resolution;
+
+    if (!Number.isFinite(tile) || tile <= 0) {
+        return 1;
+    }
+
+    return Math.ceil(resolution.x / tile) * Math.ceil(resolution.y / tile);
+}
+
+/**
+ * The background of one image: the colour it is mostly made of.
+ *
+ * The capture runs under a flat environment (see `flat_environment`), so the background is one
+ * constant value covering more of the frame than any other colour — which makes "what is the
+ * background" a counting question with an exact answer, instead of a modelling question with a
+ * threshold.
+ *
+ * That is the whole reason the environment is swapped. Every previous version of this fitted a
+ * gradient and argued about tolerance: too tight and a noisy traced sky reads as geometry, too loose
+ * and a shadowed limb reads as sky, and there is no value that does both because under a photographed
+ * sky the two overlap. A constant background does not overlap with anything.
+ *
+ * The tolerance is small and fixed on purpose. A constant environment produces a constant radiance,
+ * so background pixels differ from the mode only by tone-mapping rounding — not by noise, because
+ * there is no variance to sample.
+ *
+ * @param {{data: Uint8ClampedArray, width: number, height: number}} image
+ * @returns {{sample: function(number, number): (number[]|null), tolerance: number, coverage: number}}
+ */
+function fit_flat_background(image) {
+    const { data, width, height } = image;
+
+    const counts = new Map();
+
+    let best = 0;
+    let best_key = -1;
+
+    // every fourth pixel each way — a mode does not need all of them, and this runs per capture
+    for (let y = 0; y < height; y += 4) {
+        for (let x = 0; x < width; x += 4) {
+            const i = (y * width + x) * 4;
+
+            const key = (data[i] << 16) | (data[i + 1] << 8) | data[i + 2];
+
+            const count = (counts.get(key) ?? 0) + 1;
+
+            counts.set(key, count);
+
+            if (count > best) {
+                best = count;
+                best_key = key;
+            }
+        }
+    }
+
+    const sampled = Math.ceil(height / 4) * Math.ceil(width / 4);
+
+    const colour = best_key < 0
+        ? null
+        : [(best_key >> 16) & 0xff, (best_key >> 8) & 0xff, best_key & 0xff];
+
+    return {
+        sample: () => colour,
+        tolerance: 12,
+        coverage: sampled === 0 ? 0 : best / sampled,
+    };
+}
+
+/**
+ * Is this pixel its own image's background?
+ *
+ * @param {Uint8ClampedArray} data
+ * @param {number} i byte index
+ * @param {number[]|null} sky the fitted background there, or null where none was sampled
+ * @returns {boolean}
+ */
+function is_background(data, i, sky, tolerance) {
+    return Math.abs(data[i] - sky[0])
+        + Math.abs(data[i + 1] - sky[1])
+        + Math.abs(data[i + 2] - sky[2]) <= tolerance;
+}
+
+/**
+ * A texture the renderer can draw into and this can read back out of, sized to the renderer's
+ * current output resolution.
+ *
+ * Not the canvas. A canvas texture is configured by the presentation path, cannot carry `COPY_SRC`,
+ * and is rotated away the moment the frame is presented — so a `drawImage` off it a task later
+ * comes back empty, which is how the first version of this managed to compare two blanks and call
+ * them identical. `render_to_target` exists for precisely this, and its own documentation says so.
+ *
+ * @param {Renderer} renderer
+ * @returns {Promise<{texture: GPUTexture, target: GPUTextureContext, width: number, height: number, bytes_per_row: number, buffer: GPUBuffer, destroy: function(): void}>}
+ */
+async function make_capture_target(renderer) {
+    const { GPUTextureContext } = await import('../../renderer/texture/GPUTextureContext.js');
+
+    const device = renderer.graphics.device;
+
+    const resolution = renderer.output_resolution;
+
+    const width = resolution.x;
+    const height = resolution.y;
+
+    // Same rule the renderer's own context configuration follows.
+    const format = window.matchMedia('(dynamic-range: high)').matches
+        ? 'rgba16float'
+        : navigator.gpu.getPreferredCanvasFormat();
+
+    const texture = device.createTexture({
+        label: 'diff/capture',
+        size: [width, height, 1],
+        format,
+        usage: GPUTextureUsage.RENDER_ATTACHMENT
+            | GPUTextureUsage.COPY_SRC
+            | GPUTextureUsage.COPY_DST
+            | GPUTextureUsage.TEXTURE_BINDING,
+    });
+
+    const bytes_per_pixel = format === 'rgba16float' ? 8 : 4;
+
+    // copyTextureToBuffer wants rows on a 256-byte boundary
+    const bytes_per_row = Math.ceil(width * bytes_per_pixel / 256) * 256;
+
+    const buffer = device.createBuffer({
+        label: 'diff/readback',
+        size: bytes_per_row * height,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    return {
+        texture,
+        target: GPUTextureContext.fromTexture(texture, device),
+        width,
+        height,
+        format,
+        bytes_per_row,
+        buffer,
+        destroy() {
+            texture.destroy();
+            buffer.destroy();
+        },
+    };
+}
+
+/**
+ * Half-precision float from its bits, for reading an HDR capture back.
+ *
+ * @param {number} bits
+ * @returns {number}
+ */
+function half_to_float(bits) {
+    const sign = (bits & 0x8000) ? -1 : 1;
+    const exponent = (bits >> 10) & 0x1f;
+    const fraction = bits & 0x3ff;
+
+    if (exponent === 0) {
+        return sign * fraction * 2 ** -24;
+    }
+
+    if (exponent === 31) {
+        return fraction === 0 ? sign * Infinity : NaN;
+    }
+
+    return sign * (1 + fraction / 1024) * 2 ** (exponent - 15);
+}
+
+/**
+ * Render the scene one way and read the pixels back as 8-bit RGBA.
+ *
+ * The accumulator is cleared and given a fixed number of frames at `dt = 0`, so the pose is frozen
+ * and both readings are of the same instant. Without that the tracer would be comparing a settled
+ * image against a moving one.
+ *
+ * @param {Renderer} renderer
+ * @param {PerspectiveCamera} camera
+ * @param {Scene} scene
+ * @param {object} capture from {@link make_capture_target}
+ * @param {boolean} traced
+ * @param {number} frames
+ * @returns {Promise<{data: Uint8ClampedArray, width: number, height: number}>}
+ */
+async function render_and_read(renderer, camera, scene, capture, traced, frames) {
+    const device = renderer.graphics.device;
+
+    renderer.feature_path_tracing_enabled = traced;
+    renderer.feature_taa_enabled = false;
+
+    renderer.path_tracer.clear_history = true;
+    renderer.indicate_view_change();
+
+    for (let i = 0; i < frames; i++) {
+        renderer.render_to_target(camera, scene, 0, capture.target);
+
+        await device.queue.onSubmittedWorkDone();
+    }
+
+    const encoder = device.createCommandEncoder({ label: 'diff/readback' });
+
+    encoder.copyTextureToBuffer(
+        { texture: capture.texture },
+        { buffer: capture.buffer, bytesPerRow: capture.bytes_per_row },
+        [capture.width, capture.height, 1]
+    );
+
+    device.queue.submit([encoder.finish()]);
+
+    await capture.buffer.mapAsync(GPUMapMode.READ);
+
+    const raw = capture.buffer.getMappedRange().slice(0);
+
+    capture.buffer.unmap();
+
+    const { width, height, bytes_per_row, format } = capture;
+
+    const data = new Uint8ClampedArray(width * height * 4);
+
+    // Flatten the padded rows, and bring an HDR capture down to 8 bits so both paths compare the
+    // same way. The comparison only ever asks "is this sky" and "how far apart are these", so a
+    // rough tone map is enough — it just has to be the same one for both renderings.
+    if (format === 'rgba16float') {
+        const source = new Uint16Array(raw);
+
+        for (let y = 0; y < height; y++) {
+            const row = y * bytes_per_row / 2;
+
+            for (let x = 0; x < width; x++) {
+                for (let channel = 0; channel < 4; channel++) {
+                    const value = half_to_float(source[row + x * 4 + channel]);
+
+                    data[(y * width + x) * 4 + channel] = channel === 3
+                        ? value * 255
+                        : Math.min(1, Math.max(0, value)) ** (1 / 2.2) * 255;
+                }
+            }
+        }
+    } else {
+        const source = new Uint8Array(raw);
+
+        const swizzle = format.startsWith('bgra');
+
+        for (let y = 0; y < height; y++) {
+            const row = y * bytes_per_row;
+
+            for (let x = 0; x < width; x++) {
+                const from = row + x * 4;
+                const to = (y * width + x) * 4;
+
+                data[to] = source[from + (swizzle ? 2 : 0)];
+                data[to + 1] = source[from + 1];
+                data[to + 2] = source[from + (swizzle ? 0 : 2)];
+                data[to + 3] = source[from + 3];
+            }
+        }
+    }
+
+    return { data, width, height };
+}
+
+/**
+ * Did we actually capture two renderings, or two copies of nothing?
+ *
+ * A `drawImage` off a WebGPU canvas gives back an empty bitmap when the frame was presented and
+ * replaced between the render and the read — which is exactly what happens while the page's own
+ * animation loop is still drawing over us. Every pixel then comes back transparent black, every
+ * pixel fails the background test, and the comparison reports a whole frame of agreement: a clean
+ * bill of health from a measurement that never happened.
+ *
+ * So the capture has to prove itself before its numbers are worth anything.
+ *
+ * @param {ImageData} traced
+ * @param {ImageData} rasterized
+ * @returns {string|null} why the capture is untrustworthy, or `null` if it is fine
+ */
+function capture_refusal(traced, rasterized) {
+    let lit = 0;
+    let differing = 0;
+
+    for (let i = 0; i < traced.data.length; i += 4) {
+        if (traced.data[i] > 0 || traced.data[i + 1] > 0 || traced.data[i + 2] > 0) {
+            lit += 1;
+        }
+
+        if (traced.data[i] !== rasterized.data[i]
+            || traced.data[i + 1] !== rasterized.data[i + 1]
+            || traced.data[i + 2] !== rasterized.data[i + 2]) {
+            differing += 1;
+        }
+    }
+
+    if (lit === 0) {
+        return 'the capture read back entirely black — nothing was rendered into it';
+    }
+
+    if (differing === 0) {
+        return 'both captures are byte-identical — the second render never reached the target';
+    }
+
+    return null;
+}
+
+/**
+ * Sizes of the connected runs of set pixels, largest first.
+ *
+ * Four-connected and iterative — a recursive flood fill blows the stack on a blob of any size, and
+ * a blob of some size is the thing this exists to find.
+ *
+ * @param {Uint8Array} mask one byte per pixel
+ * @param {number} width
+ * @param {number} height
+ * @returns {number[]}
+ */
+function component_sizes(mask, width, height) {
+    const seen = new Uint8Array(width * height);
+
+    const sizes = [];
+
+    for (let start = 0; start < mask.length; start++) {
+        if (mask[start] === 0 || seen[start] === 1) {
+            continue;
+        }
+
+        let size = 0;
+
+        const stack = [start];
+
+        seen[start] = 1;
+
+        while (stack.length > 0) {
+            const pixel = stack.pop();
+
+            size += 1;
+
+            const x = pixel % width;
+            const y = (pixel / width) | 0;
+
+            if (x > 0) { const n = pixel - 1; if (mask[n] && !seen[n]) { seen[n] = 1; stack.push(n); } }
+            if (x < width - 1) { const n = pixel + 1; if (mask[n] && !seen[n]) { seen[n] = 1; stack.push(n); } }
+            if (y > 0) { const n = pixel - width; if (mask[n] && !seen[n]) { seen[n] = 1; stack.push(n); } }
+            if (y < height - 1) { const n = pixel + width; if (mask[n] && !seen[n]) { seen[n] = 1; stack.push(n); } }
+        }
+
+        sizes.push(size);
+    }
+
+    sizes.sort((a, b) => b - a);
+
+    return sizes;
+}
+
+/**
+ * Drop the overlay {@link diff_traced_against_rasterized} left on screen.
+ */
+export function clear_diff_overlay() {
+    document.getElementById('blas_diff_overlay')?.remove();
+}
+
+/**
+ * @param {ImageData} traced
+ * @param {ImageData} rasterized
+ * @param {number} width
+ * @param {number} height
+ * @param {Uint8Array} delta
+ */
+function paint_overlay(traced, rasterized, width, height, delta, sky_traced, sky_rasterized) {
+    clear_diff_overlay();
+
+    const overlay = document.createElement('canvas');
+
+    overlay.id = 'blas_diff_overlay';
+    overlay.width = width;
+    overlay.height = height;
+
+    Object.assign(overlay.style, {
+        position: 'fixed',
+        inset: '0',
+        width: '100vw',
+        height: '100vh',
+        pointerEvents: 'none',
+        zIndex: '5',
+    });
+
+    const image = new ImageData(width, height);
+
+    for (let i = 0; i < image.data.length; i += 4) {
+        const pixel = i / 4;
+        const x = pixel % width;
+        const y = (pixel / width) | 0;
+
+        const in_traced = !is_background(traced.data, i, sky_traced.sample(x, y), sky_traced.tolerance);
+        const in_rasterized = !is_background(rasterized.data, i, sky_rasterized.sample(x, y), sky_rasterized.tolerance);
+
+        if (in_traced === in_rasterized) {
+            if (delta[i / 4] === 1) {
+                // agree about coverage, disagree about colour — a sliver sharing its pixel with the
+                // sky, or a highlight the two paths shade differently
+                image.data[i] = 230;
+                image.data[i + 1] = 200;
+                image.data[i + 2] = 60;
+                image.data[i + 3] = 130;
+
+                continue;
+            }
+
+            // agreement, whether that is geometry or sky — transparent, so the render shows through
+            image.data[i + 3] = 0;
+
+            continue;
+        }
+
+        // red: the rasterizer has it and the tracer does not — the direction that means the tree
+        // failed to deliver a triangle. Blue is the opposite, and a healthy image has both.
+        image.data[i] = in_rasterized ? 255 : 40;
+        image.data[i + 1] = in_rasterized ? 40 : 140;
+        image.data[i + 2] = in_rasterized ? 40 : 255;
+        image.data[i + 3] = 255;
+    }
+
+    overlay.getContext('2d').putImageData(image, 0, 0);
+
+    document.body.append(overlay);
+}
+
+/**
+ * Run the comparison from wherever the camera is now.
+ *
+ * `suspend` should hold off the page's own frame loop, so the renderer is not being asked to draw
+ * two different things at once. The capture itself no longer goes through the canvas.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {PerspectiveCamera} options.camera
+ * @param {Scene} options.scene
+ * @param {function(boolean): void} [options.suspend] called with `true` before capture and `false`
+ * after, to hold off the page's own frame loop
+ * @param {number} [options.samples] samples per pixel to accumulate before reading — not frames,
+ * see {@link frames_per_sample}
+ * @returns {Promise<object>}
+ */
+export async function diff_traced_against_rasterized({
+                                                         renderer,
+                                                         camera,
+                                                         scene,
+                                                         suspend = () => undefined,
+                                                         samples = DEFAULT_SAMPLES_PER_PIXEL,
+                                                     }) {
+    clear_diff_overlay();
+
+    const per_sample = frames_per_sample(renderer);
+
+    const frames = Math.max(1, Math.round(samples * per_sample));
+
+    // an eighth of the budget, but never so few that the control is pure noise
+    const control_frames = Math.max(per_sample, frames >> 3);
+
+    const was_traced = renderer.feature_path_tracing_enabled;
+    const was_taa = renderer.feature_taa_enabled;
+
+    suspend(true);
+
+    // A constant background for the duration. Every colour-based attempt to separate sky from
+    // geometry under a photographed sky has been wrong in a different direction — see
+    // `flat_environment` — and this makes the question trivial instead of delicate. Restored
+    // afterwards, so the page looks the way it did.
+    const restore_environment = use_flat_environment(scene);
+
+    let traced;
+    let rasterized;
+
+    // A control at a fraction of the sample budget. The tracer resolves primary visibility
+    // stochastically, so a triangle thin enough to cover a sliver of a pixel needs many samples
+    // before one lands on it — and until then the pixel reads as sky and the comparison calls it
+    // missing geometry. Under-convergence produces exactly the signature a real fault would:
+    // hundreds of raster-only pixels in blobs, one-directional.
+    //
+    // What separates them is that convergence *moves*. If the short run disagrees more than the
+    // long one, the number is still falling and no verdict off it is worth anything yet.
+    let control;
+
+    const capture = await make_capture_target(renderer);
+
+    try {
+        control = await render_and_read(renderer, camera, scene, capture, true, control_frames);
+
+        traced = await render_and_read(renderer, camera, scene, capture, true, frames);
+        rasterized = await render_and_read(renderer, camera, scene, capture, false, frames);
+    } finally {
+        capture.destroy();
+
+        restore_environment();
+
+        suspend(false);
+    }
+
+    const refusal = capture_refusal(traced, rasterized);
+
+    if (refusal !== null) {
+        renderer.feature_path_tracing_enabled = was_traced;
+        renderer.feature_taa_enabled = was_taa;
+
+        throw new Error(`${refusal} — the comparison would have reported agreement it never measured`);
+    }
+
+    const width = traced.width;
+    const height = traced.height;
+
+    const raster_only = new Uint8Array(width * height);
+    const traced_only = new Uint8Array(width * height);
+    const delta = new Uint8Array(width * height);
+
+    let both = 0;
+
+    // one per image, so a difference in exposure cannot masquerade as a difference in coverage
+    const sky_traced = fit_flat_background(traced);
+    const sky_rasterized = fit_flat_background(rasterized);
+    const sky_control = fit_flat_background(control);
+
+    for (let pixel = 0; pixel < width * height; pixel++) {
+        const i = pixel * 4;
+
+        const x = pixel % width;
+        const y = (pixel / width) | 0;
+
+        const in_traced = !is_background(traced.data, i, sky_traced.sample(x, y), sky_traced.tolerance);
+        const in_rasterized = !is_background(rasterized.data, i, sky_rasterized.sample(x, y), sky_rasterized.tolerance);
+
+        if (in_traced && in_rasterized) {
+            both += 1;
+        } else if (in_rasterized) {
+            raster_only[pixel] = 1;
+        } else if (in_traced) {
+            traced_only[pixel] = 1;
+        }
+
+        const difference = Math.abs(traced.data[i] - rasterized.data[i])
+            + Math.abs(traced.data[i + 1] - rasterized.data[i + 1])
+            + Math.abs(traced.data[i + 2] - rasterized.data[i + 2]);
+
+        if (difference > DELTA_THRESHOLD) {
+            delta[pixel] = 1;
+        }
+    }
+
+    // Split the colour disagreement by what the two renderings *agree* is there, because the two
+    // halves mean opposite things.
+    //
+    // Both called it sky, yet the colour differs: something tinted one image and not the other — a
+    // sliver too thin to own its pixel, which is precisely the geometry the silhouette mask cannot
+    // see. This is the half that means a triangle is missing.
+    //
+    // Both called it geometry: the two paths shaded the same surface differently. A traced specular
+    // highlight against a rasterized one disagrees violently and means nothing about the tree.
+    const delta_over_sky = new Uint8Array(width * height);
+    const delta_over_geometry = new Uint8Array(width * height);
+
+    for (let pixel = 0; pixel < width * height; pixel++) {
+        if (delta[pixel] === 0 || raster_only[pixel] === 1 || traced_only[pixel] === 1) {
+            continue;
+        }
+
+        if (is_background(rasterized.data, pixel * 4,
+            sky_rasterized.sample(pixel % width, (pixel / width) | 0), sky_rasterized.tolerance)) {
+            delta_over_sky[pixel] = 1;
+        } else {
+            delta_over_geometry[pixel] = 1;
+        }
+    }
+
+    const sizes = component_sizes(raster_only, width, height);
+    const delta_sizes = component_sizes(delta, width, height);
+    const sky_sizes = component_sizes(delta_over_sky, width, height);
+    const lit_sizes = component_sizes(delta_over_geometry, width, height);
+
+    const missing = sizes.reduce((a, b) => a + b, 0);
+    const extra = traced_only.reduce((a, b) => a + b, 0);
+
+    const covered = both + missing;
+
+    paint_overlay(traced, rasterized, width, height, delta, sky_traced, sky_rasterized);
+
+    renderer.feature_path_tracing_enabled = was_traced;
+    renderer.feature_taa_enabled = was_taa;
+    renderer.path_tracer.clear_history = true;
+    renderer.indicate_view_change();
+
+    const largest = sizes[0] ?? 0;
+    const median = sizes.length === 0 ? 0 : sizes[(sizes.length / 2) | 0];
+
+    // the same comparison the control would have produced, at an eighth of the samples
+    let control_missing = 0;
+
+    for (let pixel = 0; pixel < width * height; pixel++) {
+        const i = pixel * 4;
+
+        const x = pixel % width;
+        const y = (pixel / width) | 0;
+
+        if (!is_background(rasterized.data, i, sky_rasterized.sample(x, y), sky_rasterized.tolerance)
+            && is_background(control.data, i, sky_control.sample(x, y), sky_control.tolerance)) {
+            control_missing += 1;
+        }
+    }
+
+    // Both a ratio and an absolute floor. On a converged image the two counts differ by a handful
+    // of pixels of sampling noise, and a ratio alone would call that "still converging" forever.
+    const still_converging = control_missing > missing * 1.25
+        && control_missing - missing > BLOB_PIXELS / 2;
+
+    const result = {
+        resolution: [width, height],
+        covered,
+        raster_only: missing,
+        traced_only: extra,
+        raster_only_pct: covered === 0 ? 0 : +(missing / covered * 100).toFixed(2),
+        components: sizes.length,
+        largest_components: sizes.slice(0, 10),
+        median_component: median,
+        // the sliver-sensitive half: pixels the two renderings simply disagree about, whether or
+        // not either of them called it geometry
+        delta_pixels: delta_sizes.reduce((a, b) => a + b, 0),
+        delta_components: delta_sizes.length,
+        largest_delta_components: delta_sizes.slice(0, 10),
+        // sub-pixel geometry one path has and the other does not
+        delta_over_sky_pixels: sky_sizes.reduce((a, b) => a + b, 0),
+        largest_delta_over_sky: sky_sizes.slice(0, 10),
+        // the same surface, shaded differently — expected, and not about the tree
+        delta_over_geometry_pixels: lit_sizes.reduce((a, b) => a + b, 0),
+        largest_delta_over_geometry: lit_sizes.slice(0, 10),
+        samples,
+        frames,
+        frames_per_sample: per_sample,
+        control_samples: +(control_frames / per_sample).toFixed(2),
+        control_raster_only: control_missing,
+        still_converging,
+        // How far apart the two are on brightness alone, which is not a geometry fault but is worth
+        // knowing, because it is what makes a shaded limb hard to see against the sky
+        sky_traced: sky_traced.sample(0, 0),
+        sky_rasterized: sky_rasterized.sample(0, 0),
+        sky_tolerance: [sky_traced.tolerance, sky_rasterized.tolerance],
+        // what fraction of each image the background colour actually occupies — if the two disagree
+        // wildly, one of them is not showing the flat background and nothing below means anything
+        background_coverage: [
+            +sky_traced.coverage.toFixed(3),
+            +sky_rasterized.coverage.toFixed(3),
+        ],
+        silhouette_reliable: sky_traced.sample() !== null && sky_rasterized.sample() !== null,
+        // A blob is geometry the tracer never delivered. A rim is the two paths disagreeing about
+        // which side of an edge a pixel centre falls on, which they are entitled to do. And a count
+        // that is still falling with samples is neither yet.
+        verdict: sky_traced.sample() === null || sky_rasterized.sample() === null
+            ? `inconclusive — no background colour could be identified in one of the captures`
+            : still_converging
+            ? `still converging — ${control_missing} raster-only pixels at `
+            + `${(control_frames / per_sample).toFixed(1)} samples/pixel against ${missing} at `
+            + `${samples}, so the gap is sample count, not the tree. Raise samples until the two `
+            + `agree before reading anything into it.`
+            : largest >= BLOB_PIXELS && missing > extra * 2
+                ? `a ${largest}-pixel blob is missing under the tracer — that is geometry, not an edge`
+                : (lit_sizes[0] ?? 0) >= BLOB_PIXELS
+                    // Silhouettes agreeing is only half of "the same picture". A blob the two shade
+                    // completely differently is not a geometry fault, but reporting "edge
+                    // disagreement only" over the top of one is how this tool last missed the thing
+                    // it was pointed at.
+                    ? `silhouettes agree (largest ${largest} px), but ${lit_sizes[0]} pixels of one `
+                    + `surface are shaded very differently — brightness, not coverage`
+                    : `edge disagreement only — ${sizes.length} components, median ${median} px, `
+                    + `largest ${largest} px, and ${extra} pixels disagree the other way`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}