Metadata-Version: 2.4
Name: ct-segmentation-toolkit
Version: 0.2.0
Summary: Supervised (U-Net), unsupervised (Otsu/k-means/GMM), and label-free spectral-spatial (SOM) segmentation of scientific image stacks.
Author-email: "Cameron B. Renteria" <crentb@uw.edu>
License: Apache-2.0
Project-URL: Homepage, https://github.com/crentb/ct-segmentation-toolkit
Project-URL: Issues, https://github.com/crentb/ct-segmentation-toolkit/issues
Keywords: image segmentation,computed tomography,U-Net,self-organizing map,unsupervised,feature extraction,hyperspectral,scientific imaging
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scikit-image>=0.21
Requires-Dist: tifffile>=2023.1
Requires-Dist: minisom>=2.3
Requires-Dist: tqdm>=4.65
Requires-Dist: Pillow>=9.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: torch>=2.0
Provides-Extra: viz
Requires-Dist: napari[all]>=0.4; extra == "viz"
Requires-Dist: pyvista>=0.43; extra == "viz"
Provides-Extra: mlops
Requires-Dist: mlflow>=2.0; extra == "mlops"
Provides-Extra: denoise
Requires-Dist: albumentations>=1.3; extra == "denoise"
Requires-Dist: PyYAML>=6.0; extra == "denoise"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff==0.14.10; extra == "dev"
Requires-Dist: black==26.3.1; extra == "dev"
Requires-Dist: mypy==1.17.1; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Dynamic: license-file

# ct-segmentation-toolkit

[![CI](https://github.com/crentb/ct-segmentation-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/crentb/ct-segmentation-toolkit/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.12-blue.svg)](pyproject.toml)

Segmentation of scientific image stacks (e.g., synchrotron CT) across the full
supervision spectrum, in one installable, tested package:

- **Supervised** — a U-Net (`ct_seg.model.UNetSegmentation`) with training + inference.
- **Unsupervised** — multi-Otsu, k-means, and GMM segmentation by intensity, with no
  training data needed.
- **Label-free spectral-spatial** — a Self-Organizing-Map segmenter that describes each
  pixel by multi-scale density, structure-tensor orientation/coherence, a Gabor filter
  bank, and local variance, then clusters the SOM nodes. The same spectral-spatial
  feature engineering transfers directly to **hyperspectral** cubes.
- **Self-supervised denoising** — a 2.5D **Noise2Inverse** denoiser (`ct_seg.denoise`): a
  no-skip U-Net trained from one noisy reconstruction (no clean reference), with a Laplacian
  Contrast Loss and edge-aware model selection. The author's own implementation of the N2I
  framework (upstream credit in [ct_seg/denoise/ACKNOWLEDGMENTS.md](ct_seg/denoise/ACKNOWLEDGMENTS.md)).

## Install

```bash
git clone https://github.com/crentb/ct-segmentation-toolkit.git
cd ct-segmentation-toolkit
python -m pip install -e ".[dev]"          # core + dev tools (pytest, ruff, black, mypy)
python -m pip install -e ".[viz]"          # optional: napari labeling + pyvista viewer
python -m pip install -e ".[mlops]"        # optional: MLflow experiment tracking
python -m pip install -e ".[denoise]"      # optional: N2I training (albumentations, PyYAML)
```

## Python API

```python
import numpy as np
from ct_seg import segment_kmeans, som_segment, UNetSegmentation

volume = np.random.rand(16, 256, 256).astype("float32")   # (slices, H, W) in [0, 1]

# Unsupervised intensity segmentation (no labels)
labels, info = segment_kmeans(volume, num_classes=4)

# Label-free spectral-spatial segmentation of a single slice
band_map = som_segment(volume[0], n_clusters=4)

# Supervised U-Net
model = UNetSegmentation(in_channels=1, num_classes=4)
```

## Command line

```bash
# Unsupervised (otsu | kmeans | gmm)
python -m ct_seg.segment --input /path/to/tiffs --method kmeans --num_classes 4 --save_overlay

# Train a U-Net, then segment with it
python -m ct_seg.train   --images /path/to/tiffs --masks /path/to/masks --num_classes 4
python -m ct_seg.segment --input /path/to/tiffs --method unet --model SegOutput/best_model.pth --num_classes 4
```

(Interactive `ct_seg.labeling` (napari) and `ct_seg.viewer` (napari/pyvista) require the
`[viz]` extra.)

## Experiment tracking & profiling

Training integrates optional **MLflow** logging (run parameters, per-epoch loss/mIoU,
and the best checkpoint). Install the extra and it logs automatically; without MLflow,
tracking is a harmless no-op and training is unaffected:

```bash
pip install -e ".[mlops]"
python -m ct_seg.train --images ... --masks ... --num_classes 4   # logs to ./mlruns
mlflow ui                                                          # browse runs
```

A reproducible **performance profile** (forward / train-step latency, throughput, and
peak GPU memory) is in [docs/PERF.md](docs/PERF.md):

```bash
python scripts/profile_unet.py --device cuda --sizes 256 512
```

## Testing

```bash
pytest -m "not slow"      # fast suite (what CI runs)
pytest                    # everything
```

## Status

The supervised, unsupervised, SOM, and **Noise2Inverse denoising** paths are functional and
tested. The denoiser (`ct_seg.denoise`) is the author's own implementation of the N2I
framework (upstream credit in `ct_seg/denoise/ACKNOWLEDGMENTS.md`). Related published work on deep-learning
segmentation and self-supervised denoising of synchrotron CT is available as a preprint:
https://ssrn.com/abstract=6805001

## Acknowledgments

`ct_seg.denoise` implements the Noise2Inverse framework (Hendriksen, Pelt & Batenburg,
*IEEE Transactions on Computational Imaging*, 2020; https://github.com/ahendriksen/noise2inverse).
See [ct_seg/denoise/ACKNOWLEDGMENTS.md](ct_seg/denoise/ACKNOWLEDGMENTS.md).

## License

Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
