Build Packages / Create release (push) Successful in 8s
Build Packages / build:portable:macos-arm64:nocuda (push) Successful in 5m11s
Build Packages / build:rugnux:linux-aarch64:cuda (push) Successful in 10m32s
Build Packages / build:portable:linux-x86_64:nocuda (push) Successful in 18m26s
Build Packages / build:portable:linux-x86_64:cuda (push) Successful in 22m11s
Build Packages / build:jfjoch:ubuntu2204:nocuda (push) Successful in 23m32s
Build Packages / build:portable:windows-x86_64:nocuda (push) Successful in 25m36s
Build Packages / build:jfjoch:rocky8:nocuda (push) Successful in 27m28s
Build Packages / HDF5 consumer tests (DIALS, XDS) (push) Successful in 28m10s
Build Packages / build:jfjoch:rocky9:nocuda (push) Successful in 28m10s
Build Packages / build:portable:windows-x86_64:cuda (push) Successful in 29m24s
Build Packages / build:jfjoch:ubuntu2404:nocuda (push) Successful in 21m45s
Build Packages / Generate python client (push) Successful in 31s
Build Packages / Build documentation (push) Successful in 1m21s
Build Packages / build:jfjoch:rocky8:cuda-sls9 (push) Successful in 24m2s
Build Packages / build:jfjoch:rocky9:cuda-sls9 (push) Successful in 29m25s
Build Packages / build:jfjoch:rocky8:cuda (push) Successful in 30m27s
Build Packages / build:jfjoch:ubuntu2204:cuda (push) Successful in 27m12s
Build Packages / build:jfjoch:ubuntu2404:cuda (push) Successful in 32m20s
Build Packages / build:jfjoch:rocky9:cuda (push) Successful in 33m36s
Build Packages / Unit tests (push) Successful in 2h7m18s
Build Packages / Validation Battery (push) Successful in 33m19s
* Rugnux: Stills processing needs only the unit cell and space group beyond what the file records - detector distance, beam centre, tilt, panel placement, saturation level, gain and polarisation plane are found from the images - and is up to twice as fast. * Rugnux: Stills can be indexed without a GPU, with a CPU implementation of the fast-feedback indexer (macOS, computers without a GPU). * Rugnux: Rotation and stills data are integrated in the detector's own units with one gain model, improving data from CCD detectors. * Web frontend: The Rugnux live page shows the placed model with its electron density and anomalous difference map in a Mol* viewer. Reviewed-on: #90 Co-authored-by: Filip Leonarski <filip.leonarski@psi.ch>
79 lines
4.4 KiB
C++
79 lines
4.4 KiB
C++
// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
|
|
// SPDX-License-Identifier: GPL-3.0-only
|
|
|
|
#pragma once
|
|
|
|
#include <array>
|
|
#include <cstddef>
|
|
#include <cstdint>
|
|
#include <optional>
|
|
#include <vector>
|
|
|
|
// The background noise of a detector that reports ADU rather than counted photons. For a photon
|
|
// counter a background pixel's variance equals its mean; a CCD's pixel value is a gain times the
|
|
// photons plus read noise, so its variance is g*mean (+ a constant). The gain is not in the headers
|
|
// (an SMV file states none, every marCCD file states the writer's default of 1 ADU/photon), so it is
|
|
// measured: the variance per unit mean of the difference between two pixels two columns apart, which
|
|
// share the background, but are far enough apart that the detector's point spread does not correlate
|
|
// them. Bragg peaks and zingers are clipped per level. Taken per level (bins of the pair's mean, a
|
|
// factor 1.25 wide) and summarised as the median ratio over all pairs, i.e. over the background that
|
|
// holds most of the pixels.
|
|
//
|
|
// The variance/mean of pixels in a neighbourhood is how XDS fills its GAIN table (INIT step,
|
|
// Kabsch (2010) Acta Cryst. D66, 125-132).
|
|
namespace background_gain {
|
|
|
|
constexpr int N_BINS = 64; // levels 1.25^0 .. 1.25^63, i.e. up to ~1.3e6 ADU
|
|
constexpr size_t MIN_PAIRS_PER_BIN = 1000;
|
|
constexpr size_t MIN_BINS = 3;
|
|
// Frames of the pre-scan sample it is measured on, spread over the sample. The answer moves by under
|
|
// 1 % between frames of a sweep, so more only cost time.
|
|
constexpr size_t GAIN_MAX_FRAMES = 16;
|
|
|
|
// Per level, over the pairs that survived the clip: the count, the sum of the pair means and the sum
|
|
// of the squared differences.
|
|
struct Levels {
|
|
std::array<uint64_t, N_BINS> n{};
|
|
std::array<double, N_BINS> sum_mean{};
|
|
std::array<double, N_BINS> sum_diff2{};
|
|
};
|
|
|
|
// One frame. A pixel takes part if the mask is zero there and 1 <= value < saturation (a CCD reads
|
|
// its bias in the dark, so a zero is a pixel outside the active area).
|
|
Levels MeasureFrame(const std::vector<int32_t> &image, size_t width, size_t height,
|
|
const std::vector<uint32_t> &mask, int64_t saturation);
|
|
|
|
// The gain over frames: the pair-weighted median of the per-level variance/mean, or nothing with
|
|
// fewer than MIN_BINS levels holding MIN_PAIRS_PER_BIN pairs.
|
|
std::optional<float> Gain(const std::vector<Levels> &frames);
|
|
|
|
// The gain of a detector whose background resolves single photons (a JUNGFRAU with its pedestal
|
|
// subtracted): the histogram of pixel values has a peak at zero photons, one at a single photon and
|
|
// another at two, a gain apart. The variance per unit mean above does not see it on a sparse background -
|
|
// the empty pixels it leaves out are most of it - so the quantum is read off the histogram instead. The
|
|
// gain is the spacing of the peaks, not the single photon's value, so a frame whose baseline was never
|
|
// subtracted - its zero-photon peak well above zero - reads the same gain, and its baseline besides.
|
|
constexpr size_t PEAK_HISTOGRAM_BINS = 16384;
|
|
|
|
// Adds the frame's unmasked pixels with 0 <= value < min(saturation, PEAK_HISTOGRAM_BINS) to histogram
|
|
// (PEAK_HISTOGRAM_BINS long, one bin per value).
|
|
void AddToHistogram(const std::vector<int32_t> &image, const std::vector<uint32_t> &mask, int64_t saturation,
|
|
std::vector<uint64_t> &histogram);
|
|
|
|
struct GainEstimate {
|
|
float gain; // detector units per photon (photon peaks: from the zero-photon to the single-photon peak)
|
|
float pedestal; // where the zero-photon peak sits; 0 where the baseline was subtracted or no peak shows
|
|
};
|
|
|
|
// The zero-photon peak is the highest bin; the single-photon peak the highest past its descent, standing out
|
|
// of the valley before it, falling to half its height before the midpoint to the next, and repeated by a
|
|
// two-photon peak near one more gain on. Nothing where the histogram shows no such pair - integer photon
|
|
// counts, whose single photon is the bin next to the zero peak, or a detector whose noise hides the photons.
|
|
std::optional<GainEstimate> PhotonPeak(const std::vector<uint64_t> &histogram);
|
|
|
|
// The gain of any input that reports detector units, rotation or stills, from the same frames: the photon
|
|
// peaks where the histogram shows them, else the variance per unit mean of the levels.
|
|
std::optional<GainEstimate> Estimate(const std::vector<Levels> &frames, const std::vector<uint64_t> &histogram);
|
|
|
|
} // namespace background_gain
|