Jungfraujoch/rugnux/DiagnosticOutput.h

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

#pragma once

#include <string>
#include <vector>

#include "../common/ColorScale.h"
#include "../common/DiffractionExperiment.h"
#include "../common/PixelMask.h"

// Two files a person reads to check by eye what the run decided, written next to the reflections on
// every rotation run: the detector as the pipeline saw it, and one row per image.

// The mean projection the beam-stop pre-scan built, coloured with the viewer's own default map
// (common/ColorScale.h): white-to-indigo for the counts, grey for the module and chip gaps, coral
// for the detected shadow, magenta for everything else the mask holds. The shadow is a place where
// the background is missing, so drawing the mask on top of the very projection the detection tested
// is what makes a wrong shadow visible - a coral patch over unbroken background, or a dark patch
// left uncoloured.
std::vector<rgb> DetectorDiagnosticRGB(const PixelMask &pixel_mask,
                                       const std::vector<float> &mean_projection);

// The same picture as JPEG bytes, at the detector's own pixel count.
std::string RenderDetectorDiagnostic(const DiffractionExperiment &experiment,
                                     const PixelMask &pixel_mask,
                                     const std::vector<float> &mean_projection);

// The columns of <prefix>_plot.txt. Every vector is indexed by the processed-image ordinal - the
// numbering of every per-image array rugnux writes - and a value nothing measured is NAN.
// frame_disposition holds FrameDisposition (Merge.h) and is empty when the sweep-quality diagnostic
// did not run.
struct PerImagePlot {
    std::vector<float> bkg_estimate;
    std::vector<float> resolution_A;
    std::vector<float> spot_count;
    std::vector<float> scale_g;
    std::vector<float> mosaicity_deg;
    std::vector<float> cc_to_merge;
    std::vector<int> cc_n;
    std::vector<uint8_t> frame_disposition;
    std::optional<GoniometerAxis> goniometer;   // the angle column; none: nan
    size_t image_count = 0;                     // the rows
};

// The text of <prefix>_plot.txt: one '#' legend line naming the columns, then one whitespace-separated
// row per image, so `plot '<f>' using 1:4` works with nothing in between.
std::string PerImagePlotText(const PerImagePlot &plot);