Basic Usage

This page provides an overview of how to use EZStitcher for basic image stitching tasks. If you’re looking for a quick start guide, see Getting Started with EZStitcher.

Three-Tier Approach

EZStitcher offers three main approaches for creating stitching pipelines, each designed for a different level of user experience and need for control:

  1. EZ Module (Beginner Level)

    A simplified, one-liner interface for beginners and non-coders:

    • “I just want to stitch my images quickly”

    • Uses sensible defaults and auto-detection

    • Handles common use cases with a single function call

    • Example: stitch_plate("path/to/plate")

  2. Custom Pipelines with Steps (Intermediate Level)

    More flexibility and control using pre-defined steps:

    • “I need more control over the processing steps”

    • Uses pre-defined steps that provide a clean interface for common operations

    • Allows customization of processing steps and parameters

    • See Intermediate Usage for details

  3. Library Extension with Base Step (Advanced Level)

    For advanced users who need to understand implementation details:

    • “I need to understand how the steps work under the hood”

    • Uses the base Step class to create custom processing functions

    • Provides maximum flexibility and control

    • See Advanced Usage for details

This guide focuses on the EZ Module approach, which is recommended for most users.

Getting Started with EZStitcher

The simplest way to use EZStitcher is through the EZ module, which provides a one-liner function for stitching microscopy images:

from ezstitcher import stitch_plate

# Stitch a plate with default settings
stitch_plate("path/to/plate")

That’s it! This single line will:

  1. Automatically detect the plate format

  2. Process all channels and Z-stacks appropriately

  3. Generate positions and stitch images

  4. Save the output to a new directory

Key Parameters

While the default settings work well for most cases, you can customize the behavior with a few key parameters:

stitch_plate(
    "path/to/plate",                    # Input directory with microscopy images
    output_path="path/to/output",       # Where to save results (optional)
    normalize=True,                     # Apply intensity normalization (default: True)
    flatten_z=True,                     # Flatten Z-stacks to 2D (auto-detected if None)
    z_method="max",                     # How to flatten Z-stacks: "max", "mean", "focus"
    channel_weights=[0.7, 0.3, 0],      # Weights for position finding (auto-detected if None)
    well_filter=["A01", "B02"]          # Process only specific wells (optional)
)

Z-Stack Processing

For plates with Z-stacks, you can control how they’re flattened:

# Maximum intensity projection (brightest pixel from each Z-stack)
stitch_plate("path/to/plate", flatten_z=True, z_method="max")

# Focus-based projection (selects best-focused plane)
stitch_plate("path/to/plate", flatten_z=True, z_method="focus")

# Mean projection (average across Z-planes)
stitch_plate("path/to/plate", flatten_z=True, z_method="mean")

More Control

For slightly more control while keeping things simple, use the EZStitcher class:

from ezstitcher import EZStitcher

# Create a stitcher
stitcher = EZStitcher("path/to/plate")

# Set options
stitcher.set_options(
    normalize=True,
    z_method="focus"
)

# Run stitching
stitcher.stitch()

Troubleshooting

Common issues:

  • No output: Check that the input path exists and contains microscopy images

  • Z-stacks not detected: Explicitly set flatten_z=True

  • Poor quality: Try different z_method values or adjust channel_weights

Understanding Key Concepts

Here are the key concepts you need to understand for basic usage:

Plates and Wells

EZStitcher processes microscopy data organized in plates and wells. A plate contains multiple wells, and each well contains multiple images.

Images and Channels

Microscopy images can have multiple channels (e.g., DAPI, GFP, RFP) and Z-stacks (multiple focal planes).

Processing Steps

Behind the scenes, EZStitcher processes images through a series of steps:

  • Z-flattening: Converting 3D Z-stacks into 2D images

  • Normalization: Adjusting image intensity for consistent visualization

  • Channel compositing: Combining multiple channels into a single image

  • Position generation: Finding the relative positions of tiles

  • Image stitching: Combining tiles into a complete image

These steps are organized into two standard pipelines:

  1. Position Generation Pipeline: Z-flattening → Normalization → Channel compositing → Position generation

  2. Assembly Pipeline: Normalization → Image stitching

The EZ module handles all these steps automatically, so you don’t need to worry about them unless you need more control.

For more detailed information about EZStitcher’s architecture and concepts, see Architecture Overview and the Overview and Key Components section.

When You Need More Control

If you need more flexibility than the EZ module provides:

  1. First, explore all the options available in the EZ module (see the Key Parameters section above)

  2. If you still need more control, see Intermediate Usage to learn how to create custom pipelines with steps

  3. For even more advanced usage, see Advanced Usage for understanding implementation details

For detailed API documentation of the EZ module, see EZ Module.