Jungfraujoch/common/DetectorModules.h

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

#pragma once

#include <cstdint>
#include <utility>
#include <vector>

#include "ModuleShift.h"

class DetectorGeometry;

// One detector module: where its pixels are in the image rugnux reads, and where they really are on the
// detector plane. The plane is the one DiffractionGeometry describes (beam centre, distance, tilt), in its
// pixel units, so a module placed exactly as the image has it maps every pixel onto itself.
//
// Image pixel (x, y) of the module, x0 <= x < x0 + width, y0 <= y < y0 + height, lies on the plane at
//   (ox, oy) + (x - x0) (fx, fy) + (y - y0) (sx, sy)
// - the NXdetector_module description (data_origin, data_size, module_offset, fast_pixel_direction,
// slow_pixel_direction) taken in the plane. A pixel's centre is at its index, as everywhere in the image.
struct DetectorModule {
    int64_t x0 = 0, y0 = 0, width = 0, height = 0;
    double ox = 0, oy = 0;
    double fx = 1, fy = 0;
    double sx = 0, sy = 1;

    // The module where the image has it: every pixel maps onto itself.
    static DetectorModule AsImaged(int64_t x0, int64_t y0, int64_t width, int64_t height);

    [[nodiscard]] bool ContainsImagePixel(double x, double y) const;
    [[nodiscard]] std::pair<double, double> ImageToPlane(double x, double y) const;
    [[nodiscard]] std::pair<double, double> PlaneToImage(double px, double py) const;
    // Plane position of the module's centre.
    [[nodiscard]] std::pair<double, double> PlaneCentre() const;
    // Moved by a refinement's rigid step, which is expressed on the plane (ModuleShift: turn about
    // (x0, y0) of the shift, then shift).
    void Apply(const ModuleShift &shift);
};

// The modules of one detector. Empty means the image is one flat detector: every mapping is the identity.
class DetectorModules {
    std::vector<DetectorModule> modules;
public:
    DetectorModules() = default;
    explicit DetectorModules(std::vector<DetectorModule> modules);

    [[nodiscard]] bool empty() const;
    [[nodiscard]] size_t size() const;
    [[nodiscard]] const DetectorModule &operator[](size_t i) const;
    [[nodiscard]] const std::vector<DetectorModule> &Get() const;

    // True where some module is placed other than as imaged.
    [[nodiscard]] bool Moved() const;

    // Module of an image pixel, or -1 (a gap, or outside every module).
    [[nodiscard]] int64_t ModuleOfImagePixel(double x, double y) const;
    // Module whose placed footprint holds a plane point, or -1.
    [[nodiscard]] int64_t ModuleOfPlanePoint(double px, double py) const;

    // Image -> plane; a point on no module is left as it is.
    [[nodiscard]] std::pair<double, double> ImageToPlane(double x, double y) const;
    // Plane -> image; a point on no placed module is left as it is.
    [[nodiscard]] std::pair<double, double> PlaneToImage(double px, double py) const;

    // Each module moved by the shift whose centre is nearest its own plane centre (and within it).
    void Apply(const std::vector<ModuleShift> &shifts);
    // The modules as refinement starting points: their plane centres, no move.
    [[nodiscard]] std::vector<ModuleShift> Centres() const;
};

// The modules of a modular (JUNGFRAU) detector where its assembled image puts them: one box per module,
// CONVERTED_MODULE_COLS x CONVERTED_MODULE_LINES turned the way the geometry turns it, placed as imaged.
// Empty for a detector of one module.
DetectorModules ModulesAsImaged(const DetectorGeometry &geom);