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)[source]

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 (list[float] or tuple[float], optional) – Timestamps for each frame in seconds. If None or invalid, frame indices are used.

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

  • output_path (str) – Path where the GIF will be saved. Default is ‘output’.

  • duration (float) – Duration of each frame in seconds. Default is 0.5.

  • cmap_name (str) – Name of the matplotlib colormap to apply. Default is ‘afmhot’.

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

zmaxfloat or str or None, optional

Maximum z-value mapped to colormap high end. The string literal "auto" uses the 99th percentile.

draw_tsbool

Whether to draw timestamps. Default is True.

draw_scalebool

Whether to draw a scale bar. Default is True.

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[source]

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) – If True, export raw (unprocessed) data; otherwise export processed data if available. Default is False.

  • zmin (float or None, optional) – Minimum z-value mapped to colormap low end. The string literal "auto" can also be used to automatically set the 1st percentile. None uses the minimum value of the data.

  • zmax (float or None, optional) – Maximum z-value mapped to colormap high end. The string literal "auto" can also be used to automatically set the 99th percentile. None uses the maximum value of the data.

  • 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

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

  • Timestamps and pixel size are read from afm_stack metadata although if raw data is exported after an edit_stack processing step then the timestamps in afm_stack.state_backups['frame_metadata_before_edit'] are retrived and used.

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