playNano.io package

Subpackages

• playNano.io.formats package
  • Submodules
  • playNano.io.formats.read_asd module
    • load_asd_file()
  • playNano.io.formats.read_h5jpk module
    • apply_z_unit_conversion()
    • load_h5jpk()
  • playNano.io.formats.read_jpk_folder module
    • load_jpk_folder()
  • playNano.io.formats.read_spm_folder module
    • load_spm_folder()
    • parse_spm_header()
  • Module contents

Submodules

playNano.io.data_loaders module

Data loaders for stacks exported by playNano.

This module provides readers for AFMImageStack bundles created by our export routines (.npz, .h5, and OME-TIFF). Each loader will reconstruct an AFMImageStack with correct data, pixel size, channel, and per-frame metadata (timestamps).

Functions

load_npz_bundle

Load a .npz bundle into an AFMImageStack.

load_h5_bundle

Load an HDF5 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

Load an AFMImageStack from a .h5 bundle produced by save_h5_bundle.

Expects:

• /data

  float32 (n_frames, H, W)

• /processed/<step> float32 subgroups

• /masks/<mask> boolean subgroups

• /timestamps

  float64 (n_frames,)

• /frame_metadata_json

  UTF-8 string (JSON list of dict)

• /provenance_json

  UTF-8 string (JSON dict)

Attributes: - pixel_size_nm : float - channel : UTF-8 string

Parameters:

• path (Path) – Path to the .h5 file.

• channel (str = "height_trace") – For being called by load_afm_stack but ignored.

Returns:

Reconstructed stack, with .processed, .masks, and .provenance filled.

Return type:

AFMImageStack

Raises:

ValueError – 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

Load an AFMImageStack from a .npz bundle produced by save_npz_bundle.

Expects keys:

• data : float32 (n_frames, H, W)

• pixel_size_nm : float32 scalar

• channel : object scalar

• frame_metadata_json: object scalar (JSON list of dict)

• provenance_json : object scalar (JSON dict)

• processed__<step> : float32 arrays

• masks__<mask> : boolean arrays

Parameters:

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

• channel (str = "height_trace") – For being called by load_afm_stack but ignored.

Returns:

Reconstructed stack, with .processed, .masks, and .provenance filled.

Return type:

AFMImageStack

Raises:

ValueError – If required arrays (frame_metadata_json or provenance_json) are missing or contain invalid JSON.

playNano.io.data_loaders.load_ome_tiff_stack(path: Path, channel: str = 'height_trace') → AFMImageStack

Load an OME-TIFF bundle into an AFMImageStack.

Parameters:

• path (Path) – Path to the .ome.tif file produced 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) or 5D float32 array (T, 1, 1, H, W) - pixel_size_nm: float (converted from µm metadata if available) - channel: first entry of ChannelName OME tag or the channel parameter - frame_metadata: list of dicts with “timestamp” if available

Return type:

AFMImageStack

Raises:

ValueError – If required datasets (frame_metadata_json or provenance_json) are missing or contain invalid JSON.

playNano.io.export_data module

Tools for exporting AFM image stacks in multiple formats.

Provides functions to export AFM stacks with metadata as OME-TIFF, NPZ, or HDF5 bundles. Handles path validation, metadata embedding, and file structure creation.

playNano.io.export_data.check_path_is_path(path: str | Path) → Path

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

Export a playNano AFMImageStack in OME-TIFF, NPZ, and/or HDF5 formats.

OME-TIFF

• Writes a single 5D TCZYX TIFF containing only pixel data.

• Embeds these metadata in OME-XML “UserData…” tags: - PhysicalSizeX/Y/Z, TimeIncrement, TimePoint, ChannelName - UserDataProcessed: JSON list of processing step names - UserDataProvenance: JSON dump of the stack’s provenance dict

• Use raw=True to export the unfiltered snapshot (.processed['raw']). Otherwise, exports the current .data (post-filtered).

NPZ & HDF5 Bundles

• Round-trip safe serialization of the entire AFMImageStack: .data, .processed, .masks, .frame_metadata, .pixel_size_nm, .channel, and .provenance.

• Reloading yields the identical Python object.

• Use raw=True to export just the unfiltered snapshot (.processed['raw']). Otherwise, exports all data.

Notes

• If raw=True, all formats (TIFF, NPZ, HDF5) will contain only the raw snapshot (.processed[‘raw’]) and ignore .processed and .masks.

