QuPath Basic Stitching Extension

Part of the QPSC (QuPath Scope Control) system For complete installation instructions and system overview, see: https://github.com/uw-loci/QPSC

A basic image stitching extension for QuPath that combines multiple image tiles into seamless pyramidal images. This extension supports multiple stitching strategies, dual output formats (OME-TIFF and OME-ZARR), and is designed for high-throughput microscopy workflows.

Features

Multiple Stitching Strategies: Support for filename-based coordinates, TileConfiguration.txt files, and Vectra metadata
Dual Output Formats: Choose between traditional OME-TIFF or cloud-native OME-ZARR
Pyramidal Output: Generates multi-resolution pyramids for efficient viewing at all scales
Flexible Compression: Supports various compression formats (TIFF: JPEG, LZW, ZIP; ZARR: zstd, lz4, blosc)
Cloud-Native ZARR: Directory-based format optimized for cloud storage and parallel access
Batch Processing: Process multiple slides simultaneously with matching criteria
Multi-subdirectory Support: Automatically creates separate outputs for each matched subdirectory
Robust Error Handling: Comprehensive logging and validation for troubleshooting
Memory Efficient: Optimized for large datasets with configurable downsampling
Parallel Writing: ZARR format utilizes multi-threaded tile writing for faster output

Requirements

QuPath: Version 0.6.0 or greater
Java: Java 11 or higher
Memory: Recommended 8GB+ RAM for large image datasets

Installation

Option 1: Download Release

Download the latest .jar file from the Releases page
Copy the JAR file to your QuPath extensions directory:
- Windows: %USERPROFILE%/QuPath/extensions
- macOS: ~/QuPath/extensions
- Linux: ~/QuPath/extensions
Restart QuPath

Alternatively, drag and drop the extension into QuPath.

Option 2: Build from Source

git clone https://github.com/yourusername/qupath-basic-stitching.git
cd qupath-basic-stitching
./gradlew build
# Copy build/libs/qupath-extension-basic-stitching-*.jar to your QuPath extensions directory

Developers of qpsc may want to also run the following to enable working with qpsc in IntelliJ.

./gradlew publishToMavenLocal

Usage

Accessing the Extension

Open QuPath
Navigate to Extensions → Basic Stitching → Stitch Images
The stitching dialog will open

Stitching Strategies

1. Filename[x,y] with Coordinates in Microns

For images with coordinates embedded in filenames:

image_tile[1000,2000].tif
image_tile[1500,2000].tif
image_tile[1000,2500].tif

Usage:

Select folder containing subdirectories with tiles
Coordinates in brackets represent physical positions in microns
Extension automatically calculates tile positions and overlaps

2. TileConfiguration.txt File

For ImageJ/Fiji tile configuration format:

# Define the number of dimensions we are working on
dim = 2

# Define the image coordinates
tile_001.tif; ; (0.0, 0.0)
tile_002.tif; ; (1024.0, 0.0)
tile_003.tif; ; (0.0, 1024.0)
tile_004.tif; ; (1024.0, 1024.0)

Usage:

Each subdirectory must contain a TileConfiguration.txt file
Coordinates represent pixel positions
Automatically scaled based on pixel size and downsample settings

Batch Processing Multiple Subdirectories: When the matching string matches multiple subdirectories, each subdirectory is stitched independently:

input_folder/bounds/
├── -5.0/
│   ├── TileConfiguration.txt
│   └── [tile files]
├── 0.0/
│   ├── TileConfiguration.txt
│   └── [tile files]
└── 5.0/
    ├── TileConfiguration.txt
    └── [tile files]

With matching string "." results in:

-5.0.ome.tif
0.0.ome.tif
5.0.ome.tif

3. Vectra Tiles with Metadata

For Akoya/PerkinElmer Vectra imaging systems:

Reads positioning information directly from TIFF metadata tags
Uses TAG_X_POSITION, TAG_Y_POSITION, and resolution tags
No additional configuration files required

