playnano.utils.io_utils module

Utility functions for IO operations in playNano.

playnano.utils.io_utils.compute_zscale_range(data: ndarray, zmin: float | str = 'auto', zmax: float | str = 'auto', lower_percentile: int = 1, upper_percentile: int = 99) → tuple[float, float][source]

Compute robust Z-scale bounds (height or intensity range) for normalization.

Parameters:

  • data (np.ndarray) – 2D or 3D array of AFM image data.

  • zmin (float, "auto", or None) – Lower bound: “auto” uses percentile, None uses data min, float uses value.

  • zmax (float or "auto") – Upper bound: “auto” uses percentile, None uses data max, float uses value.

  • lower_percentile (int, optional) – Percentile to use for lower bound when zmin == “auto”. Default is 1.

  • upper_percentile (int, optional) – Percentile to use for upper bound when zmax == “auto”. Default is 99.

Returns:

zmin and zmax values suitable for normalization.

Return type:

(float, float)

Raises:

ValueError – If zmin > zmax after processing or invalid input types.

playnano.utils.io_utils.convert_height_units_to_nm(data: ndarray, unit: str) → ndarray[source]

Convert AFM height data from the guessed unit to nanometers.

Parameters:

  • data (np.ndarray) – Input height data array, typically 2D or 3D.

  • unit (str) – Unit string as returned by guess_height_data_units. Must be one of: ‘pm’, ‘nm’, ‘um’, ‘mm’, or ‘m’.

Returns:

The input data converted to nanometers.

Return type:

np.ndarray

Raises:

ValueError – If the provided unit string is not recognized.

playnano.utils.io_utils.decode_hdf5_attr(attr: bytes | str) → str[source]

Decode an attribute that may be bytes or a string.

Parameters:

attr (bytes or str) – The attribute to decode.

Returns:

The decoded string.

Return type:

str

playnano.utils.io_utils.guess_height_data_units(stack: ndarray) → str[source]

Guess the most likely units of AFM height data from the data range.

Parameters:

stack (np.ndarray) – AFM height data array, typically 2D or 3D. Non-finite values (NaN or infinity) are ignored when determining the range.

Returns:

A string indicating the guessed unit of the height data, one of: ‘pm’ (picometers), ‘nm’ (nanometers), ‘um’ (micrometers), ‘mm’ (millimeters), or ‘m’ (meters).

Return type:

str

Raises:

ValueError – If the input array contains no finite values.

Notes

The unit is estimated based on the numeric range of the data as follows:

  • Range > 1e4 : ‘pm’

  • 1e-2 < Range <= 1e4 : ‘nm’

  • 1e-4 < Range <= 1e-2 : ‘um’

  • 1e-5 < Range <= 1e-4 : ‘mm’

  • Range <= 1e-5 : ‘m’

Examples

>>> import numpy as np
>>> data = np.array([[0, 5e-9], [1e-8, 2e-8]])
>>> guess_height_data_units(data)
'nm'
playnano.utils.io_utils.make_json_safe(obj)[source]

Recursively convert NumPy types and non-JSON objects into serializable ones.

playnano.utils.io_utils.normalize_to_uint8(image: ndarray) → ndarray[source]

Normalize a float image to the uint8 [0, 255] range, handling NaNs and Infs.

Parameters:

image (np.ndarray) – Input image as a NumPy array of floats. May contain NaNs or infinite values.

Returns:

Normalized image as a uint8 NumPy array with values in the range [0, 255].

Return type:

np.ndarray

playnano.utils.io_utils.pad_to_square(img: ndarray, border_color: int = 0) → ndarray[source]

Pad a 2D grayscale image to a square canvas by centring it.

playnano.utils.io_utils.prepare_output_directory(folder: str | None, default: str = 'output') → Path[source]

Validate, resolve, and create the output directory if it doesn’t exist.

Parameters:

  • folder (str or None) – User-provided output folder path. If None, use default.

  • default (str, optional) – Default folder name to use if folder not specified.

Returns:

A Path object pointing to the created output directory.

Return type:

Path

Raises:

ValueError – If any part of the folder path contains invalid characters.

playnano.utils.io_utils.sanitize_output_name(name: str, default: str) → str[source]

Sanitize output file names by removing extensions and stripping whitespace.

Parameters:

  • name (str) – The output file name provided by the user.

  • default (str) – Default name to use if name is empty or None.

Returns:

Sanitized base file name without extension.

Return type:

str