Microscope Interfaces

This module provides abstract base classes for handling microscope-specific functionality, including filename parsing and metadata handling.

For conceptual explanation, see Architecture Overview. For information about extending EZStitcher with support for new microscope types, see Adding a New Microscope Type in the Extending EZStitcher guide.

MicroscopeHandler

class ezstitcher.core.microscope_interfaces.MicroscopeHandler(plate_folder=None, parser=None, metadata_handler=None, microscope_type='auto')

Composed class for handling microscope-specific functionality.

Parameters:

  • plate_folder (str or Path, optional) – Path to the plate folder

  • parser (FilenameParser, optional) – Parser for microscopy filenames

  • metadata_handler (MetadataHandler, optional) – Handler for microscope metadata

  • microscope_type (str, optional) – Type of microscope (‘auto’, ‘ImageXpress’, ‘OperaPhenix’, etc.)

DEFAULT_MICROSCOPE: str = 'ImageXpress'

Default microscope type to use if auto-detection fails.

parse_filename(filename)

Delegate to parser.

Parameters:

filename (str) – Filename to parse

Returns:

Dictionary with extracted components or None if parsing fails

Return type:

dict or None

construct_filename(well, site=None, channel=None, z_index=None, extension='.tif', site_padding=3, z_padding=3)

Delegate to parser.

Parameters:

  • well (str) – Well ID (e.g., ‘A01’)

  • site (int or str, optional) – Site number or placeholder string (e.g., ‘{iii}’)

  • channel (int, optional) – Channel/wavelength number

  • z_index (int or str, optional) – Z-index or placeholder string (e.g., ‘{zzz}’)

  • extension (str, optional) – File extension

  • site_padding (int, optional) – Width to pad site numbers to

  • z_padding (int, optional) – Width to pad Z-index numbers to

Returns:

Constructed filename

Return type:

str

auto_detect_patterns(folder_path, well_filter=None, extensions=None, group_by='channel', variable_components=None)

Delegate to parser.

Parameters:

  • folder_path (str or Path) – Path to the folder

  • well_filter (list, optional) – Optional list of wells to include

  • extensions (list, optional) – Optional list of file extensions to include

  • group_by (str, optional) – How to group patterns (‘channel’ or ‘z_index’)

  • variable_components (list, optional) – List of components to make variable (e.g., [‘site’, ‘z_index’])

Returns:

Dictionary mapping wells to patterns grouped by channel or z-index

Return type:

dict

path_list_from_pattern(directory, pattern)

Delegate to parser.

Parameters:

  • directory (str or Path) – Directory to search

  • pattern (str) – Pattern to match with {iii} placeholder for site index

Returns:

List of matching filenames

Return type:

list

find_metadata_file(plate_path)

Delegate to metadata handler.

Parameters:

plate_path (str or Path) – Path to the plate folder

Returns:

Path to the metadata file, or None if not found

Return type:

Path or None

get_grid_dimensions(plate_path)

Delegate to metadata handler.

Parameters:

plate_path (str or Path) – Path to the plate folder

Returns:

Tuple of (grid_size_x, grid_size_y)

Return type:

tuple

get_pixel_size(plate_path)

Delegate to metadata handler.

Parameters:

plate_path (str or Path) – Path to the plate folder

Returns:

Pixel size in micrometers, or None if not available

Return type:

float or None

FilenameParser

class ezstitcher.core.microscope_interfaces.FilenameParser

Abstract base class for parsing microscopy image filenames.

FILENAME_COMPONENTS: list = ['well', 'site', 'channel', 'z_index', 'extension']

List of components that can be extracted from filenames.

PLACEHOLDER_PATTERN: str = '{iii}'

Placeholder pattern for variable components.

classmethod can_parse(cls, filename)

Check if this parser can parse the given filename.

Parameters:

filename (str) – Filename to check

Returns:

True if this parser can parse the filename, False otherwise

Return type:

bool

parse_filename(filename)

Parse a microscopy image filename to extract all components.

Parameters:

filename (str) – Filename to parse

Returns:

Dictionary with extracted components or None if parsing fails

Return type:

dict or None

construct_filename(well, site=None, channel=None, z_index=None, extension='.tif', site_padding=3, z_padding=3)

Construct a filename from components.

Parameters:

  • well (str) – Well ID (e.g., ‘A01’)

  • site (int or str, optional) – Site number or placeholder string (e.g., ‘{iii}’)

  • channel (int, optional) – Channel/wavelength number

  • z_index (int or str, optional) – Z-index or placeholder string (e.g., ‘{zzz}’)

  • extension (str, optional) – File extension

  • site_padding (int, optional) – Width to pad site numbers to

  • z_padding (int, optional) – Width to pad Z-index numbers to

Returns:

Constructed filename

Return type:

str

path_list_from_pattern(directory, pattern)

Get a list of filenames matching a pattern in a directory.

Parameters:

  • directory (str or Path) – Directory to search

  • pattern (str) – Pattern to match with {iii} placeholder for site index

Returns:

List of matching filenames

Return type:

list

group_patterns_by_component(patterns, component='channel', default_value='1')

Group patterns by a specific component (channel, z_index, site, well, etc.)

Parameters:

  • patterns (list) – List of patterns to group

  • component (str, optional) – Component to group by (e.g., ‘channel’, ‘z_index’, ‘site’, ‘well’)

  • default_value (str, optional) – Default value to use if component is not found

Returns:

Dictionary mapping component values to patterns

Return type:

dict

auto_detect_patterns(folder_path, well_filter=None, extensions=None, group_by='channel', variable_components=None)

Automatically detect image patterns in a folder.

Parameters:

  • folder_path (str or Path) – Path to the folder

  • well_filter (list, optional) – Optional list of wells to include

  • extensions (list, optional) – Optional list of file extensions to include

  • group_by (str, optional) – How to group patterns (‘channel’ or ‘z_index’)

  • variable_components (list, optional) – List of components to make variable (e.g., [‘site’, ‘z_index’])

Returns:

Dictionary mapping wells to patterns grouped by channel or z-index

Return type:

dict

MetadataHandler

class ezstitcher.core.microscope_interfaces.MetadataHandler

Abstract base class for handling microscope metadata.

find_metadata_file(plate_path)

Find the metadata file for a plate.

Parameters:

plate_path (str or Path) – Path to the plate folder

Returns:

Path to the metadata file, or None if not found

Return type:

Path or None

get_grid_dimensions(plate_path)

Get grid dimensions for stitching from metadata.

Parameters:

plate_path (str or Path) – Path to the plate folder

Returns:

Tuple of (grid_size_x, grid_size_y)

Return type:

tuple

get_pixel_size(plate_path)

Get the pixel size from metadata.

Parameters:

plate_path (str or Path) – Path to the plate folder

Returns:

Pixel size in micrometers, or None if not available

Return type:

float or None

Functions

ezstitcher.core.microscope_interfaces.create_microscope_handler(microscope_type='auto', **kwargs)

Create the appropriate microscope handler.

Parameters:

  • microscope_type (str, optional) – Type of microscope (‘auto’, ‘ImageXpress’, ‘OperaPhenix’, etc.)

  • kwargs (dict) – Additional keyword arguments to pass to MicroscopeHandler

Returns:

Microscope handler

Return type:

MicroscopeHandler