Jungfraujoch/image_analysis/geom_refinement/BeamCenterFFT.h

// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
// SPDX-License-Identifier: GPL-3.0-only

#pragma once

#include <cstdint>
#include <vector>

#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<BeamCenterFFTCandidate> 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<float> &mean,
                   const BeamCenterFFTSettings &settings = {});

// Convenience wrapper over the pre-scan projection.
[[nodiscard]] BeamCenterFFTResult
FindBeamCenterFFT(const DiffractionExperiment &experiment, const std::vector<float> &mean,
                  const BeamCenterFFTSettings &settings = {});