rc179: everything on rc178 after its merge into main (#88), except the CHANGELOG

The rc178 branch continued after #88 was squash-merged; this is its content from b9ada7914 (the tree
#88 squashed) to 094eee31a, as one change on main. The individual commits stay on the rc178 branch:

- still battery: --cold evicts each set's input from the page cache; Alvra pixel masks; manifest fixes
- AGIPD: converter to one rigid panel per module, int16 photons, mask folded in; still battery reads the converted sets
- DetectorModules: panel look-up by id, plane -> panel, plane bounds and a per-pixel walk; mask size checked
- tests: [PanelLayout] equivalence harness, stacked vs assembled panel layout
- Dense per-pixel maps through the panel table (panel layout stage 1)
- Panel id on spots and the panel table in the start message
- Viewer and preview show a panel detector as it lies on the detector plane
- Panel layout stage 3: per-panel spot finding (CPU+GPU, CCL) and raster algorithms on the plane raster
- Panel layout stage 2: prediction and Bragg integration through the panel table
- XTC reader: frames handed up as stored, streams indexed in parallel
- XFEL reader: integer frames stay integer, one gain, placement by panel
- EXTERNAL_TEST_DATA_STILLS.md: images used vs the entry for every set; drop "Not in the battery"
- still battery: EuXFEL sets read the depositors' Cheetah CXI files directly; AGIPD converter removed
- float32_to_int16.py: a non-finite pixel becomes -32768, the int16 error marker, not a zero count
- CrystFEL geometry: read the pixel masks and bad regions instead of ignoring them
- Panel layout stage 5: the XFEL reader hands up the stored frame and its panel table
- Panel table persisted in NXmx; modulation grid and pre-scan memo key on the plane
- still battery: Alvra sets take their pixel mask from the CrystFEL geometry, not --mask-good
- still battery: take the deposited model as mmCIF where the RCSB has no PDB-format file
- still battery: dimple gets PDB-format coordinates converted from an mmCIF-only deposition
- stills fixed cost: geometry refinement and pre-scan do the same work in less wall time
- stills geometry sample and trial spot finding run as many workers as the image pass
- Stills integration: background ring reach measured on empty apertures, radial curvature from the whole frame
- StillsPartialityRefine: the partiality width is the run's, measured on the crystals, not the prediction window's
- MergeOnTheFly: capture term and multiplicative outlier band for the stills merge (both opt-in)
- Stills given a cell: the written cell is the mean over the frames that are merged
- Stills: the radial curvature correction decided per run on the same empty apertures
- StillsPartialityRefine: measure the run width only on shells with signal
- Stills pre-scan: report the paired z of the radial-correction comparison
- module placement: the five concurrent fits each keep every thread
- still battery: score R-free against the deposited data through the same dimple protocol
- still battery: the R-free target is the lower of the deposition's dimple and published values
- Stills: background clip follows the radial curve; signal disk from the lattice spacing
- Stills keep an overloaded observation as a lower bound instead of dropping it
- Stills: drop the lattice-spacing signal disk; the correction decision back on the plain clip
- battery: R-free against the deposition without refinement only, one protocol for rotation and stills
- still battery: EuXFEL sets run on a 2,000-image subset for now
- stills geometry refinement: fit the detector distance and the cell together
- stills geometry refinement: a distance given with --detector-distance is held in the joint fit
- Metal integration engine: back to its panel-s5 kernels; Mac stills keep the old clip, no saturation count
- Metal integration test: the CPU comparison runs on a rotation experiment
- Stills: kept overloads go back to the drop where they are not concentrated at low resolution
- stills distance search: an absolute 30-3000 mm scan, a sample found without d-limits, the fit iterated
- battery results: XFEL still battery 20261022-1358 on rc178 0cf62452c - 12 sets, cold, R_free unrefined
- battery results: still summary gains the resolution of our merge and of the deposition
- Pre-scan masks a pixel at the saturation limit on most frames, as one holding the error value
- Stills keep an overload as a lower bound only where it has pixels at the limit; run-level gate removed
- XFEL reader: a per-frame mask is read the way the frames are, its chunk inflated outside the HDF5 lock
- stills distance search: every centre scanned with a wider acceptance, a larger sample where nothing indexes
- rugnux usage: --beam-center-check describes the absolute 30-3000 mm stills distance scan, not the old 60-160 % grid
- stills: detector tilt refined in the geometry pre-pass, kept where held-out frames agree
- CLAUDE.md: the changelog is written once, just before the merge into main - condensed one-liners of what users get
- broker: serve the placed model and its maps of the last rugnux live run (/rugnux/model.cif, /rugnux/map.ccp4)
- frontend: Mol* viewer of the placed model and its density on the Rugnux live page
- writer: _model.cif from rugnux live keeps the input model's metadata, as the served model.cif does
- rugnux live maps: one unit cell centred on the model; the viewer opens on all of it
- Anomalous difference map: ANOM/PHANOM in _maps.mtz, /rugnux/map.ccp4?type=anom, a magenta mesh in the viewer
- Mol* viewer: open with the maps drawn within 10 A of the centre of view
- Mol* viewer: aaredb's structure-viewer setup, on a black stage
- rugnux: the gain of a stills file that states none is read off its single-photon peak where the background resolves photons
- Mol* viewer: in line with AareDB's StructureView at its current head (8ece2c2)
- ACKNOWLEDGEMENT: the web frontend's Mol* viewer follows AareDB's setup (G. Gotthard, PSI)
- stills tilt decision: the modules stay where the run placed them
- still battery: no distance pins and no per-set tuning flags; gain from the data except where a file's baseline hides it
- battery results: rc178 6f6f69 - full still battery and full rotation battery with REFMAC
- Bragg integration: a CCD rotation sweep's sigmas at the measured gain, intensities in photons
- BackgroundGain: the gain of a frame that resolves photons is the spacing of its photon peaks, so a baseline left in the frame no longer hides it
- ShadowFinder: measure the background's azimuthal modulation instead of predicting it from the polarization
- BackgroundGain: one gain estimate for rotation and stills; the still battery no longer gives EuXFEL 152 its gain
- ShadowFinder: measure the modulation robustly under a wide one-sided shadow
- ShadowFinderTest: a one-sided shadow is not fitted as part of the background's modulation
- ShadowFinder: back to the predicted polarization factor, in the plane the background shows
- MXAnalysisAfterFPGA: the Bragg engine's edge mask in the image's layout, so raw / untransformed FPGA runs start again
- battery results: still battery on rc178 e54f55 replaces the earlier rc178 still tables
- XFELReader: per-frame mask and photon conversion without a library call or a branch per pixel
- stills geometry trial: the hypotheses a search asks are indexed side by side
- stills tilt decision: the fits start beside the pre-scan and the geometry trial
- XFELReader: a deflated frame is inflated and converted a piece at a time, while it is in the cache
- XFELReader: a byte-shuffled frame is unshuffled a piece at a time, a whole pixel per step
- GeometryRefiner: residuals carry only the blocks a fit moves; beam and distance one block
- GeometryRefiner: a spot's residual differentiates its observed and predicted halves apart
- docs: EXTERNAL_TEST_DATA lists every open-arm battery set, with corrected values and counts
- battery: doc_check.py cross-checks the manifests against the dataset pages
- stills module placement: the placement fit gets half the threads, each held-out fit an eighth
- still battery: the EuXFEL sets run on all their frames, as the published still runs did
- battery results: still battery on rc178 a0ce6c, cold on a quiet machine, replaces the earlier rc178 table
- macOS build: explicit size_t in the XFEL reader's row bounds; parentheses in the CPU preprocessor's select

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015CeEGgpKdfkCTJb3YNMJcu

image_analysis/bragg_integration/BraggIntegrationEngine.cpp

@@ -13,6 +13,7 @@
 
 #include "../../common/JFJochMath.h"   // PI (M_PI is not standard, and MSVC does not define it)
 #include "../SensorAbsorption.h"
+#include "RingBackground.h"
 
 namespace {
 
@@ -51,7 +52,8 @@ std::map<RadialKernelKey, std::vector<float>> radial_kernel_cache;
 }   // namespace
 
 BraggIntegrationEngine::BraggIntegrationEngine(const DiffractionExperiment &experiment)
-    : geom(experiment.GetDiffractionGeometry()) {
+    : geom(experiment.GetDiffractionGeometry()), modules(experiment.GetModules()),
+      plane_bounds(modules.PlaneBounds(experiment.GetXPixelsNum(), experiment.GetYPixelsNum())) {
     const auto settings = experiment.GetBraggIntegrationSettings();
     const auto &det = experiment.GetDetectorSetup();
 
@@ -116,6 +118,7 @@ BraggIntegrationEngine::BraggIntegrationEngine(const DiffractionExperiment &expe
     // longer overrides it for broadband data.
     bkg_clip_nsigma = settings.GetBackgroundClipNSigma();
     bkg_pixel_gain = settings.GetBackgroundPixelGain();
+    pixel_gain = settings.GetPixelGain();
     bkg_trim = bkg_clip_nsigma > 0.0f ? 0.0f : settings.GetBackgroundTrimFraction();
 
     // Overlap treatment. Ownership is decided out to the fit grid's half size, which is where the
@@ -126,6 +129,8 @@ BraggIntegrationEngine::BraggIntegrationEngine(const DiffractionExperiment &expe
     if (overlap == OverlapMode::Exclude && mode == IntegratorMode::BoxSum)
         overlap = OverlapMode::Off;
     overlap_min_peak = settings.GetOverlapMinPeak();
+    keep_overloads = !experiment.IsRotationIndexing();
+    saturation_limit = static_cast<double>(experiment.GetSaturationLimit());
     claim = static_cast<float>(R);
     inv_claim = 1.0f / claim;
 
@@ -148,8 +153,8 @@ BraggIntegrationEngine::BraggIntegrationEngine(const DiffractionExperiment &expe
     // bkg_radial is raised after construction only by the auto mode (MXAnalysisWithoutFPGA), which
     // requires bkg_radial_auto, and the GPU allocates its curve buffers under the same condition.
     // n_kern is the largest row BraggStencilKernelIndex can select, plus one.
-    r_max = std::hypot(std::max<double>(beam_x, static_cast<double>(xpixel) - beam_x),
-                       std::max<double>(beam_y, static_cast<double>(ypixel) - beam_y));
+    r_max = std::hypot(std::max<double>(beam_x - plane_bounds.x0, plane_bounds.x1 - beam_x),
+                       std::max<double>(beam_y - plane_bounds.y0, plane_bounds.y1 - beam_y));
     bkg_radial_built = bkg_radial || bkg_radial_auto;
     const float grow_max = bkg_radial_built ? BraggStencilMaxGrow_px(static_cast<float>(r_max), stencil)
                                             : 0.0f;
@@ -217,10 +222,37 @@ void BraggIntegrationEngine::BuildRadialKernel(float grow) {
         k_diff.push_back(static_cast<float>(hist_ann[k] / sa - hist_disk[k] / sd));
 }
 
+void BraggIntegrationEngine::RadialBackgroundFromRings(const std::vector<float> &ring_bkg, int32_t q_bins,
+                                                       float low_q, float dq) {
+    radial_curve.clear();
+    const RingBackground rings(ring_bkg, q_bins, low_q, dq);
+    if (rings.empty())
+        return;
+    // The same bins as the engines' own curve: one per pixel of distance from the beam, out to the far
+    // corner.
+    const int n = static_cast<int>(std::ceil(r_max)) + 2;
+    const double two_k = 4.0 * PI / geom.GetWavelength_A();
+    radial_curve.resize(n);
+    for (int r = 0; r < n; ++r)
+        radial_curve[r] = static_cast<float>(rings.At(two_k * std::sin(0.5 * std::atan(r / F_px))));
+}
+
+std::vector<BraggPanel> BraggIntegrationEngine::Panels(const std::vector<Reflection> &predicted,
+                                                       size_t npredicted) const {
+    std::vector<BraggPanel> out(npredicted);
+    for (size_t i = 0; i < npredicted; ++i) {
+        const float x = predicted[i].predicted_x, y = predicted[i].predicted_y;
+        out[i] = MakeBraggPanel(modules, modules.ModuleOfImagePixel(x, y), static_cast<int64_t>(xpixel),
+                                static_cast<int64_t>(ypixel), x, y);
+    }
+    return out;
+}
+
 std::vector<Reflection> BraggIntegrationEngine::Finalize(const std::vector<Reflection> &predicted,
                                                          size_t npredicted,
+                                                         const std::vector<BraggPanel> &panels,
                                                          const std::vector<BraggFitResult> &results,
-                                                         int64_t image_number) const {
+                                                         int64_t image_number) {
     // Sized to what is kept, not to what was predicted: this vector is the one every image holds to the
     // end of the pass, and a background ring lost to the neighbours drops a reflection here - on a
     // dense pattern more than half of them, which a reserve of npredicted would carry as dead capacity.
@@ -234,10 +266,11 @@ std::vector<Reflection> BraggIntegrationEngine::Finalize(const std::vector<Refle
         if (!fr.ok)
             continue;
         Reflection refl = predicted[i];
-        refl.I = fr.I;
-        refl.sigma = fr.sigma;
-        refl.bkg = fr.bkg;
-        refl.var_bkg = fr.var_bkg;
+        // In photons: the engine measured in ADU, with variances already taken at the gain.
+        refl.I = fr.I / pixel_gain;
+        refl.sigma = fr.sigma / pixel_gain;
+        refl.bkg = fr.bkg / pixel_gain;
+        refl.var_bkg = fr.var_bkg / (pixel_gain * pixel_gain);
         if (fr.has_observed) {
             refl.observed_x = fr.observed_x;
             refl.observed_y = fr.observed_y;
@@ -245,9 +278,28 @@ std::vector<Reflection> BraggIntegrationEngine::Finalize(const std::vector<Refle
         // has_observed is set only for a signal disk every pixel of which was readable.
         refl.clipped = !fr.has_observed;
         refl.overloaded = fr.overloaded;
+        // A rotation merge drops the whole rocking event of an overloaded reflection. A still has no
+        // rocking event: its overloaded observations are the fully recorded ones of the strongest
+        // reflections, so dropping them leaves those reflections to their partial observations, whose
+        // partiality correction then sets the merged intensity - and it reads low. Measured on clipped
+        // CCD stills, the merged low-resolution intensities came out at 0.4-0.6x of the deposited ones.
+        // So a still keeps the observation as a lower bound: each saturated pixel counted at the
+        // saturation limit. (A fit to the unsaturated wings was tried and read lower still: the
+        // profile learned from unsaturated spots does not describe the wings of a clipped one.)
+        // That takes a pixel AT the limit: an observation overloaded only by pixels unreadable on
+        // this frame has nothing to count at the limit, and counting those pixels as zero is no
+        // lower bound of anything - it stays overloaded and is dropped. (A pixel stuck at the limit
+        // is no clipped spot either; the pre-scan masks it, HotPixelFinder.)
+        if (fr.overloaded && keep_overloads && fr.saturated > 0) {
+            refl.I = fr.I + static_cast<float>(fr.saturated * (saturation_limit - fr.bkg));
+            refl.sigma = std::sqrt(fr.var_bkg + std::max(refl.I, 1.0f));
+            refl.overloaded = false;
+            ++counts.overloads_kept;
+        }
         refl.observed = true;
         if (polarization)
-            refl.prescaling_corr /= geom.CalcAzIntPolarizationCorr(refl.predicted_x, refl.predicted_y, polarization.value());
+            refl.prescaling_corr /= geom.CalcAzIntPolarizationCorr(panels[i].plane_x, panels[i].plane_y,
+                                                                   polarization.value());
         refl.image_scale_corr = refl.prescaling_corr * refl.qe_corr * refl.flight_corr / refl.partiality;
         refl.image_number = static_cast<float>(image_number);
         out.push_back(refl);