pub fn modal_ground(img: &CaptureImage) -> [u8; 4]Expand description
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.
Everything built on is_lit — coverage, quadrant_spread,
radial_shell_occupancy, tonal_flatness — asks how far does this
pixel depart from the ground, and passing a constant BLACK encodes an
unstated precondition: that the scene draws light onto a ground it does not
own. A scene that paints its own paper breaks it, and reads coverage
exactly 1.0 whatever it drew (ADR-0126). This derives the reference from
the frame instead, so the same question is asked correctly in both worlds.
The mean of the band’s members, not the band’s centre. An ink-on-paper
world’s paper is a specific off-white; rounding it to the middle of a
16-level band would hand is_lit a reference the frame does not contain,
and at EPS-scale tolerances that is the difference between a ground and a
second figure.
Luminance, not RGB. Plan 0116 Phase 1 tabled a coarse-RGB cluster and a border-only band beside this one over the whole shipped library: all three re-based the same presets, cost the same zero verdict changes, and repaired the same nothing. This is the simplest of the three that measured equivalent — the border variant assumes the ground reaches the frame edge, and the RGB variant buys a sparser histogram, neither for any measured return.
Ties resolve to the brightest tied band (the last maximum), which is arbitrary but deterministic — a duotone at equal populations has two grounds and no estimator over one histogram can pick between them.