PRIMO: Panoramic Reconstruction with Integrated Microscopy-Specific Optimization

Python library and command-line tool for stitching a set of overlapping tiles into a single 2D panorama.

Installation

pip install primo-stitch

• Python 3.10–3.14.
• If you use a GPU, make sure you have a CUDA-enabled PyTorch (pytorch.org).
• Model weights are downloaded on the first run — internet access is required.

Command-line usage

primo-stitch is the main entry point.

# minimal — stitch a folder of tiles into a panorama
primo-stitch --tile_dir path/to/tiles --output_file panorama.jpg

# advanced
primo-stitch \
  --tile_dir path/to/tiles \
  --output_file panorama.png \
  --matcher "efficient loftr" \
  --device cuda:0 \
  --blending_mode full \
  --inference_size 0.5 \
  --batch_size 8 \
  --logfile run.log

Options

Python API

from primo import Matcher, Stitcher

matcher = Matcher(
    model='xfeat',            # 'xfeat' | 'efficient loftr' | 'loftr'
    device='cuda:0',          # or 'cpu'
    inference_size=0.5,
    batch_size=8,
)

# the alignment device is taken from the matcher
stitcher = Stitcher(
    matcher,
    blending_mode='full',     # 'collage' | 'mosaic' | 'full'
)

stitcher.stitch(
    input_dir='path/to/tiles',
    output_file='panorama.jpg',
)

Matcher and Stitcher expose additional keyword arguments (alignment, photometric correction, blending) — see their signatures for the full set.

Authors

• Gleb Nikolaev — Lomonosov Moscow State University
• Savelii Shashkov — Lomonosov Moscow State University
• Dmitriy Korshunov — Geological Institute of the Russian Academy of Sciences
• Andrey Krylov — Lomonosov Moscow State University
• Alexander Khvostikov (corresponding author) — Lomonosov Moscow State University

Citation

A paper describing PRIMO is currently under review; full citation details (venue, year, DOI) will be added once it is published. Until then, please credit the authors:

@unpublished{primo,
  title  = {PRIMO: Panoramic Reconstruction with Integrated Microscopy-Specific Optimization},
  author = {Nikolaev, Gleb and Shashkov, Savelii and Korshunov, Dmitriy and Krylov, Andrey and Khvostikov, Alexander},
  year   = {2026},
  note   = {Manuscript under review}
}

License

Apache-2.0; bundled third-party components — see THIRD_PARTY_LICENSES.md.