// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute // SPDX-License-Identifier: GPL-3.0-only #pragma once #include #include #include "../../common/DiffractionExperiment.h" #include "../../common/PixelMask.h" // Whole-detector beam-centre capture from the symmetry of the scattered image, via FFT. // // The centrosymmetry score of the image about a candidate centre c, sum_x I(x) I(2c - x), is the // self-convolution (I * I)(2c), so one FFT pair scores EVERY candidate centre on the detector at // half-pixel spacing in a single transform set - the cost is O(N log N) and independent of how far // the true centre is from the value in the file. The score is a 2D point inversion - a // measurement of the isotropic background (air and solvent scatter), point-symmetric about the beam // whatever the crystal does. It shares its physics with FindBeamCenterFromBackground, so their // agreement is not two votes: the strongest candidate seeds that walk. // // The score is a CAPTURE device, not a decision device: measured on 17 datasets its shortlist // holds the true centre in the top candidates every time (three gross header errors of 71-351 px // captured at rank 1 within 1 px), but the surface can be locally flat, so the result is a // shortlist plus a margin - never a single centre. The margin (best minus runner-up, as a // fraction of best, after suppression) is the self-diagnostic: measured, ambiguous surfaces sit // below ~3 % and clean ones above ~5 %. Callers must verify a candidate (index at it) before // believing it, and must not average candidates. // // The input is the mean-projection the pre-scan already accumulates for the beam-stop search // (ShadowFinder::GetMeanProjection), NAN where nothing was counted - so this costs no new I/O. // // The transforms run on the GPU where there is one with room for them and on fftw3f otherwise // (BeamCenterFFTGPU / BeamCenterFFTCPU); everything that decides anything is shared between the // two. Whole-detector reach is what this buys, and on a 16 Mpixel detector the transforms are the // whole of its cost, so which engine runs them is the difference between seconds and milliseconds. struct BeamCenterFFTCandidate { float beam_x_pxl = 0.0f; float beam_y_pxl = 0.0f; float score = 0.0f; // masked Pearson r of the image with its mirror about this centre }; struct BeamCenterFFTResult { // Non-maximum-suppressed shortlist of the 2D point-inversion score, strongest first. std::vector point; // (best - runner_up) / best; 0 when fewer than two peaks survive. float margin_point = 0.0f; }; struct BeamCenterFFTSettings { float nms_radius_pxl = 25.0f; // peak separation; tracks the score's plateau width int candidates_point = 8; // Fraction of the maximum mirror-pair count below which a centre is not scored - centres so // far out that almost no pixel has a valid mirror partner correlate noise with noise. float min_pair_fraction = 0.25f; }; // Core entry: `mean` is a width x height row-major per-pixel projection, NAN (or any non-finite // value) where no valid pixel exists. Kept free of DiffractionExperiment so it can be tested // against stored arrays. [[nodiscard]] BeamCenterFFTResult BeamCenterFFTScore(int64_t width, int64_t height, const std::vector &mean, const BeamCenterFFTSettings &settings = {}); // Convenience wrapper over the pre-scan projection. [[nodiscard]] BeamCenterFFTResult FindBeamCenterFFT(const DiffractionExperiment &experiment, const std::vector &mean, const BeamCenterFFTSettings &settings = {});