mist-stitching 1.0.0

MIST: Microscopy Image Stitching Tool

MIST - Microscopy Image Stitching Tool

MIST (Microscopy Image Stitching Tool) is a high-performance Python library for stitching 2D microscopy image datasets. Developed at the National Institute of Standards and Technology, MIST provides accurate and scalable image stitching with stage modeling and error minimization.

Java Source Code

MATLAB Source Code

Quick Navigation

- About MIST

- Wiki

- Java Installation Guide

- User Guide

- Frequently Asked Questions

- Technical Documentation

Features

• High-Performance Stitching: Optimized algorithms for large-scale microscopy image datasets
• Flexible Grid Support: Handles both sequential and row/column-based tile numbering patterns
• Stage Modeling: Incorporates stage repeatability and overlap constraints for improved accuracy
• Translation Refinement: Advanced correlation-based translation refinement with multiple optimization methods
• Memory Efficient: Configurable memory caching for optimal performance on different hardware
• Comprehensive Output: Generates translation files, statistics, and optionally assembled stitched images
• Time-Series Support: Built-in support for time-series data as sequences of independent datasets

Installation

From PyPI (Recommended)

pip install mist-stitching

From Source

git clone https://github.com/usnistgov/MIST.git
cd MIST
git checkout python
uv venv --python=3.12
source .venv/bin/activate
uv pip install numpy pandas scikit-image

or

git clone https://github.com/usnistgov/MIST.git
cd MIST
git checkout python
pip install -e .

Applicable Domain

MIST is designed to stitch 2D image datasets. It does not address volumetric or 3D stitching which requires a system to identify and correlate features across a third dimension (e.g., Z-axis). The tool has a facility for handling time-series data as a sequence of independent datasets.

Sample Data Sets

We have two datasets: a 5x5 grid of image tiles and a 10x10 one. The two datasets were acquired with 10% overlap between consecutive tiles and in two imaging modalities: phase contrast and Cy5 (a Fluorescent imaging modality with minimal background noise). An example of each image is shown in Figure 1 below. Grid tiling starts in the upper left corner and proceeds one row at a time from left to right; rows are ordered from top to bottom. File names follow the pattern, basename_r{rrr}_c{ccc}.tif, where r{rrr} is the row number and c{ccc} the column number. For example: img_Cy5_r003_c004.tif is the image acquired using Cy5 and located on row 3, column 4 on the 5x5 grid.

These datasets can be downloaded from the following links:

5x5 Image Tile Dataset

Cy5_ImageTiles.zip ~ 32 MB

Example Results: Cy5_ImageTiles.zip ~ 5 KB

Phase_Image_Tiles.zip ~ 49 MB

Example Results: Phase_Image_Tiles.zip ~ 5 KB

10x10 Image Tile Dataset

Cy5_ImageTiles.zip ~ 119 MB

Phase_Image_Tiles.zip ~ 195 MB

This dataset is hosted at and used for the 2015 BioImage Informatics Conference: Image Stitching Challenge.

Figure 1: Example Phase Contrast and Cy5 stitched images with auto adjusted contrast for visualization purposes.

Quick Start

wget https://github.com/usnistgov/MIST/wiki/testdata/Small_Phase_Test_Dataset.zip
unzip Small_Phase_Test_Dataset.zip

python src/mist_stitching/main.py \
    --image-dirpath ./Small_Phase_Test_Dataset/image-tiles \
    --output-dirpath ./Small_Phase_Test_Dataset/output \
    --grid-width 5 \
    --grid-height 5 \
    --filename-pattern "img_r{rrr}_c{ccc}.tif" \
    --filename-pattern-type ROWCOL \
    --grid-origin UL \
    --numbering-pattern HORIZONTALCOMBING \
    --save-image

Basic Usage

from mist import mist
import argparse

# Create arguments namespace
args = argparse.Namespace(
    image_dirpath='/path/to/images',
    output_dirpath='/path/to/output',
    grid_width=5,
    grid_height=5,
    filename_pattern='img_{:03d}.tif',
    filename_pattern_type='SEQUENTIAL',
    grid_origin='UL',
    numbering_pattern='HORIZONTALCOMBING',
    save_image=True
)

# Run MIST stitching
mist(args)

Command Line Usage

