pyfli.io.spad_io#

Coordinate generic and detector-specific SPAD loading, correction, and temporal folding.

This module belongs to pyfli.io and provides one normalized (H, W, T) import path for generic SPAD HDF5 files, SwissSPAD2 HDF5/BIN acquisitions, and SwissSPAD3 HDF5 acquisitions.

Functions

_check_format(detector, input_format)

Reject formats unsupported by a detector-specific loader.

_check_hdf5(result, detector)

Validate the known SwissSPAD split-gate layout after shared discovery.

_check_hp_map(data, hot_pixel_map)

Validate a spatial hot-pixel map for a SPAD cube.

_detect_format(path, configured_format)

Detect HDF5 or SwissSPAD2 BIN input unless configured explicitly.

_expected_repeats(config)

Resolve repeat count from an explicit value or acquisition frequencies.

_hdf5_args(config, detector)

Return generic HDF5 hints or a strict SwissSPAD HDF5 preset.

_load_hdf5(path, config, detector)

Load one HDF5 file or combine a directory of HDF5 cubes.

_load_raw(path, config, detector)

Load SPAD input without corrections or temporal folding.

_process(data, config, hot_pixel_map, ...)

Apply hot-pixel, pile-up, and background corrections in that order.

_process_folder(path, config, detector, ...)

Process each HDF5 cube before the configured folder sum or mean.

_read_hdf5(path, config, detector)

Read one HDF5 cube through the shared reader and validate its preset.

_sort_key(value)

Return a natural-sort key for numbered acquisition files.

load_spad(path[, config, default_bit_depth, ...])

Load SPAD data, apply optional corrections, then align and fold periods.

Classes

SpadConfig([input_format, bit_depth, ...])

Store options for SPAD data import.

SpadIO()

Provide generic, SwissSPAD2, and SwissSPAD3 SPAD loading.

SpadReadResult(data, metadata[, fold_layout])

Store normalized SPAD data, metadata, and an optional fold layout.
class SpadConfig(input_format='auto', bit_depth=10, pile_up=False, fold=False, detector_frequency_mhz=None, laser_frequency_mhz=None, fold_repetitions=None, period_bins=None, phase_shift=None, min_fold_confidence=0.6, fold_validate=True, period_search_radius=0.15, fold_smoothing_sigma=1.0, onset_threshold_fraction=0.1, onset_lead_bins=None, hdf5_dataset_path=None, hdf5_time_axis=None, hdf5_gate_group_path=None, hdf5_gate_order_attribute=None, hdf5_gate_prefix=None, hdf5_folder_mode='sum', ss2_expected_gate_count=None, ss2_top_prefix='top', ss2_bottom_prefix='btm')[source]#

Bases: object

Store options for SPAD data import.

Parameters:

  • input_format (str) – Input format selector: ‘auto’, ‘hdf5’, or ‘ss2_bin’.

  • bit_depth (int) – Detector digitization bit depth used for optional pile-up correction.

  • pile_up (bool) – Whether to apply pile-up correction before folding.

  • fold (bool) – Whether repeated excitation periods should be aligned and summed.

  • detector_frequency_mhz (float | None) – Detector acquisition frequency used to constrain repeat count.

  • laser_frequency_mhz (float | None) – Laser repetition frequency used to constrain repeat count.

  • fold_repetitions (int | None) – Explicit expected number of excitation periods in the acquisition.

  • period_bins (int | None) – Explicit number of gates in one excitation period.

  • phase_shift (int | None) – Explicit temporal circular shift. None enables automatic phase detection.

  • min_fold_confidence (float) – Minimum confidence accepted for automatic fold detection.

  • fold_validate (bool) – Whether low-confidence automatic folding should raise an error.

  • period_search_radius (float) – Fractional search radius around an expected period.

  • fold_smoothing_sigma (float) – Circular Gaussian smoothing sigma used only for timing detection.

  • onset_threshold_fraction (float) – Peak-to-baseline fraction used by the onset detector.

  • onset_lead_bins (int | None) – Gates the folded period starts before the detected onset. None selects 5 % of the period with a minimum of two gates.

  • hdf5_dataset_path (str | None) – Explicit stacked HDF5 dataset path for generic loading.

  • hdf5_time_axis (int | None) – Explicit temporal axis for a stacked generic HDF5 dataset.

  • hdf5_gate_group_path (str | None) – Explicit HDF5 group containing split 2D gate datasets.

  • hdf5_gate_order_attribute (str | None) – HDF5 dataset attribute used to order split gate datasets.

  • hdf5_gate_prefix (str | None) – Optional split-gate dataset prefix used as a discovery hint.

  • hdf5_folder_mode (str) – Combination mode for directories containing multiple HDF5 cubes.

  • ss2_expected_gate_count (int | None) – Optional expected SwissSPAD2 gate count before folding.

  • ss2_top_prefix (str) – Filename prefix for SwissSPAD2 top-detector chunks.

  • ss2_bottom_prefix (str) – Filename prefix for SwissSPAD2 bottom-detector chunks.

