File System Manager

This module provides a class for managing file system operations.

FileSystemManager

class ezstitcher.core.file_system_manager.FileSystemManager

Manages file system operations for ezstitcher. Abstracts away direct file system interactions for improved testability.

default_extensions: list = ['.tif', '.TIF', '.tiff', '.TIFF', '.jpg', '.JPG', '.jpeg', '.JPEG', '.png', '.PNG']

Default file extensions for image files.

static ensure_directory(directory)

Ensure a directory exists, creating it if necessary.

Parameters:

directory (str or Path) – Directory path to ensure exists

Returns:

Path object for the directory

Return type:

Path

static list_image_files(directory, extensions=None, recursive=False, flatten=False)

List all image files in a directory with specified extensions.

Parameters:

  • directory (str or Path) – Directory to search

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

  • recursive (bool) – Whether to search recursively

  • flatten (bool) – Whether to flatten Z-stack directories (implies recursive)

Returns:

List of Path objects for image files

Return type:

list

static load_image(file_path)

Load an image. Only 2D images are supported.

Parameters:

file_path (str or Path) – Path to the image file

Returns:

2D image or None if loading fails

Return type:

numpy.ndarray or None

Raises:

ValueError: If the image is 3D (not supported)

static save_image(file_path, image, compression=None)

Save an image to disk.

Parameters:

  • file_path (str or Path) – Path to save the image

  • image (numpy.ndarray) – Image to save

  • compression (str, optional) – Compression method

Returns:

True if successful, False otherwise

Return type:

bool

static copy_file(source_path, dest_path)

Copy a file from source to destination, preserving metadata.

Parameters:

  • source_path (str or Path) – Source file path

  • dest_path (str or Path) – Destination file path

Returns:

True if successful, False otherwise

Return type:

bool

static remove_directory(directory_path, recursive=True)

Remove a directory and optionally all its contents.

Parameters:

  • directory_path (str or Path) – Path to the directory to remove

  • recursive (bool) – Whether to remove the directory recursively

Returns:

True if successful, False otherwise

Return type:

bool

static clean_temp_folders(parent_dir, base_name, keep_suffixes=None)

Clean up temporary folders created during processing.

Parameters:

  • parent_dir (str or Path) – Parent directory

  • base_name (str) – Base name of the plate folder

  • keep_suffixes (list, optional) – List of suffixes to keep

static create_output_directories(plate_path, suffixes)

Create output directories for a plate.

Parameters:

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

  • suffixes (dict) – Dictionary mapping directory types to suffixes

Returns:

Dictionary mapping directory types to Path objects

Return type:

dict

static find_file_recursive(directory, filename)

Recursively search for a file by name in a directory and its subdirectories. Returns the first instance found.

Parameters:

  • directory (str or Path) – Directory to search in

  • filename (str) – Name of the file to find

Returns:

Path to the first instance of the file, or None if not found

Return type:

Path or None

static rename_files_with_consistent_padding(directory, parser=None, width=3, force_suffixes=False)

Rename files in a directory to have consistent site number and Z-index padding. Optionally force the addition of missing optional suffixes (site, channel, z-index).

Parameters:

  • directory (str or Path) – Directory containing files to rename

  • parser (FilenameParser, optional) – Parser to use for filename parsing and padding

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

  • force_suffixes (bool, optional) – If True, add missing optional suffixes with default values

Returns:

Dictionary mapping original filenames to new filenames

Return type:

dict

static find_z_stack_dirs(root_dir, pattern='ZStep_\\d+', recursive=True)

Find directories matching a pattern (default: ZStep_#) recursively.

Parameters:

  • root_dir (str or Path) – Root directory to start the search

  • pattern (str) – Regex pattern to match directory names (default: pattern for Z-step folders)

  • recursive (bool) – Whether to search recursively in subdirectories

Returns:

List of (z_index, directory) tuples where z_index is extracted from the pattern

Return type:

list

static find_image_directory(plate_folder, extensions=None)

Find the directory where images are actually located.

Handles both cases: 1. Images directly in a folder (returns that folder) 2. Images split across Z-step folders (returns parent of Z-step folders)

Parameters:

  • plate_folder (str or Path) – Base directory to search

  • extensions (list, optional) – List of file extensions to include. If None, uses default_extensions.

Returns:

Path to the directory containing images

Return type:

Path

static detect_zstack_folders(plate_folder, pattern=None)

Detect Z-stack folders in a plate folder.

Parameters:

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

  • pattern (str or Pattern, optional) – Regex pattern to match Z-stack folders

Returns:

Tuple of (has_zstack, z_folders) where z_folders is a list of (z_index, folder_path) tuples

Return type:

tuple

static organize_zstack_folders(plate_folder, filename_parser=None)

Organize Z-stack folders by moving files to the plate folder with proper naming.

Parameters:

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

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

Returns:

True if Z-stack was organized, False otherwise

Return type:

bool

static cleanup_processed_files(processed_files, output_files)

Clean up processed files after they’ve been used to create output files.

Parameters:

  • processed_files (set or list) – Set or list of file paths to clean up

  • output_files (list) – List of output file paths to preserve

Returns:

Number of files successfully removed

Return type:

int