pyfli.io.ss2_bin#

Decode native SwissSPAD2 binary acquisitions into PyFLI image cubes.

This module belongs to pyfli.io and implements the SwissSPAD2 binary layout used by topN.bin / btmN.bin acquisitions. Raw 256 x 512 detector halves are decoded, column banks are deinterleaved, 10-bit subframes are accumulated, and top/bottom halves are stitched into a 512 x 512 x T data cube.

Functions

_compile_chunk_pattern(prefix)

Compile a case-insensitive top/bottom chunk filename pattern.

_decode_ss2_bin_into(file_path, target, ...)

Decode one BIN chunk blockwise into a preallocated (256, 512, T) target view.

_decoded_gate_count(file_path, bit_depth)

Return raw-frame and decoded-gate counts for one SwissSPAD2 BIN chunk.

_raw_frame_count(file_path)

Return the number of complete 256 x 512 uint8 frames in one BIN chunk.

_validate_bit_depth(bit_depth)

Validate SwissSPAD2 binary acquisition bit depth.

combine_ss2_10bit_subframes(frames)

Sum each group of four SwissSPAD2 raw subframes into one 10-bit acquisition gate.

deinterleave_ss2_columns(raw_frames)

Convert SwissSPAD2 four-bank raw column order into physical detector column order.

discover_ss2_bin_files(path[, top_prefix, ...])

Discover and numerically order matching SwissSPAD2 top/bottom binary chunks.

read_ss2_bin_acquisition(path[, bit_depth, ...])

Decode, orient, concatenate, and stitch a complete SwissSPAD2 binary acquisition.

read_ss2_bin_file(file_path[, bit_depth])

Decode one SwissSPAD2 top or bottom binary chunk into (256, 512, T).

Classes

SS2BinReadResult(data, bit_depth, ...)

Store a decoded SwissSPAD2 binary acquisition and its source metadata.
class SS2BinReadResult(data, bit_depth, chunk_indices, top_files, bottom_files, raw_frame_count, gate_count)[source]#

Bases: object

Store a decoded SwissSPAD2 binary acquisition and its source metadata.

Parameters:

  • data (np.ndarray) – Stitched SwissSPAD2 data cube with shape (512, 512, T).

  • bit_depth (int) – Acquisition bit depth used to decode raw binary frames.

  • chunk_indices (tuple[int, ]) – Numeric chunk indices discovered for the top and bottom binary files.

  • top_files (tuple[str, ]) – Ordered top-detector source files.

  • bottom_files (tuple[str, ]) – Ordered bottom-detector source files.

  • raw_frame_count (int) – Total number of raw binary frames per detector half.

  • gate_count (int) – Number of decoded acquisition gates before any temporal folding.

data: ndarray#
bit_depth: int#
chunk_indices: tuple[int, ...]#
top_files: tuple[str, ...]#
bottom_files: tuple[str, ...]#
raw_frame_count: int#
gate_count: int#
to_metadata()[source]#

Convert the binary-read result to serializable metadata.

Returns:

Dictionary describing the decoded SwissSPAD2 binary acquisition.

Return type:

dict[str, object]

discover_ss2_bin_files(path, top_prefix='top', bottom_prefix='btm')[source]#

Discover and numerically order matching SwissSPAD2 top/bottom binary chunks.

Parameters:

  • path (str) – Directory containing the acquisition or one top/bottom .bin file inside it.

  • top_prefix (str) – Filename prefix used for the top detector half.

  • bottom_prefix (str) – Filename prefix used for the bottom detector half.

Returns:

Ordered top files, ordered bottom files, and their common numeric chunk indices.

Return type:

tuple[list[str], list[str], tuple[int, ]]

deinterleave_ss2_columns(raw_frames)[source]#

Convert SwissSPAD2 four-bank raw column order into physical detector column order.

Parameters:

raw_frames (np.ndarray) – Array whose last two dimensions are (256, 512), with raw columns stored as four consecutive 128-column banks.

Returns:

Array with the same shape and dtype, reordered into physical detector columns.

Return type:

np.ndarray

combine_ss2_10bit_subframes(frames)[source]#

Sum each group of four SwissSPAD2 raw subframes into one 10-bit acquisition gate.

Parameters:

frames (np.ndarray) – Deinterleaved raw frames with shape (N, 256, 512).

Returns:

Decoded acquisition gates with shape (N / 4, 256, 512) and uint16 dtype.

Return type:

np.ndarray

read_ss2_bin_file(file_path, bit_depth=10)[source]#

Decode one SwissSPAD2 top or bottom binary chunk into (256, 512, T).

Parameters:

  • file_path (str) – Path to one SwissSPAD2 binary chunk.

  • bit_depth (int) – Acquisition bit depth. Supported values are 8 and 10.

Returns:

Decoded detector-half cube with shape (256, 512, T) and uint16 dtype.

Return type:

np.ndarray

read_ss2_bin_acquisition(path, bit_depth=10, expected_gate_count=None, top_prefix='top', bottom_prefix='btm')[source]#

Decode, orient, concatenate, and stitch a complete SwissSPAD2 binary acquisition.

The native SwissSPAD2 top and bottom detector halves use opposite row orientations. The top half is retained in decoded row order, while the bottom half is vertically flipped before it is placed below the top half. The resulting cube is returned in physical detector orientation with shape (512, 512, T).

Parameters:

  • path (str) – Directory containing topN.bin / btmN.bin files or one file within that set.

  • bit_depth (int) – Acquisition bit depth. Supported values are 8 and 10.

  • expected_gate_count (int | None) – Optional expected number of decoded gates before temporal folding.

  • top_prefix (str) – Filename prefix used for the top detector half.

  • bottom_prefix (str) – Filename prefix used for the bottom detector half.

Returns:

Stitched 512 x 512 x T cube and exact source/decode metadata.

Return type:

SS2BinReadResult