Refactor

.readthedocs.yml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    # Install only the docs toolchain. The SPINEPS package itself is intentionally NOT installed:
+    # its heavy runtime dependencies (torch, nnunetv2, antspyx, monai, ...) can exceed Read the Docs
+    # build time/memory limits. mkdocstrings' griffe backend reads the package source statically
+    # (see the `paths` option in mkdocs.yml), so those dependencies are not needed to render the docs.
+    post_install:
+      # ruff is only used by mkdocstrings to format rendered signatures (lightweight, no build deps).
+      - pip install "mkdocs>=1.6" "mkdocs-material>=9.5" "mkdocstrings[python]>=0.25" ruff
+
+mkdocs:
+  configuration: mkdocs.yml

README.md

@@ -5,6 +5,7 @@
 [![codecov](https://codecov.io/gh/Hendrik-code/spineps/graph/badge.svg?token=A7FWUKO9Y4)](https://codecov.io/gh/Hendrik-code/spineps)
 [![tests](https://github.com/Hendrik-code/spineps/actions/workflows/tests.yml/badge.svg)](https://github.com/Hendrik-code/spineps/actions/workflows/tests.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Documentation Status](https://readthedocs.org/projects/spineps/badge/?version=latest)](https://spineps.readthedocs.io)
 
 # SPINEPS – Automatic Whole Spine Segmentation of T2w MR images using a Two-Phase Approach to Multi-class Semantic and Instance Segmentation.
 # and
@@ -14,6 +15,20 @@ This is a segmentation pipeline to automatically, and robustly, segment the whol
 
 ![pipeline_process](spineps/example/figures/pipeline_processflow.png?raw=true)
 
+## Documentation
+
+📖 **Online documentation: [spineps.readthedocs.io](https://spineps.readthedocs.io)**
+
+The documentation source lives in the [`docs/`](docs/) folder and is built with [MkDocs](https://www.mkdocs.org/)
+(Material theme + [mkdocstrings](https://mkdocstrings.github.io/)). To build and preview it locally:
+
+```bash
+pip install mkdocs mkdocs-material "mkdocstrings[python]"
+mkdocs serve   # then open http://127.0.0.1:8000
+```
+
+Start with [`docs/index.md`](docs/index.md) and the [Getting Started](docs/getting-started.md) guide.
+
 ## Citation
 
 If you are using SPINEPS, please cite the following:

docs/api/architectures.md

@@ -0,0 +1,19 @@
+# Architectures
+
+Network architectures and the vertebra label definitions used by the models.
+
+## spineps.architectures.read_labels
+
+::: spineps.architectures.read_labels
+
+## spineps.architectures.pl_densenet
+
+::: spineps.architectures.pl_densenet
+
+## spineps.architectures.pl_unet
+
+::: spineps.architectures.pl_unet
+
+## spineps.architectures.unet3D
+
+::: spineps.architectures.unet3D

docs/api/enums.md

@@ -0,0 +1,11 @@
+# Enums & Config
+
+Enumerations and the inference-configuration model used throughout SPINEPS.
+
+## spineps.seg_enums
+
+::: spineps.seg_enums
+
+## spineps.utils.seg_modelconfig
+
+::: spineps.utils.seg_modelconfig

docs/api/models.md

@@ -0,0 +1,15 @@
+# Models
+
+Model discovery/loading and the segmentation/labeling model classes.
+
+## spineps.get_models
+
+::: spineps.get_models
+
+## spineps.seg_model
+
+::: spineps.seg_model
+
+## spineps.lab_model
+
+::: spineps.lab_model

docs/api/phases.md

@@ -0,0 +1,23 @@
+# Processing Phases
+
+The per-phase processing functions that make up the pipeline.
+
+## spineps.phase_pre
+
+::: spineps.phase_pre
+
+## spineps.phase_semantic
+
+::: spineps.phase_semantic
+
+## spineps.phase_instance
+
+::: spineps.phase_instance
+
+## spineps.phase_labeling
+
+::: spineps.phase_labeling
+
+## spineps.phase_post
+
+::: spineps.phase_post

docs/api/pipeline.md

@@ -0,0 +1,15 @@
+# Pipeline & Run
+
+Top-level orchestration: process a single image or a whole dataset, and shared pipeline helpers.
+
+## spineps.seg_run
+
+::: spineps.seg_run
+
+## spineps.seg_pipeline
+
+::: spineps.seg_pipeline
+
+## spineps.seg_utils
+
+::: spineps.seg_utils

docs/api/utils.md

@@ -0,0 +1,31 @@
+# Utilities
+
+Image processing, the vertebra-labeling path solver, disc labeling and other helpers.
+
+## spineps.utils.proc_functions
+
+::: spineps.utils.proc_functions
+
+## spineps.utils.find_min_cost_path
+
+::: spineps.utils.find_min_cost_path
+
+## spineps.utils.generate_disc_labels
+
+::: spineps.utils.generate_disc_labels
+
+## spineps.utils.filepaths
+
+::: spineps.utils.filepaths
+
+## spineps.utils.auto_download
+
+::: spineps.utils.auto_download
+
+## spineps.utils.citation_reminder
+
+::: spineps.utils.citation_reminder
+
+## spineps.utils.compat
+
+::: spineps.utils.compat

docs/getting-started.md

@@ -0,0 +1,128 @@
+# Getting Started
+
+This guide walks you through installing SPINEPS and running your first segmentation.
+
+## Installation (Ubuntu)
+
+This installation assumes you are comfortable with conda and virtual environments. **The order of the
+following steps matters.**
+
+### 1. Create a virtual environment
+
+```bash
+conda create --name spineps python=3.11
+conda activate spineps
+conda install pip
+```
+
+### 2. Install PyTorch
+
+Go to [pytorch.org/get-started/locally](https://pytorch.org/get-started/locally/) and install a PyTorch
+build that matches your machine. Then confirm the install works:
+
+```bash
+nvidia-smi                                    # should show your GPU
+python -c "import torch; print(torch.cuda.is_available())"   # should print True
+```
+
+### 3. Install SPINEPS
+
+From PyPI:
+
+```bash
+pip install spineps
+```
+
+Or, for local development, clone the repository, `cd` into it and run:
+
+```bash
+pip install -e .
+```
+
+## Model weights
+
+SPINEPS automatically downloads the latest model weights on first use, so no manual setup is required.
+
+If you prefer to manage weights manually, download them from the GitHub release page and extract them into
+a models folder with the following structure:
+
+```text
+<models_folder>
+├── <model_name 1>
+│   ├── inference_config.json
+│   └── <other model-specific files>
+├── <model_name 2>
+│   ├── inference_config.json
+│   └── ...
+```
+
+Point SPINEPS at that folder via an environment variable (otherwise it defaults to `spineps/spineps/models/`):
+
+```bash
+export SPINEPS_SEGMENTOR_MODELS=<PATH-to-your-folder>
+echo ${SPINEPS_SEGMENTOR_MODELS}   # verify it is set
+```
+
+## Usage
+
+### Command line
+
+```bash
+spineps -h            # top-level help
+spineps sample -h     # options for a single file
+spineps dataset -h    # options for a whole dataset
+```
+
+Segment a single scan:
+
+```bash
+# T2w sagittal
+spineps sample -ignore_bids_filter -ignore_inference_compatibility \
+    -i /path/sub-testsample_T2w.nii.gz -model_semantic t2w -model_instance instance
+
+# T1w sagittal
+spineps sample -ignore_bids_filter -ignore_inference_compatibility \
+    -i /path/sub-testsample_T1w.nii.gz -model_semantic t1w -model_instance instance
+```
+
+Process a whole [BIDS](https://bids-specification.readthedocs.io/en/stable/) dataset:
+
+```bash
+spineps dataset -i /path/to/dataset -model_semantic t2w -model_instance instance
+```
+
+### Adding vertebra labels (VERIDAH)
+
+To assign anatomical vertebra labels after segmentation, additionally pass a labeling model:
+
+```bash
+spineps sample -i /path/sub-test_T2w.nii.gz \
+    -model_semantic t2w -model_instance instance -model_labeling labeling
+```
+
+### From Python
+
+```python
+from TPTBox import BIDS_FILE
+from spineps import get_semantic_model, get_instance_model, process_img_nii
+
+semantic = get_semantic_model("t2w")
+instance = get_instance_model("instance")
+
+# img_ref is a TPTBox BIDS_FILE pointing at the input scan
+img_ref = BIDS_FILE("sub-test_T2w.nii.gz", dataset="/path/to/dataset")
+
+process_img_nii(
+    img_ref,
+    model_semantic=semantic,
+    model_instance=instance,
+    derivative_name="derivatives_seg",
+)
+```
+
+See the [Pipeline](modules/pipeline.md) page for more detail on the Python entry points.
+
+## Troubleshooting
+
+- **Import issues**: re-run the install; sometimes not every dependency installs the first time.
+- **PyTorch / CUDA issues**: make sure the PyTorch build matches your CUDA version (step 2 above).

docs/index.md

@@ -0,0 +1,63 @@
+# SPINEPS
+
+**SPINEPS** is a framework for out-of-the-box **whole-spine segmentation of MR images**. It segments the
+spine in sagittal MR images (T2w, T1w and others) using a two-phase approach to multi-class **semantic**
+and **instance** segmentation, and can additionally assign anatomical **vertebra labels** via the
+**VERIDAH** labeling model.
+
+[![Paper](https://img.shields.io/badge/Paper-10.1007-blue)](https://link.springer.com/article/10.1007/s00330-024-11155-y)
+[![PyPI version](https://badge.fury.io/py/spineps.svg)](https://pypi.python.org/pypi/spineps/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+![Pipeline process flow](https://github.com/Hendrik-code/spineps/raw/main/spineps/example/figures/pipeline_processflow.png)
+
+## What it does
+
+Given a sagittal MR scan, the pipeline:
+
+1. **Semantically** segments 14 spinal structures (nine vertebra subregions, spinal cord, spinal canal,
+   intervertebral discs, endplate and sacrum).
+2. Derives a per-vertebra **instance** mask from the vertebra subregions.
+3. Optionally assigns each instance an anatomical **vertebra label** (C1–L6, sacrum) with VERIDAH.
+4. Computes **centroids** (points of interest) for each vertebra, endplate and disc.
+5. Renders a **snapshot** visualizing the result.
+
+## Quick links
+
+- [Getting Started](getting-started.md) — installation and first run.
+- [Pipeline](modules/pipeline.md) — how the two-phase pipeline is structured.
+- [Processing Phases](modules/phases.md) — pre-processing, semantic, instance, labeling and post-processing.
+- [Models & Labeling](modules/models.md) — model loading and the VERIDAH labeling model.
+- [API Reference](api/pipeline.md) — full auto-generated API documentation.
+
+## Quick start
+
+```bash
+# Install
+pip install spineps
+
+# Segment a single T2w sagittal scan
+spineps sample -i /path/sub-test_T2w.nii.gz -model_semantic t2w -model_instance instance
+```
+
+See [Getting Started](getting-started.md) for the full installation guide (including PyTorch setup and
+model weights), and the [Pipeline](modules/pipeline.md) page for calling SPINEPS from Python.
+
+## Citation
+
+If you use SPINEPS, please cite:
+
+```bibtex
+@article{moller_spinepsautomatic_2024,
+    title   = {{SPINEPS}—automatic whole spine segmentation of T2-weighted {MR} images using a two-phase approach to multi-class semantic and instance segmentation},
+    doi     = {10.1007/s00330-024-11155-y},
+    journal = {European Radiology},
+    author  = {Möller, Hendrik and Graf, Robert and Schmitt, Joachim and Keinert, Benjamin and Schön, Hanna and Atad, Matan and Sekuboyina, Anjany and Streckenbach, Felix and Kofler, Florian and Kroencke, Thomas and Bette, Stefanie and Willich, Stefan N. and Keil, Thomas and Niendorf, Thoralf and Pischon, Tobias and Endemann, Beate and Menze, Bjoern and Rueckert, Daniel and Kirschke, Jan S.},
+    date    = {2024-10-29},
+}
+```
+
+## License
+
+SPINEPS is released under the [Apache License 2.0](https://opensource.org/licenses/Apache-2.0).
+Copyright 2023 Hendrik Möller.