Metadata-Version: 2.4
Name: mcd_stitcher
Version: 2.5.0
Summary: MCD file conversion and stitching to OME-TIFFs
Author-email: Pawan Chaurasia <pchaurasia98@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/PawanChaurasia/mcd_stitcher
Project-URL: Documentation, https://pawanchaurasia.github.io/mcd_stitcher/
Project-URL: Bug Tracker, https://github.com/PawanChaurasia/mcd_stitcher/issues
Project-URL: Repository, https://github.com/PawanChaurasia/mcd_stitcher
Keywords: imaging,masscytometry,StandardBio,SBT,IMC,stitching,conversion
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.8
Requires-Dist: imagecodecs>=2024.12.30
Requires-Dist: numpy<3,>=2.0.2
Requires-Dist: pillow>=11.3.0
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: psutil>=5.9
Requires-Dist: scikit-image>=0.24.0
Requires-Dist: tifffile>=2024.8.30
Dynamic: license-file

![MCD Stitcher — whole-slide conversion and stitching for Imaging Mass Cytometry](https://raw.githubusercontent.com/PawanChaurasia/mcd_stitcher/main/docs/img/header.webp)

[![PyPI](https://img.shields.io/pypi/v/mcd_stitcher?label=PyPI&color=3fb950&style=flat-square)](https://pypi.org/project/mcd_stitcher/)
[![Python](https://img.shields.io/badge/Python-3.9%20%E2%80%93%203.13-blue?style=flat-square)](https://www.python.org/downloads/)
[![Docs](https://img.shields.io/badge/Docs-guides%20%26%20API-8957e5?style=flat-square)](https://pawanchaurasia.github.io/mcd_stitcher/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](https://github.com/PawanChaurasia/mcd_stitcher/blob/main/LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.64898%2F2026.06.26.732348-B31B1B?style=flat-square)](https://doi.org/10.64898/2026.06.26.732348)

Reads Standard BioTools `.mcd` files and writes OME-TIFFs for [QuPath](https://qupath.github.io/), [Napari](https://napari.org/) and [Fiji](https://fiji.sc/) — from a desktop app, the command line or Python.

- **Convert** — each region (ROI) becomes its own multi-channel OME-TIFF.
- **Stitch** — all regions onto one canvas, placed by recorded stage coordinates.
- **Post-process** — channel subsets, pyramidal copies, re-compression.

## 🚀 Quick start

Requires **Python 3.9+**. Runs on Windows, macOS and Linux.

```bash
pip install mcd_stitcher
```

Then open the desktop app:

```bash
mcd_gui
```

![The MCD Stitcher desktop app, with a file loaded and ready to run](https://raw.githubusercontent.com/PawanChaurasia/mcd_stitcher/main/docs/img/gui.webp)

Choose a `.mcd` file — or switch to **Batch** for a folder of them — tick the outputs you want and press **Run**. Everything lands in `MCD_Processed/<file name>/`, next to your input.

> 💡 **Tip** — tick **Pyramid** as well. It adds tiled, multi-resolution copies that let large stitched files pan and zoom smoothly, especially on low-RAM systems.

Prefer the command line or Python? The [command-line guide](https://pawanchaurasia.github.io/mcd_stitcher/command-line/) and the [Python API](https://pawanchaurasia.github.io/mcd_stitcher/python-api/) are in the documentation, along with tutorials and troubleshooting:

[![Read the documentation](https://img.shields.io/badge/Read%20the%20documentation-8957e5?style=for-the-badge)](https://pawanchaurasia.github.io/mcd_stitcher/)

---

## 🔬 How it works

![Ten per-region OME-TIFFs and the stitched canvas](https://raw.githubusercontent.com/PawanChaurasia/mcd_stitcher/main/docs/img/regions-to-canvas.webp)

<sub>Left: Ten regions from one <code>.mcd</code> file, shown to common scale. Right: the same ten placed on a single 7.0 × 4.6 mm canvas at 0.5 µm/px.</sub>

1. **Read** — each region comes straight out of the `.mcd` file with its channels, pixel size and stage position.
2. **Convert** — every region is written to its own OME-TIFF, channel names included.
3. **Stitch** — the regions are placed on one canvas at their recorded stage positions: no registration, no seam blending. Regions acquired at different step sizes are resampled onto the finest common grid, and where regions overlap the earliest acquisition stays on top.
4. **Post-process** — optional channel subsets and pyramidal copies, made from the files above.

Large slides are processed in pieces sized to the memory available, so the same run works on a laptop and on a cluster node.

## ⚡ Commands

| Command | What it does |
| --- | --- |
| `mcd_gui` | The desktop app, for one file or a batch. |
| `mcd_process` | Everything in one command: convert, stitch, panoramas and post-processing. |
| `mcd_convert`, `mcd_stitch` | One step each. |
| `tiff_subset` | Channel subsets and pyramids from existing OME-TIFFs. |

```bash
mcd_process "file.mcd" -m                     # inspect: regions, panoramas, channel indices
mcd_process "folder/" --convert --stitch      # every .mcd in a folder, both outputs
mcd_process "file.mcd" --stitch -r "0-3"      # stitch only regions 0–3 (indices from -m)
mcd_process "file.mcd" --convert -f "0-5,7"   # plus copies with only these channels
```

> 📖 **Every option, the output layout and more examples** are in the [command-line guide](https://pawanchaurasia.github.io/mcd_stitcher/command-line/).

---

## 📄 Citation

If MCD Stitcher helps your work, please cite:

> Chaurasia, P. (2026). *MCD Stitcher: An open-source tool for whole-slide stitching and conversion of Imaging Mass Cytometry data.* bioRxiv. https://doi.org/10.64898/2026.06.26.732348

```bibtex
@article{chaurasia2026mcdstitcher,
  title   = {MCD Stitcher: An open-source tool for whole-slide stitching and conversion of Imaging Mass Cytometry data},
  author  = {Chaurasia, Pawan},
  journal = {bioRxiv},
  year    = {2026},
  doi     = {10.64898/2026.06.26.732348}
}
```

## 🐛 Issues and questions

Found a bug or have a question? Open an issue on the [issue tracker](https://github.com/PawanChaurasia/mcd_stitcher/issues). A log helps: tick *Save a log file* in the app, or paste the command's output.

## 📝 Changelog

Release notes are in [CHANGELOG.md](https://github.com/PawanChaurasia/mcd_stitcher/blob/main/CHANGELOG.md), and on the [documentation site](https://pawanchaurasia.github.io/mcd_stitcher/changelog/).

## 📜 License

MIT — see [LICENSE](https://github.com/PawanChaurasia/mcd_stitcher/blob/main/LICENSE).
