Merge pull request #107 from Hendrik-code/coverage

Hendrik-code · web-flow · commit 1e24731ac776 · 2026-05-26T14:18:09.000-04:00
Coverage
diff --git a/README.md b/README.md
@@ -8,6 +8,7 @@
 [![Stable Version](https://img.shields.io/pypi/v/tptbox?label=stable)](https://pypi.python.org/pypi/tptbox/)
 [![tests](https://github.com/Hendrik-code/TPTBox/actions/workflows/tests.yml/badge.svg)](https://github.com/Hendrik-code/TPTBox/actions/workflows/tests.yml)
 [![codecov](https://codecov.io/gh/Hendrik-code/TPTBox/graph/badge.svg?token=A7FWUKO9Y4)](https://codecov.io/gh/Hendrik-code/TPTBox)
+[![Documentation](https://readthedocs.org/projects/tptbox/badge/?version=latest)](https://tptbox.readthedocs.io/en/latest/)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
 
@@ -22,6 +23,31 @@ It can find, filter, search any BIDS_Family and subjects, and has many functiona
 - Logging everything consistently
 - ...
 
+## Documentation
+
+Full API reference and usage guides are available at **https://tptbox.readthedocs.io**.
+
+The docs cover all sub-packages — `NII`, `POI`, `BIDS_FILE`, NumPy utilities,
+vertebra constants, spine analysis, registration, segmentation, mesh3D,
+stitching, and the logger — with hyperlinks back to the GitHub source.
+
+## Modules
+
+Each sub-package has its own README with API tables and examples:
+
+| Module | Description |
+|---|---|
+| [`core`](TPTBox/core/README.md) | `NII` (NIfTI I/O and transforms), `POI` (anatomical landmarks), BIDS dataset navigation, NumPy utilities, vertebra constants |
+| [`core/poi_fun`](TPTBox/core/poi_fun/README.md) | Internal POI computation strategies (surface points, corpus centers, disc points) |
+| [`spine`](TPTBox/spine/README.md) | Spine-specific tools: 2D snapshot generation and statistical measurements |
+| [`spine/snapshot2D`](TPTBox/spine/snapshot2D/README.md) | Modular 2D image generation — axial/sagittal/coronal slices, MIPs, segmentation overlays |
+| [`spine/spinestats`](TPTBox/spine/spinestats/README.md) | Clinical spine measurements: distances, angles, disc heights, IVD landmarks |
+| [`registration`](TPTBox/registration/README.md) | Rigid and deformable image registration via ANTs and DeepALI |
+| [`segmentation`](TPTBox/segmentation/README.md) | Integration with SPINEPS, VibeSeg/TotalVibeSeg, and nnU-Net pipelines |
+| [`mesh3D`](TPTBox/mesh3D/README.md) | 3D surface mesh generation and rendering from segmentation volumes |
+| [`stitching`](TPTBox/stitching/README.md) | Multi-station NIfTI stitching for whole-body or long-spine acquisitions |
+| [`logger`](TPTBox/logger/README.md) | Structured, consistent logging for medical image processing pipelines |
+
 ## Install the package
 ```bash
 conda create -n 3.10 python=3.10
@@ -93,7 +119,7 @@ Python function and script for arbitrary image stitching. [See Details](TPTBox/s
 
 ![Example of two lumbar vertebrae. The left example is derived from 1 mm isotropic CT, the right from sagittal MRI with a resolution of 3.3 mm in the left–right direction. Top row: Subregion of the vertebra used for analysis. Middle row: Extreme points. Bottom row: Corpus edge and ligamentum flavum points.](TPTBox/images/poi_preview.png)
 For our Spine segmentation pipline follow the installation of [SPINEPS](https://github.com/Hendrik-code/spineps).
-Image Source: Rule-based Key-Point Extraction for MR-Guided Biomechanical Digital Twins of the Spine; 
+Image Source: Rule-based Key-Point Extraction for MR-Guided Biomechanical Digital Twins of the Spine;
 
 
 
@@ -252,4 +278,4 @@ TBD
 
 > [!IMPORTANT]
 > Importantly
--->
+-->
diff --git a/docs/modules/core.md b/docs/modules/core.md
@@ -0,0 +1 @@
+--8<-- "TPTBox/core/README.md"
diff --git a/docs/modules/logger.md b/docs/modules/logger.md
@@ -0,0 +1 @@
+--8<-- "TPTBox/logger/README.md"
diff --git a/docs/modules/mesh3d.md b/docs/modules/mesh3d.md
@@ -0,0 +1 @@
+--8<-- "TPTBox/mesh3D/README.md"
diff --git a/docs/modules/poi_fun.md b/docs/modules/poi_fun.md
@@ -0,0 +1 @@
+--8<-- "TPTBox/core/poi_fun/README.md"
diff --git a/docs/modules/registration.md b/docs/modules/registration.md
@@ -0,0 +1 @@
+--8<-- "TPTBox/registration/README.md"
diff --git a/docs/modules/segmentation.md b/docs/modules/segmentation.md
@@ -0,0 +1 @@
+--8<-- "TPTBox/segmentation/README.md"
diff --git a/docs/modules/snapshot2d.md b/docs/modules/snapshot2d.md
@@ -0,0 +1 @@
+--8<-- "TPTBox/spine/snapshot2D/README.md"
diff --git a/docs/modules/spine.md b/docs/modules/spine.md
@@ -0,0 +1,27 @@
+# Spine (`TPTBox.spine`)
+
+Spine-specific utilities built on top of the core `NII` and `POI` abstractions.
+Contains two sub-modules: 2D snapshot generation and statistical spine measurements.
+
+## Sub-modules
+
+| Sub-module | Description |
+|---|---|
+| [`snapshot2D/`](snapshot2d.md) | Modular 2D image snapshot generation (slices, MIPs, overlays) |
+| [`spinestats/`](spinestats.md) | Clinical measurements: distances, Cobb angles, IVD POIs, endplates |
+
+## Quick Example
+
+```python
+from TPTBox import NII, calc_centroids
+from TPTBox.spine.snapshot2D.snapshot_modular import Snapshot_Frame, create_snapshot
+
+ct = NII.load("ct.nii.gz", seg=False)
+seg = NII.load("seg.nii.gz", seg=True)
+
+# Generate a 2D sagittal snapshot with a segmentation overlay
+create_snapshot(
+    [Snapshot_Frame(image=ct, segmentation=seg, mode="CT")],
+    to="snapshot.png",
+)
+```
diff --git a/docs/modules/spinestats.md b/docs/modules/spinestats.md
@@ -0,0 +1 @@
+--8<-- "TPTBox/spine/spinestats/README.md"
diff --git a/docs/modules/stitching.md b/docs/modules/stitching.md
@@ -0,0 +1,90 @@
+# Stitching (`TPTBox.stitching`)
+
+Merges multiple NIfTI images that are already aligned in global space into a single volume.
+Useful for whole-body or long-spine multi-station acquisitions.
+You can verify alignment by opening the images in ITKSnap with "open additional image."
+
+## API
+
+| Function | Description |
+|---|---|
+| `stitching(nii_list, out, ...)` | Stitch a list of `NII` objects; returns `(result_nii, ramp_nii)` |
+| `stitching_raw(paths, out, ...)` | Stitch from file paths directly |
+| `GNC_stitch_T2w(nii_list, ...)` | GNC-based stitching optimised for T2w spine MRI |
+
+![Example of a stitching](https://raw.githubusercontent.com/Hendrik-code/TPTBox/main/TPTBox/stitching/stitching.jpg "Example of a stitching")
+
+
+### Standalone
+This script can be run directly from the console. Copy 'stitching.py' and install the necessary package.
+
+```
+stitching.py
+[-h] print the help message
+[-i IMAGES [IMAGES ...]] a list of input image paths
+[-o OUTPUT] The output image path
+[-v] verbose - if set, there will be more printouts.
+[-min_value MIN_VALUE] New pixels not present will get this value. Recommended 0 for MRI and for CT -1024 or the known min-value.
+[-seg] This flag is required if you merge segmentation Niftis.
+Switches:
+[-no_bias] If set: Do not use n4_bias_field_correction. It speeds up the process, but n4_bias_field_correction helps in roughly aligning the histogram.
+[-bias_crop] crop empty spaces by the bias field mask.
+[-crop] crop empty space away
+[-sr] Store the ramp and stitching of the images in a 4d nii.gz
+Optional:
+[-hists] Use histogram matching to put the images in the roughly same histogram. The previous image is used when hist_n is not set.
+[-hist_n HISTOGRAM_NAME] path to an image that should be used for histogram matching
+[-ramp_e RAMP_EDGE_MIN_VALUE] The ramp is only considering values above this minimum value
+[-ms MIN_SPACING] Set the minimum Spacing (in mm)
+[-dtype DTYPE] Force a dtype
+```
+
+Example:
+
+Given the image a.nii.gz,b.nii.gz,c.nii.gz and the segmentations a_msk.nii.gz,b_msk.nii.gz,c_msk.nii.gz. The images can be merged with:
+
+```bash
+stitching.py  -i a.nii.gz b.nii.gz c.nii.gz -o out.nii.gz
+stitching.py  -i a_msk.nii.gz b_msk.nii.gz c_msk.nii.gz -o out_msk.nii.gz -seg
+```
+
+### Install as a package
+
+Install on Python 3.10 or higher
+```bash
+pip install TPTBox
+```
+
+```python
+from TPTBox import NII
+from TPTBox.stitching import stitching
+out_nii,_ = stitching([NII.load("a.nii.gz",seg=False), NII.load("b.nii.gz",seg=False), NII.load("c.nii.gz",seg=False)], out="out.nii.gz")
+
+```
+
+or
+
+
+```python
+from TPTBox.stitching import stitching_raw
+stitching_raw(["a.nii.gz", "b.nii.gz", "c.nii.gz"], "out.nii.gz", is_segmentation=False)
+```
+
+
+### Cite
+```
+Graf, R., Platzek, PS., Riedel, E.O. et al. Generating synthetic high-resolution spinal STIR and T1w images from T2w FSE and low-resolution axial Dixon. Eur Radiol (2024). https://doi.org/10.1007/s00330-024-11047-1
+
+```
+
+```
+@article{graf2024generating,
+  title={Generating synthetic high-resolution spinal STIR and T1w images from T2w FSE and low-resolution axial Dixon},
+  author={Graf, Robert and Platzek, Paul-S{\"o}ren and Riedel, Evamaria Olga and Kim, Su Hwan and Lenhart, Nicolas and Ramsch{\"u}tz, Constanze and Paprottka, Karolin Johanna and Kertels, Olivia Ruriko and M{\"o}ller, Hendrik Kristian and Atad, Matan and others},
+  journal={European Radiology},
+  pages={1--11},
+  year={2024},
+  publisher={Springer}
+}
+
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -53,7 +53,8 @@ markdown_extensions:
   - pymdownx.highlight:
       anchor_linenums: true
   - pymdownx.inlinehilite
-  - pymdownx.snippets
+  - pymdownx.snippets:
+      base_path: ["."]
   - attr_list
   - md_in_html
   - toc:
@@ -62,6 +63,17 @@ markdown_extensions:
 nav:
   - Home: index.md
   - Getting Started: getting-started.md
+  - Modules:
+      - Core: modules/core.md
+      - POI Strategies: modules/poi_fun.md
+      - Spine: modules/spine.md
+      - "Spine – 2D Snapshots": modules/snapshot2d.md
+      - "Spine – Statistics": modules/spinestats.md
+      - Registration: modules/registration.md
+      - Segmentation: modules/segmentation.md
+      - Mesh 3D: modules/mesh3d.md
+      - Stitching: modules/stitching.md
+      - Logger: modules/logger.md
   - API Reference:
       - Core:
           - NII (NIfTI wrapper): api/nii.md
diff --git a/unit_tests/test_nii_extended.py b/unit_tests/test_nii_extended.py
diff --git a/unit_tests/test_nputils_extended.py b/unit_tests/test_nputils_extended.py
diff --git a/unit_tests/test_poi_ops.py b/unit_tests/test_poi_ops.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+--8<-- "TPTBox/spine/snapshot2D/README.md"`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+--8<-- "TPTBox/spine/spinestats/README.md"`