playnano.io.image_sequence_export module

Image-sequence export utilities for AFM image stacks.

This module provides functions for saving each frame of an AFM image stack as an individual PNG or JPEG file inside a dedicated output folder. Frames can be normalised automatically or scaled with a fixed z-range, and are annotated with optional timestamps and scale bars using the shared rendering pipeline in render_utils

Dependencies

  • matplotlib

  • numpy

  • Pillow (PIL)

playnano.io.image_sequence_export.create_image_sequence(image_stack: ndarray, pixel_sizes_nm: list, timestamps=None, scale_bar_length_nm: int = 100, output_folder: str | Path = 'output_frames', base_name: str = 'frame', fmt: str = 'png', cmap_name: str = 'afm_brown', zmin: float | str | None = None, zmax: float | str | None = None, draw_ts: bool = True, draw_scale: bool = True, font_scale: float = 2.0) → Path[source]

Save every frame of an AFM image stack as an individual image file.

Frames are normalised, colourised with a matplotlib colormap, and annotated with a scale bar and timestamp before being written to output_folder as <base_name>_NNNN.<fmt>.

Parameters:

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

  • pixel_sizes_nm (list) – Per-frame pixel size in nanometres. Must have the same length as image_stack.

  • timestamps (list[float] or tuple[float], optional) – Timestamps in seconds for each frame. Frame indices are used as a fallback when None or invalid.

  • scale_bar_length_nm (int) – Length of the scale bar in nanometres. Default is 100.

  • output_folder (str or Path) – Directory in which the frame images will be saved. Created automatically if it does not exist.

  • base_name (str) – Stem used for each file: <base_name>_0000.png, etc. Default is "frame".

  • fmt ({"png", "jpg", "jpeg"}) – Image file format. Default is "png".

  • cmap_name (str) – Name of the matplotlib colormap. Default is 'afmhot'.

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

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

  • draw_ts (bool) – Whether to draw timestamps on each frame. Default is True.

  • draw_scale (bool) – Whether to draw a scale bar on each frame. Default is True.

  • font_scale (float) – Base font scale for annotations at the reference height.

Returns:

The resolved output folder where images were written.

Return type:

Path

Raises:

ValueError – If fmt is not a supported image format, or if zmin == zmax.

Notes

  • Frames are normalised globally when zmin/zmax are provided, otherwise per-frame normalisation is applied.

  • PNG files are lossless; JPEG files are saved at quality _JPEG_QUALITY (default 90).

  • Zero-padded four-digit frame indices are used so files sort correctly up to 9 999 frames; for larger stacks the padding grows automatically.

playnano.io.image_sequence_export.export_image_sequence(afm_stack, make_sequence: bool, output_folder: str | None, output_name: str | None, scale_bar_nm: int | None, fmt: str = 'png', raw: bool = False, zmin: float | None = None, zmax: float | None = None, draw_ts: bool = True, draw_scale: bool = True, cmap_name: str = 'afm_brown', font_scale: float = 2.0) → None[source]

Export an AFM image stack as a folder of annotated PNG or JPEG images.

Each frame is saved as a separate file named <stem>_NNNN.<fmt> inside a subfolder <output_folder>/<stem>/.

Parameters:

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

  • make_sequence (bool) – Whether to generate the image sequence. Returns immediately when False.

  • output_folder (str or None) – Root directory for output. Defaults to "output" when None. A subfolder named after the stack stem is created inside it.

  • output_name (str or None) – Base name for the subfolder and frame files. Derived from the stack file name when None.

  • scale_bar_nm (int or None) – Scale bar length in nanometres. Defaults to 100 nm when None.

  • fmt ({"png", "jpg", "jpeg"}) – Image file format. Default is "png".

  • raw (bool) – If True, export the unprocessed raw snapshot. Default is False.

  • zmin (float or None, optional) – Minimum z-value for colormap scaling. "auto" triggers the 1st percentile. None uses per-frame minimum.

  • zmax (float or None, optional) – Maximum z-value for colormap scaling. "auto" triggers the 99th percentile. None uses per-frame maximum.

  • draw_ts (bool) – Whether to draw timestamps on each frame. Default is True.

  • draw_scale (bool) – Whether to draw a scale bar on each frame. Default is True.

Return type:

None

Notes

  • Processed data is preferred over raw when available; _filtered is appended to the output stem in that case.

  • Timestamps and pixel size are read from afm_stack.frame_metadata. When exporting raw data after an edit_stack step, the pre-edit metadata stored in afm_stack.state_backups['frame_metadata_before_edit'] is used.