Module metrics 

Pure image metrics over CaptureImages (Plan 0013): pixel and shape difference plus coverage/spread, shared by the differential visual-QA tests and the shot CLI report.

Everything here is a pure function of its input pixels — no GPU, no clock, no allocation beyond the small working buffers. Not a per-frame hot path, but it lives under render/ so it carries the panic-denial pragma (and the hygiene guard needs it): written index- and panic-free throughout.

Structs

DrawExtent

How much of the drawn segment length landed inside the render target, summed over one LineRenderer::draw call (Plan 0069, ADR-0083).

StepResponse

How many frames a captured response took to settle after a step up and after the matching step down (Plan 0037, ADR-0039).

Constants

MIN_GROUND_SHARE

Minimum share of a frame that its modal luminance band must hold before that band is called a ground.

MIN_SHELL_LIT

Minimum share of a shell’s own pixels that must be lit for the shell to count as occupied in radial_shell_occupancy.

NO_GROUND

The reference tone modal_ground returns for a frame that has no ground — black, the same value a caller with no ground of its own supplies.

RADIAL_SHELLS

Concentric annuli radial_shell_occupancy divides the frame’s inscribed disc into. Ten equal-radius shells is the granularity the Plan 0065 lane’s one-off prototype measured with when it separated the four-ring mandala from the bare rosette (9 shells against 1, design-backlog 0072), and it is kept: coarse enough that a 96×96 capture gives the innermost shell a usable pixel count (~70), fine enough that “occupies most shells” cannot be satisfied by one ring and a halo.

SETTLE_FRAC

Fraction of a step’s total change the response must reach to count as settled. 0.9 is the textbook rise-time convention, and it is the one the one-pole arithmetic in ADR-0019 is quoted against: a smoother with time constant tau reaches it at t = tau * ln(10) = 2.303 * tau.

TONE_BANDS

Luminance buckets tonal_flatness histograms into. 16 over the 0..255 range makes each bucket 16 levels wide — narrow enough that a figure with any modelling at all spreads across several, wide enough that dithering and 8-bit quantization do not split one tone in two.

Functions

boundary_density

Perimeter of the lit figure over its area: the share of lit pixels having at least one unlit 4-neighbour (0.0..=1.0) — “is the lit set a solid mass, or does it have interior?”

coverage

Fraction of pixels whose RGB differs from bg by more than eps on any channel — “how much of the frame is lit” (0.0..=1.0). Alpha is ignored.

extent_diagnostic_on

Whether the in-frame geometry diagnostic is measuring on this thread.

footprint_diff

Mean absolute per-channel (RGB) difference measured over the union of lit pixels in the two frames rather than over the whole frame, normalized to 0.0..=1.0 — the footprint statistic of ADR-0091 (Plan 0077 Phase 1).

frame_diff

Mean absolute per-channel (RGB) difference between two images, normalized to 0.0..=1.0 (0 = identical, 1 = every channel maximally different). Mismatched dimensions read as fully different (1.0). Alpha is ignored — the capture background is opaque, so alpha carries no signal.

frames_to_settle

Index of the first frame in segment whose distance from segment[0] has reached settle_frac of the distance between the first and last frames.

mean_lit_level

Mean linear light over the lit set — the level statistic (ADR-0150), in 0.0..=1.0. 0.0 for a frame with no lit pixels, the convention tonal_flatness and boundary_density use.

modal_ground

The frame’s own ground: the mean RGB of its most populous luminance band, or NO_GROUND when no band holds more than MIN_GROUND_SHARE of it.

peak_to_mean

Ratio of the frame’s peak departure from its background luminance to the mean departure over every pixel — the crest factor, and the direct reading of has the population piled onto a few places? (Plan 0085 Phase 1).

quadrant_spread

How many of the four image quadrants contain at least one lit pixel (0..=4) — a cheap “not just a dot in one corner” spread check.

radial_shell_occupancy

How many of RADIAL_SHELLS concentric equal-radius annuli over the frame’s inscribed disc contain a meaningful share of lit pixels (0..=RADIAL_SHELLS) — a structural occupancy measure: at how many radii does this picture exist?

record_draw_extent

Record one measured draw, replacing whatever the slot held.

segment_settled

Whether segment’s last frame is close enough to its asymptote for frames_to_settle to mean anything — the question that function cannot answer about itself (Plan 0038 Phase 7).

set_extent_diagnostic

Turn the in-frame geometry diagnostic on or off for this thread, clearing any measurement already recorded. Off by default; the shipped render path never calls this.

srgb_decode_lut

The 256-entry sRGB→linear decode table, built once — the workspace’s one sRGB decode. A table rather than a powf per channel because frames_to_settle runs a full-frame difference per captured frame, and the probe is a whole sequence of them.

step_response

Measure a step response from two captured segments: rise starting at the last frame before the step up, fall starting at the last frame before the step down. Each segment’s own last frame is taken as its settled state.

struct_diff

Shape-aware difference in 0.0..=1.0: downscale each image to a small grayscale grid, take the Sobel edge magnitude, normalize each edge map by its own peak, and mean-abs-diff them. Normalizing per-image cancels overall contrast, so a recolor of the same shape scores low while a different shape scores high — the near-duplicate probe (an approximation of SSIM).

take_draw_extent

Take the extent of the most recent measured draw, leaving the slot empty. None when no line scene has drawn since the diagnostic was enabled (or when it is off) — distinct from a recorded draw whose fraction is None because nothing was drawn.

tonal_flatness

Share of the lit figure whose luminance falls inside the single most populated narrow luminance band (0.0..=1.0) — “does this picture have any tonal structure”.