Jungfraujoch/image_analysis/beam_stop/ShadowFinderInternal.h

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

#pragma once

// What ShadowFinder::GetMask shares with its device twin (ShadowMaskGPU): the constants it tests
// against, where a pixel sits on its ring, and the two small fits made over whole rings and sectors,
// which stay on the host on both paths.

#include <cmath>
#include <cstdint>
#include <vector>

#ifdef __CUDACC__
#define SHADOW_FINDER_HD __host__ __device__ inline
#else
#define SHADOW_FINDER_HD inline
#endif

namespace shadow_finder {

// Where a pixel sits on the ring it is compared along. A ring is a cone of constant 2theta about the
// beam. On an untilted detector that is a circle about the beam centre, but on a tilted one - a
// detector on a swung 2theta arm - it is a circle about no pixel at all, and a circle drawn about the
// centre runs across the background's own fall-off: 5 degrees of tilt at 50 mm put a quarter of a
// detector in the shadow. So a pixel's ring is its 2theta, in pixels: `radius` is distance *
// tan(2theta), the radius it would have on an untilted detector at the same distance, and (lx, ly) is
// its offset from the beam in that frame, which gives its azimuth. A tilt also makes a pixel's solid
// angle vary along the ring, by tens of per cent at that same tilt; `obliquity` is the pixel's solid
// angle over the one the untilted detector has at the same 2theta, (distance / lz)^3, and the
// background is divided by it as by the polarization factor.
// (dx, dy) is the pixel's offset from the geometry's beam centre, `det_matrix` the detector matrix
// (row major) and `distance_px` the detector distance in pixels. Untilted, (lx, ly) is (dx, dy) and
// the obliquity is 1, exactly.
struct RingPosition {
    float lx, ly, radius, obliquity;
};

SHADOW_FINDER_HD RingPosition ring_position(const float *det_matrix, float distance_px, float dx, float dy) {
    const float *m = det_matrix;
    const float lx = m[0] * dx + m[1] * dy + m[2] * distance_px;
    const float ly = m[3] * dx + m[4] * dy + m[5] * distance_px;
    const float lz = m[6] * dx + m[7] * dy + m[8] * distance_px;
    const float stretch = distance_px / lz;
    return {lx, ly, sqrtf(lx * lx + ly * ly) * stretch, stretch * stretch * stretch};
}

// The values of ShadowFinder::SHADOW and ShadowFinder::TRANSMITTING, for the device code, which does
// not include ShadowFinder.h.
inline constexpr uint32_t MASK_SHADOW = 1;
inline constexpr uint32_t MASK_TRANSMITTING = 2;

// A pixel is shadow when its background is below this fraction of the background it is
// compared against.
inline constexpr float SHADOW_RATIO = 0.50f;

// The boundary grows outward into partially shadowed pixels down to this fraction, but no
// further than PENUMBRA_MAX_PX from the core. A pin or a loop casts a wide half-shadow, so the
// reach is a good deal more than the beam stop's own edge needs.
inline constexpr float PENUMBRA_RATIO = 0.75f;
inline constexpr int   PENUMBRA_MAX_PX = 30;

// Bridge small breaks along the holder arm. A module gap wider than this is bridged separately for
// the arm search (see bridge_gaps).
inline constexpr int BRIDGE_PX = 6;

// A pixel whose maximum reaches this many photons recorded a real reflection and is never masked - a
// beam stop cannot block a reflection that was measured. On a detector read in ADU it is taken at the
// gain.
inline constexpr int64_t MIN_REFLECTION = 25;

// How far below the background it is compared against a pixel must sit before the dip is
// believed, in standard deviations of the photons that back it (counts divided by the gain on a
// detector read in ADU), so their scatter is Poisson and the deficit is measured against it rather
// than against a fixed number:
// on a well-exposed sweep a third of the background missing is overwhelming, and on a handful of
// low-background frames the same third is noise. Without this a six-frame pre-scan of a
// low-background sweep masks three quarters of the detector.
inline constexpr double MIN_DEFICIT_SIGMA = 6.0;

// Smallest region the per-pixel test may return. A shadow is cast by something physical and is
// correspondingly large; an isolated patch this small is the background wandering, not hardware.
// This is what keeps the test specific now that a shadow no longer has to touch the direct beam.
inline constexpr int MIN_SHADOW_PIXELS = 2000;

// ... and of those, how many must be deep (below SHADOW_RATIO) for a region of merely DIM pixels -
// hardware that lets part of the beam through - to count. A thin holder arm is dim along most of
// its length and deep in places; the background drifting over a detector's edge is dim everywhere
// and deep nowhere.
inline constexpr int MIN_CORE_PIXELS = 200;

// The arm search compares a pixel with its ring as the ring actually varies around the beam. A ring
// of background is not flat once divided by the polarization factor when that factor is not the
// beam's: the remainder is a second harmonic in azimuth, cos 2phi, which reaches tens of percent at
// high angle. It is measured over radial bands of HARMONIC_BAND_PX, from the median of each of
// HARMONIC_SECTORS sectors that holds at least MIN_SECTOR_PIXELS pixels.
inline constexpr int HARMONIC_BAND_PX = 64;
inline constexpr int HARMONIC_SECTORS = 24;
inline constexpr int MIN_SECTOR_PIXELS = 200;

// Side of the box the background is pooled over before testing. Its area is how many pixels back
// a ring's countability test, which decides where an azimuthal comparison is possible at all.
inline constexpr int    POOL_PX = 5;
inline constexpr double MEAN_POOLED_PIXELS = POOL_PX * POOL_PX;

// A ring with fewer valid pixels than this says nothing about whether it was counted.
inline constexpr int MIN_RING_PIXELS = 32;

// A ring lies wholly inside the stop when its background is below this fraction of the background
// further out. This asks about a whole ring rather than about a pixel, so it keeps a threshold of
// its own and does not follow SHADOW_RATIO.
inline constexpr float BLOCKED_RING_RATIO = 0.35f;

// The rings that lie wholly inside the stop: walking outward, every judgeable ring (at least
// MIN_RING_PIXELS pixels) before the first whose baseline reaches BLOCKED_RING_RATIO of the typical
// background. -1 when there is none. See GetMask.
int BlockedOutTo(const std::vector<float> &baseline, const std::vector<int> &ring_pixels);

// The second harmonic in azimuth of each radial band, relative to its level, fitted to the medians of
// its HARMONIC_SECTORS sectors (sector_median[band * HARMONIC_SECTORS + k], negative where the sector
// has too few pixels). See GetMask.
void HarmonicFit(const std::vector<double> &sector_median, int n_bands,
                 std::vector<float> &harm_c, std::vector<float> &harm_s);

// How closely, over the radial bands, the background's cos 2phi harmonic must follow the profile a
// polarized source gives it (the correlation), and how large it must be against the profile of a fully
// polarized source (the least-squares scale), before the plane is taken from the background rather
// than as stated. Of 244 synchrotron rotation sweeps, all polarized horizontally, 216 show that plane
// past both; apart from the one under PLANE_MODULATION_MAX the largest values towards the vertical plane
// are 0.01 and 0.002, and on 11 sweeps from laboratory sources 0.43 and 0.14. On a stills run whose
// plane lies along the image's y axis they are 0.998 and 0.47 - the scale reduced there by the
// placeholder distance the pre-scan reads it at.
inline constexpr double PLANE_CORRELATION = 0.5;
inline constexpr double PLANE_MODULATION = 0.3;
// No polarized source modulates the background by more than a fully polarized one does (a scale of 1). A
// harmonic of twice that or more is not the source's: at a long distance, where polarization can move
// the background by a few per cent at most, a sweep's background carried ten per cent along image y
// (scale 2.9, correlation 0.66) on a horizontally polarized beamline. It decides nothing.
inline constexpr double PLANE_MODULATION_MAX = 2.0;
// The box the background is pooled over before the plane is measured, in pixels: the modulation changes
// over hundreds of pixels, and pooling is what gives a sparse background a median that is not zero.
inline constexpr int PLANE_POOL_PX = 9;

// The plane the source is polarized in, as the background shows it, and the two numbers it is decided on.
struct PlaneEvidence {
    float plane = 0.0f;        // +1 for the plane containing lab x (a horizontally polarized source), -1 for
                               // the plane turned by 90 degrees, 0 where the background does not show one clearly
    double correlation = NAN;  // of the bands' cos 2phi harmonic with a polarized source's profile
    double modulation = NAN;   // the harmonic against a fully polarized source's (least-squares scale)
                               // both positive towards the turned plane, negative towards lab x
};

// `sector_median` is laid out as for HarmonicFit, each band's background relative to its rings;
// `amplitude[band]` is the relative modulation a fully polarized source gives the band,
// sin^2 2theta / (1 + cos^2 2theta). See GetMask.
PlaneEvidence PolarizationPlane(const std::vector<double> &sector_median, const std::vector<float> &amplitude);

}   // namespace shadow_finder