Metadata-Version: 2.4
Name: primo-stitch
Version: 0.1.0
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
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_LICENSES.md
Requires-Dist: numpy<2
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: PyMaxflow
Requires-Dist: einops
Requires-Dist: torch<2.3,>=2.1
Requires-Dist: torchvision<0.19,>=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
```

- Requires **Python 3.10–3.12**.
- PRIMO depends on **PyTorch**. The default install pulls the CPU build; for GPU
  use, install the CUDA build of `torch`/`torchvision` first (see
  https://pytorch.org), then install PRIMO.
- Matcher weights are downloaded automatically on first use (Hugging Face Hub /
  Torch Hub) and cached locally.

After installation you get the `primo-stitch` command and the importable
`primo` package (install name `primo-stitch`, import name `primo`).

## 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.png

# 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 \
  --cache_dir cache/ \
  --logfile run.log
```

> By default (`full` blending with `--save_alpha_channel` on), the panorama is
> written as **`.png`** (RGBA) regardless of the requested extension. Pass
> `--no-save_alpha_channel` to save a `.jpg`.

### 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/` | Cache directory (created automatically) |
| `--matcher` | `xfeat` | `xfeat` \| `efficient loftr` \| `loftr` |
| `--device` | `cpu` | `cpu`, `cuda`, `cuda:0`, ... |
| `--blending_mode` | `full` | `collage` \| `mosaic` \| `full` |
| `--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` | on | 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'
    save_alpha_channel=True,
)

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

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

## Demo

The interactive demo (live preview + machine-readable progress) is driven by
`primo-stitch-online` and the `run_online.sh` wrapper. For normal use they are
not needed; `primo-stitch` can also emit progress by adding `--online`, which
writes a `status.json` and a `preview.jpg` while processing.

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

If you use PRIMO in your research, please cite (update pages/DOI with the
final proceedings entry):

```bibtex
@inproceedings{primo2026,
  title     = {PRIMO: Panoramic Reconstruction with Integrated Microscopy-Specific Optimization},
  author    = {Nikolaev, Gleb and Shashkov, Savelii and Korshunov, Dmitriy and Krylov, Andrey and Khvostikov, Alexander},
  booktitle = {Proceedings of the 34th ACM International Conference on Multimedia (MM '26)},
  year      = {2026},
}
```

## License

PRIMO's source code is licensed under the [Apache License 2.0](LICENSE). It
bundles third-party components under their own licenses (Apache-2.0, MIT); see
[THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).

The accompanying paper is published by ACM under CC BY 4.0 (chosen via the ACM
eRights process) — this is separate from the software license above.
