Jungfraujoch/image_analysis/geom_refinement/RingsFromProfile.h

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

#pragma once

#include <vector>

#include "../../common/AzimuthalIntegrationMapping.h"
#include "../../common/DiffractionGeometry.h"
#include "RingOptimizer.h"

// Turn an accumulated (q x azimuth) powder profile into ring points for RingOptimizer.
//
// The calibration this feeds already exists (AssignSpotsToRings + RingOptimizer); what it has always
// been given is a SPOT LIST from a single image. A powder ring is not a set of spots - it is a smooth
// arc - so a spot finder samples it wherever its threshold happens to bite, and one image carries only
// as much of the ring as that image's counting statistics allow. An azimuthally-binned profile summed
// over a run measures the same ring directly, at every azimuth, with the whole run's counts behind it.
//
// Where the ring falls is what carries the geometry. A powder ring is a conic centred on the beam, so
// a wrong beam centre makes its apparent radius oscillate once per turn - a cos(phi) term, the SAME
// amplitude on every ring. A detector tilt beta produces a cos(phi) term as well, not the cos(2 phi)
// one might expect: to first order r(phi) = R + (R^2/F)(beta_x cos phi + beta_y sin phi), so it grows
// as the ring's radius SQUARED. Measured on a powder standard, the genuine cos(2 phi) term is of order
// R^3 beta^2 / F^2, i.e. hundredths of a pixel and below the noise. So the two are told apart by how
// the cos(phi) amplitude scales with radius, which needs at least two rings - on a single ring they are
// exactly degenerate. Neither depends on the calibrant's d-spacings, which is why the beam centre is
// the one thing a powder pattern determines without assuming anything about the standard; the distance,
// by contrast, is only as good as the lattice constant it is measured against, and its lever collapses
// as the detector moves back and the rings crowd into small 2theta.
//
// profile is the mean intensity per bin (AzimuthalIntegrationProfile::GetResult()): q_bins x azimuthal
// bins, indexed bin = q_bin + phi_bin * q_bins. geom supplies the CURRENT geometry, used only to turn a
// measured (q, phi) back into the pixel it came from - RingOptimizer then refines that geometry so the
// q it predicts at that pixel matches the calibrant's. Rings outside the profile's q range, and sectors
// where no peak stands clear of the local background, are skipped rather than guessed at.
//
// calibrant_ring_q is the calibrant's rings as q = 2*pi/d (CalibrantRings). A ring list rather than a
// UnitCell so that ice, whose rings are measured rather than enumerated from a cell, can be used too.
std::vector<RingOptimizerInput> RingsFromAzimuthalProfile(const std::vector<float> &profile,
                                                          const AzimuthalIntegrationMapping &mapping,
                                                          const DiffractionGeometry &geom,
                                                          const std::vector<float> &calibrant_ring_q,
                                                          float q_window_recipA = 0.06f,
                                                          float min_peak_over_noise = 3.0f);