Jungfraujoch/image_analysis/spot_finding/SpotFindingSettings.h

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

#pragma once

#include <optional>
#include <cstdint>

struct SpotFindingSettings {
    bool enable = true;
    float signal_to_noise_threshold = 4.0;  // STRONG_PIXEL in XDS
    int64_t photon_count_threshold = 10;  // Threshold in photon counts
    // Minimum connected pixels per spot. std::nullopt = choose it per image: on the stills indexing
    // path the frame is indexed at min-pix 3/2/1 and the one maximising indexed count x indexed fraction
    // is kept (see MXAnalysisWithoutFPGA::Analyze); a value fixes it. Defaults to a concrete value, so
    // the online receiver and the FPGA path keep the single-pass fixed behaviour unless set otherwise.
    std::optional<int64_t> min_pix_per_spot = 2;
    int64_t max_pix_per_spot = 50;        // Maximum pixels per spot
    // High-resolution limit for spot finding [A]. std::nullopt = as far as the detector reaches, i.e. no
    // resolution clipping of the detection at all (DiffractionExperiment::GetDetectorMaxResolution_A
    // supplies the number where one is needed, e.g. for the spot plot's shells).
    std::optional<float> high_resolution_limit;
    // Low-resolution limit for spot finding [A]. std::nullopt = no limit at the low-resolution end, the
    // mirror of high_resolution_limit above. Optional rather than a zero sentinel because zero is not a
    // natural "no limit" here: every pixel has d above it, so the plain comparison would mask the whole
    // image rather than none of it. Defaults to a concrete value, which is where the detection normally
    // stops - the direct beam and its halo sit beyond it.
    std::optional<float> low_resolution_limit = 50.0;
    float cutoff_spot_count_low_res = 5.0;
    std::optional<float> high_res_gap_Q_recipA = 1.5; // 0.25 * 2 * pi

    // Half-width of the ice-ring exclusion band in q (2*pi/d). Measured hexagonal-ice ring FWHM on the
    // JUNGFRAU is ~0.06 q, so the band half-width is ~0.03; 0.02 under-covered the strong low-res rings.
    float ice_ring_width_Q_recipA = 0.03;

    bool indexing = true;
    bool quick_integration = true;

    // Self-calibrating detection (offline/rugnux path): when true, the fixed photon_count_threshold is
    // replaced by a per-resolution-ring threshold set from the image's own noise (see
    // AdaptiveSpotFinderCPU), so the same setting adapts across datasets with no per-dataset tuning.
    // false_pixels_per_frame is the one portable knob: the expected number of noise pixels tolerated
    // per frame (the threshold's operating point), ~100 for a multi-megapixel detector.
    bool adaptive_threshold = false;
    float false_pixels_per_frame = 100.0f;
};