playnano.io.export_data module

Tools for exporting AFM image stacks in multiple formats.

This module provides utilities for serializing AFMImageStack objects into round-trip-safe formats: OME-TIFF, NPZ, and HDF5. Each export preserves pixel data, metadata, masks, provenance, and processing history.

Supported formats

  • OME-TIFF: For image analysis interoperability (Bio-Formats compatible).

  • NPZ: Compact NumPy archive with full AFMImageStack data and metadata.

  • HDF5: Hierarchical bundle ideal for provenance-rich workflows.

Each export supports both filtered and raw modes.

playnano.io.export_data.check_path_is_path(path: str | Path) → Path[source]

Ensure the input is returned as a pathlib.Path.

Converts strings to Path objects. Raises TypeError for unsupported types.

Parameters:

path (str or Path) – The input path to validate or convert.

Returns:

A pathlib.Path object representing the input path.

Return type:

Path

Raises:

TypeError – If the input is not a str or Path.

playnano.io.export_data.export_bundles(afm_stack: AFMImageStack, output_folder: Path, base_name: str, formats: list[str], raw: bool = False) → None[source]

Export an AFMImageStack in one or more serialization formats.

Parameters:

  • afm_stack (AFMImageStack) – The stack to export.

  • output_folder (Path) – Target directory for output files.

  • base_name (str) – Base filename (no extension).

  • formats (list of {"tif", "npz", "h5"}) – Which formats to produce.

  • raw (bool, optional) – If True, exports only the unprocessed raw snapshot, (.processed['raw']). Default is False.

Raises:

SystemExit – If an unsupported format string is provided.

playnano.io.export_data.save_h5_bundle(path: Path, stack: AFMImageStack, raw: bool = False) → None[source]

Save an AFMImageStack and metadata as an HDF5 bundle.

The hierarchical layout preserves round-trip reconstruction fidelity and stores all relevant AFM stack data, processed layers, masks, timestamps, and provenance.

File structure

/data

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

/processed/<step> : float32 datasets for each processing step /masks/<mask> : bool datasets for each mask /timestamps : float64 array of length n_frames /frame_metadata_json : UTF-8 encoded JSON string /provenance_json : UTF-8 encoded JSON string /state_backups_json : UTF-8 encoded JSON string (only if present)

Root attributes

pixel_size_nmfloat

Physical pixel size in nanometers.

channelstr

Name of the imaging channel.

param path:

Destination path for the HDF5 file. The ‘.h5’ suffix will be added automatically.

type path:

Path

param stack:

The stack to export.

type stack:

AFMImageStack

param raw:

If True, only the unprocessed raw snapshot (processed[‘raw’]) is exported. Otherwise, the full .data, masks, and processed layers are included.

type raw:

bool, optional

Notes

  • state_backups_json is only created if the stack has a non-empty

state_backups attribute. - Timestamps are taken from state_backups[‘frame_metadata_before_edit’] if exporting raw data, otherwise from .frame_metadata. - Provenance is sanitized via make_json_safe().

playnano.io.export_data.save_npz_bundle(path: Path, stack: AFMImageStack, raw: bool = False) → None[source]

Save AFMImageStack with metadata as a .npz bundle.

The NPZ archive consolidates the AFM stack data, metadata, provenance, masks, and processed layers for full round-trip reconstruction.

File structure

data : float32 array of shape (n_frames, H, W) processed__<step> : float32 arrays for each processing step masks__<mask> : bool arrays for each mask timestamps : float64 array of length n_frames frame_metadata_json : UTF-8 encoded JSON string provenance_json : UTF-8 encoded JSON string state_backups_json : UTF-8 encoded JSON string (only if present) pixel_size_nm : float32 scalar channel : object array (string)

param path:

Destination path for the .npz file. The extension will be added automatically.

type path:

Path

param stack:

The stack to export.

type stack:

AFMImageStack

param raw:

If True, only the unprocessed raw snapshot and essential metadata are saved. Otherwise, the full data (.data), masks, and processed layers are included.

type raw:

bool, optional

Notes

  • state_backups_json is only included if the stack defines a state_backups attribute.

  • When raw=True, timestamps are taken from state_backups['frame_metadata_before_edit'] (if available), otherwise from .frame_metadata.

  • Provenance is serialized using make_json_safe() to ensure JSON compatibility.

  • The saved file can be reloaded via load_npz_bundle().

Examples

>>> from pathlib import Path
>>> from playnano.io.export_data import save_npz_bundle
>>> save_npz_bundle(Path("output/stack_export"), stack)
>>> save_npz_bundle(Path("output/raw_only"), stack, raw=True)
playnano.io.export_data.save_ome_tiff_stack(path: Path, afm_stack: AFMImageStack, raw: bool = False) → None[source]

Save an AFMImageStack as an OME-TIFF file.

The OME-TIFF export embeds image data, pixel calibration, timestamps, and provenance metadata into a single, standards-compliant file suitable for downstream analysis in microscopy or image-processing software.

File structure

  • Image data is stored in 5D OME-TIFF format with axes (T, C, Z, Y, X). Only a single channel (C=1) and a single Z-slice (Z=1) are used.

  • Physical calibration is stored in micrometres (µm) under PhysicalSizeX and PhysicalSizeY.

  • Provenance and processed-layer keys are stored as binary JSON under private TIFF tags 65000 and 65001.

param path:

Output path for the .ome.tif file.

type path:

Path

param afm_stack:

The AFM image stack to export.

type afm_stack:

AFMImageStack

param raw:

If True, export the unprocessed raw snapshot (processed['raw'] if present). Otherwise, export the current data in .data with all processing applied.

type raw:

bool, optional

Notes

  • Each frame’s timestamp is stored in the OME metadata as DeltaT.

  • The pixel size (in nm) is converted to micrometres for OME compliance.

  • The exported file includes additional TIFF tags:

    • 65000: JSON-encoded provenance dictionary

    • 65001: JSON list of processed layer names

  • The file can be reloaded with standard OME-TIFF readers such as tifffile or aicsimageio.

Examples

>>> from pathlib import Path
>>> from playnano.io.export_data import save_ome_tiff_stack
>>> save_ome_tiff_stack(Path("output/stack.ome.tif"), stack)
>>> save_ome_tiff_stack(Path("output/raw_stack.ome.tif"), stack, raw=True)