PRIMO

Panoramic Reconstruction In Microscopy with Optimization

Stitch microscopy tiles into seamless panoramas — with global geometric alignment, distortion correction, and photometric normalization built for real acquisitions.

Run PRIMO Explore Gallery

Three-stage pipeline

From overlapping tiles to a single consistent panorama

PRIMO combines deep feature matching with gradient-based global optimization — handling irregular layouts, lens distortion, and uneven illumination in one optimization pipeline.

  1. 1

    Feature matching

    An adaptive cascade of deep matchers: fast XFeat runs by default, with LoFTR and Efficient LoFTR brought in to refine difficult pairs. Works on regular grids or unordered tile sets with no layout metadata.

  2. 2

    Global alignment

    Sequential registration followed by bundle adjustment with optional Brown–Conrady distortion correction — all refined via autograd and AdamW.

  3. 3

    Compositing

    Global photometric normalization, seam masking, and multi-band blending remove exposure drift and visible seams across large panoramas.

Python package

Install PRIMO from PyPI

Beyond this web demo, PRIMO is published as a Python package on PyPI. Use the command-line tool for quick experiments or embed the library in your own pipelines.

Command line

Create a virtual environment, install from PyPI, and stitch a tile folder in one command.

uv venv --python 3.12
uv pip install primo-stitch
uv run primo-stitch \
  --tile_dir=folder_with_tiles \
  --output_file=panorama.jpg \
  --device=cpu \
  --matcher=xfeat \
  --blending_mode=collage \
  --inference_size=0.3

Python API

Import PRIMO in scripts and notebooks for batch processing or custom workflows.

from primo import Matcher, Stitcher

matcher = Matcher(
    model='xfeat',            # 'xfeat' | 'efficient loftr' | 'loftr'
    device='cuda:0',          # or 'cpu'
    inference_size=0.5,
)
stitcher = Stitcher(
    matcher,
    blending_mode='full',     # 'collage' | 'mosaic' | 'full'
)
stitcher.stitch(
    input_dir='path/to/tiles',
    output_file='panorama.png',
)

Comparison with baselines

Stitching artifacts on microscopy panoramas

Side-by-side results on real microscopy panoramas — the same tile set stitched with a baseline method and with PRIMO.

Step through common geometric and photometric failure modes below.

Competing method MIST

MIST result — Misalignment

PRIMO

PRIMO result — Misalignment

Misalignment

Pairwise stitching leaves visible seams and offset structures where tile overlaps should align. PRIMO’s global bundle adjustment corrects drift across the full panorama instead of accumulating error tile by tile.

Visual assessment

Qualitative comparison across microscopy datasets

Each row is one microscopy dataset. Its input tiles were stitched with every method listed in the table (default settings where applicable), then rated by operator visual inspection for geometric alignment and photometric consistency.

Success Partial success Failure Not applicable

Per cell: left mark — geometric alignment; right mark — photometric consistency.

Dataset modality Adobe Photoshop Commercial PanoramaStudio 4 Pro Commercial PTGui 13.3 Commercial Image Compositor Editor (ICE) Free MIST Open-Source BigStitcher Open-Source PRIMO Open-Source, ours
NIST Steel Mosaic DIC ✕ ✕ ✓ ± ✓ ✓ ✓ ± ✓ ✕ Not applicable ✓ ✓
vEMstitch SEM ✕ ✕ ✓ ✓ ✕ ✕ ✕ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Shading w/o corrections brightfield ✕ ✕ ✓ ✕ ✕ ± ✓ ✕ ✕ ✕ Not applicable ✓ ±
Shading with corrections brightfield ✕ ✕ ✓ ± ✓ ± ✓ ✓ ✓ ± Not applicable ✓ ✓
PanoMic-Geo, ours optical-reflected ± ± ✓ ± ✓ ✓ ✓ ± ✕ ✕ Not applicable ✓ ✓
PanoMic-GeoBig, ours optical-reflected ✕ ✕ ✓ ✕ ✕ ✕ ± ✕ ✕ ✕ Not applicable ✓ ✓
PanoMic-Metal, ours SEM ✕ ✕ ✓ ✕ ✕ ✕ ± ✕ ✓ ✕ ✓ ✕ ✓ ✓
PanoMic-Synth, ours synthetic ✓ ✕ ✓ ✓ ✓ ✓ ± ✕ ✕ ✕ ✓ ✕ ✓ ✓

Black-box evaluation

Tile-based metrics across stitching methods

We compare stitching methods quantitatively without access to their internals: each source tile is reverse-registered onto the stitched panorama, and metrics are computed between the original tile and its projected crop inside the valid mask. The same pipeline applies to open-source and commercial tools alike.