Configuration Parameters

Parameter	Description	Default
Input Folder	Root directory containing image subdirectories	Required
Output Folder	Directory for stitched output files	Required
Pixel Size (μm)	Physical size of each pixel in microns	0.5
Base Downsample	Downsampling factor for output	1.0
Compression	Compression algorithm (TIFF: LZW, JPEG; ZARR: zstd, lz4)	LZW
Output Format	OME-TIFF (single file) or OME-ZARR (directory)	OME-TIFF
Matching String	Filter subdirectories by name pattern. Use "." to process all subdirectories separately	"" (all)
Z-Spacing (μm)	Z-axis spacing for 3D datasets	1.0

Output Format Options

OME-TIFF (Traditional)

Structure: Single pyramidal TIFF file
Compatibility: Widely supported by QuPath, ImageJ, and most imaging software
Use Case: General purpose, local storage, maximum compatibility
Extension: .ome.tif
Compression: LZW, JPEG, JPEG-2000, Uncompressed
Best For: Desktop workflows, maximum software compatibility

OME-ZARR (Cloud-Native)

Structure: Directory containing chunked arrays
Compatibility: QuPath 0.6.0+, napari, Python imaging libraries
Use Case: Cloud storage, large datasets, parallel processing
Extension: .ome.zarr (directory)
Compression: zstd (best balance), lz4 (fastest), lz4hc, blosclz, zlib
Best For: Cloud storage, collaborative access, very large images (> 10GB)

Key Advantages of ZARR:

Faster Writing: Multi-threaded tile writing (typically 2-3x faster than TIFF)
Better Compression: Blosc/zstd compression achieves 20-30% smaller files than LZW
Cloud-Optimized: Native support for S3, Azure Blob, Google Cloud Storage
Partial Access: Read specific regions without downloading entire file
Parallel Processing: Multiple processes can read different regions simultaneously
Progress Tracking: Per-tile progress callbacks for better user feedback

Compression Recommendations:

zstd (default): Best balance of speed and compression ratio
lz4: Fastest compression/decompression, slightly larger files
lz4hc: Better compression than lz4, slower writing
zlib: Compatible with standard zip compression
blosclz: Optimized for binary data

When to Use ZARR:

Stitched images > 5GB in size
Cloud storage or collaborative workflows
High-throughput batch processing
Need for parallel data access
Long-term archival with cloud backup

When to Use OME-TIFF:

Need maximum software compatibility
Working with legacy analysis pipelines
Smaller images (< 2GB)
Desktop-only workflows
Sharing with users without ZARR support

Example Workflows

Basic Stitching (OME-TIFF)

// Programmatic usage example - traditional OME-TIFF output
StitchingConfig config = new StitchingConfig(
    "Filename[x,y] with coordinates in microns",  // Strategy
    "/path/to/input/folder",                      // Input path
    "/path/to/output/folder",                     // Output path
    "LZW",                                        // Compression
    0.5,                                          // Pixel size (μm)
    1.0,                                          // Base downsample
    "slide",                                      // Matching string
    1.0,                                          // Z-spacing (μm)
    StitchingConfig.OutputFormat.OME_TIFF         // Output format
);
String result = StitchingWorkflow.run(config);

Cloud-Native ZARR Output

// High-performance ZARR output with fast compression
StitchingConfig config = new StitchingConfig(
    "Coordinates in TileConfiguration.txt file",
    "/data/microscopy/slides",
    "/data/output/stitched",
    "zstd",                                       // ZARR compression (fast + good ratio)
    0.25,                                         // 0.25 μm/pixel
    1.0,                                          // Base downsample
    ".",                                          // Process all subdirectories
    1.0,                                          // Z-spacing
    StitchingConfig.OutputFormat.OME_ZARR         // ZARR format
);
String result = StitchingWorkflow.run(config);
// Output: multiple .ome.zarr directories, one per subdirectory

Batch Processing with Downsampling (TIFF)

