Radial background: one mechanism for stills and rotation, decided per run on empty apertures (D5)

Wherever the correction is set for the whole run its curve is the frame's peak-excluded ring
background (the adaptive spot finder's, whole frame) and the ring's clip follows it - as stills have
done since integ-pal - now rotation too. One empty-aperture measurement (BackgroundAperture) decides
it for both workflows:

- The apertures' corrected difference is now taken as the integrator applies the correction: the
  clip follows the curve (each ring pixel's threshold raised by the curve's rise from the centre, in
  whole counts) as well as the kernel correction. Before, the tally clipped flat, so it measured a
  correction the engine never applies.
- Rotation measures the stencils the spot width can give it (r1 = 4, 5, 6 with the ring-area rule,
  RotationStencil) and decides on the one it gets, and separately on the pre-adaptive stencil the
  geometry pre-pass and the starvation guard return to.
- Stills: on wherever the corrected ring predicts the empty disk better (unchanged rule).
  Rotation: the frame's curve on every image only where it takes >= 10% of the apertures' mean
  square error away (ROTATION_RADIAL_MIN_GAIN); otherwise the existing per-image ice gate with the
  reflections' curve is left exactly as it was. Why a margin on rotation only: a still has no other
  correction, a sweep has one. Measured over 18 rotation sets (forced on every image): photon-counting
  sweeps gain 0.1-5% on the apertures (z 3-4) and lose ISa/anomalous signal when corrected
  (insulin, lysozyme, cytochrome c; 9yzk R-free +0.009 at 1.2%), as the earlier stills-rule trial
  found; the home-source CCD and smooth-ice runs gain 13-31%.

Result (CPU A/B vs 87684012f, 18 rotation sets): 12 .hkl byte-identical (every photon-counting
control without ice), 5uth R-free 0.210 -> 0.201 / ISa 10.4 -> 10.8, the ice set neutral; stills:
lcls242_s turns the correction on (the clip-following tally), R-free 0.2399 -> 0.2406.
No integration kernel changed; the tally is host code. Tests: BackgroundAperture_CorrectedClipFollowsTheCurve,
RadialHelps margins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015CeEGgpKdfkCTJb3YNMJcu
(cherry picked from commit dd3f3f2da39f5338e7dda1874bbdd535229bce98)

image_analysis/MXAnalysisWithoutFPGA.cpp

@@ -237,9 +237,11 @@ void MXAnalysisWithoutFPGA::Analyze(DataMessage &output,
         // Where no such background exists (no adaptive finder), auto leaves the correction off: the
         // plain profile carries the Bragg peaks and cannot support an absolute threshold.
         //
-        // On stills the correction also takes its CURVE from that background, and auto applies it to
-        // every image that has one (rugnux's pre-scan turns it off for a run whose empty apertures say
-        // the radial model does not hold there). A serial frame has a few dozen predicted reflections, so their own
+        // On stills - and wherever the correction is set for the whole run rather than left to auto, as
+        // rugnux's pre-scan sets it on a rotation run whose empty apertures ask for it - the correction
+        // takes its CURVE from that background, and on stills auto applies it to every image that has one
+        // (the pre-scan turns it off for a run whose empty apertures say the radial model does not hold
+        // there). A serial frame has a few dozen predicted reflections, so their own
         // ring pixels - where the curve comes from otherwise - sample the radial background sparsely,
         // while the finder's rings hold every pixel of the frame. And the correction is the measured
         // curvature itself: where the background has none it is zero, so there is nothing for a gate
@@ -254,7 +256,7 @@ void MXAnalysisWithoutFPGA::Analyze(DataMessage &output,
             const std::vector<float> &ring_bkg = spot_finding_settings.adaptive_threshold
                                                  ? adaptiveSpotFinder->GetRingBackground() : no_rings;
             const bool stills = !experiment.IsRotationIndexing();
-            if (stills)
+            if (stills || !bragg_engine->IsBackgroundRadialAuto())
                 bragg_engine->RadialBackgroundFromRings(ring_bkg, integration.GetQBinCount(),
                                                         integration.Settings().GetLowQ_recipA(),
                                                         integration.Settings().GetQSpacing_recipA());

image_analysis/bragg_integration/BackgroundAperture.cpp

@@ -91,9 +91,17 @@ void background_aperture::MeasureFrame(ImagePreprocessorBuffer &image, int width
         }
         disk_v /= static_cast<double>(disk.size());
         disk_b /= static_cast<double>(disk.size());
+        // The curve at the aperture's centre, which the corrected clip measures the ring's rise from.
+        double centre_b = 0.0;
+        if (!rings.empty()) {
+            const auto [px, py] = modules.ImageToPlane(panel, cx[a], cy[a]);
+            centre_b = rings.At(2.0 * PI / geometry.PxlToRes(static_cast<float>(px), static_cast<float>(py)));
+        }
 
-        // Every candidate ring as the integrator reads it: the mean, then one high-side clip pass. The
-        // radial correction is taken over the ring's geometry, as the integrator's kernel is.
+        // Every candidate ring as the integrator reads it: the mean, then one high-side clip pass. With the
+        // radial correction, as the integrator applies it: the clip follows the curve (each pixel's
+        // threshold raised by the curve's rise from the centre to it, in whole counts -
+        // RadialClipOffset), and the correction is taken over the ring's geometry, as the kernel is.
         std::vector<double> d_plain(r3.size()), d_radial(r3.size());
         bool measured = true;
         for (size_t k = 0; k < r3.size() && measured; ++k) {
@@ -112,17 +120,24 @@ void background_aperture::MeasureFrame(ImagePreprocessorBuffer &image, int width
             }
             const double mean = sum / n;
             const double thr = mean + clip_nsigma * std::sqrt(gain * std::max(mean, static_cast<double>(gain)));
-            double kept = 0.0;
-            int n_kept = 0;
-            for (const auto &p : ring)
-                if (p.d2 < r3_sq && (clip_nsigma <= 0.0f || p.v <= thr)) {
+            double kept = 0.0, kept_radial = 0.0;
+            int n_kept = 0, n_kept_radial = 0;
+            for (const auto &p : ring) {
+                if (p.d2 >= r3_sq)
+                    continue;
+                if (clip_nsigma <= 0.0f || p.v <= thr) {
                     kept += p.v;
                     ++n_kept;
                 }
-            measured = n_kept > 0;
+                if (clip_nsigma <= 0.0f || p.v <= thr + static_cast<double>(std::lround(p.b - centre_b))) {
+                    kept_radial += p.v;
+                    ++n_kept_radial;
+                }
+            }
+            measured = n_kept > 0 && n_kept_radial > 0;
             if (measured) {
                 d_plain[k] = disk_v - kept / n_kept;
-                d_radial[k] = d_plain[k] - (disk_b - sum_b / n);
+                d_radial[k] = disk_v - kept_radial / n_kept_radial - (disk_b - sum_b / n);
             }
         }
         if (!measured)
@@ -179,3 +194,9 @@ int background_aperture::Best(const std::vector<double> &mean_square) {
         return -1;
     return static_cast<int>(std::min_element(mean_square.begin(), mean_square.end()) - mean_square.begin());
 }
+
+bool background_aperture::RadialHelps(const Tally &tally, size_t k, double min_gain) {
+    if (tally.apertures == 0 || tally.apertures_radial != tally.apertures || k >= tally.sum_d2.size())
+        return false;
+    return tally.sum_d2_radial[k] < (1.0 - min_gain) * tally.sum_d2[k];
+}

image_analysis/bragg_integration/BackgroundAperture.h

@@ -32,12 +32,14 @@
 // mean + nsigma * sqrt(gain * mean)).
 //
 // The same apertures also say whether the radial background-curvature correction helps: each difference
-// is taken a second time with the correction applied - the frame's own ring background (RingBackground)
-// averaged over the ring's pixels minus over the disk's, which is what the integrator's kernel takes off a
-// reflection. Where the background really is a function of the radius the corrected ring predicts the
-// disk better; where it is not - a strongly polarised beam, panels of different response - it predicts it
-// worse, and the run measures which. The ring is chosen on the plain differences first, so its reach does
-// not rest on the radial model; the correction is then kept where it improves that ring.
+// is taken a second time with the correction applied as the integrator applies it - the ring's clip
+// following the frame's own ring background (RingBackground), and that background averaged over the
+// ring's pixels minus over the disk's, which is what the integrator's kernel takes off a reflection.
+// Where the background really is a function of the radius the corrected ring predicts the disk better;
+// where it is not - a strongly polarised beam, panels of different response - it predicts it worse, and
+// the run measures which. On stills the ring is chosen on the plain differences first, so its reach does
+// not rest on the radial model; the correction is then kept where it improves that ring. Rotation measures
+// every stencil the spot width can give it, and reads the one it gets.
 namespace background_aperture {
 
 // The squared disk-minus-ring differences, summed per candidate r3 over every aperture measured: plain,
@@ -56,6 +58,12 @@ struct Tally {
     [[nodiscard]] double RadialZ(size_t k) const;
 };
 
+// A signal disk r1, the inner edge of its ring r2, and the candidate outer edges r3.
+struct Stencil {
+    float r1 = 0.0f, r2 = 0.0f;
+    std::vector<float> r3;
+};
+
 // The candidate outer radii: from r2 + 2 up to max_r3, one pixel apart.
 [[nodiscard]] std::vector<float> CandidateR3(float r2, float max_r3);
 
@@ -69,6 +77,17 @@ void MeasureFrame(ImagePreprocessorBuffer &image, int width, int height,
                   const RingBackground &rings, const DiffractionGeometry &geometry,
                   const DetectorModules &modules, Tally &tally);
 
+// Whether the radial correction makes candidate k's ring predict the disk better - its mean square
+// difference lower by at least the fraction min_gain - on apertures that were all measured both ways.
+[[nodiscard]] bool RadialHelps(const Tally &tally, size_t k, double min_gain = 0.0);
+
+// The part of the background error the correction must take away on a rotation run. A still has no other
+// correction, so any gain is taken there; a rotation run already corrects the frames whose ice score shows
+// a smooth ring, and the frame's curve on every frame replaces that only for a clear gain. Measured: on
+// photon-counting sweeps the apertures gain 0.1-5% (z 3-4) and every image corrected costs ISa and
+// anomalous signal; where it pays - home-source CCD rings, a smooth ice ring - they gain 13-31%.
+constexpr double ROTATION_RADIAL_MIN_GAIN = 0.10;
+
 // The candidate with the smallest mean square difference, or -1 where nothing was measured.
 [[nodiscard]] int Best(const std::vector<double> &mean_square);