Reverse tile registration locates each input tile on the final panorama; fidelity, structural, and perceptual scores are aggregated per dataset (mean across panoramas).

Reported metrics include structural and perceptual scores (SSIM, HFI-SSIM, CW-SSIM, LPIPS) as well as photometric fidelity (MSE, ΔE, JSD).

Bar charts of LPIPS, HFI-SSIM, and JSD across four microscopy datasets for six stitching methods, with rank-stability scatter plots below. PRIMO leads on structural and perceptual metrics.

Why PRIMO

Built for microscopy, where general-purpose stitchers fail

General-purpose stitchers often fail on artifact-heavy acquisitions. PRIMO targets geometric drift, missing tiles, vignetting, and exposure variation that appear in real microscopy workflows.

Regular & irregular layouts

Works on mechanical grids and manually acquired tile sets with approximate or incomplete layouts — no strict stage model required.

Distortion-aware alignment

Jointly optimizes tile homographies with Brown–Conrady lens parameters, starting from a no-distortion prior and refining from overlap consistency.

Global photometric consistency

Estimates a Gaussian-mixture illumination map and per-tile gains from overlapping regions — critical for segmentation and quantitative analysis.

Optimization core

One optimization principle for geometry and photometry

Alignment and photometric correction share the same principle: minimize disagreement between corresponding pixels in overlapping tile pairs.

Bundle adjustment

Minimize reprojection error over inlier matches $\Omega$:

$$ \sum_{(i,j)\in\Omega} \left\lVert H_i\,\tilde{\mathbf{m}}_{ij} - H_j\,\tilde{\mathbf{m}}_{ji} \right\rVert^2 \;\longrightarrow\; \min_{H_1,\dots,H_{r-1},H_{r+1},\dots,H_n,\,D,\,C} $$

where $\tilde{\mathbf{m}} = C D^{-1} C^{-1} \mathbf{m}$, $\mathbf{m} = (x,y,1)^{\top}$, $C$ — camera calibration matrix, $D$ — distortion operator:

$$ D\!\begin{pmatrix} x \\ y \end{pmatrix} = \begin{pmatrix} x\,(1 + k_1 r^2 + k_2 r^4) + 2 p_1 x y + p_2 (r^2 + 2x^2) \\[4pt] y\,(1 + k_1 r^2 + k_2 r^4) + p_1 (r^2 + 2y^2) + 2 p_2 x y \end{pmatrix}, \qquad r^2 = x^2 + y^2 . $$

The inverse distortion $D^{-1}$ is computed using OpenCV's fixed-point iteration. Homographies $H_i$ are refined with automatic differentiation; one tile is held fixed as the reference.

Photometric normalization

Match corrected intensities in overlap regions:

$$ \sum_{(i,j)\in\Omega} \left\lVert I_i^{\mathrm{corr}}\!\big(H_i^{-1}(S_{ij})\big) - I_j^{\mathrm{corr}}\!\big(H_j^{-1}(S_{ij})\big) \right\rVert^2 \;\longrightarrow\; \min_{\mathbf{g},\,M(x)} $$
$$ I_i^{\mathrm{corr}}(x) = g_i\,\frac{I_i(x)}{M(x)}, \qquad M(x) = \sum_{k=1}^{N_{\mathrm{gaussian}}} s_k\, \frac{\exp\!\left(-\dfrac{x_k^2 + y_k^2}{2\sigma_k^2}\right)}{2\pi\sigma_k} $$

where $\Omega$ — overlapping tile pairs, $S_{ij}$ — overlap region, $H_i$ — homography of tile $i$, $g_i$ — per-tile gain, $M(x)$ — shared illumination map (mixture of Gaussians). Per-tile gains $g_i$ and the Gaussian-mixture map $M(x)$ compensate vignetting and exposure variation across the panorama.

Multi-domain evaluation

PanoMic & real-world microscopy

PRIMO is evaluated on optical reflected-light geology sections, large irregular layouts, SEM panoramas, and synthetic panoramas with controlled artifacts — plus public benchmarks without ground-truth stitches.

  • Geo

    Polished geological sections, manual grids

  • GeoBig

    Up to ~190 tiles, irregular layouts

  • Metal

    Large-scale SEM panoramas

  • Synth

    Controlled illumination & distortion

This web demo lets you run PRIMO on prepared tile sets or your own uploads, track progress live, and explore results in a deep-zoom viewer — try the gallery for precomputed examples across domains.

Ready to stitch?

Start from a prepared dataset or upload your own tiles. No account required — your session keeps track of jobs privately.

Run PRIMO Explore Gallery