autoemx.core.em_runtime.frame_navigator module

Frame and grid navigation module for automated electron microscopy.

This module provides functionality for calculating scan frames, grid layouts, and navigating between acquisition points in a sample.

Classes

FrameNavigator

Handles frame center calculation and frame-by-frame navigation.

Created on 2026 @author: Andrea

class autoemx.core.em_runtime.frame_navigator.FrameNavigator(EM_controller, sample_cfg, sample_substrate_cfg, measurement_cfg, powder_meas_cfg, bulk_meas_cfg, center_pos, sample_hw_mm, im_width, im_height, EM_driver_obj, results_dir=None, verbose=True, development_mode=False, xsp_spot_selector: Callable[[XSpSpotSelectionContext], Sequence[Tuple[int, int]]] | None = None)[source]

Bases: object

Handles frame planning and navigation for electron microscopy samples.

Calculates frame centers for systematic scanning across samples, supports multiple sample types (powder, bulk, manual), and manages frame-by-frame navigation during acquisition.

Parameters:

  • EM_controller (EM_Controller) – Reference to the parent EM_Controller for hardware access.

  • sample_cfg (SampleConfig) – Sample configuration.

  • sample_substrate_cfg (SampleSubstrateConfig) – Sample substrate configuration.

  • measurement_cfg (MeasurementConfig) – Measurement configuration.

  • powder_meas_cfg (PowderMeasurementConfig) – Powder measurement configuration.

  • bulk_meas_cfg (BulkMeasurementConfig) – Bulk measurement configuration.

  • center_pos (tuple) – Sample center position (x, y).

  • sample_hw_mm (float) – Sample half-width in mm.

  • im_width (int) – Image width in pixels.

  • im_height (int) – Image height in pixels.

  • EM_driver_obj (module) – EM driver for hardware access.

  • results_dir (str or None) – Directory for saving results.

  • verbose (bool) – If True, print progress information.

  • development_mode (bool) – If True, enables offline testing mode.

initialise_sample_navigator(grid_search_fw_mm, exclude_sample_margin=True)[source]

Initialize the sample navigator for automated spectra collection.

Supports ‘powder’ and ‘bulk’ samples with automated navigation, as well as manual navigation mode.

Parameters:

  • grid_search_fw_mm (float) – Frame width in mm for grid search.

  • exclude_sample_margin (bool) – Whether to exclude sample margin when calculating frames.

Raises:

NotImplementedError – If the sample type is not supported.

reset_frame_cursor() → None[source]

Reset the frame index so the next go_to_next_frame starts at frame 0.

skip_frames(frame_labels: Iterable[str]) → None[source]

Remove frames from the planned frames, by label (e.g. frames already analysed by an interrupted particle size statistics measurement), and restart from the first remaining frame.

skip_frames_overlapping(areas_mm: Iterable[Tuple[Tuple[float, float], Tuple[float, float]]]) → int[source]

Remove the planned frames overlapping areas of the sample already searched (centre and half width and height of each, in mm), e.g. frames searched by EDS, and restart from the first remaining frame. Returns the number of frames removed.

get_visited_band_frames() → List[Tuple[str, Tuple[float, float], float]][source]

Return frames visited during the current size band (in visit order).

configure_top_level_particle_frames(frame_width_mm: float, randomize_frames: bool = True, exclude_sample_margin: bool = True) → None[source]

Rebuild the sample-wide particle-search grid for the coarsest size band.

configure_particle_subframes(parent_frames: Sequence[Tuple[str, Tuple[float, float], float]], child_fw_mm: float, randomize_frames: bool = True) → None[source]

Build hierarchical child frames inside each parent FOV.

Child labels use a compact lowercase AlphabetMapper scheme (a0, b1, …) and are joined to the parent id as {parent}_{local}.

update_current_pos_from_stage() → None[source]

Set the current frame position to the stage position, after the user moved the stage manually.

Uses the optional driver function get_position(). If the driver does not provide it, or the position cannot be read, the last known position is kept (initially the sample center), and current_pos_is_measured is False: frames are then recorded without position.

go_to_next_frame(microscope_ctrl) → bool[source]

Move the microscope to the next frame position.

Checks for remaining frames, moves to next position, and adjusts frame width and EM settings as needed.

Parameters:

microscope_ctrl (MicroscopeController) – Reference to microscope controller.

Returns:

True if moved to next frame, False if no frames remain.

Return type:

bool