Metadata-Version: 2.4
Name: tomo-image-stitcher
Version: 0.2.0
Summary: GPU-accelerated 3D volumetric stitcher for tomographic and microscopy volumes.
Author: Endri Lacaj, Indrajeet Tambe
License: MIT License
        
        Copyright (c) Endri Lacaj, Indrajeet Tambe
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/indrajeettambe/TomoImageStitcher
Project-URL: Issues, https://github.com/indrajeettambe/TomoImageStitcher/issues
Project-URL: Documentation, https://github.com/indrajeettambe/TomoImageStitcher/tree/main/docs
Keywords: stitching,tomography,registration,GPU,CuPy,volume-stitching,3D
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.2
Requires-Dist: h5py>=3.8
Requires-Dist: tifffile>=2023.4
Requires-Dist: imagecodecs>=2023.1
Requires-Dist: SimpleITK>=2.3
Requires-Dist: scikit-image>=0.20
Requires-Dist: matplotlib>=3.7
Requires-Dist: tqdm>=4.65
Requires-Dist: cupy-cuda12x>=13.0; sys_platform != "darwin"
Provides-Extra: danmax
Requires-Dist: ipywidgets>=8.0; extra == "danmax"
Requires-Dist: pyFAI>=2023.1; extra == "danmax"
Requires-Dist: pytz>=2023.3; extra == "danmax"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0; extra == "notebook"
Requires-Dist: ipykernel>=6.0; extra == "notebook"
Requires-Dist: notebook>=7.0; extra == "notebook"
Provides-Extra: dev
Requires-Dist: pytest>=7.3; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Provides-Extra: all
Requires-Dist: tomo-image-stitcher[danmax,dev,notebook]; extra == "all"
Dynamic: license-file

# TomoImageStitcher

