79 lines
4.7 KiB
C++
79 lines
4.7 KiB
C++
// 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.
|
|
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 = {});
|
|
|
|
// 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);
|