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 <cstddef>
#include <cstdint>
#include <array>
#include <optional>
#include <string>
#include <utility>
#include <vector>

#include "ModuleShift.h"
#include "DetectorModuleGeometry.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.
//
// `fast` and `slow` say which way the module's readout axes run in the image; its readout pixel 0 is the
// corner of the box they start from (ReadoutX0/Y0). They name the module in a placement (ModulePlacement)
// and change nothing in the mapping above. A module whose readout is not known is its own pixel array: +x, +y.
struct DetectorModule {
    using Direction = DetectorModuleGeometry::Direction;
    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;
    Direction fast = Direction::Xpos, slow = Direction::Ypos;

    // 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);

    // Image position of the readout pixel 0.
    [[nodiscard]] int64_t ReadoutX0() const;
    [[nodiscard]] int64_t ReadoutY0() const;

    [[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 image unit step of a readout direction (Xp = (1, 0), Yn = (0, -1), ...), and its name in
// jfjoch_api.yaml (detector_module_direction: Xp, Xn, Yp, Yn).
std::pair<int64_t, int64_t> DirectionStep(DetectorModuleGeometry::Direction d);
std::string DirectionName(DetectorModuleGeometry::Direction d);
// The direction of an image step along x or y (the larger of the two).
DetectorModuleGeometry::Direction DirectionOfStep(double dx, double dy);
DetectorModuleGeometry::Direction DirectionFromName(const std::string &name);

// One entry of a module placement (dataset_settings.module_placement of jfjoch_api.yaml, docs/RUGNUX_FORMATS.md):
// the module named by its readout pixel 0 (x0, y0) and readout axes in the image, and where it lies on the
// plane: readout pixel (i, j) at (x0_plane, y0_plane) + i fast_step + j slow_step.
struct ModulePlacement {
    int64_t x0 = 0, y0 = 0;
    DetectorModuleGeometry::Direction fast = DetectorModuleGeometry::Direction::Xpos;
    DetectorModuleGeometry::Direction slow = DetectorModuleGeometry::Direction::Ypos;
    double x0_plane = 0, y0_plane = 0;
    std::array<double, 2> fast_step{1, 0}, slow_step{0, 1};
};

// The placement entry of a module: where it is now.
ModulePlacement PlacementOf(const DetectorModule &m);

// A point in the image rugnux reads, on panel `panel` (an index into DetectorModules; -1 when the table is
// empty and the whole image is one flat panel).
struct PanelPoint {
    int64_t panel;
    double x, y;
};

// An axis-aligned box on the detector plane, x0 <= x < x1, y0 <= y < y1.
struct PlaneBox {
    double x0, y0, x1, y1;
};

// The modules of one detector. Empty means the image is one flat detector: every mapping is the identity.
// A module is a panel: one rigid box of the image with one placement. Panel ids are indices into the table.
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;

    // Image <-> plane on a known panel, no search. Panel -1 (the empty table) is the identity.
    [[nodiscard]] std::pair<double, double> ImageToPlane(int64_t panel, double x, double y) const;
    [[nodiscard]] std::pair<double, double> PlaneToImage(int64_t panel, double px, double py) const;
    // The panel whose placed footprint holds a plane point, and where that point is in the image; nullopt in
    // a gap or off every panel. Empty table: panel -1 and the point itself, wherever it is - the caller
    // bounds it by the image, as without panels.
    [[nodiscard]] std::optional<PanelPoint> PlaneToPanel(double px, double py) const;
    // Box on the plane enclosing every panel's pixels (their footprints, half a pixel beyond the edge pixel
    // centres): a quick reject before PlaneToPanel. Empty table: [0, width) x [0, height), the image
    // rectangle the bounds tests without panels use.
    [[nodiscard]] PlaneBox PlaneBounds(int64_t width, int64_t height) const;

    // Calls f(panel, index, px, py) for every image pixel on a panel - panel by panel, row by row - with
    // index = y * width + x in the image and (px, py) its centre on the plane. Pixels on no panel (gaps) are
    // not visited. Empty table: one panel -1 that is the whole image, plane == image.
    template<class F>
    void ForEachPixel(int64_t width, int64_t height, F &&f) const {
        if (modules.empty()) {
            for (int64_t y = 0; y < height; y++)
                for (int64_t x = 0; x < width; x++)
                    f(int64_t(-1), static_cast<size_t>(y * width + x), static_cast<double>(x), static_cast<double>(y));
            return;
        }
        for (size_t p = 0; p < modules.size(); p++) {
            const DetectorModule &m = modules[p];
            for (int64_t y = m.y0; y < m.y0 + m.height; y++)
                for (int64_t x = m.x0; x < m.x0 + m.width; x++) {
                    const auto [px, py] = m.ImageToPlane(static_cast<double>(x), static_cast<double>(y));
                    f(static_cast<int64_t>(p), static_cast<size_t>(y * width + x), px, py);
                }
        }
    }

    // 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);

// `target` with its modules where `placement` puts them (a module placement file: docs/RUGNUX_FORMATS.md). A
// placement entry names its module by its readout pixel 0 and readout axes in the image (x0, y0, fast, slow),
// never by its place in the list: each entry has to match one module of `target` exactly and every module
// of `target` has to be named once, else this throws, naming the first that does not match.
DetectorModules ModulesPlaced(const DetectorModules &target, const std::vector<ModulePlacement> &placement);

// The modules of a JUNGFRAU image where only its pixel mask says where they are: every region of pixels
// clear of the module-gap bit (PixelMask::ModuleGapPixelBit) has to be one whole module,
// CONVERTED_MODULE_COLS x CONVERTED_MODULE_LINES either way round, and is taken as placed as imaged.
// Empty where any region is not, or where there are fewer than two. The mask is row-major, width x height.
DetectorModules ModulesFromGapMask(const std::vector<uint32_t> &mask, int64_t width, int64_t height);