Choose min-pix-per-spot adaptively per image for serial-stills indexing

For stills indexing the minimum-pixels-per-spot filter is now chosen per image
instead of being fixed: the frame is indexed at min-pix 3/2/1 and the setting that
maximises indexed-spot count weighted by indexed fraction (n_indexed^2 / n_total)
is kept, then integrated once at that min-pix. The fraction factor keeps a smaller
min-pix's extra spots only when the lattice actually explains them, so strong frames
retain their real weak spots (extending resolution) while noise-flooded frames stay
strict.

The mode is selected by the presence of --min-pix-per-spot, now optional
(SpotFindingSettings::min_pix_per_spot is std::optional<int64_t>): omit it for the
adaptive per-image path, give a value to force a fixed min-pix. It applies only to
the stills indexing path -- rotation indexing builds one global lattice and keeps a
fixed min-pix, and the online receiver and the FPGA host path always carry a concrete
value, so neither changes. IndexAndRefine::ProcessImage now returns whether the frame
indexed, to drive the per-image selection.

Exposed in the jfjoch_viewer spot-finding settings (adaptive-threshold and
adaptive-min-pix checkboxes, each greying out the control it overrides); the broker
uses neither.

Validated on the full rotation regression battery (no regression) and the whole
serial-stills target battery at full image count.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/CPU_DATA_ANALYSIS.md

@@ -219,6 +219,14 @@ Strong pixels are grouped into connected components (adjacent strong pixels) usi
 
 Spot-level filters include minimum/maximum pixel count and resolution limits.
 
+### 3.5 Adaptive per-image minimum spot size
+
+The minimum-pixels-per-spot filter (§3.4) trades sensitivity against noise: a small value keeps faint one- or two-pixel spots — real signal on strong data, but detector noise on high-background frames — while a larger value keeps only well-formed spots. The best value is dataset-dependent, so for serial-stills indexing it can be chosen **per image** rather than fixed. The frame is indexed three times, at min-pix 3, 2 and 1, and the setting that maximises
+
+$$ \frac{n_\mathrm{indexed}^2}{n_\mathrm{total}} \quad\text{(indexed-spot count weighted by indexed fraction)} $$
+
+is kept; the frame is then integrated once at that min-pix. The fraction factor discounts the extra spots a smaller min-pix admits *unless the lattice actually explains them*, so strong frames keep their real weak spots (extending resolution) while noise-flooded frames stay strict. Because min-pix filters the connected components *after* detection, the three attempts only repeat the cheap CCL and spot-level filter, not the pixel reduction; the azimuthal profile is identical across them. This is a **stills-only, indexing-path** option — rotation indexing builds one global lattice from all frames and keeps a fixed min-pix. In `rugnux` it is the default; giving an explicit `--min-pix-per-spot` pins a fixed value instead.
+
 ---
 
 ## 4. Indexing overview

docs/RUGNUX.md

@@ -150,15 +150,18 @@ then merge against a reference structure:
 rugnux serial_master.h5 \
     -o serial_run -N 32 \
     -X ffbidx -C 79,79,38,90,90,90 -S 96 \
-    --spot-sigma 4 \
+    --adaptive-spots \
     -z reference.mtz \
     --scaling-high-resolution 1.8
 ```
 
 `ffbidx` requires a known cell (`-C`) and is the indexer of choice for sparse serial stills. For
-weak serial data, tightening spot finding with `--spot-sigma 4` typically raises the indexing rate
-substantially. If a dataset *does* carry a goniometer axis but you want per-frame stills processing
-anyway, add `--force-still`.
+serial stills, prefer the self-calibrating spot finder (`--adaptive-spots`) and leave
+`--min-pix-per-spot` **unset** so it is chosen per image — across the still-target battery this
+combination raises the indexing rate and typically extends resolution over a fixed threshold and
+fixed min-pix, at equal or better CC½. (You can still pin a fixed threshold with `--spot-sigma` /
+`--spot-threshold` and a fixed min-pix with `--min-pix-per-spot`.) If a dataset *does* carry a
+goniometer axis but you want per-frame stills processing anyway, add `--force-still`.
 
 ## Command-line options
 
@@ -186,9 +189,11 @@ Spot finding:
 | --- | --- |
 | `--spot-sigma <num>` | Noise sigma level for spot finding (default: 3.0) |
 | `--spot-threshold <num>` | Photon-count threshold for spot finding (default: 10) |
+| `--adaptive-spots` | Self-calibrating detection: replace the fixed `--spot-threshold` with a per-resolution-ring threshold derived from each image's own noise, so one setting adapts across datasets (no per-dataset `--spot-threshold`/`--spot-sigma` tuning) |
+| `--spot-false-pixels <num>` | Adaptive-detection operating point: expected noise pixels tolerated per frame (default: 100; implies `--adaptive-spots`) |
 | `--spot-high-resolution <num>` | High-resolution limit for spot finding, Å (default: 1.5) |
 | `--spot-low-resolution <num>` | Low-resolution limit for spot finding, Å (default: 50; lower it, e.g. 24, to exclude the direct-beam halo on weak serial data) |
-| `--min-pix-per-spot <num>` | Minimum connected strong pixels per spot (default: 2; serial data can index better with 1 and a higher `--spot-threshold`) |
+| `--min-pix-per-spot <num>` | Minimum connected strong pixels per spot. **If omitted, min-pix is chosen per image** (stills indexing): the frame is indexed at min-pix 3/2/1 and the one maximising indexed-spot count × indexed fraction is kept. Give an explicit value to force a fixed min-pix instead. |
 | `--max-spots <num>` | Maximum spot count (default: 250) |
 | `--detect-ice-rings[=on\|off]` | Flag ice-ring spots (de-prioritised in indexing) and exclude ice-ring reflections from scaling/merging; overrides the dataset/master-file setting (default: use the dataset value) |