TileFusion

GPU/CPU-accelerated tile registration and fusion for 2D microscopy images.

Features

• Multi-format support: OME-TIFF, individual TIFFs with coordinates.csv, Zarr
• GPU acceleration: Optional CUDA support via CuPy/cuCIM for 10-50x speedup
• Robust registration: Phase cross-correlation with SSIM scoring and outlier rejection
• Memory-efficient: Chunked processing for large datasets
• OME-NGFF output: Zarr v3 with multiscale pyramids

Installation

From source (recommended)

# Clone the repository
git clone https://github.com/cephla/tilefusion.git
cd tilefusion

# Basic installation (CPU only)
pip install -e .

# For development (includes linting tools)
pip install -e ".[dev]"
pre-commit install  # Enable automatic formatting on commit

# With GUI support
pip install -e ".[gui]"

# With GPU support (requires CUDA)
pip install -e ".[gpu]"

# Full installation (GPU + GUI + dev tools)
pip install -e ".[all]"

From PyPI (when published)

pip install tilefusion
pip install tilefusion[gui]  # With GUI
pip install tilefusion[gpu]  # With GPU support

Quick Start

Python API

from tilefusion import TileFusion

# Create stitcher instance
tf = TileFusion(
    "path/to/tiles.ome.tiff",
    blend_pixels=(50, 50),
    downsample_factors=(2, 2),
)

# Run full pipeline
tf.run()

GUI

stitcher-gui

CLI

# Convert individual TIFFs to Zarr
convert-to-zarr path/to/folder -o output.zarr

Supported Formats

Input

• OME-TIFF: Multi-series TIFF with OME-XML metadata
• Individual TIFFs: Folder with manual_{fov}_{z}_{channel}.tiff and coordinates.csv
• Zarr: Zarr v3 with per_index_metadata stage positions

Output

• OME-NGFF Zarr v3: With multiscale pyramids for efficient visualization

Thread Safety

TileFusion uses thread-local file handles for safe concurrent tile reads. Each thread gets its own TiffFile handle, avoiding race conditions that occur when multiple threads share a single file descriptor.

Recommended Usage

Use the context manager (safest):

with TileFusion("tiles.ome.tiff") as tf:
    # All operations here are thread-safe
    tf.run()
# Handles automatically closed when exiting the context

Manual lifecycle management:

tf = TileFusion("tiles.ome.tiff")
try:
    tf.run()  # Handles thread pool internally
finally:
    tf.close()

Known Limitations

• Do not call close() while threads are reading: Closing handles mid-operation causes errors. Always ensure all read operations complete before calling close() or exiting the context manager.
• Thread-local handles consume file descriptors: Each thread creates its own handle. With many threads, you may hit OS file descriptor limits.

Acknowledgments

This project is based on the tilefusion module from opm-processing-v2 by Doug Shepherd and the QI2lab team at Arizona State University.

License

BSD-3-Clause