python main.py \
    --image-dirpath /path/to/images \
    --output-dirpath /path/to/output \
    --grid-width 5 \
    --grid-height 5 \
    --filename-pattern "img_{:03d}.tif" \
    --filename-pattern-type SEQUENTIAL \
    --grid-origin UL \
    --numbering-pattern HORIZONTALCOMBING \
    --save-image

Supported File Naming Patterns

Sequential Numbering

• Pattern: img_{:03d}.tif (e.g., img_000.tif, img_001.tif, ...)
• Type: SEQUENTIAL
• Use Case: Simple sequential tile numbering

Row/Column Numbering

• Pattern: img_r{rrr}_c{ccc}.tif (e.g., img_r003_c004.tif)
• Type: ROWCOL
• Use Case: Grid-based tile organization

Grid Organization Options

Grid Origins

• UL: Upper Left
• UR: Upper Right
• LL: Lower Left
• LR: Lower Right

Numbering Patterns

• HORIZONTALCOMBING: Left to right, top to bottom
• VERTICALCOMBING: Top to bottom, left to right
• HORIZONTALCONTINUOUS: Continuous horizontal numbering
• VERTICALCONTINUOUS: Continuous vertical numbering

Advanced Configuration

Stage Model Parameters

--stage-repeatability 0.5        # Stage repeatability in pixels
--horizontal-overlap 0.1         # Expected horizontal overlap (0.0-1.0)
--vertical-overlap 0.1           # Expected vertical overlap (0.0-1.0)
--overlap-uncertainty 3.0        # Overlap uncertainty in pixels
--valid-correlation-threshold 0.5 # Minimum NCC value for valid translation

Translation Refinement

--translation-refinement-method SINGLEHILLCLIMB  # SINGLEHILLCLIMB or MULTIPOINTHILLCLIMB
--num-hill-climbs 16                            # Number of hill climbing iterations
--num-fft-peaks 2                               # Number of FFT peaks to consider

Performance Options

--disable-mem-cache             # Disable memory caching for low-memory systems
--time-slice 0                  # Time slice for time-series data

Output Files

MIST generates several output files in the specified output directory:

• {prefix}relative-positions-no-optimization-{time}.txt: Initial pairwise translations
• {prefix}statistics-{time}.txt: Stage model statistics and analysis
• {prefix}relative-positions-{time}.txt: Refined pairwise translations
• {prefix}global-positions-{time}.txt: Final global positions for all tiles
• {prefix}stitched-{time}.tif: Assembled stitched image (if --save-image is used)
• {prefix}log.txt: Detailed processing log

License

NIST-developed software is provided by NIST as a public service. You may use, copy and distribute copies of the software in any medium, provided that you keep intact this entire notice. You may improve, modify and create derivative works of the software or any portion of the software, and you may copy and distribute such modifications or works. Modified works should carry a notice stating that you changed the software and should note the date and nature of any such change. Please explicitly acknowledge the National Institute of Standards and Technology as the source of the software.

NIST-developed software is expressly provided "AS IS." NIST MAKES NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED, IN FACT OR ARISING BY OPERATION OF LAW, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND DATA ACCURACY. NIST NEITHER REPRESENTS NOR WARRANTS THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT ANY DEFECTS WILL BE CORRECTED. NIST DOES NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF THE SOFTWARE OR THE RESULTS THEREOF, INCLUDING BUT NOT LIMITED TO THE CORRECTNESS, ACCURACY, RELIABILITY, OR USEFULNESS OF THE SOFTWARE.

You are solely responsible for determining the appropriateness of using and distributing the software and you assume all risks associated with its use, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and the unavailability or interruption of operation. This software is not intended to be used in any situation where a failure could cause risk of injury or damage to property. The software developed by NIST employees is not subject to copyright protection within the United States.

Support

For questions, issues, or support:

• Open an issue on GitHub
• Check the original MIST documentation
• Contact the development team at NIST

How to cite our work

If you are using MIST in your research, please use the following references to cite us.

T. Blattner et. al., "A Hybrid CPU-GPU System for Stitching of Large Scale Optical Microscopy Images", 2014 International Conference on Parallel Processing, 2014 download pdf, view article

J. Chalfoun, et al. "MIST: Accurate and Scalable Microscopy Image Stitching Tool with Stage Modeling and Error Minimization". Scientific Reports. 2017;7:4988. doi:10.1038/s41598-017-04567-y download pdf, view article