Jungfraujoch/image_analysis/grid_scan_analysis/AnalyzeGridScan.h

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

#pragma once

#include "../../common/GridScanSettings.h"
#include "../../common/ScanResult.h"
#include "../../common/GridScanResult.h"
#include "../../common/GridScanAnalysisSettings.h"

// Finds the crystals in a completed grid scan: the per-image protein score is scattered back onto
// the raster, the map is thresholded and labelled, and each blob is reported as one crystal.
// Pure - no I/O, no state, no detector.
//
// The sizes reported are MEASURED, and the beam is still in them: what the raster sees is the
// crystal convolved with the beam, and nothing here takes the beam back out. That is deliberate -
// the beam size is in the file as incident_beam_size, so a downstream consumer can do the
// deconvolution itself, reproducibly and reversibly, and is not stuck with ours.
//
// If it does: removing an anisotropic beam is a subtraction of the two 2x2 covariance matrices
// followed by re-diagonalising the difference, NOT a per-axis quadrature removal of beam_x from
// major_um and beam_y from minor_um. Per-axis is silently wrong the moment the crystal is not
// aligned with the grid axes - a needle at 45 deg has both beam widths mixed into both of its own
// axes - and a needle at an arbitrary angle is exactly the case this whole design exists for.
// beam_size_x_um/beam_size_y_um are only copied into the result, so it says what the sizes contain.

// beam_size_x_um/beam_size_y_um are the beam at the sample. Pass 0 where it is not known: the grid
// step is then reported in its place, since a raster is stepped at about the beam size and a zero
// beam would tell a consumer the extents are exact when they still contain one.
GridScanResult AnalyzeGridScan(const ScanResult &scan,
                               const GridScanSettings &grid,
                               float beam_size_x_um,
                               float beam_size_y_um,
                               const GridScanAnalysisSettings &settings = {});