v1.0.0-rc.178 (#88)

* Rugnux: Processes serial crystallography data from XFELs - SACLA (MPCCD), PAL-XFEL and European XFEL (CXI), LCLS (XTC) and SwissFEL Alvra (JUNGFRAU with a CrystFEL module geometry) - with several files or Jungfraujoch master files merged in one run (`rugnux *_master.h5`).
* Rugnux: Stills processing takes a known unit cell and space group as a starting point, finds the beam centre (and, with a cell, the detector distance) from the images, detects the saturation level in other facilities' files and refines the placement of individual detector panels.
* Rugnux: The stills report gives R_split and CC1/2 from frame half-sets, comparable with CrystFEL.
* jfjoch_viewer: Opens the same XFEL file formats.
* Validation: A stills battery checks Rugnux against deposited structures from SACLA, PAL-XFEL, LCLS, European XFEL and SwissFEL.
* Rugnux: More reliable convergence of rotation scaling, and live molecular replacement starts as soon as the model is uploaded.
* jfjoch_broker: Initialize clears the previous dataset's bearer tokens, image buffer and live Rugnux status, and a slow CUDA JIT cache is reported at start.

Reviewed-on: #88
Co-authored-by: Filip Leonarski <filip.leonarski@psi.ch>

image_analysis/image_preprocessing/CMakeLists.txt

@@ -2,7 +2,9 @@ ADD_LIBRARY(JFJochImagePreprocessing STATIC ImagePreprocessor.cpp ImagePreproces
         ImagePreprocessorCPU.cpp
         ImagePreprocessorCPU.h
         ImagePreprocessorBuffer.cpp
-        ImagePreprocessorBuffer.h)
+        ImagePreprocessorBuffer.h
+        SaturationCeiling.cpp
+        SaturationCeiling.h)
 
 TARGET_LINK_LIBRARIES(JFJochImagePreprocessing JFJochCommon)
 

image_analysis/image_preprocessing/SaturationCeiling.cpp

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
+// SPDX-License-Identifier: GPL-3.0-only
+
+#include "SaturationCeiling.h"
+
+#include <algorithm>
+#include <cmath>
+
+namespace saturation_ceiling {
+
+namespace {
+
+int Bin(int64_t value) {
+    return static_cast<int>(std::floor(std::log2(static_cast<double>(value) / FLOOR) * BINS_PER_OCTAVE));
+}
+
+int64_t LowerEdge(int bin) {
+    return static_cast<int64_t>(std::ceil(FLOOR * std::exp2(static_cast<double>(bin) / BINS_PER_OCTAVE)));
+}
+
+}  // namespace
+
+void Add(Histogram &h, int64_t value) {
+    if (value < FLOOR)
+        return;
+    const int b = Bin(value);
+    if (b < N_BINS)
+        h[b]++;
+}
+
+void Add(Histogram &h, const std::vector<int32_t> &values, const std::vector<uint32_t> &mask) {
+    for (size_t i = 0; i < values.size(); i++)
+        if (i >= mask.size() || mask[i] == 0)
+            Add(h, values[i]);
+}
+
+std::optional<int64_t> Ceiling(const Histogram &h) {
+    for (int b = WINDOW; b < N_BINS; b++) {
+        const uint64_t below = *std::max_element(h.begin() + b - WINDOW, h.begin() + b);
+        if (h[b] >= MIN_PIXELS && static_cast<double>(h[b]) > RISE * static_cast<double>(below))
+            return LowerEdge(b);
+    }
+    return std::nullopt;
+}
+
+}  // namespace saturation_ceiling

image_analysis/image_preprocessing/SaturationCeiling.h

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
+// SPDX-License-Identifier: GPL-3.0-only
+
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <optional>
+#include <vector>
+
+// Where a detector's pixel values stop, read off the values themselves. The bright tail of a frame -
+// the cores of Bragg peaks - falls off steadily with value; a detector that saturates clips everything
+// beyond its ceiling down to it, so the values pile up just below where they stop. Where each pixel has
+// its own ceiling (an ADC limit less that pixel's dark), the pile-up is a band rather than one value,
+// and its lower edge is where clipping starts. A file's own statement of the limit is often missing
+// or wrong for detectors outside the facility that wrote it.
+namespace saturation_ceiling {
+
+// Values are binned on a log scale, BINS_PER_OCTAVE to a factor of two, from FLOOR up: a bin of the
+// tail is then about 1% wide, narrow enough to place the edge, while below FLOOR a bin is narrower
+// than one integer and the counts jump between neighbouring bins for no reason in the data.
+constexpr int BINS_PER_OCTAVE = 64;
+constexpr int64_t FLOOR = 256;
+constexpr int N_BINS = BINS_PER_OCTAVE * 23;   // up to 2^31
+// A pile-up bin holds more than RISE times the most any bin in the WINDOW below it held - a tail that
+// only falls never does that - and at least MIN_PIXELS pixel values.
+constexpr double RISE = 2.0;
+constexpr int WINDOW = 8;
+constexpr uint64_t MIN_PIXELS = 50;
+
+using Histogram = std::array<uint64_t, N_BINS>;
+
+void Add(Histogram &h, const std::vector<int32_t> &values, const std::vector<uint32_t> &mask);
+void Add(Histogram &h, int64_t value);
+
+// The lower edge of the lowest bin that rises above the tail below it, if any does.
+std::optional<int64_t> Ceiling(const Histogram &h);
+
+}  // namespace saturation_ceiling