• If raw=False, OME-TIFF exports afm_stack.data, while NPZ and HDF5 export the entire AFMImageStack.

param afm_stack:

The stack to export.

type afm_stack:

AFMImageStack

param output_folder:

Directory in which to write the outputs.

type output_folder:

Path

param base_name:

Base filename (no extension) for each export.

type base_name:

str

param formats:

Formats to produce.

type formats:

list of {“tif”, “npz”, “h5”}

param raw:

If True, the exports will contain the raw snapshot (.processed['raw'])

type raw:

bool, default=False

raises SystemExit:

If any entry in formats is not one of {“tif”,”npz”,”h5”}.

playNano.io.export_data.save_h5_bundle(path: Path, stack: AFMImageStack, raw: bool = False) → None

Save an AFMImageStack (data + metadata + processed + masks) into a single HDF5 file.

File structure:

/data

float32 dataset, (n_frames, H, W)

/processed/<step> float32 datasets, per-step snapshots /masks/<mask> boolean datasets, per-mask /timestamps float64 dataset, (n_frames,) /frame_metadata_json variable-length UTF-8 string, JSON dump of list of dicts /provenance_json variable-length UTF-8 string, JSON dump of provenance dict

Attributes on root:

pixel_size_nm : float channel : UTF-8 string

Parameters:

• path (Path) – Base filepath for the .h5 (the “.h5” extension will be added).

• stack (AFMImageStack) – The stack to serialize.

• raw (bool, default=False) – If True, save only the raw snapshot (stack.processed[‘raw’]), and exclude .processed and .masks. Otherwise, save the entire AFMImageStack.

Return type:

None

playNano.io.export_data.save_npz_bundle(path: Path, stack: AFMImageStack, raw: bool = False) → None

Save an AFMImageStack (data + metadata + processed + masks) in a single .npz file.

Top-level arrays / metadata keys:

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

• pixel_size_nm : float32 scalar array

• timestamps : float64 array, (n_frames,)

• channel : object scalar array

• frame_metadata_json: object scalar array (JSON dump of list of dicts)

• provenance_json : object scalar array (JSON dump of provenance dict)

Then one array per processed-step under key processed__<step_name>, and one per mask under masks__<mask_name>.

Parameters:

• path (Path) – Base filepath for the .npz (the “.npz” extension will be added).

• stack (AFMImageStack) – The stack to serialize.

• raw (bool, default=False) – If True, save only the raw snapshot (stack.processed[‘raw’]), and exclude .processed and .masks. Otherwise, save the entire AFMImageStack.

Return type:

None

playNano.io.export_data.save_ome_tiff_stack(path: Path, afm_stack: AFMImageStack, raw: bool = False) → None

Save an AFMImageStack as an OME-TIFF.

Embedds both pixel data and key metadata (timestamps, provenance, processed-step names).

Parameters:

• path (Path) – Output path for the OME-TIFF file (will be overwritten).

• afm_stack (AFMImageStack) – The image stack to export (its .data or .processed[‘raw’]).

• raw (bool, default=False) – If True, use the raw snapshot (.processed[‘raw’]), otherwise use the current .data array (post-filtered).

Return type:

None

playNano.io.gif_export module

GIF export utilities for AFM image stacks.

This module provides functions for generating animated GIFs from AFM image stacks, with optional timestamps and scale bars. Frames can be normalized automatically or scaled using a fixed z-range.

Dependencies

• matplotlib

• numpy

• Pillow (PIL)

playNano.io.gif_export.create_gif_with_scale_and_timestamp(image_stack, pixel_size_nm, timestamps=None, scale_bar_length_nm=100, output_path='output', duration=0.5, cmap_name='afmhot', zmin: float | str | None = None, zmax: float | str | None = None, draw_ts: bool = True, draw_scale: bool = True)

Create an animated GIF from an AFM image stack with optional overlays.

Frames are normalized, colorized using a matplotlib colormap, and annotated with a scale bar and timestamps before being compiled into a GIF.

Parameters:

• image_stack (np.ndarray) – 3D array of shape (N, H, W) representing the AFM image stack.

• pixel_size_nm (float) – Size of each pixel in nanometers.

• timestamps (sequence of float, optional) – Timestamps for each frame in seconds. If None or invalid, frame indices are used.

• scale_bar_length_nm (int, default=100) – Length of the scale bar in nanometers.

• output_path (str, default="output") – Path where the GIF will be saved.

• duration (float, default=0.5) – Duration of each frame in seconds.

