playnano.io.video_export module

Video export utilities for AFM image stacks.

This module provides functions for generating MP4, AVI, MOV, or MKV video files from AFM image stacks, with optional timestamps and scale bars. Frames can be normalised automatically or scaled using a fixed z-range.

The rendered frame pipeline is identical to gif_export: frames are colourised with a matplotlib colormap and annotated via render_utils before being written to a container format using cv2.

Dependencies

  • matplotlib

  • numpy

  • OpenCV (cv2)

playnano.io.video_export.create_video_with_scale_and_timestamp(image_stack: ndarray, pixel_sizes_nm: list, timestamps=None, scale_bar_length_nm: int = 100, output_path: str | Path = 'output.mp4', fps: float = 5.0, 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) → None[source]

Create a video file from an AFM image stack with optional overlays.

Frames are normalised, colourised using a matplotlib colormap, and annotated with a scale bar and timestamps before being compiled into an MP4 or AVI file.

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_path (str or Path) – Destination path including filename and extension (".mp4" or ".avi"). Default is 'output.mp4'.

  • fps (float) – Playback frame rate in frames per second. Default is 5.0.

  • 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. The string literal "auto" sets this to the 1st percentile of the stack.

  • zmax (float or str or None, optional) – Maximum z-value mapped to the high end of the colormap. The string literal "auto" sets this to the 99th percentile of the 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.

Raises:

ValueError – If zmin equals zmax.

Return type:

None

Notes

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

  • RGB frames (uint8, shape H×W×3) are written via cv2.

  • Requires opencv-python-headless.

playnano.io.video_export.export_video(afm_stack, make_video: bool, output_folder: str | None, output_name: str | None, scale_bar_nm: int | None, fmt: str = 'mp4', fps: float = 5.0, 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 an annotated MP4 or AVI video.

Parameters:

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

  • make_video (bool) – Whether to generate the video. If False, the function returns immediately.

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

  • output_name (str or None) – Base name for the output file (without extension). 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 ({"mp4", "avi", "mov", "mkv"}) – Container format. Default is "mp4".

  • fps (float) – Playback frame rate. Default is 5.0.

  • raw (bool) – If True, export the unprocessed raw snapshot; otherwise export the current (processed) data. 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.

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

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.

  • Requires opencv-python-headless: pip install opencv-python-headless.