input_format: str = 'auto'#
bit_depth: int = 10#
pile_up: bool = False#
fold: bool = False#
detector_frequency_mhz: float | None = None#
laser_frequency_mhz: float | None = None#
fold_repetitions: int | None = None#
period_bins: int | None = None#
phase_shift: int | None = None#
min_fold_confidence: float = 0.6#
fold_validate: bool = True#
period_search_radius: float = 0.15#
fold_smoothing_sigma: float = 1.0#
onset_threshold_fraction: float = 0.1#
onset_lead_bins: int | None = None#
hdf5_dataset_path: str | None = None#
hdf5_time_axis: int | None = None#
hdf5_gate_group_path: str | None = None#
hdf5_gate_order_attribute: str | None = None#
hdf5_gate_prefix: str | None = None#
hdf5_folder_mode: str = 'sum'#
ss2_expected_gate_count: int | None = None#
ss2_top_prefix: str = 'top'#
ss2_bottom_prefix: str = 'btm'#
classmethod from_value(value, default_bit_depth=10)[source]#

Build a validated configuration from an object, mapping, or defaults.

Parameters:
Return type:

SpadConfig

to_metadata()[source]#

Return the configuration as serializable metadata.

Return type:

dict[str, Any]

class SpadReadResult(data, metadata, fold_layout=None)[source]#

Bases: object

Store normalized SPAD data, metadata, and an optional fold layout.

Parameters:
data: ndarray#
metadata: dict[str, Any]#
fold_layout: SpadFoldLayout | None = None#
load_spad(path, config=None, default_bit_depth=10, fold_layout=None, hot_pixel_map=None, background=None, sub_bg=False, detector=None)[source]#

Load SPAD data, apply optional corrections, then align and fold periods.

Parameters:

  • path (str) – SPAD HDF5 path, SwissSPAD2 BIN path, or supported acquisition directory.

  • config (SpadConfig | dict[str, Any] | None) – SPAD loading and processing options.

  • default_bit_depth (int) – Detector bit depth used when config does not provide one.

  • fold_layout (SpadFoldLayout | None) – Existing fold layout to reuse for a related acquisition.

  • hot_pixel_map (np.ndarray | None) – Optional 2D hot-pixel map.

  • background (np.ndarray | None) – Optional background cube matching the pre-fold SPAD cube.

  • sub_bg (bool) – Whether to subtract the supplied background before folding.

  • detector (str | None) – Optional detector preset: ‘ss2’ or ‘ss3’. None keeps generic discovery.

Returns:

Normalized SPAD cube and import metadata.

Return type:

SpadReadResult

class SpadIO[source]#

Bases: object

Provide generic, SwissSPAD2, and SwissSPAD3 SPAD loading.

static get_format(path, config=None, default_bit_depth=10, detector=None)[source]#

Resolve and validate the input format without loading data.

Parameters:
Return type:

str

static load(path, config=None, default_bit_depth=10, fold_layout=None, hot_pixel_map=None, background=None, sub_bg=False)[source]#

Load generic SPAD HDF5 or SwissSPAD2 BIN data.

Parameters:
Return type:

SpadReadResult

static load_ss2(path, config=None, default_bit_depth=10, fold_layout=None, hot_pixel_map=None, background=None, sub_bg=False, pile_up=None)[source]#

Load SwissSPAD2 HDF5 or native BIN data.

Parameters:
Return type:

SpadReadResult

static load_ss3(path, config=None, default_bit_depth=10, fold_layout=None, hot_pixel_map=None, background=None, sub_bg=False, pile_up=None)[source]#

Load SwissSPAD3 HDF5 data.

Parameters:
Return type:

SpadReadResult