playnano.utils.time_utils module

Timestamp and annotation utilities for playNano.

This module provides functions for normalising per-frame timestamps, drawing scale bar and timestamp overlays onto AFM image frames, and generating UTC timestamps for provenance records.

Functions

normalize_timestamps

Parse and normalise per-frame timestamp metadata to float seconds.

draw_scale_and_timestamp

Draw a scale bar and timestamp overlay onto an AFM image frame.

utc_now_iso

Return the current UTC time as an ISO 8601 string.

playnano.utils.time_utils.draw_scale_and_timestamp(image: ndarray, timestamp: float, pixel_size_nm: float, resize_scale: float, annotation_scale: float, bar_length_nm: int = 100, font_scale: float = 1, draw_ts: bool = True, draw_scale: bool = True, color: tuple = (255, 255, 255)) → ndarray[source]

Draw a scale bar and/or timestamp overlay onto an AFM image frame.

Two separate scale factors are used to decouple physical accuracy from visual consistency. resize_scale ensures the scale bar length correctly represents the physical nanometre distance regardless of how the frame was resized. annotation_scale ensures margins, bar thickness, and text positions appear proportionally identical at any output resolution.

Parameters:

  • image (np.ndarray) – RGB image array of shape (H, W, 3), dtype uint8.

  • timestamp (float) – Timestamp in seconds to display in the top-left corner.

  • pixel_size_nm (float) – Physical size of one pixel in the original (pre-resize) frame, in nanometres. Used to compute the scale bar length in pixels.

  • resize_scale (float) – Factor by which the frame was upscaled from its original resolution (output_height / original_height). Used only for computing the physically accurate scale bar width.

  • annotation_scale (float) – Factor relative to REFERENCE_HEIGHT used to scale all annotation geometry — margins, bar thickness, label gaps, and text position (output_height / REFERENCE_HEIGHT). Ensures annotations occupy the same visual proportion at any output resolution.

  • bar_length_nm (int) – Desired scale bar length in nanometres. Default is 100.

  • font_scale (float) – Multiplier applied to the base font point size (15 pt). Default is 1.

  • draw_ts (bool) – Whether to draw the timestamp in the top-left corner. Default is True.

  • draw_scale (bool) – Whether to draw the scale bar and label in the bottom-left corner. Default is True.

  • color (tuple) – RGB colour for all annotations. Default is white (255, 255, 255).

Returns:

Annotated image as a uint8 array of shape (H, W, 3).

Return type:

np.ndarray

Notes

  • Requires the Steps-Mono font bundled in playnano.resources.fonts. Falls back to the PIL default font if the file cannot be loaded.

  • The scale bar is only drawn when pixel_size_nm > 0 and bar_length_nm > 0.

playnano.utils.time_utils.normalize_timestamps(metadata_list: list[dict[str, Any]]) → list[dict[str, Any]][source]

Normalize timestamp data to a float in seconds.

Given a list of per-frame metadata dicts, parse each ‘timestamp’ entry (if present) into a float (seconds). Returns a new list of dicts with ‘timestamp’ replaced by float or None.

  • ISO-format strings → parsed with dateutil.isoparse()

  • datetime objects → .timestamp()

  • numeric (int/float) → float()

  • missing/unparsable → None

Parameters:

metadata_list (list of dict) – List of metadata dictionaries, each possibly containing a ‘timestamp’.

Returns:

List of metadata dicts with ‘timestamp’ normalized to float seconds or None.

Return type:

list of dict

playnano.utils.time_utils.utc_now_iso() → str[source]

Return the current UTC time as an ISO 8601 string.

Returns:

UTC timestamp in ISO 8601 format, e.g. '2024-01-15T10:30:00Z'.

Return type:

str