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_sizes_nm, timestamps=None, scale_bar_length_nm=100, output_path='output', fps: float = 5.0, cmap_name='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)[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_sizes_nm (list) – List containing the size of a pixel in nanometers for each frame.

  • 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’.

  • fps (float) – Playback frame rate in frames per second. Default is 5.0. GIF format has limited temporal resolution; the actual frame delay is rounded to the nearest millisecond.

  • 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.

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

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

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

  • font_scale (float) – Base font scale for annotations.

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, cmap_name: str = 'afm_brown', raw: bool = False, fps: float = 5.0, zmin: float | None = None, zmax: float | None = None, draw_ts: bool = True, draw_scale: bool = True, font_scale: float = 2.0) → 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.

  • fps (float) – Frame rate for the GIF in frames per second. Default is 5.0.

  • 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.

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

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 retrieved and used.

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