The dynamic cutoff in C++, with SMAP's nearest-rank quantiles

[lanceXwq]

What

Detection's dynamic cutoff (median + factor × the 20–80 % slope of each frame's local maxima) is now computed in C++, and takes its quantiles the way SMAP does.

• Speed. The cutoff was a Python loop with three np.quantile calls per frame. csrc/cutoff.hpp now finds the three order statistics with nth_element, with frames split over threads (_fit3d.segment_cutoffs, called from DynamicCutoff.thresholds):

  200 frames	before	after
  cutoff step, 1500 maxima per frame	9.3 ms	1.1 ms
  find_candidates, 200 px	22 ms	15 ms
  find_candidates, 200 px, split frame	32 ms	17 ms

  The lexsort that NOTES.md suggested turns out to be slower than the loop (52 ms), and NOTES.md now says so.

• SMAP's quantiles. A quantile is now the ⌈n·p⌉-th smallest maximum (SMAP's myquantilefast), and the slope is divided by 0.8 - 0.2, as in SMAP's getdynamiccutoff. smappy used np.quantile's linear interpolation before, which is numpy's default; nothing records choosing it.

Effect on results

Measured on 2000 simulated frames at 200 px and 64 px, with and without a split:

• The cutoff differs in ~90 % of frames: by 0.04 % at 1500 maxima per frame and ~1 % at 140 maxima per frame. It always moves upward.
• 0.01–0.14 % of the candidates are dropped, all of them at the threshold. None are added.
• The four Fit plugins' versions are bumped (Gaussian 2D 2→3, Spline 3D 2→3, Spline 3D 2C 5→6, Gaussian 2D 2C 3→4). Their help pages and the example chain follow, so batch runs refit files done with the old cutoff.

Checks

• DynamicCutoff.__call__ matches a line-by-line transcription of SMAP's getdynamiccutoff bit for bit (5,000 random frames).
• The C++ kernel matches __call__ bit for bit (55,196 segments: several factors, one or many threads, ties, negative values, frames with fewer than 10 maxima). The final multiply-add is kept from being fused into an FMA. Clang fuses by default, and that moved a threshold by one ulp during development.
• New tests in tests/test_detect_roi.py:
  • a worked example of the nearest-rank quantiles;
  • block thresholds equal the per-frame cutoff, with and without the extension;
  • find_candidates keeps exactly what the per-frame loop keeps, with and without a split.
• pytest tests --slow -n auto: 1371 passed, 5 skipped (no GPU, Piper, calibration data or uiPSF on this machine). ci/smoke.py passes.

Not in this PR

The fit plugin's single-frame preview reports its cutoff from the top 1 % of all pixels in the filtered frame (plugins/fit.py, preview), not from the local maxima that detection uses. The reported number is far off the real one: 322 against 8.23 on the test_preview.py fixture. The candidates it draws are correct. This will be a separate fix.

🤖 Generated with Claude Code