[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![CuPy](https://img.shields.io/badge/GPU-CuPy-76B900.svg)](https://cupy.dev/)

A GPU-accelerated, sub-pixel accurate **3D volumetric stitcher** for tomographic and
large-volume microscopy datasets. TomoImageStitcher registers overlapping 3D
sub-volumes acquired on a translation (and optionally rotation) stage and produces
a single seamless volume with mask-aware blending and optional intensity
equalisation.

> Originally developed for stitching local X-ray tomography volumes for the Experiment at the **DanMAX** beamline, Sweden.

For a **detailed step-by-step walkthrough** of every pipeline stage with synthetic
data, see [`notebooks/02_full_pipeline.ipynb`](notebooks/02_full_pipeline.ipynb).
For the mathematical details of the registration, see **[PUBLICATION]**.

---

## What is it

TomoImageStitcher stitches together a set of **overlapping 3D sub-volumes**
(typically reconstructed tomography volumes) into **one seamless volume**.
Each stage is a Python call on the `Stitcher` object, so you can inspect and
re-run any stage on its own.

The pipeline runs in **six stages**:

| # | Stage | What it does |
|---|-------|--------------|
| 1 | **Organise sub-volumes** | Classify into z-layers, compute global padding, find intersections. |
| 2 | **Registration** | ZNCC pixel search + IC-GN Lucas–Kanade refinement per pair. |
| 3 | **Accumulate displacements** | Chain per-pair shifts into a global warp graph (BFS). |
| 4 | **Equalisation** | Match intensities across overlaps via joint histograms. |
| 5 | **Blending** | Distance-map blending onto the global canvas, on the GPU. |
| 6 | **Save and inspect** | Write per-layer `.h5` files with full pipeline metadata. |

The full per-stage walk-through with the code for every step lives in the
**detailed notebook** linked above. The math behind the registration and
blending lives in [PUBLICATION].

---

## Where you can use it

- Stitching **3D X-ray tomography reconstructions** from a multi-tile
  translation scan.
- Stitching **raw projection volumes** (radiographs) before reconstruction.
- Stitching **3D microscopy datasets** (light-sheet, confocal) where individual
  tiles are too large to fit into memory.
- **Multi-scan** stitching where you have several scans with overlapping
  lateral extent.
- Stitching on a **rotation stage** (helical or tomographic) — see
  `notebooks/03_stitching_with_rotation.ipynb`.

---

## Install

TomoImageStitcher is on PyPI. A CUDA-capable GPU with the matching CuPy wheel
is required for the GPU stages; everything else is plain Python.

```bash
# 1. (Recommended) a clean environment
python -m venv .venv && source .venv/bin/activate

# 2. Install with the notebook extras
pip install -U pip
pip install "tomo-image-stitcher[notebook,danmax]"

# 3. Install CuPy matching your CUDA version (CUDA 12.x shown)
pip install cupy-cuda12x
```

If you cannot install `git`, or you are behind a proxy that blocks it:

```bash
pip install https://github.com/indrajeettambe/TomoImageStitcher/archive/main.zip
```

For full instructions (drivers, conda env, troubleshooting) see
[`docs/installation.md`](docs/installation.md).

---

## Quick start

A minimal end-to-end example on synthetic data. The full version with
explanations and intermediate visualisations is in
[`notebooks/02_full_pipeline.ipynb`](notebooks/02_full_pipeline.ipynb).

```python
import numpy as np
from tomo_image_stitcher import Stitcher

# 1. List of .h5 files and their motor positions in millimetres
file_paths    = ["scan_001.h5", "scan_002.h5", "scan_003.h5"]
motor_coords  = np.array([[ 0.0,  0.0,  0.0],
                          [ 0.8,  0.0,  0.0],
                          [ 1.6,  0.0,  0.0]])
mm_per_voxel  = 0.0022                       # 2.2 µm voxels

# 2. Initialise the stitcher
st = Stitcher(file_paths, motor_coords, mm_per_voxel,
              x_y_z_correspondance=(-1, 3, 2))

# 3. Run the six stages
st.get_layers_in_z(tolerance_mm=4)           # (1) Organise
st.get_padding()
st.get_intersections(check=True)
st.compute_shift_in_layers(downscale=4, downscale_stages=4,   # (2) Registration
                           downscale_LC=True, mask=True, mask_radius=300)
st.get_displacement_pyramid(check=False)
st.accumulate_displacement(exclude_NCC=50)   # (3) Accumulate
st.compose_final_displacements()
st.stitch_volumes_blend_equalize(...)        # (4) + (5) Equalise + Blend
st.stitch_layers(path_save="output/")        # (6) Save

# 4. Read the stitched volume
import h5py
with h5py.File("output/Stitched_layers/Layer_0.h5", "r") as f:
    volume = f["stitched_data/stitched_image"][:]
```

---

## Documentation

| Resource | Description |
|----------|-------------|
| [`notebooks/02_full_pipeline.ipynb`](notebooks/02_full_pipeline.ipynb) | **Detailed step-by-step walkthrough** of the full pipeline on synthetic data. Start here. |
| [`notebooks/01_quickstart.ipynb`](notebooks/01_quickstart.ipynb) | Minimal 5-line end-to-end example. |
| [`notebooks/03_stitching_with_rotation.ipynb`](notebooks/03_stitching_with_rotation.ipynb) | Original DanMAX rotation-stage example (update paths before running). |
| [`docs/architecture.md`](docs/architecture.md) | Data structures used between pipeline stages. |
| [`docs/api.md`](docs/api.md) | Public classes, methods, and parameters. |
| [`docs/quickstart.md`](docs/quickstart.md) | More copy-paste recipes. |
| [`docs/troubleshooting.md`](docs/troubleshooting.md) | Common errors and how to recover. |

The mathematical details of the registration (ZNCC, IC-GN Lucas–Kanade, mask
weighting) and blending (distance-map weighting) are described in
**[PUBLICATION]**.

---

## Project layout

```
TomoImageStitcher/
├── src/tomo_image_stitcher/    Package source (Stitcher, RegistrationKIT, …)
├── notebooks/                  Jupyter tutorials (start with 02_full_pipeline)
├── examples/                   Standalone Python scripts
├── tests/                      pytest test-suite
├── docs/                       Architecture, API, troubleshooting
├── pyproject.toml              Build & dependency metadata
├── LICENSE                     MIT
└── CITATION.cff                Software citation
```

---

## Citation

If you use TomoImageStitcher in your research, please cite it using the
metadata in [`CITATION.cff`](CITATION.cff). A publication describing the
algorithm is in preparation and will be linked here when available
([PUBLICATION]).

---

## License

MIT — see [`LICENSE`](LICENSE).

## Contributors

TomoImageStitcher was originally developed at the **DanMAX** beamline
(MAX IV Laboratory, Sweden). See the git log for the full list of
contributors.
