Jungfraujoch/reader/SFRM.h

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

#pragma once

#include <array>
#include <cstdint>
#include <map>
#include <string>
#include <vector>

// Bruker .sfrm: the frame format of Bruker's SMART, PROTEUM and APEX software. An ASCII header of
// 80-character "KEY    :value" lines, HDRBLKS blocks of 512 bytes long, then the pixels as unsigned
// little-endian integers of NPIXELB[0] bytes, row after row, then the tables that hold what did not
// fit in that container.
//
//   FORMAT :100        VERSION:11      HDRBLKS:15
//   NOVERFL:-1 5502 0  NPIXELB:1 1     NROWS  :1024    NCOLS  :1024
//   ANGLES :2theta omega phi chi       AXIS   :2       START  :0.0    INCREME:-0.2
//   DISTANC:10.0 (cm)  CENTER :506 511 ...             WAVELEN:1.5419 1.5406 1.5444
//
// Two layouts of the tables exist. FORMAT 86 (VERSION < 11) has one ASCII overflow table after the
// image: NOVERFL entries of 16 characters, a 9-digit count and a 7-digit pixel offset, padded to a
// whole 512-byte block. FORMAT 100 has three binary tables, each padded to 16 bytes: NOVERFL[0]
// underflows of NPIXELB[1] bytes (absent where NOVERFL[0] is -1), NOVERFL[1] 16-bit overflows and
// NOVERFL[2] 32-bit ones. A pixel holding its container's maximum takes the next value of the next
// wider table, in pixel order; a pixel holding 0 takes the next underflow. The 32-bit table is
// signed - a pixel far enough below the baseline is stored there as a negative count. Every stored value carries
// the baseline offset NEXP[2], so the counts are the values less that offset.
//
// The layout as Bruker's frame format documents it, checked byte for byte against APEX's own
// conversion of the same frames to imgCIF: the pixels come out identical but for the baseline, which
// the conversion subtracts.
namespace sfrm {

struct Header {
    int64_t format = 0;                 // 86 or 100
    int64_t header_blocks = 0;          // HDRBLKS
    int64_t nrows = 0;
    int64_t ncols = 0;
    int64_t bytes_per_pixel = 1;        // NPIXELB[0]
    int64_t bytes_per_underflow = 1;    // NPIXELB[1], FORMAT 100
    std::array<int64_t, 3> overflows{-1, 0, 0};   // NOVERFL: FORMAT 86 uses [0] only
    int64_t baseline = 0;               // NEXP[2]
    std::array<double, 4> angles{};     // ANGLES: 2theta, omega, phi, chi at the start of the frame (deg)
    int64_t axis = 0;                   // AXIS: 1 2theta, 2 omega, 3 phi, 4 chi
    double start_deg = 0;               // START
    double increment_deg = 0;           // INCREME, signed
    double distance_cm = 0;             // DISTANC, its last value
    std::vector<double> center;         // CENTER, pixels
    double pixels_per_cm_512 = 0;       // DETTYPE[1]: pixels per cm on a 512-pixel frame
    double grid_offset_cm = 0;          // DETTYPE[2]: detector face to the calibration grid
    double wavelength_A = 0;            // WAVELEN[0]
    double exposure_s = 0;              // CUMULAT
    double saturation = 0;              // CCDPARM[4]; 0 where not stated
    std::array<double, 6> detpar{};     // DETPAR: three offsets, then pitch, roll, yaw (deg)
    double monochromator_2theta_deg = 0;   // FILTER2[0]: the monochromator's scattering angle; 0 for none
    std::string detector;               // DETTYPE[0]
    std::map<std::string, std::string> raw;   // every key; repeated keys joined with a space
};

// True if the path names something this reader can open: a .sfrm frame, or a directory holding one.
bool CanRead(const std::string &path);

// The files of one sweep, in collection order. path is a directory, or one frame inside it.
std::vector<std::string> CollectSweep(const std::string &path);

// Parse a header from its bytes (at least HDRBLKS * 512 of them).
Header ParseHeader(const char *data, size_t size);

// Header only - reads just the header blocks.
Header ReadHeader(const std::string &path);

// Header + counts (stored value with the overflows resolved, less the baseline) into memory the
// caller already has. scratch carries the raw bytes between frames.
Header ReadInto(const std::string &path, int32_t *out, size_t capacity, std::vector<uint8_t> &scratch);

// The same, decoding from the whole file already in memory. Throws if out holds fewer than
// nrows * ncols pixels or the tables run past the end.
Header Decode(const uint8_t *data, size_t size, int32_t *out, size_t capacity);

// Header + counts into a vector sized to fit.
Header Read(const std::string &path, std::vector<int32_t> &out);

}  // namespace sfrm