Pipeline Factory

Overview

Pipeline factories are used internally by the EZ module to create pipelines with sensible defaults. They are not typically used directly by end users, who should prefer the EZ module or custom pipelines.

The AutoPipelineFactory is a unified factory class that creates pre-configured pipelines for all common stitching workflows. It simplifies pipeline creation by automatically configuring the appropriate steps based on input parameters, with no need to differentiate between different types of pipelines.

Note

The EZ module provides a simplified interface that wraps the AutoPipelineFactory. For details, see Basic Usage.

from ezstitcher.core import AutoPipelineFactory
from ezstitcher.core.pipeline_orchestrator import PipelineOrchestrator

# Create a factory with custom configuration
factory = AutoPipelineFactory(
    input_dir=orchestrator.workspace_path,
    normalize=True,
    flatten_z=True,  # Flatten Z-stacks in the assembly pipeline
    z_method="max",  # Use maximum intensity projection
    channel_weights=[0.7, 0.3, 0]  # Use only first two channels for reference image
)

# Create the pipelines
pipelines = factory.create_pipelines()

# Run the pipelines
orchestrator.run(pipelines=pipelines)

The AutoPipelineFactory handles all types of stitching workflows with a single implementation:

2D single-channel stitching
2D multi-channel stitching
Z-stack per plane stitching
Z-stack projection stitching

This unified approach simplifies the API and makes it easier to create pipelines for common use cases.

Pipeline Structure

The AutoPipelineFactory creates two pipelines with a consistent structure:

Position Generation Pipeline

Creates position files for stitching
- Steps: * Flatten Z (if flatten_z=True) * Normalize (if normalize=True) * Create composite (always) * Generate positions (always)
- Purpose: Process images and generate position files for stitching
Image Assembly Pipeline

Stitches images using the position files
- Steps: * Normalize (if normalize=True) * Flatten Z (if flatten_z=True) * Stitch images (always)
- Purpose: Process and stitch images using the position files

This structure is consistent regardless of data type (single/multi-channel, single/multi-Z), with parameters controlling step behavior rather than pipeline structure.

Parameters

For detailed API documentation, see Pipeline Factory.

The AutoPipelineFactory accepts the following parameters:

input_dir: Input directory containing images
output_dir: Output directory for stitched images (optional)
normalize: Whether to include normalization (default: True)
normalization_params: Parameters for normalization (optional)
well_filter: Wells to process (optional)
flatten_z: Whether to flatten Z-stacks in the assembly pipeline (default: False)
z_method: Z-stack processing method (default: “max”) - Projection methods: “max”, “mean”, “median”, etc. - Focus detection methods: “combined”, “laplacian”, “tenengrad”, “normalized_variance”, “fft”
channel_weights: Weights for channel compositing in the reference image (optional)

Important behaviors to note:

Z-stacks are always flattened for position generation regardless of the flatten_z setting
Channel compositing is always performed for position generation
If channel_weights is None, weights are distributed evenly across all channels

Step Types

The AutoPipelineFactory uses various step types from the steps module:

ZFlatStep: For Z-stack flattening using projection methods (used in both pipelines when appropriate)
FocusStep: For Z-stack processing using focus detection methods (used when z_method is a focus method)
CompositeStep: For channel compositing (always used in position generation)
PositionGenerationStep: For generating position files
ImageStitchingStep: For stitching images

These steps simplify the pipeline creation process by encapsulating common operations with appropriate defaults.

Examples

Basic Single-Channel Pipeline

factory = AutoPipelineFactory(
    input_dir=orchestrator.workspace_path,
    normalize=True
)
pipelines = factory.create_pipelines()

Multi-Channel Pipeline with Custom Weights

factory = AutoPipelineFactory(
    input_dir=orchestrator.workspace_path,
    channel_weights=[0.7, 0.3, 0]  # Use only first two channels for reference image
)
pipelines = factory.create_pipelines()

Z-Stack Pipeline with Projection

factory = AutoPipelineFactory(
    input_dir=orchestrator.workspace_path,
    flatten_z=True,  # Flatten Z-stacks in the assembly pipeline
    z_method="max"   # Use maximum intensity projection
)
pipelines = factory.create_pipelines()

Z-Stack Pipeline with Focus Detection

factory = AutoPipelineFactory(
    input_dir=orchestrator.workspace_path,
    flatten_z=True,  # Flatten Z-stacks in the assembly pipeline
    z_method="combined"   # Use combined focus metric
)
pipelines = factory.create_pipelines()

Pipeline with Custom Normalization

factory = AutoPipelineFactory(
    input_dir=orchestrator.workspace_path,
    normalize=True,
    normalization_params={'low_percentile': 0.5, 'high_percentile': 99.5}
)
pipelines = factory.create_pipelines()

Factory Pipelines vs. Custom Pipelines

EZStitcher offers two main approaches for creating stitching pipelines:

Using AutoPipelineFactory: For standard workflows with configurable parameters
Building custom pipelines: For maximum flexibility and control

While both approaches are valid, they serve different purposes and should be used in different scenarios:

When to Use AutoPipelineFactory: - For standard stitching workflows without custom processing steps - When the built-in parameters (normalize, flatten_z, z_method, etc.) are sufficient - For quick prototyping and getting started quickly - When you want to leverage pre-configured, optimized pipelines

When to Create Custom Pipelines: - When you need custom processing steps beyond what AutoPipelineFactory provides - When you need precise control over pipeline structure - When you need to implement specialized workflows - When you want maximum readability and maintainability for complex pipelines

Important

While it is technically possible to modify pipelines created by AutoPipelineFactory after creation, this approach is generally not recommended. Creating custom pipelines from scratch is usually more readable, maintainable, and less error-prone for any workflow that requires customization beyond what AutoPipelineFactory parameters provide.

For custom workflows, create pipelines from scratch instead of modifying factory pipelines:

from ezstitcher.core.pipeline import Pipeline
from ezstitcher.core.steps import Step, ZFlatStep, CompositeStep, PositionGenerationStep, ImageStitchingStep
from ezstitcher.core.image_processor import ImageProcessor as IP

# Create a custom pipeline with steps
position_pipeline = Pipeline(
    input_dir=orchestrator.workspace_path,
    steps=[
        # Step 1: Normalize images
        Step(
            name="Normalize Images",
            func=IP.stack_percentile_normalize
        ),

        # Step 2: Custom processing (example)
        Step(
            name="Custom Enhancement",
            func=custom_enhance
        ),

        # Step 3: Create composite for position generation
        CompositeStep(weights=[0.7, 0.3, 0]),

        # Step 4: Generate positions
        PositionGenerationStep()
    ],
    name="Custom Position Generation Pipeline"
)

# Create assembly pipeline
assembly_pipeline = Pipeline(
    input_dir=orchestrator.workspace_path,
    steps=[
        # Step 1: Normalize images
        NormStep(),

        # Step 2: Stitch images
        ImageStitchingStep()
    ],
    name="Custom Assembly Pipeline"
)

# Run the pipelines
orchestrator.run(pipelines=[position_pipeline, assembly_pipeline])

This approach provides several benefits:

Readability: The pipeline structure is explicit and easy to understand
Maintainability: Changes can be made directly to the pipeline definition
Flexibility: Complete control over each step and its parameters
Robustness: No risk of unexpected behavior from modifying factory pipelines