Intermediate Usage

This section shows how to reimplement the EZ module functionality using pipelines and steps, providing a bridge between the simplified EZ module and the advanced usage of EZStitcher.

What You’ll Learn:

How the EZ module works under the hood
How to create custom pipelines with steps
How to reimplement EZ module functionality with more control

Learning Path:

If you are new to EZStitcher, start with the Basic Usage guide (beginner level)
After completing this intermediate guide, see Advanced Usage for advanced techniques

EZStitcher automatically chains input_dir / output_dir between steps. See Directory Structure for details on how directories are managed.

Understanding the EZ Module Under the Hood

The EZ module provides a simplified interface, but behind the scenes, it creates pipelines and steps. When you call stitch_plate(), it creates pipelines similar to this:

from ezstitcher import stitch_plate

# This simple call...
stitch_plate("path/to/plate")

# ...creates pipelines and steps similar to this:
# 1. Position Generation Pipeline with:
#    - ZFlatStep (if Z-stacks are detected)
#    - NormStep (for normalization)
#    - CompositeStep (for channel compositing)
#    - PositionGenerationStep
#
# 2. Assembly Pipeline with:
#    - NormStep (for normalization)
#    - ImageStitchingStep

Each specialized step serves a specific purpose in the image processing pipeline:

ZFlatStep: Converts 3D Z-stacks into 2D images using various projection methods
- method="max": Maximum intensity projection (brightest pixel)
- method="mean": Average intensity projection
- method="focus": Focus-based projection for better detail
NormStep: Normalizes image intensities for consistent visualization
- Applies percentile-based normalization (default: 1-99 percentile)
- Helps balance brightness across different images
CompositeStep: Combines multiple channels into a single reference image
- Accepts weights to control channel contributions, equal weighting by default
- Example: weights=[0.7, 0.3, 0] uses 70% channel 1, 30% channel 2, 0% channel 3
PositionGenerationStep: Analyzes images to determine how tiles fit together
- Detects overlapping regions between adjacent tiles
- Generates position information for stitching
ImageStitchingStep: Combines all tiles into final stitched image
- Uses positions from PositionGenerationStep
- Handles blending between overlapping regions

By understanding this structure, you can create custom pipelines that provide more control while still leveraging the power of EZStitcher’s steps.

Reimplementing EZ Module Functionality

Here’s how to reimplement the basic EZ module functionality using pipelines and steps:

from pathlib import Path
from ezstitcher.core.pipeline_orchestrator import PipelineOrchestrator
from ezstitcher.core.pipeline import Pipeline
from ezstitcher.core.steps import NormStep, ZFlatStep, CompositeStep, PositionGenerationStep, ImageStitchingStep

plate_path = Path("~/data/PlateA").expanduser()
orchestrator = PipelineOrchestrator(plate_path)

# Position generation pipeline
pos_pipe = Pipeline(
    input_dir=orchestrator.workspace_path,
    steps=[
        ZFlatStep(),  # Z-stack flattening
        NormStep(),  # Normalization
        CompositeStep(),  # Channel compositing
        PositionGenerationStep(),  # Position generation
    ],
    name="Position Generation",
)

# Assembly pipeline
asm_pipe = Pipeline(
    input_dir=orchestrator.workspace_path,
    steps=[
        NormStep(),  # Normalization
        ImageStitchingStep(),  # Image stitching
    ],
    name="Assembly",
)

orchestrator.run(pipelines=[pos_pipe, asm_pipe])

This approach gives you more control over the processing steps while still using the pre-defined steps that provide a clean interface for common operations.

Simple Examples of Custom Pipelines

Z-stack processing:

Here’s how to process Z-stacks with custom pipelines:

from pathlib import Path
from ezstitcher.core.pipeline_orchestrator import PipelineOrchestrator
from ezstitcher.core.pipeline import Pipeline
from ezstitcher.core.steps import NormStep, ZFlatStep, FocusStep, CompositeStep, PositionGenerationStep, ImageStitchingStep

plate_path = Path("~/data/PlateA").expanduser()
orchestrator = PipelineOrchestrator(plate_path)

# Position generation pipeline with Z-stack flattening
pos_pipe = Pipeline(
    input_dir=orchestrator.workspace_path,
    steps=[
        ZFlatStep(),  # Z-stack flattening
        NormStep(),  # Normalization
        CompositeStep(),  # Channel compositing
        PositionGenerationStep(),  # Position generation
    ],
    name="Position Generation",
)

# Assembly pipeline
asm_pipe = Pipeline(
    input_dir=orchestrator.workspace_path,
    steps=[
        NormStep(),  # Normalization
        #This is the only difference from the previous example
        FocusStep(focus_options={'metric': 'combined'}),  # Focus-based Z processing
        ImageStitchingStep(),  # Image stitching
    ],
    name="Assembly",
)

orchestrator.run(pipelines=[pos_pipe, asm_pipe])

Customizing step parameters:

You can customize the behavior of steps by passing parameters:

# Customize Z-flattening method
ZFlatStep(method="mean")  # Use mean projection instead of max projection

# Customize focus metrics
FocusStep(focus_options={'metric': 'combined'})  # Use combined focus metric
FocusStep(focus_options={'metric': 'laplacian'})  # Use Laplacian focus metric

# Customize normalization
NormStep(percentile=95)  # Use 95th percentile for normalization

# Customize channel compositing
CompositeStep(weights=[0.7, 0.3, 0])  # Custom weights for RGB channels

When to Move to Advanced Usage

Consider moving to the advanced usage level when:

You need to implement custom processing functions
You want to understand the implementation details of steps
You need to extend EZStitcher with new functionality
You want to create your own custom steps

The advanced usage level provides deeper insights into how EZStitcher works and how to extend it for your specific needs.

Next up: Advanced Usage.