Metadata-Version: 2.4
Name: primo-stitch
Version: 0.2.1
Summary: PRIMO: Panoramic Reconstruction with Integrated Microscopy-Specific Optimization
Author-email: Gleb Nikolaev <nikolaevgv@my.msu.ru>, Savelii Shashkov <s02230302@gse.cs.msu.ru>, Dmitriy Korshunov <d.korshunov@ginras.ru>, Andrey Krylov <kryl@cs.msu.ru>, Alexander Khvostikov <khvostikov@cs.msu.ru>
Maintainer-email: Alexander Khvostikov <khvostikov@cs.msu.ru>
License-Expression: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_LICENSES.md
Requires-Dist: numpy>=1.24
Requires-Dist: scipy
Requires-Dist: tifffile
Requires-Dist: imagecodecs>=2025.3.30
Requires-Dist: matplotlib
Requires-Dist: psutil>=5.9
Requires-Dist: tqdm
Requires-Dist: opencv-python
Requires-Dist: pillow
Requires-Dist: scikit-image
Requires-Dist: loguru
Requires-Dist: yacs
Requires-Dist: huggingface_hub
Requires-Dist: safetensors
Requires-Dist: kornia<0.9,>=0.8.2
Requires-Dist: einops
Requires-Dist: torch>=2.1
Requires-Dist: torchvision>=0.16
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install primo-stitch
```

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

## Command-line usage

`primo-stitch` is the main entry point.

```bash
# 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

| Flag | Default | Description |
|---|---|---|
| `--tile_dir` | *(required)* | Directory with the input tiles |
| `--output_file` | `panorama.jpg` | Output panorama path (extension may be adjusted, e.g. `.png` when alpha is saved) |
| `--cache_dir` | `.cache/` | Directory for intermediate results (created automatically, cleaned up after the run) |
| `--matcher` | `xfeat` | `xfeat` \| `efficient loftr` \| `loftr` |
| `--device` | `cpu` | `cpu`, `cuda`, `cuda:0`, ... |
| `--blending_mode` | `full` | `collage` — fast paste-over, no correction; `mosaic` — photocorrection + hard seams, no blending; `full` — photocorrection + seams + multiband blending |
| `--inference_size` | `0.3` | Matcher input scale relative to the original (`0.25`, `0.5`, `1`, ...) |
| `--batch_size` | `1` | Matcher batch size (higher = faster, more memory) |
| `--save_alpha_channel` / `--no-save_alpha_channel` | off | Save the transparency channel; forces `.png` output in `full` mode |
| `--logfile` | *(none)* | Write a debug log to this file |

## Python API

```python
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:

```bibtex
@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](LICENSE); bundled third-party components — see
[THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).
