// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute // 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 #include #include #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 &baseline, const std::vector &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 §or_median, int n_bands, std::vector &harm_c, std::vector &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. On 46 rotation sweeps and 11 stills runs whose plane is horizontal, the largest values // towards the vertical plane are 0.48 and 0.18, the latter on a background with almost no modulation; // 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; // The plane the source is polarized in, as the background shows it: +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. `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. float PolarizationPlane(const std::vector §or_median, const std::vector &litude); } // namespace shadow_finder