Jungfraujoch/image_analysis/geom_refinement/BeamCenterFromBackground.h

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

#pragma once

#include <optional>
#include <utility>
#include <vector>

#include "BeamCenterFFT.h"
#include "../../common/DiffractionExperiment.h"
#include "../../common/PixelMask.h"

struct BeamCenterEstimate {
    float beam_x_pxl = 0.0f;
    float beam_y_pxl = 0.0f;
    float sigma_pxl = 0.0f;   // 1 sigma on the fitted shift, the larger of the two axes
};

// Beam centre from the isotropy of the scattered background, before anything is indexed.
//
// The solvent and air scatter is isotropic in 2-theta about the beam, so a centre that is off
// shifts each azimuthal sector's radial profile by a different amount. Sector k's profile is
// m_k * g(2theta + d_k), with the shift d_k = Jx_k*dx + Jy_k*dy and m_k an amplitude that
// absorbs anything multiplicative and azimuthal - a holder arm, a cryostream shadow, a
// flat-field gradient. Fitting the amplitude alongside the shift is what makes this usable:
// a 50% shadow over one sextant otherwise reads as several tens of pixels of centre error.
//
// The leverage comes from the CURVATURE of the radial profile - the water ring - because for a
// pure exponential decay g' is proportional to g and shift and amplitude are indistinguishable.
// The sigma measures that leverage, so it grows as the curvature weakens, and the caller's gate on
// it is what keeps an ill-determined centre out. It is a precision and not an accuracy: on a
// background with NO curvature at all there is nothing to separate the two parameters, the fit
// follows the noise in g' instead, and it does so confidently.
//
// `mean` is a per-pixel projection over a few tens of frames, NAN where no frame contributed.
// nthreads = 0 asks for all hardware threads. The pixels are split into a fixed number of row
// blocks whatever that count is, so the answer does not depend on it.
//
// `start` is where the walk begins; the centre in the file when it is not given. The walk advances
// by a bounded distance per iteration, so where it starts decides how much of its budget is spent
// travelling and - on a surface with more than one basin - which fixed point it can reach at all.
//
// With a GPU the passes over the pixels run on it (BeamCenterBackgroundGPU); allow_device = false
// keeps them on the host, which is what the parity test compares against.
std::optional<BeamCenterEstimate>
FindBeamCenterFromBackground(const DiffractionExperiment &experiment, const PixelMask &mask,
                             const std::vector<float> &mean, size_t nthreads = 0,
                             std::optional<std::pair<float, float>> start = {},
                             bool allow_device = true);

// The precision of a centre that is the FFT capture alone, with no walk behind it. The capture is
// a half-pixel grid position read off a surface, measured over 75 rotation datasets at a median
// 3.2 px and a 90th percentile of 11 px from the truth, so this is what it knows the centre to -
// a capture precision and not a fit precision. It is deliberately far above the ceiling the
// callers adopt a centre on: a capture is evidence about where the beam is, not a measurement of
// where it is.
constexpr float BEAM_CENTER_CAPTURE_SIGMA_PXL = 5.0f;

// The beam centre from the background, captured globally and then refined locally.
//
// The walk in FindBeamCenterFromBackground is a good local refiner and a poor searcher: it moves
// one or two pixels per iteration, it is seeded at the centre in the file, and on a background
// whose isotropy is broken it has a second basin to fall into. The FFT score is the opposite -
// it evaluates EVERY candidate centre on the detector in one transform set, at a cost that does
// not depend on how wrong the file is, but it returns a half-pixel grid position and no sigma.
// Composing them takes the reach from one and the precision from the other: the capture chooses
// the basin, the walk finishes inside it and reports what it knows the answer to.
//
// The shadow of the beam stop is blanked out of the image the capture scores. A one-sided opaque
// region imposes a centrosymmetry of its own that can beat the background's - measured, an umbra
// over 9.6 % of the detector put the capture 48 px out, and masking it put it back to 1.1 px,
// while a random mask of the same area changed nothing.
//
// Where the walk declines at the capture the walk is asked again from the centre in the file, and
// only where neither start gives it something to fit does the capture stand alone, at
// BEAM_CENTER_CAPTURE_SIGMA_PXL - which is what lets a caller that only needs a hypothesis to test
// still get one. Returns nothing only where the capture has no candidate either.
std::optional<BeamCenterEstimate>
FindBeamCenter(const DiffractionExperiment &experiment, const PixelMask &mask,
               const std::vector<float> &mean, size_t nthreads = 0,
               BeamCenterFFTResult *capture = nullptr);