pyfli.io.spad_hdf5#

Discover and read SPAD data from arbitrary HDF5 structures.

This module belongs to pyfli.io and provides structure-aware HDF5 discovery without requiring detector-specific group or dataset names. Explicit metadata and user hints take priority over structural inference, while ambiguous layouts are reported instead of selected silently.

Functions

_attribute_lookup(attributes, name)

Find an HDF5 attribute by normalized case-insensitive name.

_build_split_candidates(infos, ...)

Build candidate split-gate layouts from repeated 2D numeric datasets.

_build_stacked_candidates(infos, ...)

Build candidate stacked-cube layouts from 3D numeric datasets.

_candidate_description(candidate)

Return a compact human-readable HDF5 candidate description.

_candidate_is_readable(candidate)

Return whether a candidate has enough information for deterministic loading.

_collect_numeric_datasets(file_handle)

Collect metadata for every non-compound numeric dataset in an HDF5 file.

_extract_numeric_tokens(path)

Extract numeric tokens from an HDF5 path in left-to-right order.

_infer_attribute_order(infos, ...)

Infer gate ordering from a shared scalar numeric dataset attribute.

_infer_path_order(infos)

Infer ordering from the numeric path component that varies across datasets.

_infer_split_order(infos, gate_order_attribute)

Infer deterministic gate ordering using metadata first and path numbers second.

_infer_time_axis(info, requested_time_axis)

Infer a stacked cube's temporal axis using metadata before shape clues.

_is_numeric_dataset(dataset)

Return True for non-compound numeric datasets suitable for SPAD image data.

_keyword_score(paths)

Return a small semantic bonus without making names part of the schema.

_normalize_name(value)

Normalize an attribute or axis label for semantic comparison.

_normalize_path(path)

Normalize an HDF5 object path to a leading-slash representation.

_numeric_path_pattern(path)

Replace numeric tokens in a path so repeated datasets group together.

_numeric_scalar(value)

Convert a scalar numeric HDF5 attribute to float, otherwise return None.

_parent_path(path)

Return the normalized HDF5 parent path.

_parse_axis_tokens(value)

Parse a common HDF5 axis-order attribute into normalized axis tokens.

_python_scalar(value)

Convert HDF5 attribute values to lightweight Python representations.

_read_split_candidate(file_handle, candidate)

Read an ordered set of 2D gate datasets and stack them into (H, W, T).

_read_stacked_candidate(file_handle, candidate)

Read one stacked 3D dataset and move its temporal axis to the last dimension.

_select_candidate(candidates)

Select one deterministic HDF5 layout, rejecting missing or ambiguous discovery.

inspect_spad_hdf5(fname[, dataset_path, ...])

Inspect an HDF5 file and return ranked candidate SPAD layouts.

read_spad_hdf5(fname[, dataset_path, ...])

Discover and normalize SPAD image data from an HDF5 file into (H, W, T).

Classes

HDF5Candidate(kind, dataset_paths, score, ...)

Describe one candidate SPAD layout discovered inside an HDF5 file.

HDF5DatasetInfo(path, shape, dtype, ...)

Describe one numeric HDF5 dataset without loading its full contents.

SpadHDF5ReadResult(data, candidate, source_path)

Store normalized SPAD HDF5 data and discovery metadata.
class HDF5DatasetInfo(path, shape, dtype, attributes, dimension_labels)[source]#

Bases: object

Describe one numeric HDF5 dataset without loading its full contents.

Parameters:
path: str#
shape: tuple[int, ...]#
dtype: str#
attributes: dict[str, Any]#
dimension_labels: tuple[str, ...]#
class HDF5Candidate(kind, dataset_paths, score, spatial_shape, time_axis, gate_values, ordering_source, original_shape)[source]#

Bases: object

Describe one candidate SPAD layout discovered inside an HDF5 file.

Parameters:
kind: str#
dataset_paths: tuple[str, ...]#
score: float#
spatial_shape: tuple[int, int] | None#
time_axis: int | None#
gate_values: tuple[float, ...] | None#
ordering_source: str | None#
original_shape: tuple[int, ...] | None#
to_metadata()[source]#

Return a serializable candidate description.

Return type:

dict[str, object]

class SpadHDF5ReadResult(data, candidate, source_path)[source]#

Bases: object

Store normalized SPAD HDF5 data and discovery metadata.

Parameters:
data: ndarray#
candidate: HDF5Candidate#
source_path: str#
to_metadata()[source]#

Return serializable metadata for the selected HDF5 layout.

Return type:

dict[str, object]

inspect_spad_hdf5(fname, dataset_path=None, time_axis=None, gate_group_path=None, gate_order_attribute=None, gate_prefix=None)[source]#

Inspect an HDF5 file and return ranked candidate SPAD layouts.

Parameters:

  • fname (str) – HDF5 file to inspect.

  • dataset_path (str | None) – Explicit stacked 3D dataset path.

  • time_axis (int | None) – Explicit temporal axis for a stacked 3D dataset.

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

  • gate_order_attribute (str | None) – Dataset attribute used to order split gates.

  • gate_prefix (str | None) – Optional dataset-name prefix used as a backwards-compatible discovery hint.

Returns:

Candidate layouts sorted from highest to lowest discovery score.

Return type:

list[HDF5Candidate]

read_spad_hdf5(fname, dataset_path=None, time_axis=None, gate_group_path=None, gate_order_attribute=None, gate_prefix=None)[source]#

Discover and normalize SPAD image data from an HDF5 file into (H, W, T).

Parameters:

  • fname (str) – HDF5 file to read.

  • dataset_path (str | None) – Explicit stacked 3D dataset path when automatic discovery is ambiguous.

  • time_axis (int | None) – Explicit temporal axis for a stacked 3D dataset.

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

  • gate_order_attribute (str | None) – Dataset attribute used to order split gate datasets.

  • gate_prefix (str | None) – Optional dataset-name prefix used as a backwards-compatible discovery hint.

Returns:

Normalized HDF5 data cube and discovery metadata.

Return type:

SpadHDF5ReadResult