StitchingConfig config = new StitchingConfig(
    "Coordinates in TileConfiguration.txt file",
    "/data/microscopy/slides",
    "/data/output/stitched",
    "JPEG",                                       // TIFF compression
    0.25,                                         // 0.25 μm/pixel
    4.0,                                          // 4x downsample
    "H&E",                                        // Process only H&E slides
    1.0,
    StitchingConfig.OutputFormat.OME_TIFF         // Traditional TIFF
);
String result = StitchingWorkflow.run(config);

Special Use Cases

Rotation Angle Processing

For workflows with multiple rotation angles stored in separate folders:

bounds/
├── -5.0/
│   ├── TileConfiguration.txt
│   └── [9 tiles]
├── 0.0/
│   ├── TileConfiguration.txt
│   └── [9 tiles]
└── 5.0/
    ├── TileConfiguration.txt
    └── [9 tiles]

Using matching string "." will create three separate stitched images, one for each angle.

Directory Structure

Input Directory Structure

input_folder/
├── slide001_tumor/
│   ├── tile_001[0,0].tif
│   ├── tile_002[1000,0].tif
│   └── tile_003[0,1000].tif
├── slide002_normal/
│   ├── tile_001[0,0].tif
│   └── tile_002[1000,0].tif
└── slide003_control/
    └── TileConfiguration.txt
    ├── image_001.tif
    └── image_002.tif

Output Structure

Output files are named based on the subdirectory being processed:

When matching string equals folder name: uses folder name
When processing multiple subdirectories: each gets its own output file named after the subdirectory

output_folder/
├── slide001_tumor.ome.tif
├── slide002_normal.ome.tif
└── slide003_control.ome.tif

When processing subdirectories:

output_folder/
├── -5.0.ome.tif
├── 0.0.ome.tif
└── 5.0.ome.tif

Performance Optimization

Memory Management

Large Datasets: Use higher downsample values (2x, 4x) for initial processing
RAM Usage: Monitor memory usage; increase JVM heap size if needed:
```
java -Xmx16G -jar QuPath.jar
```

Processing Speed

Parallel Processing: Extension automatically uses multiple CPU cores
SSD Storage: Use SSD drives for input/output to improve I/O performance
Network Storage: Avoid network drives for temporary processing

Tile Size Recommendations

Small Tiles (< 2048px): Fast processing, more metadata overhead
Large Tiles (> 8192px): Slower processing, less overhead
Optimal Range: 2048-4096 pixels per tile dimension

Troubleshooting

Common Issues

"No valid tile configurations found"

Cause: Directory structure doesn't match expected format
Solution: Verify subdirectory naming and tile file patterns
Check: Enable debug logging to see which directories are processed

"Could not retrieve dimensions for image"

Cause: Corrupted or unsupported image format
Solution: Verify TIFF files are valid and readable
Check: Test individual files in QuPath or ImageJ

"Mismatch between tile configuration file names"

Cause: TileConfiguration.txt references files not present in directory
Solution: Ensure all referenced files exist and names match exactly
Check: Case sensitivity on Linux/macOS systems

Multiple subdirectories stitched into one file

Cause: Using substring matching that matches unintended folders
Solution: Use exact matching or "." to process each subdirectory separately
Example: "5.0" matches both "5.0" and "-5.0"; use "." instead

Out of Memory Errors

Cause: Insufficient JVM heap space for large datasets
Solution: Increase heap size or use higher downsample values
Command: java -Xmx16G -jar QuPath.jar

Debug Logging

Enable detailed logging by setting log level to DEBUG:

# In QuPath logging configuration
logger.qupath.ext.basicstitching=DEBUG

Validation Steps

File Integrity: Verify all input TIFF files open correctly
Coordinate Extraction: Check log output for parsed coordinates
Directory Matching: Confirm subdirectories match the filtering criteria
Output Verification: Open resulting OME-TIFF in QuPath to verify stitching quality

