Metadata-Version: 2.4
Name: mcd_stitcher
Version: 2.4.0
Summary: A package for 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: 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: pandas>=2.3.3
Requires-Dist: pillow>=11.3.0
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: psutil>=5.9
Requires-Dist: readimc>=0.9.2
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/)
[![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/).

- **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
```

Convert each region to its own OME-TIFF:

```bash
mcd_process "path/to/file.mcd" --convert
```

Stitch all regions into a single image:

```bash
mcd_process "path/to/file.mcd" --stitch --pyramid
```

> 💡 **Tip** — `--pyramid` adds tiled, multi-resolution copies that let large stitched files pan and zoom smoothly, especially on low-RAM systems.

Everything lands in `MCD_Processed/<file name>/`, next to your input.

---

## 🔬 What it does

![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>

`--convert` writes each region to its own OME-TIFF and `--stitch` places them all on one canvas using the stage positions recorded in the file — no registration, no seam blending. Regions acquired at different step sizes are resampled onto the finest common grid.

<details>
<summary><b>Native resolution is preserved end to end</b></summary>

![Whole canvas beside a native-resolution crop](https://raw.githubusercontent.com/PawanChaurasia/mcd_stitcher/main/docs/img/canvas-and-detail.webp)

A 7.0 × 4.6 mm canvas at 0.5 µm/px still resolves single cells — stitching costs no detail. `--pyramid` adds the tiled copy that makes a canvas this size navigable.

</details>

## ⚡ Commands

```bash
mcd_process <input_path> [<output_path>] [OPTIONS]      # a .mcd file, or a folder of them
```

```bash
mcd_process "file.mcd" -m                     # inspect: regions, panoramas, channel indices
mcd_process "file.mcd" --convert              # one OME-TIFF per region
mcd_process "file.mcd" --stitch --pyramid     # one zoomable stitched canvas
mcd_process "folder/" --convert --stitch      # a whole batch, both outputs, single pass
```

<details>
<summary><b>🔧 All options, output layout and the Python API</b></summary>

| Option | What it does |
| --- | --- |
| `--convert` | One OME-TIFF per region. |
| `--stitch` | All regions onto one canvas. |
| `-p, --panorama` | Panorama overviews; large ones get region outlines. |
| `-m, --metadata` | Print regions, panoramas, indexed channels. Writes nothing. |
| `--roi_map IDX` | Region → panorama pixel map. Needs convert/stitch. |
| `-f, --filter "LIST"` | Keep only these channels, e.g. `"0-5,7"`. Indices from `-m`. |
| `--pyramid` | Also write a tiled, multi-resolution copy. |
| `-r, --roi "LIST"` | Only these regions, e.g. `"0-5,7"`. Indices from `-m`. |
| `-d, --output_type` | `uint16` (default) / `float32`. |
| `-c, --compression` | `zstd` (default) / `LZW` / `None`. |
| `--max-memory SIZE` | Cap memory for image buffers, e.g. `8G`. Detected automatically from the container/scheduler limit or free RAM; set this to override, or on a shared machine where you want a reproducible plan. Also read from `$MCD_STITCHER_MAX_MEM`. |

`-f` and `--pyramid` are post-processing steps and need `--convert` or `--stitch`.

```
MCD_Processed/<file name>/
├── <region>.ome.tiff                       --convert
├── <file name>_stitched.ome.tiff           --stitch
├── <file name>_slide_0_pano_0.png          -p        (+ _overlay.png)
└── <file name>_slide_0_pano_0_roi_map.txt  --roi_map
```

`mcd_convert`, `mcd_stitch` and `tiff_subset` each do one step; `tiff_subset` works on existing OME-TIFFs.

```python
from mcd_stitcher import mcd_process
mcd_process(input_path="file.mcd", convert=True, stitch=True)
```

</details>

---

## 📄 Citation

> 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

<details>
<summary>BibTeX</summary>

```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}
}
```

</details>

## 📜 License, issues & changelog

MIT — see [LICENSE](https://github.com/PawanChaurasia/mcd_stitcher/blob/main/LICENSE). Report problems on the [issue tracker](https://github.com/PawanChaurasia/mcd_stitcher/issues); release notes are in the [changelog](https://github.com/PawanChaurasia/mcd_stitcher/blob/main/CHANGELOG.md).
