playnano.io.data_loaders module

Data loaders for AFM image stacks exported by playNano.

This module provides readers for serialized AFMImageStack bundles created by the export routines (.npz, .h5, and OME-TIFF). Each loader reconstructs a AFMImageStack with correct data, pixel size, channel name, and per-frame metadata (timestamps). All loaders restore provenance and any stored processing or mask data.

Functions

load_npz_bundle

Load a .npz bundle into an AFMImageStack.

load_h5_bundle

Load a .h5 bundle into an AFMImageStack.

load_ome_tiff_stack

Load an OME-TIFF bundle into an AFMImageStack.

playnano.io.data_loaders.load_h5_bundle(path: Path, channel: str = 'height_trace') → AFMImageStack[source]

Load an AFMImageStack from an HDF5 bundle.

Expected HDF5 structure

Datasets

  • /data : float32 array of shape (n_frames, H, W)

  • /processed/<step> : optional processed datasets

  • /masks/<mask> : optional boolean mask datasets

  • /frame_metadata_json : UTF-8 encoded JSON (list of dicts)

  • /provenance_json : UTF-8 encoded JSON (dict)

  • /state_backups_json : optional UTF-8 JSON (dict)

Attributes

  • pixel_size_nm : scalar float

  • channel : string

Files with the structure are produced by playNano.io.export_data.save_h5_bundle().

param path:

Path to the .h5 file.

type path:

pathlib.Path

param channel:

Provided for API compatibility with load_afm_stack() but ignored when reading the bundle.

type channel:

str, default=”height_trace”

returns:

Fully reconstructed AFM image stack with provenance, processed steps, and masks restored.

rtype:

playNano.afm_stack.AFMImageStack

raises ValueError:

If required datasets are missing or JSON decoding fails. If required datasets (frame_metadata_json or provenance_json) are missing or contain invalid JSON.

playnano.io.data_loaders.load_npz_bundle(path: Path, channel: str = 'height_trace') → AFMImageStack[source]

Load an AFMImageStack from a .npz bundle.

The .npz file must contain the following keys:

  • data : float32 array of shape (n_frames, H, W)

  • pixel_size_nm : scalar float

  • channel : str scalar

  • frame_metadata_json : JSON-encoded list of dicts

  • provenance_json : JSON-encoded dict

  • processed__<step> : optional processed frame arrays

  • masks__<mask> : optional boolean mask arrays

  • state_backups_json : optional JSON-encoded dict of saved states

This is the structure produced by playNano.io.export_data.save_npz_bundle().

Parameters:

  • path (pathlib.Path) – Path to the .npz file.

  • channel (str, default="height_trace") – Provided for API compatibility with load_afm_stack() but ignored when reading the bundle.

Returns:

Reconstructed AFM image stack with attributes populated: .processed, .masks, and .provenance.

Return type:

playNano.afm_stack.AFMImageStack

Raises:

ValueError – If required keys are missing or JSON blobs cannot be decoded.

playnano.io.data_loaders.load_ome_tiff_stack(path: Path, channel: str = 'height_trace') → AFMImageStack[source]

Load an OME-TIFF bundle into an AFMImageStack.

Attempts to parse OME-XML and custom metadata tags to reconstruct pixel size, timestamps, and provenance. Falls back gracefully if certain metadata are unavailable.

Parameters:

  • path (pathlib.Path) – Path to the .ome.tif file created by save_ome_tiff_stack().

  • channel (str, optional) – Fallback channel name if none is found in OME metadata.

Returns:

Reconstructed AFMImageStack with:

  • data : 3D float32 array (T, H, W)

  • pixel_size_nm : float, derived from OME physical size

  • channel : str, from OME Channel or fallback

  • frame_metadata : list of dicts containing timestamps

  • provenance : dict reconstructed from custom or embedded tags

Return type:

playNano.afm_stack.AFMImageStack

Raises:

ValueError – If the image array shape is unsupported or essential metadata cannot be parsed.