Jungfraujoch/image_analysis/geom_refinement/BeamCenterFromSpots.h

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

#pragma once

#include <cmath>
#include <optional>
#include <vector>

#include "BeamCenterFromBackground.h"
#include "../../common/DiffractionExperiment.h"

// One spot of the pre-scan sample: its position in image pixels, its photon count, and which of the
// sampled frames it came from (an index into the angles the estimator is given).
struct BeamCenterSpot {
    float x = 0.0f;
    float y = 0.0f;
    float intensity = 0.0f;
    int frame = 0;
};

// Where the spindle really points. The goniometer axis in the file is a nominal - every master of
// the regression set writes it as exactly a lab axis, and no beamline can hold one there - so the
// two angles the beam-centre estimator cannot do without are measured from the spots instead.
//
// AZIMUTH: the spindle turned about the beam. Both mirror lines turn with it, and a mirror taken
// about the nominal one instead leaves a residual of twice the azimuth times the other detector
// coordinate - which does not bias the vote but spreads it until the wrong tooth wins.
//
// TIP: the spindle tipped out of the plane perpendicular to the beam, i.e. the part that makes it
// not perpendicular at all. The Friedel mate is then no longer in diffracting condition at exactly
// phi+180, and the compensating rotation leaves a purely radial residual along the mirrored
// coordinate. The crossing axis does not see it; only the Friedel one does.
//
// Both are angles of the spindle, not of the detector, and neither is ever written to the geometry.
struct SpindleEstimate {
    float azimuth_rad = NAN;          // fitted rotation of the spindle about the beam
    float tip_rad = NAN;              // fitted rotation of the spindle towards the beam
    float vote_excess = NAN;          // the Friedel vote's tallest tooth there
    float vote_excess_nominal = NAN;  // and at the nominal spindle, for comparison
};

// Beam centre from the symmetry of a rotation sweep's spot positions, before anything is indexed.
// Nothing here uses the background, a ring, a unit cell or an orientation matrix - only where the
// spots are, and two facts that hold exactly for any crystal on a single-axis goniometer.
//
// Friedel. Rotating the crystal 180 deg about the spindle m and taking -h negates the scattering
// vector's component ALONG m and leaves the rest untouched, so the spots on the frame at phi+180 are
// the exact mirror image, in that lab component, of the spots on the frame at phi. Mirroring one
// frame's spots onto its partner's therefore measures the beam coordinate along m.
//
// Second crossing. Along the sweep |q| and q.m are both constant and the Ewald condition fixes the
// component along the beam, so the remaining one can only change sign: every reflection is recorded
// twice, at positions mirrored in the coordinate PERPENDICULAR to m. That gives the other coordinate.
//
// The estimate is of the physical direct beam; it is returned in the PONI parametrisation the rest of
// the geometry uses, so the caller can put it straight into DiffractionExperiment.
//
// `sigma_pxl` is what the caller gates on, and it is the larger of two things: the scatter of what
// the individual frame pairs said, and how far the answer moves when the search is started
// elsewhere. The second is what matters. The vote sees only +-30 px about wherever it starts, so a
// header far enough out leaves the true peak outside the window and a false one wins it with a
// perfectly small scatter - a precision, not an accuracy. Only a start somewhere else finds that.
//
// The sweep has to reach 180 deg for the first and about a full turn for the second, which is why
// this cannot serve stills, screening wedges or short sweeps - the background estimator does, on
// three frames. `frame_angle_deg` is the rotation angle of each sampled frame, and the estimator
// pairs them itself; `spots` is the pooled spot list of those frames.
//
// std::nullopt when the sweep, or the diffraction on it, does not support the measurement.
// A non-null `spindle` is what asks for the spindle to be fitted and applied; with a null pointer
// this is exactly the estimator that was here before.
std::optional<BeamCenterEstimate>
FindBeamCenterFromSpotSymmetry(const DiffractionExperiment &experiment,
                               const std::vector<float> &frame_angle_deg,
                               const std::vector<BeamCenterSpot> &spots,
                               SpindleEstimate *spindle = nullptr);