RawFile

Reading requires frame padding to be enabled or Frame Discard Policy to be discardpartial. The constructor checks the parsed master metadata before opening data subfiles and throws std::runtime_error with the master path if this requirement is not met. This applies to JSON and legacy .raw masters, including when opened through aare::File. RawMasterFile can still be used to inspect their metadata.

total_frames() is the minimum actual frame count across all selected RawSubFile objects in all ROIs. Each subfile count includes its complete series of .raw files and is determined when the file is opened. Disabled UDP ports are excluded. An empty subfile makes the count zero; opening a file with no selected subfiles raises an error.

A warning is logged once on opening if the subfile counts differ or their minimum differs from master().frames_in_file(). It reports the subfile count range, the master count, and the count used for reading. The master metadata is preserved. Its expected frame count does not affect the count used for reading.

Frame, batch, ROI, and frame-number reads use this minimum as their bound. Frame-number synchronization may still fail within this bound if detector frame numbers differ between subfiles.

Read errors include the attempted zero-based frame index and the failing file path. Errors from a data subfile identify that subfile’s path and preserve the underlying failure reason without adding a master-file wrapper or C++ source location. Out-of-range subfile errors also report the available frame count across that subfile’s series. This applies to frame, batch, ROI, and frame-number reads, including reads through aare::File.

The frame index is the position in the file, not the frame number recorded by the detector. Batch errors report the index of the frame that failed.

Synchronization errors identify the last .raw data file read for the module that ran out of frames. Requests rejected as out of range before accessing a subfile report the master path, since there is no single failing data file. The top-level frame bounds error states the number of frames in the file and that indices are zero-based.

class RawFile : public aare::FileInterface

Class to read .raw files. The class will parse the master file to find the correct geometry for the frames.

Note

A more generic interface is available in the aare::File class. Consider using that unless you need raw file specific functionality.

Public Functions

RawFile(const std::filesystem::path &fname, const std::string &mode = "r")

RawFile constructor.

Parameters:

• fname – path to the master file (.json)

• mode – file mode (only “r” is supported at the moment)

Throws:

std::runtime_error – if frame padding is disabled and the frame discard policy is not DiscardPartial.

virtual ~RawFile() override = default

virtual Frame read_frame() override

one frame from the file at the current position

Returns:

Frame

virtual Frame read_frame(size_t frame_number) override

read one frame from the file at the given frame number

Parameters:

frame_number – frame number to read

Returns:

frame

virtual std::vector<Frame> read_n(size_t n_frames) override

read n_frames from the file at the current position

Parameters:

n_frames – number of frames to read

Returns:

vector of frames

Frame read_roi(const size_t roi_index)

Read one ROI defined in the master file.

Note

the frame index is incremented after calling this function so reading rois one after the other wont work.

Parameters:

roi_index – index of the ROI to read

Returns:

Frame

std::vector<Frame> read_rois()

Read all ROIs defined in the master file.

Returns:

vector of Frames (one Frame per ROI)

std::vector<Frame> read_n_with_roi(const size_t n_frames, const size_t roi_index)

Read n frames for the given ROI index.

Parameters:

• n_frames – number of frames to read

• roi_index – index of the ROI to read

Returns:

vector of Frames

virtual void read_into(std::byte *image_buf) override

read one frame from the file at the current position and store it in the provided buffer

Parameters:

image_buf – buffer to store the frame

Returns:

void

virtual void read_into(std::byte *image_buf, size_t n_frames) override

read n_frames from the file at the current position and store them in the provided buffer

Parameters:

• image_buf – buffer to store the frames

• n_frames – number of frames to read

Returns:

void

void read_into(std::byte *image_buf, DetectorHeader *header = nullptr)

void read_into(std::byte *image_buf, size_t n_frames, DetectorHeader *header)

void read_roi_into(std::byte *image_buf, const size_t roi_index, const size_t frame_number, DetectorHeader *header = nullptr)

virtual size_t frame_number(size_t frame_index) override

get the frame number at the given frame index

Parameters:

frame_index – index of the frame

Returns:

frame number

virtual size_t bytes_per_frame() override

get the size of one frame in bytes

Returns:

size of one frame

size_t bytes_per_frame(const size_t roi_index)

bytes per frame for the given ROI

Parameters:

roi_index – index of the ROI

virtual size_t pixels_per_frame() override

get the number of pixels in one frame

Returns:

number of pixels in one frame

size_t pixels_per_frame(const size_t roi_index)

pixels per frame for the given ROI

Parameters:

roi_index – index of the ROI

size_t bytes_per_pixel() const

virtual void seek(size_t frame_index) override

seek to the given frame number

Parameters:

frame_number – frame number to seek to

Returns:

void

virtual size_t tell() override

get the current position of the file pointer

Returns:

current position of the file pointer

virtual size_t total_frames() const override

Minimum actual frame count across all subfiles and ROIs.

virtual size_t rows() const override

get the number of rows in the file

Returns:

number of rows in the file

size_t rows(const size_t roi_index) const

rows for the given ROI

Parameters:

roi_index – index of the ROI

virtual size_t cols() const override

get the number of columns in the file

Returns:

number of columns in the file

size_t cols(const size_t roi_index) const

cols for the given ROI

Parameters:

roi_index – index of the ROI

virtual size_t bitdepth() const override

get the bitdepth of the file

Returns:

bitdepth of the file

inline virtual Dtype dtype() const override

get the data type of the pixels

Returns:

pixel data type

size_t n_modules() const

size_t num_rois() const

number of ROIs defined (always 1 for complete ROI)

const ROIGeometry &roi_geometries(size_t roi_index) const

get the ROI geometry for the given ROI index

Parameters:

roi_index – index of the ROI

std::vector<size_t> n_modules_in_roi() const

number of modules in each ROI

xy geometry() const

RawMasterFile master() const

virtual DetectorType detector_type() const override

Public Static Functions

static DetectorHeader read_header(const std::filesystem::path &fname)

read the header of the file

Parameters:

fname – path to the data subfile

Returns:

DetectorHeader

Private Functions

std::runtime_error frame_error(size_t frame_index, const std::string &message) const

void get_frame_into(size_t frame_index, std::byte *frame_buffer, const size_t roi_index = 0, DetectorHeader *header = nullptr)

read the frame at the given frame index into the image buffer

Parameters:

• frame_index – frame number to read

• frame_buffer – buffer to store the frame

• roi_index – index of the ROI to read (default is 0 e.g. full frame)

Frame get_frame(size_t frame_index, const size_t roi_index = 0)

get the frame at the given frame index

Parameters:

• frame_number – frame number to read

• roi_index – index of the ROI to read (default is 0 e.g. full frame)

Returns:

Frame

void open_subfiles(const size_t roi_index)

Private Members

std::vector<std::vector<std::unique_ptr<RawSubFile>>> m_subfiles

RawMasterFile m_master

size_t m_current_frame = {}

std::vector<ROIGeometry> m_ROI_geometries

size_t m_frames_in_file = {}

Minimum frame count across the selected raw subfile series.