API Documentation

Core Classes

`StitchingImplementations`

Main coordination class for stitching operations.

Key Methods:

stitchCore(): Primary stitching method
setStitchingStrategy(): Configure stitching algorithm

Strategy Classes

FileNameStitchingStrategy: Parse coordinates from filenames
TileConfigurationTxtStrategy: Read ImageJ tile configurations
VectraMetadataStrategy: Extract Vectra TIFF metadata

Extension Points

The extension supports custom stitching strategies by implementing the StitchingStrategy interface:

public interface StitchingStrategy {
    List<Map<String, Object>> prepareStitching(
        String folderPath, 
        double pixelSizeInMicrons,
        double baseDownsample, 
        String matchingString
    );
}

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/yourusername/qupath-basic-stitching.git
cd qupath-basic-stitching
./gradlew build
./gradlew test

Code Style

Follow standard Java conventions
Add comprehensive logging for debugging
Include unit tests for new functionality
Update documentation for API changes

License

This project is licensed under the MIT license - see the LICENSE file for details.

Citation

If you use this extension in your research, please cite:

@software{qupath_basic_stitching,
  title={QuPath Basic Stitching Extension},
  author={Your Name},
  year={2025},
  url={https://github.com/yourusername/qupath-basic-stitching},
  version={1.0.0}
}

Support

Issues: Report bugs and feature requests via GitHub Issues
Discussions: Join the conversation in GitHub Discussions
QuPath Forum: Get help from the community at image.sc

Changelog

Version 0.2.0 (ZARR Support)

NEW: OME-ZARR output format support (cloud-native, directory-based)
NEW: Multi-threaded parallel tile writing for ZARR format
NEW: Advanced compression options (zstd, lz4, lz4hc, blosclz)
NEW: Per-tile progress tracking for ZARR writes
ENHANCED: GUI now includes output format selection dropdown
ENHANCED: Automatic compression mapping (TIFF types to ZARR equivalents)
ENHANCED: Comprehensive unit tests for format support
PERFORMANCE: 2-3x faster writing speed with ZARR parallel processing
PERFORMANCE: 20-30% smaller file sizes with Blosc compression
Backward compatible: existing code defaults to OME-TIFF format

Version 0.1.0

Initial Java conversion from Groovy implementation
Support for QuPath 0.6.0+
Three stitching strategies implemented
Multi-subdirectory batch processing with separate outputs
Comprehensive error handling and logging
Performance optimizations for large datasets

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
.github		.github
gradle/wrapper		gradle/wrapper
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
Workflow.md		Workflow.md
build.gradle.kts		build.gradle.kts
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

Folders and files

Latest commit

History

Repository files navigation

QuPath Basic Stitching Extension

Features

Requirements

Installation

Option 1: Download Release

Option 2: Build from Source

Usage

Accessing the Extension

Stitching Strategies

1. Filename[x,y] with Coordinates in Microns

2. TileConfiguration.txt File

3. Vectra Tiles with Metadata

Configuration Parameters

Output Format Options

OME-TIFF (Traditional)

OME-ZARR (Cloud-Native)

Example Workflows

Basic Stitching (OME-TIFF)

Cloud-Native ZARR Output

Batch Processing with Downsampling (TIFF)

Special Use Cases

Rotation Angle Processing

Directory Structure

Input Directory Structure

Output Structure

Performance Optimization

Memory Management

Processing Speed

Tile Size Recommendations

Troubleshooting

Common Issues

"No valid tile configurations found"

"Could not retrieve dimensions for image"

"Mismatch between tile configuration file names"

Multiple subdirectories stitched into one file

Out of Memory Errors

Debug Logging

Validation Steps

API Documentation

Core Classes

StitchingImplementations

Strategy Classes

Extension Points

Contributing

Development Setup

Code Style

License

Citation

Support

Changelog

Version 0.2.0 (ZARR Support)

Version 0.1.0

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`StitchingImplementations`

Packages