Module tiff_stack 

Multi-frame TIFF stack loading for neutron imaging data.

VENUS beamline data is typically stored as multi-frame TIFF files where each frame corresponds to a time-of-flight (TOF) bin. The result is a 3D array with dimensions (n_tof, height, width).

Supported formats

• Single multi-frame TIFF (all TOF bins in one file)
• Directory of single-frame TIFFs (one file per TOF bin, sorted by name)
• Chunked VENUS autoreduced folder: files named <prefix>_<chunk>_<frame>.tif(f) where the DAQ split one run into several chunks that each cover the full TOF frame range

Chunked folders

When every filename stem in the (extension- and pattern-filtered) folder parses as <prefix>_<chunk>_<frame> with a single common prefix, the folder is treated as chunked:

• one chunk → frames are ordered by numeric frame index (identical to lexicographic order for zero-padded names, and strictly better for unpadded ones where _10 sorts before _2 lexicographically);
• two or more chunks with identical frame-index sequences → chunks are summed element-wise by default (each chunk covers the same TOF bins, so the physical stack is the sum, not a concatenation). Opt out with TiffFolderOptions::sum_chunks = false to get the legacy lexicographic concatenation (the flag only affects folders with two or more chunks — single-chunk folders always load in numeric frame order);
• ragged chunks (differing frame counts or frame sets) or duplicate (chunk, frame) pairs → dispatched on the summing flag. On the default summing path (TiffFolderOptions::sum_chunks = true) they are a hard IoError::ChunkMismatch error, never a silent stack or partial sum (summing ragged chunks would corrupt counts). With summing opted out (sum_chunks = false) there is nothing to corrupt, so the documented legacy lexicographic concatenation loads even for inconsistent chunks, with the irregularity surfaced through TiffLoadInfo::chunk_inconsistent.

Folders with two or more distinct prefixes fall back to legacy lexicographic stacking — summing across different prefixes would merge different runs. Use the pattern argument to select one run.

Mixed folders — where at least one stem parses as <prefix>_<chunk>_<frame> but others do not (a stray overview TIFF, a misnamed frame) — also fall back to legacy lexicographic stacking, but the fallback is counted: TiffLoadInfo::n_unrecognized_files reports how many files disabled chunk detection and TiffLoadInfo::unrecognized_examples names up to MAX_UNRECOGNIZED_EXAMPLES of them, so consumers (the GUI provenance log, the Python UserWarning) can surface that a chunked-looking run folder was not chunk-loaded. Remove the stray files or use pattern to exclude them.

One acquisition per folder

The chunk heuristic assumes the folder holds one acquisition — the VENUS autoreduce layout, where each run gets its own directory (verified on IPTS-37432 output; note the <chunk> field in real names is a run-ish id, e.g. ..._ob_0_116_00000.tif). The heuristic cannot distinguish same-prefix sibling runs co-located in one folder from DAQ chunks of a single run: such siblings would be summed. When a folder may hold multiple runs, select one with pattern or pass TiffFolderOptions::sum_chunks = false.

Pixel-value policy

Raw detector counts are non-negative by construction, so a negative or non-finite pixel signals file corruption or a signed-type readout bug. By default every loader rejects such values with IoError::BadPixelValue (PixelValuePolicy::Reject). Two escape hatches exist:

• PixelValuePolicy::ClipToZero clamps negative values to 0.0 (counted in TiffLoadInfo::n_clipped_pixels); non-finite values still error, because clipping a NaN would invent data;
• PixelValuePolicy::Allow accepts all values verbatim — required for pre-normalized transmission stacks, where noise around zero can legitimately produce small negative values.

For corrupt readout pixels in raw counts (e.g. a railed pixel stuck at a signed sentinel), the right tool is a per-acquisition mask from nereids_io::normalization::detect_bad_pixels, not a load-time clamp.

Data types

• 16-bit unsigned integer (common for neutron detectors)
• 32-bit float (normalized data)

Structs

TiffFolderOptions

Options controlling how a TIFF folder (or file) is loaded.

TiffLoadInfo

Provenance metadata about a completed TIFF load.

TiffStackInfo

Metadata about a loaded TIFF stack.

Enums

PixelValuePolicy

Policy for negative or non-finite pixel values encountered during load.

Constants

MAX_UNRECOGNIZED_EXAMPLES

Maximum number of offending filenames retained in TiffLoadInfo::unrecognized_examples when a mixed folder disables chunk detection (the count in TiffLoadInfo::n_unrecognized_files is never capped).

Functions

load_tiff_auto

Load TIFF data from either a single multi-frame file or a directory.

load_tiff_auto_with_options

Load TIFF data from a file or directory, returning provenance metadata.

load_tiff_directory

Load a directory of single-frame TIFFs as a 3D stack.

load_tiff_folder

Load a directory of TIFFs matching a glob pattern as a 3D stack.

load_tiff_folder_with_options

Load a directory of TIFFs matching a glob pattern, returning provenance metadata.

load_tiff_stack

Load a multi-frame TIFF into a 3D array (n_frames, height, width).

load_tiff_stack_with_options

Load a multi-frame TIFF with an explicit pixel-value policy, returning provenance metadata.