• cmap_name (str, default="afmhot") – Name of the matplotlib colormap to apply.

• zmin (float or {"auto"} or None, optional) – Minimum z-value mapped to colormap low end. "auto" uses the 1st percentile. None uses the minimum value of each frame.

• zmax (float or {"auto"} or None, optional) – Maximum z-value mapped to colormap high end. "auto" uses the 99th percentile. None uses the maximum value of each frame.

• draw_ts (bool, default=True) – Whether to draw timestamps.

• draw_scale (bool, default=True) – Whether to draw a scale bar.

Raises:

ValueError – If zmin equals zmax or timestamps have incorrect shape.

Return type:

None

Notes

• Timestamps and scale bars are drawn in white.

• Frames are normalized globally if zmin and zmax are provided;

otherwise, per-frame.

playNano.io.gif_export.export_gif(afm_stack, make_gif: bool, output_folder: str | None, output_name: str | None, scale_bar_nm: int | None, raw: bool = False, zmin: float | None = None, zmax: float | None = None, draw_ts: bool = True, draw_scale: bool = True) → None

Export an AFM image stack as an annotated GIF.

Parameters:

• afm_stack (AFMImageStack) – AFM stack object containing raw and/or processed data.

• make_gif (bool) – Whether to generate the GIF. If False, the function exits immediately.

• output_folder (str or None) – Directory to save the GIF. Defaults to "output" if None.

• output_name (str or None) – Base name for the GIF file. If None, derived from the stack file name.

• scale_bar_nm (int or None) – Length of the scale bar in nanometers. Defaults to 100 nm.

• raw (bool, default=False) – If True, export raw (unprocessed) data; otherwise export processed data if available.

• zmin (float or {"auto"} or None, optional) – Minimum z-value mapped to colormap low end. "auto" uses the 1st percentile. None uses the minimum value of the data.

• zmax (float or {"auto"} or None, optional) – Maximum z-value mapped to colormap high end. "auto" uses the 99th percentile. None uses the maximum value of the data.

• draw_ts (bool, default=True) – Whether to draw timestamps on each frame.

• draw_scale (bool, default=True) – Whether to draw a scale bar on each frame.

Return type:

None

Notes

• Uses processed data if available; otherwise falls back to raw data.

• Timestamps and pixel size are read from afm_stack metadata.

• Output file name includes "_filtered" if processed data is exported.

playNano.io.loader module

Common loader for various high speed AFM video formats and playNano export bundles.

Supported extensions:

• .jpk (folder)

• .spm (folder)

• .h5-jpk (single-file JPK)

• .asd (single-file ASD)

• .ome.tif / .tif (OME-TIFF bundles)

• .npz (playNano NPZ bundles)

• .h5 (playNano HDF5 bundles)

playNano.io.loader.get_loader_for_file(file_path: Path, file_loaders: dict, folder_loaders: dict) → callable

Determine the appropriate loader for a single multi-frame AFM file.

Parameters:

• file_path (Path) – Path to the file.

• file_loaders (dict) – Mapping from file extensions to file loader functions.

• folder_loaders (dict) – Mapping from extensions for folder loaders (for error handling).

Returns:

The file extention string and the loader function for the file.

Return type:

(str, callable)

Raises:

ValueError – If the file type is unsupported or better handled as a folder.

playNano.io.loader.get_loader_for_folder(folder_path: Path, folder_loaders: dict) → tuple[str, callable]

Determine the appropriate loader for a folder containing AFM data.

Parameters:

• folder_path (Path) – Path to the folder.

• folder_loaders (dict) – Mapping from file extension to loader function.

Returns:

The chosen extension and loader function.

Return type:

(str, callable)

Raises:

FileNotFoundError – If no known file types are found.

playNano.io.loader.load_afm_stack(file_path: Path, channel: str = 'height_trace') → AFMImageStack

Unified interface to load AFM stacks from various file formats.

High speed AFM videos can be saved as either individual frames within a folder or as multiple frames within a single file. This loader splits these two approaches and loads both into the common AFMImageStack object for processing.

As well as the file formats exported from AFM instruments, this function also read raw and processed exports from playNano (NPZ, OME_TIF and HDF5).

All data values with length units (i.e. m) are converted to nm.

Parameters:

• file_path (Path | str) – Path to the AFM data file or folder of files.

• channel (str) – Scan channel name.

Returns:

Loaded image stack with metadata.

Return type:

AFMImageStack

Module contents

Public package initialization.