autoemx.core.em_runtime.image_utilities module

Image utilities and coordinate conversion module for electron microscopy.

This module provides image processing, saving, and coordinate transformation utilities for scanning electron microscopy applications.

Functions

convert_pixel_pos_to_mm

Convert pixel coordinates to absolute stage coordinates.

convert_XS_coords_to_pixels

Convert XS coordinates to pixel coordinates.

draw_annotations

Draw circles and labels (e.g. X-ray spectrum spots) on an RGB image.

save_frame_image

Save an EM frame, with optional annotations and scale bar.

normalise_img

Normalize brightness of an RGB image.

Created on 2026 @author: Andrea

autoemx.core.em_runtime.image_utilities.convert_pixel_pos_to_mm(pos_pixels, im_width, im_height, pixel_size_um, current_pos, image_to_stage_coords_transform)

Convert a position from pixel coordinates to absolute stage coordinates in mm.

Parameters:

• pos_pixels (array-like of float) – Position in pixel coordinates (x, y).

• im_width (int) – Image width in pixels.

• im_height (int) – Image height in pixels.

• pixel_size_um (float) – Pixel size in micrometers.

• current_pos (tuple) – Current position in mm (x, y).

• image_to_stage_coords_transform (array) – Transformation matrix for coordinate system conversion.

Returns:

pos_abs_mm – Absolute position in millimeters (x, y).

Return type:

ndarray of float

autoemx.core.em_runtime.image_utilities.convert_XS_coords_to_pixels(xy_coords, im_width, im_height, EM_driver)

Convert XY coordinates from the XS coordinate system to pixel coordinates.

Parameters:

• xy_coords (tuple(float, float)) – The XY coordinates in the XS coordinate system.

• im_width (int) – Image width in pixels.

• im_height (int) – Image height in pixels.

• EM_driver (module) – EM driver module.

Returns:

The corresponding (x, y) pixel coordinates as integers.

Return type:

tuple(int, int)

autoemx.core.em_runtime.image_utilities.draw_annotations(color_image, im_annotations)

Draw circles and text labels on an RGB image, in place.

Parameters:

• color_image (np.ndarray) – RGB image to annotate.

• im_annotations (dict | list(dict)) –

  Dictionary or list of dictionaries with annotations:

  • ’circle’: (radius, xy_center, border_thickness), with border_thickness -1 for a filled dot

  • ’text’: (text, xy_coords)

Returns:

The annotated image.

Return type:

np.ndarray

autoemx.core.em_runtime.image_utilities.RAW_IMAGE_SUFFIX = '_raw'

Suffix of the raw copy of an annotated image saved in a format without pages (e.g. <name>_raw.png).

autoemx.core.em_runtime.image_utilities.load_raw_saved_image(path)

RGB array of the un-annotated version of an image saved by save_frame_image(): its _raw copy if present, the second (raw) page of a two-page TIFF, or the image itself.

autoemx.core.em_runtime.image_utilities.particle_mark_annotations(particle_marks, im_width, text_margin=30, text_pos_scale=0.9)

Annotations of the particles marked in a frame: a circle around each and, if it has one, its particle id at the top-right of the circle (at its centre near the top or right edge of the image).

Parameters:

• particle_marks (sequence of (x, y, radius, particle_id or None)) – Particles, in pixels (see ParticleStatsFrame.particle_marks_px).

• im_width (int) – Image width, in pixels.

Returns:

Annotations for draw_annotations().

Return type:

list of dict

autoemx.core.em_runtime.image_utilities.xsp_spot_annotation(spectrum_id, xy_center)

Annotation of an X-ray spectrum spot: red dot with the spectrum ID at its top-left.

autoemx.core.em_runtime.image_utilities.save_frame_image(frame_image, pixel_size_um, im_width, im_height, sample_id, microscope_cfg, filename, results_dir, im_annotations=None, scalebar=True, image_extension: str = 'tif', save_raw_image: bool = False, EM_driver=None, auto_adjust_bc=True)

Save an electron microscopy (EM) frame, with optional markers and scale bar.

If the image is annotated and save_raw_image is True, the raw image is saved as well: as second page of the TIFF file, or as <filename>_raw.<ext> for other formats. The image metadata (sample, microscope, resolution, pixel size) is stored in the TIFF/PNG image description, e.g. to draw scale bars on raw images afterwards.

Parameters:

• frame_image (np.ndarray) – Frame image to save. If None, acquires current frame.

• pixel_size_um (float) – Pixel size in micrometers.

• im_width (int) – Image width in pixels.

• im_height (int) – Image height in pixels.

• sample_id (str) – Canonical sample identifier used for metadata.

• microscope_cfg (MicroscopeConfig) – Microscope configuration.

• filename (str) – Name used for saved .tif image file (without extension).

• results_dir (str) – Directory in which to save the TIFF file.

• im_annotations (dict | list(dict) | None, optional) –

  Dictionary or list of dictionaries with annotations:

  • ’circle’: (radius, xy_center, border_thickness)

  • ’text’: (text, xy_coords)

• scalebar (bool, optional) – Whether to annotate the image with a scalebar (default: True).

• EM_driver (module, optional) – EM driver for image acquisition if frame_image is None.

• auto_adjust_bc (bool, optional) – Whether to auto-adjust brightness/contrast before saving (default: True).

Notes

• Images are saved as RGB to maximize compatibility.

autoemx.core.em_runtime.image_utilities.normalise_img(img: ndarray, target_brightness: float = 128.0) → ndarray

Normalize brightness of an RGB image to a target brightness level.

Parameters:

• img (np.ndarray) – Input RGB image (uint8).

• target_brightness (float, optional) – Desired average brightness (0–255), default 128.0.

Returns:

Brightness-normalized RGB image (uint8).

Return type:

np.ndarray

Raises:

• TypeError – If input is not a numpy array.

• ValueError – If image does not have 3 channels after conversion.