playnano.io.render_utils module

Shared frame-rendering utilities for all rendered AFM exports.

This module provides the single source of truth for how frames are normalised, colourised, resized, and annotated across GIF, video, and image-sequence exports. Changing appearance here affects all three export formats consistently.

Constants

MIN_FRAME_HEIGHTint

Frames shorter than this are upscaled; taller frames are unchanged.

REFERENCE_HEIGHTint

The height at which font_scale=1.0 produces the default annotation size. Derived font scale is proportional to the actual frame height.

ANNOTATION_COLORtuple

Default RGB colour for all annotations.

DEFAULT_FONT_SCALEfloat

Base font scale passed to draw_scale_and_timestamp at REFERENCE_HEIGHT.

playnano.io.render_utils.render_frame(frame: ndarray, cmap, timestamp: float, pixel_size_nm: float, scale_bar_length_nm: int, font_scale: float, draw_ts: bool, draw_scale: bool, zmin_val: float | None = None, zmax_val: float | None = None) → ndarray[source]

Normalise, colourise, resize, and annotate a single AFM frame.

This is the shared rendering pipeline used by all rendered exports (GIF, video, image sequence). All appearance decisions are made here.

Parameters:

  • frame (np.ndarray) – 2D float array (H, W) representing a single AFM frame.

  • cmap (matplotlib.colors.Colormap) – Colormap to apply.

  • timestamp (float) – Timestamp in seconds for the annotation overlay.

  • pixel_size_nm (float) – Pixel size in nanometres, used to compute the scale bar length.

  • scale_bar_length_nm (int) – Desired scale bar length in nanometres.

  • font_scale (float) – Base font scale. The actual font size is derived proportionally from the frame height relative to REFERENCE_HEIGHT, so annotations appear the same visual size regardless of resolution.

  • draw_ts (bool) – Whether to draw the timestamp overlay.

  • draw_scale (bool) – Whether to draw the scale bar overlay.

  • zmin_val (float or None) – Pre-computed global minimum for normalisation. If None, per-frame normalisation is used.

  • zmax_val (float or None) – Pre-computed global maximum for normalisation. If None, per-frame normalisation is used.

Returns:

Annotated RGB frame as a uint8 array of shape (H, W, 3). Height is at least MIN_FRAME_HEIGHT.

Return type:

np.ndarray

playnano.io.render_utils.resolve_stack_data(afm_stack, raw: bool) → tuple[source]

Select the correct data source and metadata for a rendered export.

Centralises the raw-vs-processed selection logic shared by all export_* functions.

Parameters:

  • afm_stack (AFMImageStack) – The stack to export.

  • raw (bool) – If True, use the unprocessed raw snapshot when available.

Returns:

  • stack_data (np.ndarray) – The frame data array to render.

  • meta_src (list[dict]) – Per-frame metadata (timestamps, pixel sizes).

  • is_filtered (bool) – True when processed (filtered) data is being exported. Callers should append "_filtered" to the output name.