pub fn select_native_points(
b: &[u8],
width: usize,
height: usize,
region: Rect,
mask: Option<(&[u8], u8)>,
guide: Option<(Gray<'_>, usize)>,
) -> Vec<i64>Expand description
Picks the native-refinement sample points for b inside region: a step×step cell grid, keeping one
point per cell rather than sampling only the pixel at the cell’s corner (its lattice node). A node-only
sampler finds an edge with probability proportional to local edge density, so a sparse page (few edges
anywhere) starves the sample (< 12 points → Infinity, the true step read as “static”) and a
screen-fixed line that happens to align with a lattice row or column dominates it (every node on that row
is an edge, nothing else is) — see docs/ARCHITECTURE.md §五/§十. Depends only on b, region, mask and
guide, not on any hypothesis, so a caller evaluating several candidate displacements can select once and
reuse the points for all of them.
Without a guide: a full-resolution scan keeps, per cell, the pixel with the strongest native luma
gradient (ties broken by row-major order) — the exact per-cell argmax.
With guide = Some((g, f)) — g is b’s own analysis-scale gray at integer downscale factor f
(raster::downscale_gray; analysis pixel (ax, ay) covers the native block [ax·f, ax·f+f) × [ay·f, ay·f+f), edge blocks partial): coarse-to-fine instead of full-resolution. Per cell, first pick the
analysis pixel (among those whose native block intersects the cell, skipping the analysis image’s own
1px border and any pixel whose block centre fails mask) with the strongest analysis-scale gradient, then
the native pixel with the strongest native gradient inside that one analysis pixel’s block ∩ cell ∩ window
∩ mask — luma computed only for that handful of pixels and their four neighbours, not a full luma plane.
f = 1 makes g b’s own native luma one-for-one (downscale_gray’s factor == 1 branch), every block
a single pixel, and this reduce exactly to the unguided per-cell argmax — this is a property relied on
elsewhere (the f = 1 odometry parity cases), not merely incidental.