diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..83af2c3
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,25 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package and docs dependencies
+        run: |
+          pip install -e .
+          pip install mkdocs mkdocs-material "mkdocstrings[python]" mkdocs-gen-files mkdocs-literate-nav
+
+      - name: Build docs
+        run: mkdocs build
diff --git a/.readthedocs.yml b/.readthedocs.yml
new file mode 100644
index 0000000..4995b0d
--- /dev/null
+++ b/.readthedocs.yml
@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_install:
+      - pip install "mkdocs>=1.6" "mkdocs-material>=9.5" "mkdocstrings[python]>=0.25"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..87c77ae
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,95 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+TPTBox is a Python package for processing BIDS-compliant medical imaging datasets (CT, MRI), with a focus on torso/spine analysis. It provides NIfTI I/O, reorientation/resampling, Points of Interest (POI) computation for vertebrae, 2D/3D snapshots, registration, and segmentation integrations (SPINEPS, nnU-Net).
+
+## Commands
+
+### Installation
+```bash
+pip install poetry
+poetry install --with dev
+```
+
+### Running Tests
+```bash
+# All tests
+pytest unit_tests/
+
+# Single test file
+pytest unit_tests/test_nii.py
+
+# Single test function
+pytest unit_tests/test_nii.py::test_function_name
+
+# With coverage
+coverage run --source=TPTBox -m pytest unit_tests/
+```
+
+### Linting & Formatting
+```bash
+# Lint (auto-fix where possible)
+ruff check . --fix
+
+# Format
+ruff format .
+
+# Both (mirrors pre-commit behavior)
+pre-commit run --all-files
+```
+
+### CI Linting (as run in GitHub Actions)
+```bash
+flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+```
+
+## Architecture
+
+### Core Abstractions
+
+**`NII`** (`TPTBox/core/nii_wrapper.py`) — Central class wrapping nibabel NIfTI images. Handles reorientation, resampling, affine transforms, boolean masking, and mathematical operations. Nearly all image operations in the package go through `NII`. Math operations live in `nii_wrapper_math.py` as mixins.
+
+**`POI`** (`TPTBox/core/poi.py`) — Points of Interest container mapping `(vertebra_id, subregion_id) → 3D coordinate`. Coordinates can be in voxel or world space. POI computation strategies live in `TPTBox/core/poi_fun/`.
+
+**`BIDS_FILE` / `BIDS_Global_info`** (`TPTBox/core/bids_files.py`) — BIDS dataset navigator. `BIDS_Global_info` scans a dataset root, while `BIDS_FILE` represents a single file parsed according to BIDS naming entities. Constants for BIDS key/value vocabulary are in `bids_constants.py`.
+
+**`Location` / `Vertebra_Instance`** (`TPTBox/core/vert_constants.py`) — Enum-like constants for vertebral anatomy (vertebra IDs, subregion labels). Used as keys into `POI` objects throughout the codebase.
+
+### Package Layout
+
+```
+TPTBox/
+├── core/           # NII, POI, BIDS parsing, numpy utilities, vertebra constants
+│   └── poi_fun/    # POI calculation strategies and serialization
+├── spine/          # Spine-specific: 2D snapshots, statistics (distances, angles)
+├── segmentation/   # SPINEPS integration, nnU-Net inference, defacing
+├── registration/   # ANTs rigid/deformable, DeepALI deep learning registration
+├── mesh3D/         # 3D mesh generation and rendering from segmentations
+├── stitching/      # Multi-station image stitching
+└── logger/         # Logging infrastructure (Logger, Print_Logger, No_Logger)
+```
+
+Public API is re-exported from `TPTBox/__init__.py`. All major classes and utility functions are importable directly from `TPTBox`.
+
+### Key Relationships
+
+- `NII` + `POI` are used together constantly: compute POIs from segmentation `NII`s, then use POIs to guide further processing.
+- `BIDS_Global_info` iterates subjects/sessions; each subject has a `Subject_Container` with `BIDS_FILE` entries; `BIDS_FILE.get_nii()` returns a `NII`.
+- `vert_constants.py` defines the shared label space (`Location` enum) that ties segmentation labels to POI keys to snapshot rendering.
+- External tool integrations (SPINEPS, nnU-Net, ANTs, DeepALI) are optional; their imports are guarded so the core works without them.
+
+### Test Layout
+
+Tests live in `unit_tests/` (not `TPTBox/tests/`). `TPTBox/tests/` contains test utilities and sample data (CT/MRI NIfTIs) used by the unit tests. Some generated test files are very large (>20K LOC) — they are autogenerated and should not be edited by hand.
+
+## Code Style
+
+- **Line length**: 140 characters
+- **Formatter**: Ruff (Black-compatible, double quotes)
+- **Target Python**: 3.10+ syntax, but the package supports 3.9–3.14
+- **Naming**: Ruff N-rules are largely ignored — mixed-case class/method names are acceptable in this codebase (medical domain conventions)
+- **Complexity**: McCabe max=20; research code legitimately has deep branching
+- `from __future__ import annotations` is used widely for forward references
diff --git a/TPTBox/core/README.md b/TPTBox/core/README.md
new file mode 100644
index 0000000..9c2887f
--- /dev/null
+++ b/TPTBox/core/README.md
@@ -0,0 +1,97 @@
+# TPTBox Core
+
+The `core` subpackage is the foundation of TPTBox. It provides the three primary abstractions —
+`NII`, `POI`, and `BIDS_FILE` — along with helper utilities for array operations and anatomical constants.
+
+## Key Classes and Functions
+
+### `nii_wrapper.py` — NIfTI image wrapper
+
+| Symbol | Description |
+|---|---|
+| `NII` | Wraps `nibabel.Nifti1Image`; the central image type throughout TPTBox |
+| `NII.load(path, seg)` | Load a NIfTI file from disk (classmethod) |
+| `NII.from_numpy(arr, affine, seg)` | Construct from a numpy array and affine matrix |
+| `NII.reorient(axcodes_to)` | Reorient to a canonical axis code (e.g. `("R","A","S")`) |
+| `NII.rescale(voxel_spacing)` | Resample to new voxel spacing in mm |
+| `NII.resample_from_to(other)` | Resample to match the grid of another `NII` |
+| `NII.apply_mask(mask)` | Zero-out voxels outside a binary/label mask |
+| `NII.map_labels(label_map)` | Remap integer labels |
+| `NII.save(path)` | Save to disk as `.nii` or `.nii.gz` |
+| `NII.get_array()` | Return a copy of the underlying numpy array |
+| `NII.get_seg_array()` | Same as `get_array()` but asserts `seg=True` |
+| `Image_Reference` | Type alias: `BIDS_FILE | Nifti1Image | Path | str | NII` |
+
+### `bids_files.py` — BIDS dataset navigation
+
+| Symbol | Description |
+|---|---|
+| `BIDS_Global_info` | Scans a dataset root and indexes all BIDS files |
+| `BIDS_Global_info.enumerate_subjects()` | Iterate over subjects as `(subject_id, Subject_Container)` |
+| `Subject_Container` | Per-subject file index; entry point for queries |
+| `Subject_Container.new_query()` | Returns a `Searchquery` for this subject |
+| `BIDS_FILE` | One file parsed into BIDS entities (sub, ses, format, …) |
+| `BIDS_FILE.open_nii()` | Load this file's NIfTI |
+| `BIDS_FILE.get_changed_path(...)` | Derive a new path with changed BIDS entities |
+| `Searchquery` | Fluent query builder: `.filter()`, `.loop_dict()`, `.first()` |
+| `BIDS_Family` | `dict[str, list[BIDS_FILE]]` grouping files by format |
+
+### `poi.py` — Points of Interest
+
+| Symbol | Description |
+|---|---|
+| `POI` | Maps `(vertebra_id, subregion_id) → (x, y, z)` |
+| `calc_centroids(seg_nii)` | Compute centroids for every label in a segmentation |
+| `calc_poi_from_subreg_vert(vert, subreg)` | Compute POIs from paired vertebra + subregion segmentations |
+| `POI.save(path)` | Serialise to JSON |
+| `POI.load(path)` | Deserialise from JSON |
+| `POI.to_global(ref)` | Convert from voxel to world (mm) coordinates |
+| `POI.to_local(ref)` | Convert from world to voxel coordinates |
+
+### `np_utils.py` — NumPy utilities
+
+| Symbol | Description |
+|---|---|
+| `np_extract_label(arr, label)` | Extract a single label as a binary mask |
+| `np_center_of_mass(arr)` | Per-label centre-of-mass |
+| `np_volume(arr)` | Per-label voxel count |
+| `np_bbox_binary(mask)` | Bounding-box slice tuple for a binary array |
+| `np_dilate_msk(arr, mm, zoom)` | Morphological dilation by `mm` millimetres |
+| `np_erode_msk(arr, mm, zoom)` | Morphological erosion |
+| `np_fill_holes(arr)` | Fill holes per label |
+| `np_connected_components(arr)` | Label connected components |
+| `np_map_labels(arr, label_map)` | Remap label integers via a dict |
+| `np_unique(arr)` | Unique values (faster than `np.unique` for uint arrays) |
+
+### `vert_constants.py` — Anatomical constants
+
+| Symbol | Description |
+|---|---|
+| `Location` | `IntEnum` of anatomical subregion IDs (used as POI keys) |
+| `Vertebra_Instance` | Maps integer IDs → anatomical names (C1–S1) |
+| `v_name2idx` | Dict: `"L1" → 20`, etc. |
+| `v_idx2name` | Dict: `20 → "L1"`, etc. |
+| `v_idx_order` | Canonical sort order for vertebra IDs |
+| `ZOOMS` | Type alias: `tuple[float, float, float]` |
+| `AX_CODES` | Type alias: `tuple[str, str, str]` |
+| `AFFINE` | Type alias: `np.ndarray` (4×4) |
+
+## Quick Example
+
+```python
+from TPTBox import NII, BIDS_Global_info, calc_centroids
+
+# Load and resample a CT
+ct = NII.load("sub-001_ct.nii.gz", seg=False)
+ct_ras = ct.reorient(("R", "A", "S")).rescale((1.0, 1.0, 1.0))
+
+# Compute centroids from a segmentation
+seg = NII.load("sub-001_seg.nii.gz", seg=True)
+poi = calc_centroids(seg)
+print(poi)
+
+# Scan a BIDS dataset
+bids = BIDS_Global_info(["dataset/"], parents=["rawdata"])
+for subj, container in bids.enumerate_subjects():
+    t2 = container.new_query().filter("format", "T2w").first()
+```
diff --git a/TPTBox/core/bids_constants.py b/TPTBox/core/bids_constants.py
index 6519282..d534de3 100755
--- a/TPTBox/core/bids_constants.py
+++ b/TPTBox/core/bids_constants.py
@@ -311,6 +311,7 @@
     "Hemisphere": "hemi",  # [L,R]
     "Sample": "sample",  # such as tissue, primary cell or cell-free sample.
     # Sub recordings - Use when necessary.
+    "Split": "split",  # Never use, legacy. Is applied inconsistently by other datasets.
     ## Contrast
     "Contrast enhancement phase": "ce",
     "Tracer": "trc",  # use ce before this one.
@@ -340,7 +341,6 @@
     # Single class segmentation
     "Label": "label",
     # Others (never used)
-    "Split": "split",  # Never use, legacy. Is applied inconsistently by other datasets.
     "Density": "den",
     "version": "version",
     "Description": "desc",
diff --git a/TPTBox/core/bids_files.py b/TPTBox/core/bids_files.py
index d4daa34..4fdd4bf 100755
--- a/TPTBox/core/bids_files.py
+++ b/TPTBox/core/bids_files.py
@@ -8,11 +8,15 @@
 import typing
 from collections.abc import Sequence
 from pathlib import Path
+from typing import TYPE_CHECKING
 from warnings import warn
 
 import numpy as np
 
 import TPTBox
+
+if TYPE_CHECKING:
+    from TPTBox.core.nii_poi_abstract import Grid
 from TPTBox.core.bids_constants import (
     entities,
     entities_keys,
@@ -45,7 +49,19 @@
 # If the session level is omitted in the folder structure, the filename MUST begin with the string sub-<label>, without ses-<label>
 
 
-def validate_entities(key: str, value: str, name: str, verbose: bool):
+def validate_entities(key: str, value: str, name: str, verbose: bool) -> bool:
+    """Validate a BIDS key-value entity pair against the BIDS specification.
+
+    Args:
+        key: The BIDS entity key (e.g. ``"sub"``, ``"ses"``, ``"seg"``).
+        value: The value associated with the key.
+        name: The full filename, used for human-readable error messages.
+        verbose: If ``True``, print warnings for invalid entities.
+
+    Returns:
+        ``True`` when the entity is valid or ``verbose`` is ``False``;
+        ``False`` when a violation is detected.
+    """
     if not verbose:
         return True
     try:
@@ -105,7 +121,27 @@ def validate_entities(key: str, value: str, name: str, verbose: bool):
         return False
 
 
-def get_values_from_name(path: Path | str, verbose) -> tuple[str, dict[str, str], str, str]:
+def get_values_from_name(path: Path | str, verbose: bool) -> tuple[str, dict[str, str], str, str]:
+    """Parse a BIDS-formatted filename into its constituent components.
+
+    Splits a filename like ``sub-001_ses-01_T1w.nii.gz`` into the BIDS
+    format label, a key-value entity dictionary, the BIDS key stem, and
+    the file-type extension.
+
+    Args:
+        path: Path to (or plain name of) a BIDS file.
+        verbose: If ``True``, print warnings for non-conformant filenames.
+
+    Returns:
+        A 4-tuple ``(bids_format, info_dict, bids_key, file_type)`` where
+
+        * ``bids_format`` is the trailing label (e.g. ``"T1w"``),
+        * ``info_dict`` maps entity keys to values
+          (e.g. ``{"sub": "001", "ses": "01"}``),
+        * ``bids_key`` is the full stem without the extension
+          (e.g. ``"sub-001_ses-01_T1w"``),
+        * ``file_type`` is the extension (e.g. ``"nii.gz"``).
+    """
     name = Path(path).name
 
     bids_key, file_type = name.split(".", maxsplit=1)
@@ -146,9 +182,39 @@ def Buffered_BIDS_Global_info(
     file_name_manipulation: typing.Callable[[str], str] | None = None,
     sequence_splitting_keys: list[str] | None = None,
     filter_file: typing.Callable[[Path], bool] | None = None,
-    max_age_days=30,
-    recompute_parents=None,
-):
+    max_age_days: int = 30,
+    recompute_parents: list[str] | None = None,
+) -> BIDS_Global_info:
+    """Create a :class:`BIDS_Global_info` object backed by an on-disk file-path cache.
+
+    Scans each ``<dataset>/<parent>`` folder and serialises the discovered
+    file paths to a hidden pickle file (``.filepaths``) so that subsequent
+    calls can skip the directory walk.  The cache is automatically
+    invalidated when it is older than ``max_age_days`` days.
+
+    Args:
+        datasets: One or more dataset root directories (must contain a
+            ``dataset-`` prefix in their name per BIDS convention).
+        parents: Parent sub-folders to search inside each dataset, e.g.
+            ``["rawdata", "derivatives"]``.
+        additional_key: Extra BIDS entity keys beyond the official spec that
+            should not trigger validation warnings.
+        verbose: Print progress and cache-status messages.
+        file_name_manipulation: Optional callable applied to each filename
+            before BIDS parsing, e.g. to normalise non-conformant names.
+        sequence_splitting_keys: Keys used to group files into sequences
+            (families).  Defaults to the library-level constant when
+            ``None``.
+        filter_file: Optional predicate; if provided, only paths for which
+            the function returns ``True`` are included.
+        max_age_days: Number of days after which the on-disk cache is
+            considered stale and regenerated.  Defaults to ``30``.
+        recompute_parents: Parent names for which the cache should always be
+            rebuilt even if a valid cache exists.
+
+    Returns:
+        A fully initialised :class:`BIDS_Global_info` instance.
+    """
     import pickle
 
     if recompute_parents is None:
@@ -158,7 +224,8 @@ def Buffered_BIDS_Global_info(
         datasets = [datasets]
     files = {ds: [] for ds in datasets}
 
-    def save_buffer(f: Path, buffer_name):
+    def save_buffer(f: Path, buffer_name: str) -> list[Path]:
+        """Scan *f*, persist the discovered file list to a pickle cache, and return it."""
         global _cont  # noqa: PLW0603
         new_buffer = [Path(f.path) for f in _scan_tree(f, verbose=True) if Path(f.path).is_file()]
         try:
@@ -239,8 +306,8 @@ def save_buffer(f: Path, buffer_name):
 
 
 def _scan_tree(path, lvl=1, filter_folder=lambda _x, _y: True, verbose=False):
-    global _cont  # noqa: PLW0603
     """Recursively yield DirEntry objects for given directory."""
+    global _cont  # noqa: PLW0603
     for entry in os.scandir(path):
         if entry.is_dir(follow_symlinks=False):
             if filter_folder is not None and not filter_folder(Path(entry.path), lvl):
@@ -255,6 +322,8 @@ def _scan_tree(path, lvl=1, filter_folder=lambda _x, _y: True, verbose=False):
 
 
 class BIDS_Global_info:
+    """Global index of a BIDS dataset, mapping subjects to their files across multiple dataset roots."""
+
     def __init__(
         self,
         datasets: Sequence[Path | str] | Sequence[Path] | Sequence[str] | str | Path,
@@ -329,11 +398,32 @@ def __init__(
         self.entities_keys = entities_keys
 
     def search_folder(self, path: Path, ds, filter_folder) -> None:
+        """Recursively scan *path* and register every file found with the global info.
+
+        Args:
+            path: Directory to scan.
+            ds: Dataset root path associated with the scanned folder.
+            filter_folder: Callable ``(path, level) -> bool``; folders for
+                which this returns ``False`` are skipped.
+        """
         for entry in _scan_tree(path, filter_folder=filter_folder):
             if entry.is_file():
                 self.add_file_2_subject(Path(entry.path), ds)
 
-    def add_file_2_subject(self, bids: BIDS_FILE | Path, ds=None) -> None:
+    def add_file_2_subject(self, bids: BIDS_FILE | Path, ds: Path | str | None = None) -> None:
+        """Parse a file path (or pre-built :class:`BIDS_FILE`) and add it to the correct subject bucket.
+
+        Args:
+            bids: Either a raw filesystem path or an already-constructed
+                :class:`BIDS_FILE` instance.
+            ds: Dataset root path.  Required when *bids* is a plain
+                :class:`~pathlib.Path`; inferred automatically when *bids*
+                is a :class:`BIDS_FILE`.
+
+        Raises:
+            AssertionError: If *bids* is a :class:`~pathlib.Path` and *ds*
+                is ``None``.
+        """
         if isinstance(bids, Path) and "DS_Store" in bids.name:
             return
         if ds is None:
@@ -375,7 +465,18 @@ def add_file_2_subject(self, bids: BIDS_FILE | Path, ds=None) -> None:
         )
         self.subjects[subject].add(bids)
 
-    def enumerate_subjects(self, sort=False, shuffle=False) -> list[tuple[str, Subject_Container]]:
+    def enumerate_subjects(self, sort: bool = False, shuffle: bool = False) -> list[tuple[str, Subject_Container]]:
+        """Return all subject identifiers together with their :class:`Subject_Container`.
+
+        Args:
+            sort: If ``True``, return subjects sorted alphabetically by
+                subject ID.
+            shuffle: If ``True``, return subjects in a random order.
+                Mutually exclusive with *sort* (sort takes precedence).
+
+        Returns:
+            A list of ``(subject_id, Subject_Container)`` pairs.
+        """
         # TODO Enumerate should put out numbers...
         if sort:
             return sorted(self.subjects.items())
@@ -385,7 +486,16 @@ def enumerate_subjects(self, sort=False, shuffle=False) -> list[tuple[str, Subje
             return s
         return self.subjects.items()  # type: ignore
 
-    def iter_subjects(self, sort=False) -> list[tuple[str, Subject_Container]]:
+    def iter_subjects(self, sort: bool = False) -> list[tuple[str, Subject_Container]]:
+        """Iterate over all subjects (alias for :meth:`enumerate_subjects` without shuffle).
+
+        Args:
+            sort: If ``True``, return subjects sorted alphabetically by
+                subject ID.
+
+        Returns:
+            A list of ``(subject_id, Subject_Container)`` pairs.
+        """
         if sort:
             return sorted(self.subjects.items())
         return self.subjects.items()  # type: ignore
@@ -397,17 +507,32 @@ def __str__(self):
         return "BIDS_Global_info: parents=" + str(self.parents) + f"\nDatasets = {self.datasets}"
 
     @property
-    def _global_bids_list(self):
+    def _global_bids_list(self) -> dict:
+        """Internal mapping from BIDS key stem to :class:`BIDS_FILE` instances."""
         return self.__bids_list
 
 
 class Subject_Container:
+    """Container for all BIDS files belonging to a single subject, grouped by sequence."""
+
     def __init__(self, name, sequence_splitting_keys: list[str]) -> None:
         self.name = name
         self.sequences: dict[str, list[BIDS_FILE]] = {}
         self.sequence_splitting_keys = sequence_splitting_keys.copy()
 
-    def get_sequence_name(self, bids: BIDS_FILE):
+    def get_sequence_name(self, bids: BIDS_FILE) -> str:
+        """Derive the sequence-bucket key for a given BIDS file.
+
+        Combines the values of :attr:`sequence_splitting_keys` that are
+        present in *bids* into a single underscore-joined string.
+
+        Args:
+            bids: The file whose sequence name should be resolved.
+
+        Returns:
+            A string key identifying the sequence bucket, e.g.
+            ``"ses-01_sequ-303"``.
+        """
         key_values = []
         for key in self.sequence_splitting_keys:
             key_values.append(bids.info[key]) if key in bids.info else None
@@ -429,6 +554,14 @@ def get_sequence_name(self, bids: BIDS_FILE):
         return key + append_id
 
     def add(self, bids: BIDS_FILE) -> None:
+        """Register a BIDS file with this subject container.
+
+        Places *bids* into the correct sequence bucket (determined by
+        :meth:`get_sequence_name`) and sets the back-reference on the file.
+
+        Args:
+            bids: The BIDS file to add.
+        """
         sequ = self.get_sequence_name(bids)
         self.sequences.setdefault(sequ, [])
         if bids not in self.sequences[sequ]:
@@ -436,7 +569,7 @@ def add(self, bids: BIDS_FILE) -> None:
         bids.set_subject(self)
 
     def new_query(self, flatten=False) -> Searchquery:
-        """Make a new search_query
+        """Make a new search_query.
 
         Args:
             flatten (bool, optional): If you look for single file set flatten to True,
@@ -455,6 +588,7 @@ def get_sequence_files(
         alternative_sequ_list: list[BIDS_FILE] | None = None,
     ) -> BIDS_Family:
         """Returns a dictionary of all files the related sequence.
+
         Args:
                         sequ (str): key of the sequence
                         key_transform: function that maps BIDS_FILE to family key
@@ -466,7 +600,8 @@ def get_sequence_files(
             dict: The key is the 'format' word (ct, dixon, snp,...), except special naming keys are passed.
             Default naming keys: ["seg", "label"] (see sequence_naming_keys for the up-to-date list)
             All default naming keys as well as those passed in key_addendum are appended as key-value to the family-key.
-            Example:
+
+        Example:
             ses-123_msk.nii.gz will get key msk
             seg-subreg_msk.nii.gz will get the key msk_seg-subreg
             ses-123_T1c.nii.gz will get key T1c
@@ -500,6 +635,8 @@ def get_sequence_files(
 
 
 class BIDS_FILE:
+    """Representation of a single BIDS-compliant file with parsed entities and dataset context."""
+
     def __init__(
         self,
         file: Path | str,
@@ -508,8 +645,9 @@ def __init__(
         bids_ds: BIDS_Global_info | None = None,
         file_name_manipulation: typing.Callable[[str], str] | None = None,
     ):
-        """A multi-file representation. It holds the path to Bids-files with the same identifier (filename excluding the file type).
-        It can hold the reference to the nii.gz, json, etc at the same time.
+        """Multi-file BIDS record sharing the same identifier (all extensions of one file stem).
+
+        Holds references to `.nii.gz`, `.json`, etc. simultaneously.
 
         The following fields are imported and can be accessed.
         self.format (str): The last value determining its use/modalities like T1w, msk, dixon
@@ -548,7 +686,18 @@ def __init__(
                 self.file[file_type] = Path(file.parent, bids_key + "." + file_type)
         self.file = dict(sorted(self.file.items()))
 
-    def get_file(self, ending: str = "json", default=None):
+    def get_file(self, ending: str = "json", default: Path | None = None) -> Path | None:
+        """Return the path for a given file extension, or *default* if absent.
+
+        Args:
+            ending: File extension to look up, e.g. ``"json"`` or
+                ``"nii.gz"``.
+            default: Value returned when the extension is not present.
+
+        Returns:
+            The :class:`~pathlib.Path` for the requested extension, or
+            *default*.
+        """
         return self.file.get(ending, default)
 
     def __str__(self) -> str:
@@ -561,13 +710,24 @@ def __repr__(self):
     def __hash__(self) -> int:
         return self.BIDS_key.__hash__()
 
-    def exists(self):
+    def exists(self) -> bool:
+        """Return ``True`` when the primary file (preferring ``nii.gz``) exists on disk.
+
+        Returns:
+            ``True`` if the file exists, ``False`` otherwise.
+        """
         if "nii.gz" in self.file:
             return self.file["nii.gz"].exists()
         else:
             return self.file[next(iter(self.file.keys()))].exists()
 
-    def unlink(self, missing_ok=True):
+    def unlink(self, missing_ok: bool = True) -> None:
+        """Delete all files associated with this BIDS entry from disk.
+
+        Args:
+            missing_ok: If ``True``, suppress errors when a file does not
+                exist.  Passed directly to :meth:`pathlib.Path.unlink`.
+        """
         for f in self.file.values():
             f.unlink(missing_ok=missing_ok)
 
@@ -590,22 +750,60 @@ def __eq__(self, key):
         else:
             return False
 
-    def set_subject(self, sub: Subject_Container):
+    def set_subject(self, sub: Subject_Container) -> None:
+        """Attach a back-reference to the owning :class:`Subject_Container`.
+
+        Args:
+            sub: The subject container that owns this file.
+        """
         self.subject = sub
 
-    def set(self, key, value):
+    def set(self, key: str, value: str) -> None:
+        """Set a BIDS entity key-value pair on this file, validating the entity.
+
+        Args:
+            key: BIDS entity key (e.g. ``"seg"``).
+            value: Value to assign to the key.
+        """
         validate_entities(key, value, f"..._{key}-{value}_...", self.verbose)
         self.info[key] = value
 
-    def get(self, key, default=None):
+    def get(self, key: str, default: str | None = None) -> str | None:
+        """Return the value for a BIDS entity key, or *default* if not present.
+
+        Args:
+            key: BIDS entity key to look up (e.g. ``"sub"``, ``"ses"``).
+            default: Fallback value when *key* is absent.
+
+        Returns:
+            The entity value string, or *default*.
+        """
         if key in self.info:
             return self.info[key]
         return default
 
-    def loop_keys(self):
+    def loop_keys(self) -> typing.ItemsView[str, str]:
+        """Return all BIDS entity key-value pairs for this file.
+
+        Returns:
+            A view of ``(key, value)`` pairs from the :attr:`info` dictionary.
+        """
         return self.info.items()
 
-    def remove(self, key):
+    def remove(self, key: str) -> str:
+        """Remove and return a BIDS entity key from :attr:`info`.
+
+        Args:
+            key: Entity key to remove.  Must not be ``"sub"``.
+
+        Returns:
+            The value that was associated with *key*.
+
+        Raises:
+            AssertionError: If *key* is ``"sub"`` (subject ID cannot be
+                removed).
+            KeyError: If *key* is not present in :attr:`info`.
+        """
         assert key != "sub", "not allowed to remove subject name"
         return self.info.pop(key)
 
@@ -613,7 +811,22 @@ def add_file(
         self,
         path: Path,
         bids_ds: BIDS_Global_info | None = None,
-    ):
+    ) -> None:
+        """Associate an additional file extension with this BIDS entry.
+
+        Used to register companion files (e.g. a ``.json`` sidecar alongside
+        a ``nii.gz``) that share the same BIDS key stem.
+
+        Args:
+            path: Path to the companion file.  Its stem must match
+                :attr:`BIDS_key`.
+            bids_ds: If provided, the global registry is updated so that the
+                merged file dictionary is reflected there as well.
+
+        Raises:
+            AssertionError: If the stem of *path* does not match
+                :attr:`BIDS_key`.
+        """
         bids_key, file_type = Path(path).name.split(".", maxsplit=1)
 
         assert bids_key == self.BIDS_key, f"only aligned data aka same name different file type: {bids_key} != {self.BIDS_key}"
@@ -624,7 +837,21 @@ def add_file(
                 bids_ds._global_bids_list[bids_key].file = dict(sorted(bids_dic_file.items()))
         self.file = dict(sorted(bids_dic_file.items()))
 
-    def rename_files(self, path: Path | str, ending=".nii.gz"):
+    def rename_files(self, path: Path | str, ending: str = ".nii.gz") -> None:
+        """Rename all associated files on disk to a new base path.
+
+        The *ending* suffix is stripped from *path* to obtain the base stem,
+        then each extension in :attr:`file` is appended.
+
+        Args:
+            path: Target path including the primary extension (e.g.
+                ``/out/sub-001_T1w.nii.gz``).
+            ending: Extension that terminates *path* and that will be
+                stripped before adding per-extension suffixes.
+
+        Raises:
+            AssertionError: If *path* does not end with *ending*.
+        """
         path = str(path)
         assert path.endswith(ending), f"set 'ending' to the part after the '.'\n {path} does not end with {ending}"
         path = path.replace(ending, "")
@@ -632,7 +859,22 @@ def rename_files(self, path: Path | str, ending=".nii.gz"):
             p = Path(path + "." + key)
             value.rename(p)
 
-    def symlink_files(self, path: Path | str, ending=".nii.gz", exist_ok=False):
+    def symlink_files(self, path: Path | str, ending: str = ".nii.gz", exist_ok: bool = False) -> None:
+        """Create symbolic links for all associated files at a new base path.
+
+        Equivalent to :meth:`rename_files` but creates symlinks rather than
+        moving files.  Existing correct symlinks are silently skipped.
+
+        Args:
+            path: Target path including the primary extension (e.g.
+                ``/out/sub-001_T1w.nii.gz``).
+            ending: Extension used to compute the base stem; a leading dot is
+                added automatically if absent.
+
+        Raises:
+            AssertionError: If *path* does not end with *ending*, or if an
+                existing symlink at the target points elsewhere.
+        """
         ending = ending if ending[0] == "." else "." + ending
         path = str(path)
         assert path.endswith(ending), f"set 'ending' to the part after the '.'\n {path} does not end with {ending}"
@@ -648,7 +890,23 @@ def symlink_files(self, path: Path | str, ending=".nii.gz", exist_ok=False):
 
             os.symlink(value, p)
 
-    def get_path_decomposed(self, file_type=None) -> tuple[Path, str, str, str]:
+    def get_path_decomposed(self, file_type: str | None = None) -> tuple[Path, str, str, str]:
+        """Decompose the file path relative to the dataset root.
+
+        Args:
+            file_type: Extension key to use when selecting which path to
+                decompose (e.g. ``"nii.gz"``).  Defaults to the first
+                extension in :attr:`file`.
+
+        Returns:
+            A 4-tuple ``(dataset_path, parent, sub_path, filename)`` where
+
+            * ``dataset_path`` is the dataset root :class:`~pathlib.Path`,
+            * ``parent`` is the top-level folder (e.g. ``"rawdata"``),
+            * ``sub_path`` is the intermediate path (e.g.
+              ``"sub-001/ses-01"``),
+            * ``filename`` is the bare filename including extension.
+        """
         if file_type is None:
             file_type = next(iter(self.file.keys()))
         folder_list = str(self.file[file_type].relative_to(self.dataset)).replace("\\\\", "/").replace("\\", "/").split("/")
@@ -659,21 +917,38 @@ def get_path_decomposed(self, file_type=None) -> tuple[Path, str, str, str]:
         return self.dataset, parent, str.join("/", subpath), filename
 
     @property
-    def parent(self):
+    def parent(self) -> str:
+        """Top-level parent folder name (e.g. ``"rawdata"`` or ``"derivatives"``)."""
         return self.get_parent()
 
     @property
-    def bids_format(self):
+    def bids_format(self) -> str:
+        """Alias for :attr:`format`; the BIDS modality/format label (e.g. ``"T1w"``)."""
         return self.format
 
     @property
-    def mod(self):
+    def mod(self) -> str | None:
+        """Modality label, resolving ``"msk"`` to the underlying ``mod`` entity value.
+
+        Returns:
+            The ``mod`` entity value for mask files, or :attr:`bids_format`
+            for all other formats.
+        """
         mod = self.bids_format
         if mod == "msk":
             return self.get("mod")
         return mod
 
-    def get_parent(self, file_type=None):
+    def get_parent(self, file_type: str | None = None) -> str:
+        """Return the top-level parent folder name for this file.
+
+        Args:
+            file_type: Extension key used to select which path to inspect.
+                Defaults to the first extension in :attr:`file`.
+
+        Returns:
+            The parent folder name, e.g. ``"rawdata"`` or ``"derivatives"``.
+        """
         return self.get_path_decomposed(file_type)[1]
 
     def get_changed_bids(
@@ -683,13 +958,38 @@ def get_changed_bids(
         parent: str = "derivatives",
         path: str | None = None,
         info: dict | None = None,
-        from_info=False,
-        auto_add_run_id=False,
+        from_info: bool = False,
+        auto_add_run_id: bool = False,
         additional_folder: str | None = None,
         dataset_path: str | None = None,
-        make_parent=False,
-        non_strict_mode=False,
-    ):
+        make_parent: bool = False,
+        non_strict_mode: bool = False,
+    ) -> BIDS_FILE:
+        """Construct a new :class:`BIDS_FILE` pointing to a derived output path.
+
+        Delegates path construction to :meth:`get_changed_path` and wraps the
+        result in a :class:`BIDS_FILE` instance.
+
+        Args:
+            file_type: Target file extension (e.g. ``"nii.gz"``).
+            bids_format: Override the format/modality label.
+            parent: Target parent folder (e.g. ``"derivatives"``).
+            path: Override the intermediate sub-path; supports ``{key}``
+                template substitution.
+            info: Additional or overriding entity key-value pairs.
+            from_info: If ``True``, use the in-memory :attr:`info` dict
+                instead of the original filename entities.
+            auto_add_run_id: Append an auto-incremented ``run`` tag when the
+                target path already exists.
+            additional_folder: Extra folder appended between *path* and the
+                filename.
+            dataset_path: Override the dataset root.
+            make_parent: Create parent directories if they do not exist.
+            non_strict_mode: Relax BIDS entity validation.
+
+        Returns:
+            A new :class:`BIDS_FILE` pointing to the derived output.
+        """
         ds = dataset_path if dataset_path is not None else self.get_path_decomposed()[0]
         return BIDS_FILE(
             self.get_changed_path(
@@ -723,8 +1023,8 @@ def get_changed_path(  # noqa: C901
         no_sorting_mode: bool = False,
         non_strict_mode: bool = False,
     ) -> Path:
-        """
-        Changes part of the path to generate new flies. The new parent will be derivatives as a default.
+        """Changes part of the path to generate new flies. The new parent will be derivatives as a default.
+
         Examples:
         subreg_path = ct_bids.get_changed_path(file_type="nii.gz",parent = "derivatives",info={"seg": "subreg"}, format="cdt")
 
@@ -854,12 +1154,33 @@ def save_changed_path(
         parent: str = "derivatives",
         path: str | None = None,
         info: dict | None = None,
-        from_info=False,
-        auto_add_run_id=False,
+        from_info: bool = False,
+        auto_add_run_id: bool = False,
         additional_folder: str | None = None,
         dataset_path: str | None = None,
         non_strict_mode: bool = False,
     ) -> None:
+        """Copy all associated files to their derived output paths.
+
+        Calls :meth:`get_changed_path` for every extension in :attr:`file`
+        and copies each source file to the resulting destination using
+        :func:`shutil.copy2`.
+
+        Args:
+            bids_format: Override the format/modality label.
+            parent: Target parent folder (e.g. ``"derivatives"``).
+            path: Override the intermediate sub-path; supports ``{key}``
+                template substitution.
+            info: Additional or overriding entity key-value pairs.
+            from_info: If ``True``, use the in-memory :attr:`info` dict
+                instead of the original filename entities.
+            auto_add_run_id: Append an auto-incremented ``run`` tag when the
+                target path already exists.
+            additional_folder: Extra folder appended between *path* and the
+                filename.
+            dataset_path: Override the dataset root.
+            non_strict_mode: Relax BIDS entity validation.
+        """
         import shutil
 
         for key, value in self.file.items():
@@ -883,8 +1204,24 @@ def find_changed_path(
         bids_ds: BIDS_Global_info,
         bids_format: str | None = None,
         info: dict | None = None,
-        from_info=False,
+        from_info: bool = False,
     ) -> BIDS_FILE | None:
+        """Look up an already-registered derived file in the global BIDS index.
+
+        Constructs the expected BIDS key for the derived file (applying the
+        same entity overrides as :meth:`get_changed_path`) and returns the
+        matching :class:`BIDS_FILE` from *bids_ds* if it exists.
+
+        Args:
+            bids_ds: The global BIDS dataset to search.
+            bids_format: Override the format/modality label.
+            info: Additional or overriding entity key-value pairs.
+            from_info: If ``True``, use the in-memory :attr:`info` dict
+                instead of the original filename entities.
+
+        Returns:
+            The matching :class:`BIDS_FILE` if found, otherwise ``None``.
+        """
         if info is None:
             info = {}
 
@@ -908,10 +1245,21 @@ def find_changed_path(
         file_name += f"{bids_format if bids_format is not None else same_format}"
         return bids_ds._global_bids_list.get(file_name)
 
-    def insert_info_into_path(self, path):
-        """Helper function. Automatically replaces {key} with  values from the self.info dict in a string. Like:
-        f"sub-{sub}" --> "sub-patient001"
-        f"{sub}/ses-{ses}/sub-{sub}_ses-{ses}_label-heart_msk.nii.gz" --> "sub-patient001"
+    def insert_info_into_path(self, path: str | None) -> str | None:
+        """Replace ``{key}`` placeholders in *path* with entity values from :attr:`info`.
+
+        Example::
+
+            # With self.info = {"sub": "patient001", "ses": "01"}
+            bids.insert_info_into_path("sub-{sub}/ses-{ses}")
+            # -> "sub-patient001/ses-01"
+
+        Args:
+            path: Template string containing ``{key}`` placeholders, or
+                ``None``.
+
+        Returns:
+            The expanded string, or ``None`` when *path* is ``None``.
         """
         if path is None:
             return None
@@ -930,32 +1278,82 @@ def get_sequence_files(
         self,
         key_transform: typing.Callable[[BIDS_FILE], str | None] | None = None,
         key_addendum: list[str] | None = None,
-    ):
-        """
-        See Sequence.get_sequence_files()
-        The BIDS_file must be part of a Sequence-family. Usually automatically generated by tree generation of BIDS_Global_info
+    ) -> BIDS_Family:
+        """Return the :class:`BIDS_Family` that this file belongs to.
+
+        Delegates to :meth:`Subject_Container.get_sequence_files` using the
+        sequence name resolved from this file's entities.  The file must be
+        part of a subject sequence (i.e. registered via
+        :class:`BIDS_Global_info`).
+
+        Args:
+            key_transform: Optional callable mapping a :class:`BIDS_FILE` to
+                a custom family key string; return ``None`` to use the default
+                key.
+            key_addendum: Extra entity keys appended to the family key beyond
+                the default :attr:`sequence_naming_keys`.
 
         Returns:
-                dict:
-        """
+            The :class:`BIDS_Family` containing all related files for this
+            sequence.
 
+        Raises:
+            AssertionError: If this file has no owning
+                :class:`Subject_Container`.
+        """
         assert hasattr(self, "subject"), (
             "The BIDS_file must be part of a Sequence-family. Usually automatically generated by tree generation of BIDS_Global_info"
         )
         sequ = self.subject.get_sequence_name(self)
         return self.subject.get_sequence_files(sequ, key_transform=key_transform, key_addendum=key_addendum)
 
-    def open_nii_reorient(self, axcodes_to=("P", "I", "R"), verbose=False):
+    def open_nii_reorient(self, axcodes_to: tuple[str, ...] = ("P", "I", "R"), verbose: bool = False) -> TPTBox.NII:
+        """Open the NIfTI file and reorient it in-place to the target axis codes.
+
+        Args:
+            axcodes_to: Desired orientation as a tuple of axis code strings,
+                e.g. ``("P", "I", "R")``.
+            verbose: If ``True``, print reorientation details.
+
+        Returns:
+            The reoriented :class:`~TPTBox.NII` volume.
+        """
         return self.open_nii().reorient_(axcodes_to, verbose=verbose)
 
     def has_json(self) -> bool:
+        """Return ``True`` when a JSON sidecar is registered for this file."""
         return "json" in self.file
 
     def open_json(self) -> dict:
+        """Load and return the JSON sidecar as a dictionary.
+
+        Returns:
+            Parsed JSON contents.
+
+        Raises:
+            KeyError: If no JSON file is registered in :attr:`file`.
+        """
         with open(self.file["json"]) as f:
             return json.load(f)
 
-    def open_poi(self, nii: TPTBox.Image_Reference | None = None):
+    def open_poi(self, nii: TPTBox.Image_Reference | None = None) -> TPTBox.POI:
+        """Load the associated JSON file as a :class:`~TPTBox.POI` (point-of-interest) object.
+
+        If the POI lacks spatial metadata (zoom, shape, etc.) a reference
+        NIfTI image is required to fill in those fields.
+
+        Args:
+            nii: Optional image reference used to supply missing spatial
+                metadata.  Required when the JSON does not embed grid info.
+
+        Returns:
+            The loaded :class:`~TPTBox.POI` object with complete spatial
+            metadata.
+
+        Raises:
+            ValueError: If no JSON file is present or the POI lacks spatial
+                metadata and *nii* is ``None``.
+        """
         from TPTBox import POI
 
         try:
@@ -978,13 +1376,30 @@ def open_poi(self, nii: TPTBox.Image_Reference | None = None):
             raise ValueError(f"json not present. Found only {self.file.keys()}\t{self.file}\n\n{self}") from e
         return ctd
 
-    def open_ctd(self, nii: TPTBox.Image_Reference | None = None):
+    def open_ctd(self, nii: TPTBox.Image_Reference | None = None) -> TPTBox.POI:
+        """Alias for :meth:`open_poi`; load the centroid JSON as a :class:`~TPTBox.POI`.
+
+        Args:
+            nii: Optional image reference for missing spatial metadata.
+
+        Returns:
+            The loaded :class:`~TPTBox.POI` object.
+        """
         return self.open_poi(nii)
 
     def has_nii(self) -> bool:
+        """Return ``True`` when at least one supported NIfTI extension is registered."""
         return any(a in self.file for a in _supported_nii_files)
 
-    def open_nii(self):
+    def open_nii(self) -> TPTBox.NII:
+        """Load the NIfTI file into a :class:`~TPTBox.NII` object.
+
+        Returns:
+            The loaded :class:`~TPTBox.NII` volume.
+
+        Raises:
+            ValueError: If no NIfTI file (``nii.gz`` / ``nii``) is present.
+        """
         try:
             from TPTBox import NII
 
@@ -992,8 +1407,22 @@ def open_nii(self):
         except KeyError as e:
             raise ValueError(f"nii.gz not present. Found only {self.file.keys()}\t{self.file}\n\n{self}") from e
 
-    def get_grid_info(self, add_grid_info_to_json=True):
-        """returns the Grid info. It looks up if this info is in json. If not it loads the File, computes the Grid and saves it in the json"""
+    def get_grid_info(self, add_grid_info_to_json: bool = True) -> Grid | None:
+        """Return the spatial grid metadata for this file.
+
+        Looks up the grid info in the associated JSON sidecar.  If the JSON
+        does not contain grid information the NIfTI is loaded, the grid is
+        computed, and the result is written back to the JSON when
+        *add_grid_info_to_json* is ``True``.
+
+        Args:
+            add_grid_info_to_json: If ``True``, persist newly computed grid
+                info to the JSON sidecar.
+
+        Returns:
+            A :class:`~TPTBox.core.nii_poi_abstract.Grid` instance, or
+            ``None`` if no NIfTI file is present.
+        """
         from TPTBox.core.dicom.dicom_extract import _add_grid_info_to_json
         from TPTBox.core.nii_poi_abstract import Grid
 
@@ -1004,18 +1433,52 @@ def get_grid_info(self, add_grid_info_to_json=True):
             self.file["json"] = Path(str(nii_file).split(".")[0] + ".json")
         return Grid(**_add_grid_info_to_json(nii_file, self.file["json"], add=add_grid_info_to_json)["grid"])
 
-    def get_nii_file(self) -> Path:  # type: ignore
+    def get_nii_file(self) -> Path | None:
+        """Return the path to the first available NIfTI file.
+
+        Checks the supported NIfTI extensions (``nii.gz``, ``nii``, ``mkd``)
+        in order and returns the first one present.
+
+        Returns:
+            The :class:`~pathlib.Path` to the NIfTI file, or ``None`` if
+            none of the supported extensions are registered.
+        """
         for key in _supported_nii_files:
             if key in self.file:
                 return self.file[key]
+        return None
 
     def has_npz(self) -> bool:
+        """Return ``True`` when an NPZ array file is registered for this entry."""
         return "npz" in self.file
 
     def open_npz(self) -> dict[str, np.ndarray]:
+        """Load the associated NPZ file and return its contents as a dictionary.
+
+        Returns:
+            A dictionary mapping array names to :class:`numpy.ndarray` objects.
+
+        Raises:
+            KeyError: If no NPZ file is registered in :attr:`file`.
+        """
         return dict(np.load(self.file["npz"], allow_pickle=False))  # type: ignore
 
-    def open(self, filetype, _internal=False) -> Path | TPTBox.NII | dict | None:
+    def open(self, filetype: str, _internal: bool = False) -> Path | TPTBox.NII | dict | None:
+        """Open a file by extension, returning the appropriate Python object.
+
+        .. deprecated::
+            Use :meth:`open_nii`, :meth:`open_json`, or :attr:`file` directly.
+
+        Args:
+            filetype: Extension to open (e.g. ``"nii.gz"``, ``"json"``).
+            _internal: Suppress the deprecation warning when called internally.
+
+        Returns:
+            * A :class:`~TPTBox.NII` for NIfTI extensions.
+            * A :class:`dict` for JSON files.
+            * A :class:`~pathlib.Path` for all other file types.
+            * ``None`` if *filetype* is not registered in :attr:`file`.
+        """
         if not _internal:
             warn("open is deprecated.", DeprecationWarning, stacklevel=2)
         if filetype not in self.file:
@@ -1030,20 +1493,28 @@ def do_filter(
         self,
         key: str,
         constrain: list[str] | str | typing.Callable[[str | object], bool],
-        required=False,
-    ):
-        """
-        Returns True/False if the  key,constrain is matched
-        If a key is not present the inverse of the "required" value is returned
+        required: bool = False,
+    ) -> bool:
+        """Check whether this file satisfies a key/constraint filter.
+
+        If the *key* is not present in this file, the inverse of *required*
+        is returned (i.e. absent keys pass when ``required=False`` and fail
+        when ``required=True``).
 
         Args:
-            key (str): The key for which we filter. Can be "format", a filetype, a key from the info-dict
-                    In case of filetype + constrain is a callable you get a opened Nifti, opened json or Path
-            constrain (str | typing.Callable[[str  |  object], bool]):
-                    If a string is given: An exact string match is looked up
-                    If a callable: The function is called with the value of the key.
-            required (bool, optional): If True: A key must exist or the family/file is filtered.
-                    If False: Only if the key exist the family/file will be considers for filtering. Defaults to True.
+            key: The entity to inspect.  Special values: ``"format"`` checks
+                :attr:`format`; ``"filetype"`` checks registered extensions;
+                ``"parent"`` checks the parent folder; ``"self"`` passes the
+                whole :class:`BIDS_FILE`.  Any other value is looked up in
+                :attr:`info`, then in :attr:`file` (opening the file when a
+                callable is given).
+            constrain: Matching criterion — a string for exact match, a list
+                of strings for membership, or a callable predicate.
+            required: If ``True``, files for which *key* is absent are
+                rejected.  Defaults to ``False``.
+
+        Returns:
+            ``True`` when the constraint is satisfied, ``False`` otherwise.
         """
         key = key.lower()
         if key == "":
@@ -1079,17 +1550,28 @@ def do_filter(
         return False
 
     def get_interpolation_order(self) -> int:
-        """Returns 0 if the file is a mask or segmentation
-        Returns 3 if the file is a image.
+        """Return the interpolation order for this file (0 for masks/segmentations, 3 for images).
 
         Returns:
             int: interpolation_order
         """
         return 0 if self.format == "msk" or "label" in self.info else 3
 
-    def get_frame_of_reference_uid(self, default=None):
-        """gives a unique identifier for diffrent world spaces"""
+    def get_frame_of_reference_uid(self, default: str | None = None) -> str | None:
+        """Return a short hash identifying the world-space frame of reference.
+
+        Reads ``FrameOfReferenceUID`` from the JSON sidecar and converts it
+        to an 8-character base-36 string.  Falls back to the ``res`` or
+        ``ses`` entity, and finally to *default*, when no JSON is available.
+
+        Args:
+            default: Value returned when the frame of reference cannot be
+                determined.
 
+        Returns:
+            An 8-character base-36 hash string, a BIDS entity value, or
+            *default*.
+        """
         import hashlib
 
         length = 8
@@ -1109,7 +1591,7 @@ def get_frame_of_reference_uid(self, default=None):
         return base36[:length]
 
     def get_identifier(self, sequence_splitting_keys: list[str]) -> str:
-        """Generates an identifier for the BIDS_FILE based on subject and splitting keys
+        """Generates an identifier for the BIDS_FILE based on subject and splitting keys.
 
         Args:
             sequence_splitting_keys (list[str]): list of keys to use for splitting
@@ -1126,6 +1608,8 @@ def get_identifier(self, sequence_splitting_keys: list[str]) -> str:
 
 
 class Searchquery:
+    """Query builder for filtering and retrieving BIDS files from a Subject_Container."""
+
     def __init__(self, subj: Subject_Container, flatten=False) -> None:
         """Filter for specific files.
 
@@ -1145,7 +1629,16 @@ def __init__(self, subj: Subject_Container, flatten=False) -> None:
         self._flatten = flatten
 
     @classmethod
-    def from_BIDS_Family(cls, fam: BIDS_Family):
+    def from_BIDS_Family(cls, fam: BIDS_Family) -> Searchquery:
+        """Construct a :class:`Searchquery` pre-filtered to a single :class:`BIDS_Family`.
+
+        Args:
+            fam: The family whose sequence bucket will be the sole candidate.
+
+        Returns:
+            A new :class:`Searchquery` containing only the sequence that
+            produced *fam*.
+        """
         dic = fam.data_dict
         any_file = dic[next(iter(dic.keys()))][0]
         sub = any_file.subject
@@ -1154,7 +1647,8 @@ def from_BIDS_Family(cls, fam: BIDS_Family):
         # query.candidates = dic.copy()
         return query
 
-    def _filter_fam_id(self, fam: BIDS_Family):
+    def _filter_fam_id(self, fam: BIDS_Family) -> None:
+        """Restrict candidates to the single sequence bucket that produced *fam*."""
         self.unflatten()
         dic = fam.data_dict
         any_file = dic[next(iter(dic.keys()))][0]
@@ -1163,14 +1657,23 @@ def _filter_fam_id(self, fam: BIDS_Family):
         self.candidates = {}
         self.candidates[subject_id] = c[subject_id]  # type: ignore
 
-    def copy(self):
+    def copy(self) -> Searchquery:
+        """Return a shallow copy of this query with the same candidates.
+
+        Returns:
+            A new :class:`Searchquery` sharing the same subject and flatten
+            mode, with an independent copy of the candidates collection.
+        """
         copy = Searchquery(self.subject, self._flatten)
         copy.candidates = self.candidates.copy()
         return copy
 
-    def flatten(self):
-        """
-        Transform from multi-file-mode to single file-mode
+    def flatten(self) -> None:
+        """Transform from multi-file-mode (sequence buckets) to single-file-mode.
+
+        After calling this method, :attr:`candidates` is a flat
+        :class:`list` of :class:`BIDS_FILE` instances and
+        :meth:`loop_list` can be used to iterate over them.
         """
         if self._flatten:
             return
@@ -1182,9 +1685,11 @@ def flatten(self):
         self.candidates = a
         self._flatten = True
 
-    def unflatten(self):
-        """
-        Transforms from single file-mode to multi-file-mode. Filtered Objects are still removed
+    def unflatten(self) -> None:
+        """Transform from single-file-mode back to multi-file-mode (sequence buckets).
+
+        Previously filtered files remain excluded.  After calling this method
+        :meth:`loop_dict` can be used to iterate over sequence families.
         """
         if not self._flatten:
             return
@@ -1197,32 +1702,47 @@ def unflatten(self):
         self.candidates = a
         self._flatten = False
 
-    def filter_self(self, filter_fun: typing.Callable[[BIDS_FILE], bool], required=True) -> None:
+    def filter_self(self, filter_fun: typing.Callable[[BIDS_FILE], bool], required: bool = True) -> None:
+        """Filter candidates by applying *filter_fun* directly to each :class:`BIDS_FILE`.
+
+        Args:
+            filter_fun: Predicate receiving a :class:`BIDS_FILE`; return
+                ``True`` to keep the file.
+            required: Passed to :meth:`filter`.
+        """
         return self.filter("self", filter_fun, required=required)  # type: ignore
 
-    def filter_json(self, filter_fun: typing.Callable[[dict], bool], required=True) -> None:
+    def filter_json(self, filter_fun: typing.Callable[[dict], bool], required: bool = True) -> None:
+        """Filter candidates by applying *filter_fun* to the parsed JSON sidecar.
+
+        Args:
+            filter_fun: Predicate receiving the JSON dictionary; return
+                ``True`` to keep the file.
+            required: If ``True``, files without a JSON sidecar are removed.
+        """
         return self.filter("json", filter_fun, required=required)  # type: ignore
 
     def filter(
         self,
         key: str,
         filter_fun: list[str] | str | typing.Callable[[str | object], bool],
-        required=True,
-    ):
-        """Remove family/file from the Searchquery if:
-                        (unflatten-mode) NO single file exist in the family returns True
-                        (unflatten-mode) the filter_fun returns False
+        required: bool = True,
+    ) -> None:
+        """Remove candidates from the query that do not satisfy the filter.
 
-                        If a key is not present the inverse of the "required" value is returned
+        In flatten mode (single-file mode), individual files that do not pass
+        are removed.  In unflatten mode (sequence mode), a sequence bucket is
+        removed when *no* file in the bucket satisfies the filter.
 
         Args:
-                        key (str): The key for which we filter. Can be "format", a filetype, a key from the info-dict
-                                    In case of filetype + filter_fun is a callable you get a opened Nifti, opened json or Path
-                        filter_fun (str | typing.Callable[[str  |  object], bool]):
-                                    If a string is given: An exact string match is looked up
-                                    If a callable: The function is called with the value of the key.
-                        required (bool, optional): If True: A key must exist or the family/file is filtered.
-                                    If False: Only if the key exist the family/file will be considers for filtering. Defaults to True.
+            key: The entity to inspect.  Special values: ``"format"``,
+                ``"filetype"``, ``"parent"``, ``"self"``; otherwise looked up
+                in :attr:`BIDS_FILE.info` or :attr:`BIDS_FILE.file`.
+            filter_fun: Matching criterion — a string for exact match, a list
+                of accepted strings, or a callable predicate.
+            required: If ``True``, candidates where *key* is absent are
+                removed.  If ``False``, absent keys are silently kept.
+                Defaults to ``True``.
         """
         if self._flatten:
             assert isinstance(self.candidates, list)
@@ -1236,12 +1756,26 @@ def filter(
                 if not any(bids_file.do_filter(key, filter_fun, required=required) for bids_file in bids_files):
                     self.candidates.pop(sequences)
 
-    def filter_format(self, filter_fun: list[str] | str | typing.Callable[[str | object], bool]):
+    def filter_format(self, filter_fun: list[str] | str | typing.Callable[[str | object], bool]) -> None:
+        """Keep only files whose format label satisfies *filter_fun*.
+
+        Args:
+            filter_fun: A format string, a list of accepted format strings,
+                or a callable predicate applied to the format label.
+        """
         if isinstance(filter_fun, list):
             return self.filter_format(lambda x: x in filter_fun)
         return self.filter("format", filter_fun=filter_fun, required=True)
 
-    def filter_filetype(self, filter_fun: list[str] | str | typing.Callable[[str | object], bool], required=True):
+    def filter_filetype(self, filter_fun: list[str] | str | typing.Callable[[str | object], bool], required: bool = True) -> None:
+        """Keep only files that have a matching file extension.
+
+        Args:
+            filter_fun: An extension string (e.g. ``"nii.gz"``), a list of
+                accepted extensions, or a callable predicate.
+            required: If ``True``, files without any registered extension
+                are removed.
+        """
         return self.filter("filetype", filter_fun=filter_fun, required=required)
 
     def filter_non_existence(
@@ -1250,7 +1784,7 @@ def filter_non_existence(
         filter_fun: str | typing.Callable[[str | object], bool] = lambda x: True,  # noqa: ARG005
         required=True,
     ) -> None:
-        """Remove family/file from the Searchquery if:
+        """Remove family/file from the Searchquery if the filter condition is met.
 
             (unflatten-mode) ANY single file exist in the family returns True
 
@@ -1279,8 +1813,16 @@ def filter_non_existence(
                 if any(bids_file.do_filter(key, filter_fun, required=required) for bids_file in bids_files):
                     self.candidates.pop(sequences)
 
-    def filter_dixon_only_inphase(self):
-        def json_filter(x):
+    def filter_dixon_only_inphase(self) -> None:
+        """Remove Dixon files that are fat, water, out-of-phase, or difference images.
+
+        Retains only in-phase (or unlabelled) Dixon acquisitions by
+        inspecting both the JSON ``ImageType`` field and the ``rec``,
+        ``acq``, and ``part`` entities.
+        """
+
+        def json_filter(x: dict) -> bool:
+            """Return True if JSON ImageType does not indicate a fat/water/outphase channel."""
             return "ImageType" not in x or (
                 "W" not in x["ImageType"]
                 and "F" not in x["ImageType"]
@@ -1289,7 +1831,8 @@ def json_filter(x):
                 and "OP" not in x["ImageType"]
             )
 
-        def lam_filter(x):
+        def lam_filter(x: str) -> bool:
+            """Return True if the entity value does not indicate a non-inphase Dixon channel."""
             return (
                 x.upper() != "W"
                 and x.upper() != "F"
@@ -1306,25 +1849,35 @@ def lam_filter(x):
         self.filter("acq", lam_filter, required=False)  # type: ignore DEPRECATED
         self.filter("part", "inphase", required=False)  # type: ignore
 
-    def filter_dixon_water(self, _keys=None):
+    def filter_dixon_water(self, _keys: list[str] | None = None) -> None:
+        """Keep only Dixon water-channel images (requires flatten mode).
+
+        Args:
+            _keys: Image-type labels that identify the water channel.
+                Defaults to ``["W", "WATER"]``.
+        """
         if _keys is None:
             _keys = ["W", "WATER"]
         assert self._flatten
 
-        def json_filter(x):
+        def json_filter(x: dict) -> bool:
+            """Return True if JSON ImageType contains all required channel keys."""
             return "ImageType" not in x or all(k in x["ImageType"] for k in _keys)
 
-        def lam_filter(x):
+        def lam_filter(x: str) -> bool:
+            """Return True if the entity value matches one of the target channel keys."""
             return any(k == x.upper() for k in _keys)
 
         self.filter_json(json_filter, required=False)
         self.filter("rec", lam_filter, required=False)  # type: ignore
         self.filter("part", lam_filter, required=False)  # type: ignore
 
-    def filter_dixon_fat(self):
+    def filter_dixon_fat(self) -> None:
+        """Keep only Dixon fat-channel images (requires flatten mode)."""
         self.filter_dixon_water(_keys=["F", "FAT"])
 
-    def filter_dixon_outphase(self):
+    def filter_dixon_outphase(self) -> None:
+        """Keep only Dixon out-of-phase images (requires flatten mode)."""
         self.filter_dixon_water(_keys=["OP", "OPP", "OUTPHASE"])
 
     def action(
@@ -1333,19 +1886,27 @@ def action(
         filter_fun: str | typing.Callable[[str | object], bool] = lambda x: True,  # noqa: ARG005
         key: str = "",
         required: bool = True,
-        all_in_sequence=False,
-    ):
-        """When the filter_function is True the action_fun is applied on the BIDS_File
+        all_in_sequence: bool = False,
+    ) -> None:
+        """Apply *action_fun* to every candidate file that passes the filter.
 
         Args:
-            action_fun (typing.Callable[[BIDS_FILE], None]): If the filter-function return True: The function is called with the BIDS_file as an argument
-            key (str): The key for which we filter. Can be "format", a filetype, a key from the info-dict
-                        In case of filetype + filter_fun is a callable you get a opened Nifti, opened json or Path
-            filter_fun (str | typing.Callable[[str  |  object], bool]):
-                        If a string is given: An exact string match is looked up
-                        If a callable: The function is called with the value of the key.
-            required (bool): _description_. Defaults to True.
-                all_in_sequence (bool, optional): If True, the action_fun is called also on all family files. Defaults to False.
+            action_fun: Callable invoked with each matching
+                :class:`BIDS_FILE` as its sole argument.
+            key: The entity to inspect for filtering (same semantics as in
+                :meth:`filter`).  An empty string matches everything.
+            filter_fun: Matching criterion — a string for exact match or a
+                callable predicate.  Defaults to a predicate that always
+                returns ``True`` (act on all candidates).
+            required: If ``True``, candidates where *key* is absent are
+                skipped.  Defaults to ``True``.
+            all_in_sequence: In unflatten mode, when ``True`` and at least
+                one file in a sequence bucket matches, *action_fun* is called
+                on *every* file in that bucket.  Defaults to ``False``.
+
+        Raises:
+            AssertionError: If both :attr:`_flatten` and *all_in_sequence*
+                are ``True`` (incompatible combination).
         """
         assert not (self._flatten and all_in_sequence)
         if self._flatten:
@@ -1386,7 +1947,8 @@ def __str__(self) -> str:
             return s
 
     def loop_list(self, sort=False) -> typing.Iterator[BIDS_FILE]:
-        """Returns an iterator. Flatten must be True
+        """Returns an iterator. Flatten must be True.
+
         Args:
             sort (bool, optional): Sort alphabetically. Defaults to False.
 
@@ -1404,7 +1966,7 @@ def loop_dict(
         key_transform: typing.Callable[[BIDS_FILE], str | None] | None = None,
         key_addendum: list[str] | None = None,  # type: ignore
     ) -> typing.Iterator[BIDS_Family]:
-        """Returns an iterator. Flatten must be False: it iterates over all families, where the return is the dict from the get_sequence_files function
+        """Returns an iterator. Flatten must be False: it iterates over all families, where the return is the dict from the get_sequence_files function.
 
         Args:
             sort (bool, optional): Sort alphabetically. Defaults to False.
@@ -1429,6 +1991,8 @@ def loop_dict(
 
 
 class BIDS_Family:
+    """A group of related BIDS files sharing the same sequence-splitting key values."""
+
     def __init__(
         self,
         family_data: dict[str, list[BIDS_FILE]],
@@ -1482,41 +2046,68 @@ def __hash__(self) -> int:
     def __lt__(self, other):
         return str(self) < str(other)
 
-    def get_identifier(self):
+    def get_identifier(self) -> str:
+        """Return the subject+sequence identifier string for this family.
+
+        Delegates to :meth:`BIDS_FILE.get_identifier` on the first file in
+        the family.
+
+        Returns:
+            A string like ``"sub-001_ses-01_sequ-303"`` derived from the
+            sequence splitting keys.
+        """
         first_e = self.data_dict[next(iter(self.data_dict.keys()))][0]
         return first_e.get_identifier(self.sequence_splitting_keys)
-        # if "sub" not in first_e.info:
-        #    print(f"family_id, no sub-key, got {first_e.info} and data_dict {list(self.data_dict.keys())}")
-        #    identifier = "sub-404"
-        # else:
-        #    identifier = "sub-" + first_e.info["sub"]
-        # for s in first_e.info.keys():
-        #    if s in self.sequence_splitting_keys:
-        #        identifier += "_" + s + "-" + first_e.info[s]
-        # return identifier
-
-    def items(self):
+
+    def items(self) -> typing.ItemsView[str, list[BIDS_FILE]]:
+        """Return ``(format_key, [BIDS_FILE, ...])`` pairs from the family dictionary."""
         return self.data_dict.items()
 
-    def keys(self):
+    def keys(self) -> typing.KeysView[str]:
+        """Return the format keys present in this family."""
         return self.data_dict.keys()
 
-    def sort(self):
+    def sort(self) -> None:
+        """Sort the family dictionary alphabetically by format key in-place."""
         self.data_dict = dict(sorted(self.data_dict.items()))
 
-    def values(self):
+    def values(self) -> list[list[BIDS_FILE]]:
+        """Return all lists of :class:`BIDS_FILE` objects in this family."""
         return list(self.data_dict.values())
 
-    def new_query(self, flatten=False):
+    def new_query(self, flatten: bool = False) -> Searchquery:
+        """Create a :class:`Searchquery` scoped to this family's sequence.
+
+        Args:
+            flatten: If ``True``, the query starts in single-file mode.
+
+        Returns:
+            A :class:`Searchquery` pre-filtered to this family's sequence
+            bucket.
+        """
         q = Searchquery.from_BIDS_Family(self)
         if flatten:
             q.flatten()
         return q
 
     def get_key_len(self) -> dict[str, int]:
+        """Return the number of :class:`BIDS_FILE` instances for each format key.
+
+        Returns:
+            A dictionary mapping format key to the count of associated files.
+        """
         return {k: len(v) for k, v in self}
 
-    def get_format_len(self):
+    def get_format_len(self) -> dict[str, tuple[int, int]]:
+        """Return per-base-format counts aggregated across all sub-keys.
+
+        Groups family keys by their base format (the part before the first
+        ``_``) and accumulates ``(key_count, file_count)`` tuples.
+
+        Returns:
+            A dictionary mapping base-format label to a
+            ``(number_of_keys, total_file_count)`` tuple.
+        """
         format_len = {}
         for k, v in self:
             bids_format = k.split("_")[0]
@@ -1528,10 +2119,27 @@ def get_format_len(self):
             )
         return format_len
 
-    def get_files_with_multiples(self):
+    def get_files_with_multiples(self) -> dict[str, list[dict]]:
+        """Return file-path dictionaries for all format keys that have more than one file.
+
+        Returns:
+            A dictionary mapping format key to a list of :attr:`BIDS_FILE.file`
+            dicts, restricted to keys that hold more than one file.
+        """
         return self.get_files(key=[k for k, v in self.get_key_len().items() if v > 1])
 
-    def get_files(self, key: list[str] | str | None = None):
+    def get_files(self, key: list[str] | str | None = None) -> dict[str, list[dict]]:
+        """Return the raw file-path dictionaries for one or more format keys.
+
+        Args:
+            key: A single format key, a list of format keys, or ``None`` to
+                include all keys.
+
+        Returns:
+            A dictionary mapping each requested format key to a list of
+            :attr:`BIDS_FILE.file` dicts (one per associated
+            :class:`BIDS_FILE`).
+        """
         if key is None:
             key = [k for k, v in self]
         if isinstance(key, str):
@@ -1541,7 +2149,19 @@ def get_files(self, key: list[str] | str | None = None):
             family_dict_files[k] = [b.file for b in self[k]]
         return family_dict_files
 
-    def get(self, item: str | list[str], default=None) -> list[BIDS_FILE] | None:
+    def get(self, item: str | list[str], default: list[BIDS_FILE] | None = None) -> list[BIDS_FILE] | None:
+        """Return the list of :class:`BIDS_FILE` instances for the first matching key.
+
+        When *item* is a list the method tries each element in order and
+        returns the first hit.
+
+        Args:
+            item: A single format key or an ordered list of candidate keys.
+            default: Value returned when none of the keys are found.
+
+        Returns:
+            The list of :class:`BIDS_FILE` instances, or *default*.
+        """
         if not isinstance(item, list):
             item = [item]
         for i in item:
@@ -1550,7 +2170,7 @@ def get(self, item: str | list[str], default=None) -> list[BIDS_FILE] | None:
         return default
 
     def get_bids_files_as_dict(self, keys: list[str]) -> dict[str, BIDS_FILE]:
-        """Checks each entry of the list, if everything is there, loads everything, one for each entry in keys
+        """Checks each entry of the list, if everything is there, loads everything, one for each entry in keys.
 
         Args:
             keys: list of (keys or list of keys)
diff --git a/TPTBox/core/compat.py b/TPTBox/core/compat.py
index c1e74d5..92abac4 100644
--- a/TPTBox/core/compat.py
+++ b/TPTBox/core/compat.py
@@ -1,9 +1,8 @@
 from __future__ import annotations
 
 
-def zip_strict(*iterables):
-    """
-    A strict version of zip that raises a ValueError if the input iterables have different lengths.
+def zip_strict(*iterables) -> zip:
+    """A strict version of zip that raises a ValueError if the input iterables have different lengths.
 
     Converts each iterable to a list to check lengths. This assumes all iterables are finite.
 
diff --git a/TPTBox/core/dicom/dicom2nii_utils.py b/TPTBox/core/dicom/dicom2nii_utils.py
index a6c724c..3f512c1 100755
--- a/TPTBox/core/dicom/dicom2nii_utils.py
+++ b/TPTBox/core/dicom/dicom2nii_utils.py
@@ -47,7 +47,8 @@
 }
 
 
-def __test_nii(path: Path | str | BIDS_FILE):
+def __test_nii(path: Path | str | BIDS_FILE) -> bool:
+    """Return True if the NIfTI file at *path* can be loaded successfully."""
     if isinstance(path, str):
         path = Path(path)
     if path.exists():
@@ -58,7 +59,14 @@ def __test_nii(path: Path | str | BIDS_FILE):
     return True
 
 
-def find_all_broken(path: str = "/DATA/NAS/datasets_processed/NAKO/dataset-nako/", parents=None):
+def find_all_broken(path: str = "/DATA/NAS/datasets_processed/NAKO/dataset-nako/", parents=None) -> None:
+    """Scan a BIDS dataset for broken NIfTI files and record them in a pickle file.
+
+    Args:
+        path: Root directory of the BIDS dataset to scan.
+        parents: List of BIDS parent folders to include (e.g., ``["rawdata"]``).
+            Defaults to ``["rawdata"]`` when ``None``.
+    """
     brocken = []
     subj_id = 0
     with open("broken.pkl", "rb") as w:
@@ -90,7 +98,8 @@ def find_all_broken(path: str = "/DATA/NAS/datasets_processed/NAKO/dataset-nako/
 )
 
 
-def __test_and_replace(out_folder="/media/data/NAKO/dataset-nako2"):
+def __test_and_replace(out_folder: str = "/media/data/NAKO/dataset-nako2") -> None:
+    """Re-extract broken NIfTI files from the original DICOM source archives."""
     from TPTBox.core.dicom.dicom_extract import extract_dicom_folder
 
     with open("/run/user/1000/gvfs/smb-share:server=172.21.251.64,share=nas/tools/TPTBox/broken.pkl", "rb") as w:
@@ -157,7 +166,23 @@ def clean_dicom_data(dcm_data) -> dict:
     return py_dict
 
 
-def replace_birthdate_with_age(d):
+def replace_birthdate_with_age(d: dict) -> dict:
+    """Replace the PatientBirthDate DICOM tag with a computed PatientAge tag.
+
+    Calculates the patient's age from the birth date and the study date (or today
+    if the study date is unavailable) and stores it in the PatientAge field using
+    the DICOM age-string format (e.g. ``"034Y"``).  The PatientBirthDate field is
+    removed to avoid storing personally identifiable information.
+
+    Args:
+        d: Dictionary representation of a DICOM dataset as produced by
+            ``pydicom.dataset.Dataset.to_json_dict``.
+
+    Returns:
+        The modified dictionary with the PatientBirthDate field replaced by a
+        PatientAge field, or the original dictionary unchanged if the birth date
+        is missing or cannot be parsed.
+    """
     try:
         # DICOM tags
         BIRTH_TAG = "00100030"  # PatientBirthDate
@@ -203,7 +228,21 @@ def replace_birthdate_with_age(d):
     return d
 
 
-def get_json_from_dicom(data: list[pydicom.FileDataset] | pydicom.FileDataset):
+def get_json_from_dicom(data: list[pydicom.FileDataset] | pydicom.FileDataset) -> dict:
+    """Extract a JSON-serialisable metadata dictionary from a DICOM dataset or list of datasets.
+
+    If a list is given, only the first element is used (assumes all slices in a
+    series share the same header metadata).  Pixel data and inline binary fields
+    are stripped, and the patient birth date is replaced with a computed age.
+
+    Args:
+        data: A single DICOM ``FileDataset`` or a list of them representing one
+            imaging series.
+
+    Returns:
+        A flat dictionary mapping DICOM keyword strings to Python-native values,
+        suitable for JSON serialisation.
+    """
     if isinstance(data, list):
         data = data[0]
     py_dict = clean_dicom_data(data)
@@ -212,10 +251,7 @@ def get_json_from_dicom(data: list[pydicom.FileDataset] | pydicom.FileDataset):
 
 
 def _get_json_from_dicom(py_dict: dict):
-    """
-    takes a dictionary returned from pydicom.dataset.to_json_dict and rearranges it to be
-    compatible with json encoding
-    """
+    """Rearrange a pydicom ``to_json_dict`` output into a JSON-serialisable form."""
     data1 = {}
     for key, value in py_dict.items():
         try:
@@ -235,7 +271,17 @@ def _get_json_from_dicom(py_dict: dict):
     return data1
 
 
-def test_name_conflict(json_ob, file):
+def test_name_conflict(json_ob: dict, file: str | Path) -> bool:
+    """Check whether an existing JSON file has different content from the given object.
+
+    Args:
+        json_ob: JSON-serialisable object to compare against the file on disk.
+        file: Path to an existing (or non-existing) JSON file.
+
+    Returns:
+        ``True`` if the file exists and its content differs from ``json_ob``,
+        ``False`` otherwise (file does not exist or content matches).
+    """
     if Path(file).exists():
         with open(file) as f:
             js = json.load(f)
@@ -245,9 +291,23 @@ def test_name_conflict(json_ob, file):
     return False
 
 
-def save_json(json_ob, file, check_exist=False, override=True):
-    """
-    recieves a json object and a path and saves the object as a json file
+def save_json(json_ob: dict, file: str | Path, check_exist: bool = False, override: bool = True) -> bool:
+    """Serialize a Python object to a JSON file, handling NumPy scalar types.
+
+    Args:
+        json_ob: JSON-serialisable object to save.
+        file: Destination file path.
+        check_exist: If ``True``, raise ``FileExistsError`` when a file with
+            different content already exists at *file*.
+        override: If ``False``, skip writing when the file already exists.
+
+    Returns:
+        ``True`` if the file already existed and writing was skipped, ``False``
+        if the file was written successfully.
+
+    Raises:
+        FileExistsError: When *check_exist* is ``True`` and the existing file
+            contains different content.
     """
 
     def convert(obj):
@@ -267,7 +327,15 @@ def convert(obj):
     return False
 
 
-def load_json(file):
+def load_json(file: str | Path) -> dict:
+    """Load and parse a JSON file into a Python dictionary.
+
+    Args:
+        file: Path to the JSON file to read.
+
+    Returns:
+        Parsed contents of the JSON file.
+    """
     with open(file) as file_handel:
         return json.load(file_handel)
 
diff --git a/TPTBox/core/dicom/dicom_extract.py b/TPTBox/core/dicom/dicom_extract.py
index b2c633b..93519da 100644
--- a/TPTBox/core/dicom/dicom_extract.py
+++ b/TPTBox/core/dicom/dicom_extract.py
@@ -33,7 +33,8 @@
 logger = Print_Logger()
 
 
-def _inc_key(keys, inc=1):
+def _inc_key(keys: dict, inc: int = 1) -> None:
+    """Increment the sequence key inside *keys* by *inc*."""
     k = "sequ"
     if k not in keys:
         keys[k] = 0
@@ -52,8 +53,7 @@ def _inc_key(keys, inc=1):
 def _generate_bids_path(
     dataset_nifti_dir, keys: dict, mri_format, simp_json, make_subject_chunks: int, parent="rawdata", _subject_folder_prefix="sub-"
 ):
-    """
-    Generate a BIDS-compatible file path for NIfTI outputs based on extracted keys from DICOM headers.
+    """Generate a BIDS-compatible file path for NIfTI outputs based on extracted keys from DICOM headers.
 
     Args:
         nifti_dir (str | Path): Directory where the NIfTI file will be stored.
@@ -67,7 +67,6 @@ def _generate_bids_path(
     Returns:
         Path: Path object for the BIDS-compliant file name.
     """
-
     assert "sub" in keys, keys
     ses = keys.get("ses")
     ses = f"ses-{ses}" if ses is not None else ""
@@ -88,7 +87,14 @@ def _generate_bids_path(
     return fname.file["json"], fname
 
 
-def dicom_to_nifti_multiframe_2d(ds, nii_path, pixel_array):
+def dicom_to_nifti_multiframe_2d(ds, nii_path, pixel_array) -> None:
+    """Convert a 2D multiframe DICOM dataset to a NIfTI file using its affine metadata.
+
+    Args:
+        ds: pydicom FileDataset object containing the DICOM header.
+        nii_path: Destination path for the output NIfTI file.
+        pixel_array: Pixel data array extracted from the DICOM dataset.
+    """
     if hasattr(ds, "PixelSpacing"):
         dy, dx = map(float, ds.PixelSpacing)
         affine = np.eye(4)
@@ -119,7 +125,25 @@ def dicom_to_nifti_multiframe_2d(ds, nii_path, pixel_array):
     return nii_path
 
 
-def dicom_to_nifti_multiframe(ds, nii_path):
+def dicom_to_nifti_multiframe(ds: pydicom.FileDataset, nii_path: str | Path) -> str | Path:
+    """Convert a multi-frame DICOM dataset to a NIfTI file.
+
+    Builds a proper NIfTI affine matrix from the DICOM spatial metadata
+    (``PixelSpacing``, ``ImageOrientationPatient``, ``ImagePositionPatient``) and
+    saves the result via nibabel.
+
+    Args:
+        ds: A single pydicom ``FileDataset`` that contains multi-frame pixel data.
+        nii_path: Destination path for the output NIfTI file.
+
+    Returns:
+        The path to the saved NIfTI file (*nii_path*).
+
+    Raises:
+        ValueError: If the pixel array does not have 3 or 4 dimensions.
+        NotImplementedError: If no supported spatial metadata is found to build
+            an affine matrix.
+    """
     pixel_array = ds.pixel_array
     if len(pixel_array.shape) == 2:
         return dicom_to_nifti_multiframe_2d(ds, nii_path, pixel_array)
@@ -252,8 +276,7 @@ def _extract_txt_from_dicom(dcm_path, out_txt):
 
 
 def _extract_nii_from_dicom(dicom_out_path, nii_path):
-    """
-    Convert DICOM files to NIfTI format and handle common conversion errors.
+    """Convert DICOM files to NIfTI format and handle common conversion errors.
 
     Args:
         dicom_out_path (list | str | Path): List of DICOM `FileDataset` objects or path to a DICOM directory.
@@ -267,7 +290,6 @@ def _extract_nii_from_dicom(dicom_out_path, nii_path):
         FunctionTimedOut: Raised if the DICOM-to-NIfTI conversion times out.
         ValueError: Raised for generic validation failures.
     """
-
     try:
         if isinstance(dicom_out_path, list):
             try:
@@ -319,15 +341,38 @@ def _get_paths(
     simp_json: dict,
     dcm_data_l: list[pydicom.FileDataset] | NII | Path,
     dataset_nifti_dir: str | Path,
-    make_subject_chunks=0,
-    use_session=False,
+    make_subject_chunks: int = 0,
+    use_session: bool = False,
     parts: list | None = None,
     map_series_description_to_file_format=None,
     override_subject_name: Callable[[dict, Path], str] | None = None,
     chunk: int | str | None = None,
     keys: dict[str, str | None] | None = None,
-    parent="rawdata",
-):
+    parent: str = "rawdata",
+) -> tuple:
+    """Derive BIDS-compliant JSON and NIfTI output paths for a single DICOM series.
+
+    Args:
+        simp_json: Simplified JSON metadata dictionary extracted from the DICOM header.
+        dcm_data_l: DICOM data (list of datasets, NII object, or path).
+        dataset_nifti_dir: Root directory of the output BIDS dataset.
+        make_subject_chunks: Number of leading subject-ID characters used for sub-folder grouping.
+        use_session: Include session information in the output path when ``True``.
+        parts: List of image-part identifiers (e.g. ``["fat", "water"]``).
+        map_series_description_to_file_format: Optional callable or mapping to override the automatic
+            series-description-to-format conversion.
+        override_subject_name: Optional callable ``(dict, Path) -> str`` that returns a custom
+            subject name.
+        chunk: Chunk index used when a series is split into multiple spatial stacks.
+        keys: Additional BIDS key-value pairs to inject into the filename.
+        parent: BIDS parent directory name (e.g. ``"rawdata"``).
+
+    Returns:
+        A 3-tuple ``(json_file_name, json_bids_name, nii_path)`` where
+        *json_file_name* is the path to the sidecar JSON, *json_bids_name* is the
+        corresponding ``BIDS_FILE`` object, and *nii_path* is the path for the
+        NIfTI output.
+    """
     if keys is None:
         keys = {}
     (mri_format, keys, ending) = extract_keys_from_json(
@@ -347,7 +392,8 @@ def _get_paths(
     return json_file_name, json_bids_name, nii_path
 
 
-def _filter_dicom(dcm_data_l: list[pydicom.FileDataset]):
+def _filter_dicom(dcm_data_l: list[pydicom.FileDataset]) -> list[pydicom.FileDataset]:
+    """Filter DICOM datasets to retain only those with spatial orientation metadata."""
     if len(dcm_data_l) == 1:
         return dcm_data_l
     dcm_data_l = [d for d in dcm_data_l if hasattr(d, "ImageOrientationPatient")]
@@ -358,16 +404,37 @@ def _from_dicom_to_nii(
     dcm_data_l: list[pydicom.FileDataset],
     nifti_dir: str | Path,
     make_subject_chunks: int = 0,
-    use_session=False,
-    verbose=True,
+    use_session: bool = False,
+    verbose: bool = True,
     parts: list | None = None,
     map_series_description_to_file_format=None,
     override_subject_name: Callable[[dict, Path], str] | None = None,
-    chunk=None,
-    skip_localizer=False,
+    chunk: int | str | None = None,
+    skip_localizer: bool = False,
     parent="rawdata",
     censor_list=None,
 ):
+    """Convert a list of DICOM datasets for one series to a NIfTI file.
+
+    Handles spatial-stack splitting, metadata extraction, BIDS path generation,
+    and the actual DICOM-to-NIfTI conversion.
+
+    Args:
+        dcm_data_l: Sorted list of pydicom ``FileDataset`` objects for one series.
+        nifti_dir: Root output directory for the BIDS dataset.
+        make_subject_chunks: Number of leading subject-ID characters for sub-folder grouping.
+        use_session: Include session information in the path when ``True``.
+        verbose: Print progress messages when ``True``.
+        parts: Image-part identifiers (e.g. ``["fat", "water"]``).
+        map_series_description_to_file_format: Optional override for series-description mapping.
+        override_subject_name: Optional callable that returns a custom subject name.
+        chunk: Chunk index for multi-stack series; ``None`` triggers automatic splitting.
+        skip_localizer: Skip localizer series when ``True``.
+
+    Returns:
+        Path to the generated NIfTI file, ``None`` on failure, or a list of paths
+        when the series was automatically split into multiple stacks.
+    """
     if censor_list is None:
         censor_list = [
             "StudyDate",
@@ -443,7 +510,18 @@ def _from_dicom_to_nii(
     return nii_path if add_grid else None
 
 
-def _add_grid_info_to_json(nii_path: Path | str, simp_json: Path | str, force_update=False, add=True):
+def _add_grid_info_to_json(nii_path: Path | str, simp_json: Path | str, force_update: bool = False, add: bool = True) -> dict:
+    """Append grid metadata (shape, spacing, orientation, affine) to a sidecar JSON file.
+
+    Args:
+        nii_path: Path to the NIfTI file from which grid info is read.
+        simp_json: Path to the JSON sidecar file to update.
+        force_update: Re-compute and overwrite existing grid info when ``True``.
+        add: Write the updated dictionary back to disk when ``True``.
+
+    Returns:
+        The updated JSON dictionary including the ``"grid"`` key.
+    """
     json_dict = load_json(simp_json) if Path(simp_json).exists() else {}
     if "grid" in json_dict and not force_update:
         return json_dict
@@ -462,9 +540,8 @@ def _add_grid_info_to_json(nii_path: Path | str, simp_json: Path | str, force_up
     return json_dict
 
 
-def _find_all_files(dcm_dirs: Path | list[Path],verbose=False):
-    """
-    Recursively find all DICOM directories or files in the given paths.
+def _find_all_files(dcm_dirs: Path | list[Path], verbose=False):
+    """Recursively find all DICOM directories or files in the given paths.
 
     Args:
         dcm_dirs (Path | list[Path]): A directory or list of directories to search for DICOM files.
@@ -484,13 +561,13 @@ def _find_all_files(dcm_dirs: Path | list[Path],verbose=False):
                 for file in files:
                     if Path(file).is_file():  # str(file).endswith(".dcm") or str(file).endswith(".ima")
                         if verbose:
-                            logger.on_neutral("File ",i,end="\r")
+                            logger.on_neutral("File ", i, end="\r")
                             i += 1
                         yield Path(root, file).absolute().parent
                         break
                     else:
                         if verbose:
-                            logger.on_neutral("File ",i,end="\r")
+                            logger.on_neutral("File ", i, end="\r")
                             i += 1
                         yield Path(root, file)
                 # if "." not in str(file):
@@ -503,6 +580,7 @@ def _find_all_files(dcm_dirs: Path | list[Path],verbose=False):
 
 
 def _unzip_files(dicom_zip_path: Path, out_dir: str | Path) -> Path:
+    """Extract a ZIP archive containing DICOM files to a temporary directory."""
     with zipfile.ZipFile(dicom_zip_path, "r") as zip_ref:
         dicom_out_path = Path(out_dir, dicom_zip_path.stem)
         zip_ref.extractall(dicom_out_path)
@@ -510,8 +588,7 @@ def _unzip_files(dicom_zip_path: Path, out_dir: str | Path) -> Path:
 
 
 def _read_dicom_files(dicom_out_path: Path) -> tuple[dict[str, list[FileDataset]], dict[str, list[str]]]:
-    """
-    Read DICOM files from a directory and categorize them based on SeriesInstanceUID and type.
+    """Read DICOM files from a directory and categorize them based on SeriesInstanceUID and type.
 
     Args:
         dicom_out_path (Path): Path to the directory containing DICOM files.
@@ -559,10 +636,19 @@ def _read_dicom_files(dicom_out_path: Path) -> tuple[dict[str, list[FileDataset]
 
 
 def _classic_get_grouped_dicoms(dicom_input: list[FileDataset]) -> list[list[FileDataset]]:
-    """
-    Search all dicoms in the dicom directory, sort and validate them
+    """Group DICOM slices into spatially contiguous stacks by analysing slice direction.
 
-    fast_read = True will only read the headers not the data
+    Slices are first sorted by ``InstanceNumber``.  A new stack is started whenever
+    the inter-slice direction vector changes significantly, indicating a different
+    spatial acquisition stack.  Groups with three or fewer slices are collected
+    into a single catch-all group at the end.
+
+    Args:
+        dicom_input: Flat list of pydicom ``FileDataset`` objects for a single series.
+
+    Returns:
+        List of groups, where each group is a list of ``FileDataset`` objects
+        belonging to the same spatial stack.
     """
     # Order all dicom files by InstanceNumber
     dicoms = sorted(dicom_input, key=lambda x: x.InstanceNumber)
@@ -609,7 +695,18 @@ def _classic_get_grouped_dicoms(dicom_input: list[FileDataset]) -> list[list[Fil
     return out
 
 
-def _filter_file_type(dicom_types: dict[str, list[str]]):
+def _filter_file_type(dicom_types: dict[str, list[str]]) -> dict[str, list[str]]:
+    """Identify per-series DICOM ImageType tokens that uniquely distinguish sub-series.
+
+    Args:
+        dicom_types: Mapping of ``SeriesInstanceUID`` to a list of ImageType strings
+            found within that series.
+
+    Returns:
+        A dictionary mapping ``"{SeriesInstanceUID}_{type_string}"`` keys to the
+        list of unique ImageType tokens that distinguish this sub-series from its
+        siblings.
+    """
     dicom_parts: dict[str, list[str]] = {}
     for k, v in dicom_types.items():
         if len(v) == 1:
@@ -656,11 +753,10 @@ def extract_dicom_folder(
     n_cpu: int | None = 1,
     override_subject_name: Callable[[dict, Path], str] | None = None,
     skip_localizer=True,
-    parent="rawdata",
+    parent: str = "rawdata",
     censor_list: list | None = None,
-):
-    """
-    Extract DICOM files from a directory or list of directories, convert them to NIfTI format, and store the output.
+) -> dict:
+    """Extract DICOM files from a directory or list of directories, convert them to NIfTI format, and store the output.
 
     Args:
         dicom_folder (Union[Path, list[Path]]): Path to a directory or list of directories containing DICOM files or compressed DICOM archives.
@@ -687,7 +783,7 @@ def extract_dicom_folder(
         convert_dicom.settings.disable_validate_slice_increment()
     outs = {}
 
-    for p in _find_all_files(dicom_folder,verbose=verbose):
+    for p in _find_all_files(dicom_folder, verbose=verbose):
         dicom_path = p
 
         if str(dicom_path).endswith(".pkl"):
@@ -753,7 +849,6 @@ def process_series(key, files, parts):
             p, Path("/media/data/robert/datasets", "dataset-Durchleuchtung222"), False, False, validate_slice_increment=False
         )
 
-
     sys.exit()
     # s = "/home/robert/Downloads/bein/dataset-oberschenkel/rawdata/sub-1-3-46-670589-11-2889201787-2305829596-303261238-2367429497/mr/sub-1-3-46-670589-11-2889201787-2305829596-303261238-2367429497_sequ-406_mr.nii.gz"
     # nii2 = NII.load(s, False)
diff --git a/TPTBox/core/dicom/dicom_header_to_keys.py b/TPTBox/core/dicom/dicom_header_to_keys.py
index e7f51cb..044e4a0 100644
--- a/TPTBox/core/dicom/dicom_header_to_keys.py
+++ b/TPTBox/core/dicom/dicom_header_to_keys.py
@@ -101,15 +101,20 @@
 }
 
 
-def get_plane_dicom(dicoms: list[pydicom.FileDataset] | NII, hires_threshold=0.8) -> str | None:
-    """Determines the orientation plane of the NIfTI image along the x, y, or z-axis.
+def get_plane_dicom(dicoms: list[pydicom.FileDataset] | NII, hires_threshold: float = 0.8) -> str | None:
+    """Determine the acquisition plane from a DICOM series or NIfTI image.
+
+    Args:
+        dicoms: Either a list of pydicom datasets (one per slice) representing
+            a single DICOM series, or an already-loaded :class:`~TPTBox.NII`
+            object.
+        hires_threshold: Zoom threshold used to distinguish the slice axis from
+            in-plane axes when all zooms are similar (iso detection).
 
     Returns:
-        str: The orientation plane of the image, which can be one of the following:
-            - 'ax': Axial plane (along the z-axis).
-            - 'cor': Coronal plane (along the y-axis).
-            - 'sag': Sagittal plane (along the x-axis).
-            - 'iso': Isotropic plane (if the image has equal zoom values along all axes).
+        One of ``'ax'`` (axial), ``'cor'`` (coronal), ``'sag'`` (sagittal),
+        ``'iso'`` (isotropic), or ``None`` on failure.
+
     Examples:
         >>> nii = NII(nib.load("my_image.nii.gz"))
         >>> nii.get_plane()
@@ -148,13 +153,44 @@ def get_plane_dicom(dicoms: list[pydicom.FileDataset] | NII, hires_threshold=0.8
 def extract_keys_from_json(  # noqa: C901
     simp_json: dict,
     dcm_data_l: list[pydicom.FileDataset] | NII | Path,
-    session=False,
-    parts=None,
-    map_series_description_to_file_format=None,
+    session: bool = False,
+    parts: list[str] | None = None,
+    map_series_description_to_file_format: dict | None = None,
     override_subject_name: Callable[[dict, Path], str] | None = None,
     chunk: int | str | None = None,
     keys: dict[str, str | None] | None = None,
-):
+) -> tuple[str, dict]:
+    """Extract BIDS-style key-value pairs from a DICOM JSON metadata dictionary.
+
+    Parses study and series descriptions together with DICOM tag values to
+    infer the image format (e.g. ``"T2w"``, ``"vibe"``) and BIDS entities
+    (``sub``, ``ses``, ``acq``, ``part``, ``chunk``, ``ce``, ``sequ``).
+    Special handling is included for NAKO study data.
+
+    Args:
+        simp_json: Flattened DICOM metadata dict, typically produced by
+            ``pydicom``'s JSON export or a BIDS sidecar.
+        dcm_data_l: List of pydicom datasets for the series, an NIfTI object,
+            or a Path to a NIfTI file. Used only to compute the acquisition
+            plane when not already in ``simp_json``.
+        session: If ``True``, populate the ``ses`` key from the study date.
+        parts: Explicit Dixon part labels that override automatic detection.
+        map_series_description_to_file_format: Custom regex-to-format mapping
+            applied before the built-in defaults.
+        override_subject_name: Optional callable that receives ``(simp_json,
+            path)`` and returns the subject ID string.
+        chunk: Explicit chunk identifier; overrides automatic detection.
+        keys: Pre-populated BIDS key dict; updated in-place and returned.
+
+    Returns:
+        A tuple ``(mri_format, keys)`` where ``mri_format`` is the inferred
+        image format string (e.g. ``"T2w"``) and ``keys`` is the updated BIDS
+        entity dict.
+
+    Raises:
+        NotImplementedError: For unsupported modalities or unrecognised NAKO
+            series descriptions.
+    """
     if keys is None:
         keys = {}
     if map_series_description_to_file_format is None:
@@ -175,7 +211,6 @@ def _get(key, default=None):
 
         return value
 
-    """Extract keys from JSON based on study and series descriptions."""
     #### NAKO FIXED ####
     if "StudyDescription" in simp_json and "nako" in _get("StudyDescription", "").lower():
         keys["sub"] = _get("PatientID", "unnamed").split("_")[0]
diff --git a/TPTBox/core/dicom/fix_brocken.py b/TPTBox/core/dicom/fix_brocken.py
index 4625d85..7c5bac6 100644
--- a/TPTBox/core/dicom/fix_brocken.py
+++ b/TPTBox/core/dicom/fix_brocken.py
@@ -45,7 +45,8 @@
 }
 
 
-def test_nii(path: Path | str | BIDS_FILE):
+def test_nii(path: Path | str | BIDS_FILE) -> bool:
+    """Return ``True`` when the NIfTI file at ``path`` can be loaded without errors."""
     if isinstance(path, str):
         path = Path(path)
     if path.exists():
@@ -56,7 +57,8 @@ def test_nii(path: Path | str | BIDS_FILE):
     return True
 
 
-def _find_all_broken(path: str = "TODO/dataset-nako/", parents=None):
+def _find_all_broken(path: str = "TODO/dataset-nako/", parents: list[str] | None = None) -> None:
+    """Scan a BIDS dataset for unreadable NIfTI files and append them to a pickle log."""
     brocken = []
     subj_id = 0
     with open("broken.pkl", "rb") as w:
@@ -86,7 +88,17 @@ def _find_all_broken(path: str = "TODO/dataset-nako/", parents=None):
 source_folder_encrypted_alternative = Path("Nachlieferung")
 
 
-def _test_and_replace(out_folder="~/dataset-nako"):
+def _test_and_replace(out_folder: str = "~/dataset-nako") -> None:
+    """Re-extract corrupted NIfTI files from the original DICOM archives.
+
+    Reads the list of broken files produced by :func:`_find_all_broken`,
+    locates the corresponding DICOM zip archive in the encrypted source
+    folders, re-extracts it, and verifies the result.
+
+    Args:
+        out_folder: Target BIDS dataset directory where re-extracted files are
+            written.
+    """
     from TPTBox.core.dicom.dicom_extract import extract_dicom_folder
 
     with open("TODO", "rb") as w:
diff --git a/TPTBox/core/dicom/nii2dicom.py b/TPTBox/core/dicom/nii2dicom.py
index 8ebd8f0..9cca9c0 100644
--- a/TPTBox/core/dicom/nii2dicom.py
+++ b/TPTBox/core/dicom/nii2dicom.py
@@ -14,7 +14,21 @@
 from TPTBox import Print_Logger
 
 
-def writeSlices(series_tag_values: dict, new_img: sitk.Image, i, out_dir: str | Path, name="slice"):
+def writeSlices(series_tag_values: dict, new_img: sitk.Image, i: int, out_dir: str | Path, name: str = "slice") -> None:
+    """Write a single axial slice of a SimpleITK image as a DICOM file.
+
+    Applies shared series-level DICOM tags and slice-specific tags (instance
+    creation date/time, image position, instance number) before writing.
+
+    Args:
+        series_tag_values: Dict of DICOM tag keys (e.g. ``"0008|0060"``) to
+            values that are shared by all slices in the series.
+        new_img: 3-D SimpleITK image from which the slice is extracted.
+        i: Zero-based slice index along the Z axis.
+        out_dir: Directory where the DICOM file is written.
+        name: Filename prefix; the output file is named
+            ``<name><i:04d>.dcm``.
+    """
     image_slice: sitk.Image = new_img[:, :, i]
     writer = sitk.ImageFileWriter()
     writer.KeepOriginalImageUIDOn()
@@ -41,17 +55,34 @@ def writeSlices(series_tag_values: dict, new_img: sitk.Image, i, out_dir: str |
 
 
 def nifti2dicom_1file(
-    in_nii: str | Path, out_dir: str | Path, no_json_ok=False, secondary=False, json_path: None | str | Path = None, out_name="slice"
-):
-    """
-    This function converts one NIfTI file into a DICOM series.
-
-    Parameters:
-    - in_nii: Path to the NIfTI file
-    - out_dir: Path to the output directory
-    - no_json_ok: Whether to proceed without a JSON metadata file
-    - secondary: Whether the images are derived/secondary
-    - json_path: Optional path to the JSON metadata file
+    in_nii: str | Path,
+    out_dir: str | Path,
+    no_json_ok: bool = False,
+    secondary: bool = False,
+    json_path: None | str | Path = None,
+    out_name: str = "slice",
+) -> None:
+    r"""Convert a single NIfTI file to a DICOM series.
+
+    Reads DICOM metadata from a sidecar JSON file (BIDSy format) when
+    available, generates unique Series/Study Instance UIDs, and writes one
+    DICOM file per axial slice.
+
+    Args:
+        in_nii: Path to the input NIfTI file.
+        out_dir: Output directory; created automatically if it does not exist.
+        no_json_ok: If ``True``, proceed even when no JSON sidecar is found.
+            If ``False``, raises :class:`FileNotFoundError` when the sidecar
+            is missing.
+        secondary: If ``True``, marks the DICOM series as
+            ``DERIVED\\SECONDARY``.
+        json_path: Explicit path to the JSON metadata file. Defaults to the
+            NIfTI stem with ``.json`` extension.
+        out_name: Filename prefix for the individual DICOM slice files.
+
+    Raises:
+        FileNotFoundError: If the JSON sidecar is not found and
+            ``no_json_ok`` is ``False``.
     """
     out_dir = Path(out_dir)
     out_dir.mkdir(exist_ok=True)
@@ -108,15 +139,16 @@ def nifti2dicom_1file(
         writeSlices(series_tag_values, new_img, i, out_dir, name=out_name)
 
 
-def nifti2dicom_mfiles(nifti_dir, out_dir=""):
-    """
-    This function converts multiple NIfTI files into DICOM series.
+def nifti2dicom_mfiles(nifti_dir: str | Path, out_dir: str | Path = "") -> None:
+    """Convert all NIfTI files in a directory to individual DICOM series.
 
-    Parameters:
-    - nifti_dir: Path to the directory containing NIfTI files
-    - out_dir: Path to the output directory
+    Each ``.nii.gz`` file in ``nifti_dir`` is converted by calling
+    :func:`nifti2dicom_1file`. Output sub-directories are created automatically.
 
-    Each NIfTI file's folder will be created automatically, so no need to create an empty folder for each patient.
+    Args:
+        nifti_dir: Directory containing ``.nii.gz`` files to convert.
+        out_dir: Root output directory. Each NIfTI file's series is placed in
+            a sub-directory named after the file stem.
     """
     images = glob(nifti_dir + "/*.nii.gz")  # noqa: PTH207
 
diff --git a/TPTBox/core/internal/ants_load.py b/TPTBox/core/internal/ants_load.py
index c9bc01e..c2505c9 100644
--- a/TPTBox/core/internal/ants_load.py
+++ b/TPTBox/core/internal/ants_load.py
@@ -8,19 +8,23 @@
     from nibabel.nifti1 import Nifti1Image
 
 
-def nifti_to_ants(nib_image: Nifti1Image, **args):
-    """
-    Convert a Nifti image to an ANTsPy image.
+def nifti_to_ants(nib_image: Nifti1Image, **args) -> object:
+    """Convert a NiBabel NIfTI image to an ANTsPy image.
+
+    First attempts to use :func:`ants.utils.from_nibabel_nifti`. Falls back to
+    manually constructing the ANTs image from the q-form affine when the built-in
+    conversion raises an exception (e.g. for non-3D images or unusual metadata).
+
+    Args:
+        nib_image: The NiBabel NIfTI image to convert.
+        **args: Additional keyword arguments forwarded to
+            :func:`ants.utils.from_nibabel_nifti` when available.
 
-    Parameters
-    ----------
-    nib_image : Nifti1Image
-        The Nifti image to be converted.
+    Returns:
+        The converted ``ants.ANTsImage``.
 
-    Returns
-    -------
-    ants_image : ants.ANTsImage
-        The converted ANTs image.
+    Raises:
+        NotImplementedError: If the image has fewer than 3 spatial dimensions.
     """
     import ants
 
@@ -53,18 +57,24 @@ def nifti_to_ants(nib_image: Nifti1Image, **args):
 
 
 def get_ras_affine_from_ants(ants_img) -> np.ndarray:
-    """
-    Convert ANTs image affine to RAS coordinate system.
-    Source: https://github.com/fepegar/torchio/blob/main/src/torchio/data/io.py
-    Parameters
-    ----------
-    ants_img : ants.ANTsImage
-        The ANTs image whose affine is to be converted.
-
-    Returns
-    -------
-    affine : np.ndarray
-        The affine matrix in RAS coordinates.
+    """Convert an ANTs image affine matrix to the RAS coordinate system.
+
+    Adapted from
+    https://github.com/fepegar/torchio/blob/main/src/torchio/data/io.py.
+    Handles 3-D (direction length 9), 2-D (direction length 4), and
+    degenerate 4-D (direction length 16) cases.
+
+    Args:
+        ants_img: An ``ants.ANTsImage`` whose LPS-convention affine is to be
+            converted.
+
+    Returns:
+        A ``(4, 4)`` NumPy affine matrix in RAS coordinates compatible with
+        NiBabel conventions.
+
+    Raises:
+        NotImplementedError: If the direction matrix has an unexpected number
+            of elements.
     """
     spacing = np.array(ants_img.spacing)
     direction_lps = np.array(ants_img.direction)
@@ -97,20 +107,20 @@ def get_ras_affine_from_ants(ants_img) -> np.ndarray:
 
 
 def ants_to_nifti(img, header=None) -> Nifti1Image:
-    """
-    Convert an ANTs image to a Nifti image.
-
-    Parameters
-    ----------
-    img : ants.ANTsImage
-        The ANTs image to be converted.
-    header : Nifti1Header, optional
-        Optional header to use for the Nifti image.
-
-    Returns
-    -------
-    img : Nifti1Image
-        The converted Nifti image.
+    """Convert an ANTsPy image to a NiBabel NIfTI image.
+
+    First attempts to use :func:`ants.utils.to_nibabel_nifti`. Falls back to
+    manually building a :class:`~nibabel.nifti1.Nifti1Image` from the RAS affine
+    when the built-in conversion raises an exception.
+
+    Args:
+        img: An ``ants.ANTsImage`` to convert.
+        header: Optional :class:`~nibabel.nifti1.Nifti1Header` to attach to the
+            output image. The data dtype is updated to match the array dtype when
+            provided.
+
+    Returns:
+        The converted :class:`~nibabel.nifti1.Nifti1Image`.
     """
     import ants
 
diff --git a/TPTBox/core/internal/deep_learning_utils.py b/TPTBox/core/internal/deep_learning_utils.py
index 975510d..288ebae 100644
--- a/TPTBox/core/internal/deep_learning_utils.py
+++ b/TPTBox/core/internal/deep_learning_utils.py
@@ -7,7 +7,21 @@
 DEVICES = Literal["cpu", "cuda", "mps"]
 
 
-def get_device(ddevice: DEVICES, gpu_id: int):
+def get_device(ddevice: DEVICES, gpu_id: int) -> torch.device:
+    """Construct a :class:`torch.device` from a device type string and GPU index.
+
+    Args:
+        ddevice: Target device type — one of ``"cpu"``, ``"cuda"``, or
+            ``"mps"``.
+        gpu_id: CUDA device index (only used when ``ddevice`` is ``"cuda"``).
+
+    Returns:
+        A :class:`torch.device` configured for the requested backend.
+
+    Raises:
+        AssertionError: Via :func:`~TPTBox.core.vert_constants.never_called`
+            when ``ddevice`` is not one of the recognised values.
+    """
     if ddevice == "cpu":
         # import multiprocessing
 
diff --git a/TPTBox/core/internal/elastic_deform.py b/TPTBox/core/internal/elastic_deform.py
index 82c8274..29aecbf 100644
--- a/TPTBox/core/internal/elastic_deform.py
+++ b/TPTBox/core/internal/elastic_deform.py
@@ -16,8 +16,7 @@ def deformed_nii(
     normalize=True,
     joint_normalize=False,
 ) -> dict[str, NII]:
-    """
-    Deform a dictionary of NII objects using random grid deformation. Requires elasticdeform. 'pip install elasticdeform'
+    """Deform a dictionary of NII objects using random grid deformation (requires ``pip install elasticdeform``).
 
     IMPORTANT: Normalize your image data to 0,1. The .seg property of NII shows if this is a segmentation. (NII is form our TPTBox and is a wrapper for nibable)
 
@@ -78,13 +77,13 @@ def deformed_nii(
     return out2
 
 
-def pad(arr, p=10):
+def pad(arr: np.ndarray, p: int = 10) -> np.ndarray:
+    """Reflect-pad a 3-D array by ``p`` voxels on every side."""
     return np.pad(arr, p, mode="reflect")
 
 
-def get_random_deform_parameter(deform_factor: float = 1):
-    """
-    Generate random deformation parameters for use in 3D deformation.
+def get_random_deform_parameter(deform_factor: float = 1) -> tuple[float, int]:
+    """Generate random deformation parameters for use in 3D deformation.
 
     This function generates random values for the deformation parameters, including 'sigma' and 'points',
     based on the specified deformation factor. These parameters are used for 3D deformation operations.
diff --git a/TPTBox/core/internal/nii_help.py b/TPTBox/core/internal/nii_help.py
index 2883abf..b677bf8 100644
--- a/TPTBox/core/internal/nii_help.py
+++ b/TPTBox/core/internal/nii_help.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import shutil
+from collections.abc import Callable
 from functools import wraps
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -16,16 +17,11 @@
 from TPTBox.core.vert_constants import AFFINE, MODES, SHAPE, ZOOMS, Sentinel, _supported_img_files
 
 
-def secure_save(func):
-    """
-    A decorator that ensures a safe file-saving process by creating a backup of the target file before
-    overwriting it and restoring the backup if an error occurs during the save operation.
+def secure_save(func) -> Callable:
+    """Decorator that writes to a `.backup` file first and restores it if saving fails.
 
-    The decorator wraps a function that takes a file path as one of its arguments and adds the following safety steps:
-    1. If the target file exists, create a backup with a `.backup` suffix.
-    2. Call the wrapped function to perform the file-saving operation.
-    3. If the save is successful, delete the backup.
-    4. If an error occurs, restore the backup and clean up any partially written files.
+    Steps: (1) back up existing file, (2) call the wrapped save function, (3) delete backup on
+    success, or (4) restore backup and clean up on error.
 
     Args:
         func (callable): The function to be wrapped. It should take a file path (`str`, `Path`, or `bids_files.BIDS_FILE`)
@@ -88,10 +84,38 @@ def wrapper(self, file: str | Path | bids_files.BIDS_FILE, *args, **kwargs):
 def _resample_from_to(
     from_img: NII,
     to_img: tuple[SHAPE, AFFINE, ZOOMS] | Has_Grid,
-    order=3,
+    order: int = 3,
     mode: MODES = "nearest",
     align_corners: bool | Sentinel = Sentinel(),  # noqa: B008
-):
+) -> tuple[np.ndarray, np.ndarray, object]:
+    """Resample *from_img* into the voxel space defined by *to_img*.
+
+    Implements an optional ``align_corners`` mode (analogous to PyTorch) for
+    order-0 (nearest-neighbour) interpolation by adjusting both affines so that
+    voxel corners rather than voxel centres are aligned.
+
+    Args:
+        from_img: Source NII image to be resampled.
+        to_img: Target space, given either as a ``(shape, affine, zooms)`` tuple
+            or as any object that implements the ``Has_Grid`` interface (providing
+            ``shape_int``, ``affine``, and ``zoom`` attributes).
+        order: Spline interpolation order (0 = nearest, 1 = linear, 3 = cubic).
+        mode: Border handling mode passed to ``scipy.ndimage.affine_transform``
+            (e.g. ``"nearest"``, ``"constant"``).
+        align_corners: When ``True`` (or when left as a ``Sentinel`` and
+            ``order == 0``), voxel corners are aligned between source and target
+            grids.  When ``False``, voxel centres are aligned (standard
+            nibabel/scipy behaviour).
+
+    Returns:
+        A 3-tuple ``(data, affine, header)`` where *data* is the resampled
+        NumPy array, *affine* is the target affine matrix, and *header* is the
+        NIfTI header taken from *from_img*.
+
+    Raises:
+        AffineError: If *from_img* has fewer than 3 spatial dimensions.
+        ValueError: If *from_img* does not have spatial axes first.
+    """
     import numpy.linalg as npl
     import scipy.ndimage as scipy_img
     from nibabel.affines import AffineError, to_matvec
diff --git a/TPTBox/core/internal/slicer_nrrd.py b/TPTBox/core/internal/slicer_nrrd.py
index 17fb9fc..e694d8d 100644
--- a/TPTBox/core/internal/slicer_nrrd.py
+++ b/TPTBox/core/internal/slicer_nrrd.py
@@ -15,7 +15,7 @@
 
 
 def _read(filename, skip_voxels=False, verbos=True):
-    """Read segmentation metadata from a .seg.nrrd file or NIFTI file and store it in a dict.
+    r"""Read segmentation metadata from a .seg.nrrd file or NIFTI file and store it in a dict.
 
     Example header:
 
@@ -302,10 +302,20 @@ def _read(filename, skip_voxels=False, verbos=True):
     return segmentation
 
 
-def _write_segmentation(file, segmentation, compression_level=9, index_order=None):
-    """
-    Extracts segments from a segmentation volume and header.
-    :param segmentation: segmentation metadata and voxels
+def _write_segmentation(file: str, segmentation: dict, compression_level: int = 9, index_order: str | None = None) -> None:
+    """Write a segmentation dictionary to a 3D Slicer-compatible NRRD file.
+
+    Args:
+        file: Destination file path (must be a string as accepted by pynrrd).
+        segmentation: Dictionary with keys ``"voxels"`` (numpy array), ``"ijkToLPS"``
+            (4x4 affine), and optional segment metadata.
+        compression_level: gzip compression level (0-9). Defaults to 9.
+        index_order: NRRD index order (``"C"`` or ``"F"``). Defaults to ``"F"``.
+
+    Raises:
+        ImportError: If the ``pynrrd`` package is not installed.
+        ValueError: If the voxel array is ``None`` or has an unsupported number
+            of dimensions.
     """
     try:
         import nrrd
@@ -319,7 +329,7 @@ def _write_segmentation(file, segmentation, compression_level=9, index_order=Non
     # Copy non-segmentation fields to the extracted header
     output_header = {}
     ijkToLPS = None
-    for key in segmentation:
+    for key, value in segmentation.items():
         if key == "voxels":
             # written separately
             continue
@@ -328,17 +338,17 @@ def _write_segmentation(file, segmentation, compression_level=9, index_order=Non
             continue
         elif key == "ijkToLPS":
             # image geometry will be set later in space directions, space origin fields
-            ijkToLPS = segmentation[key]
+            ijkToLPS = value
             continue
         elif key == "containedRepresentationNames":
             # Segmentation_ContainedRepresentationNames:=Binary labelmap|Closed surface|
             # An extra closing "|" is added as this is requires by some older Slicer versions.
-            representations = "|".join(segmentation[key]) + "|"
+            representations = "|".join(value) + "|"
             output_header["Segmentation_ContainedRepresentationNames"] = representations
         elif key == "conversionParameters":
             # Segmentation_ConversionParameters:=Collapse labelmaps|1|Merge the labelmaps into as few...&Compute surface normals|1|Compute...&Crop to reference image geometry|0|Crop the model...&
             parameters_str = ""
-            parameters = segmentation[key]
+            parameters = value
             for parameter in parameters:
                 if parameters_str != "":
                     parameters_str += "&"
@@ -346,13 +356,13 @@ def _write_segmentation(file, segmentation, compression_level=9, index_order=Non
             output_header["Segmentation_ConversionParameters"] = parameters_str
         elif key == "masterRepresentation":
             # Segmentation_MasterRepresentation:=Binary labelmap
-            output_header["Segmentation_MasterRepresentation"] = segmentation[key]
+            output_header["Segmentation_MasterRepresentation"] = value
         elif key == "referenceImageExtentOffset":
             # Segmentation_ReferenceImageExtentOffset:=0 0 0
-            offset = segmentation[key]
+            offset = value
             output_header["Segmentation_ReferenceImageExtentOffset"] = " ".join([str(i) for i in offset])
         else:
-            output_header[key] = segmentation[key]
+            output_header[key] = value
 
     # Add kinds, space directions, space origin to the header
     # kinds: list domain domain domain
@@ -551,7 +561,6 @@ def _terminology_entry_from_string(terminology_str):
     Specification of terminology entry string is available at
     https://slicer.readthedocs.io/en/latest/developer_guide/modules/segmentations.html#terminologyentry-tag
     """
-
     terminology_items = terminology_str.split("~")
 
     terminology = {}
@@ -576,8 +585,8 @@ def _terminology_entry_from_string(terminology_str):
     return terminology
 
 
-def _terminology_entry_to_string(terminology):
-    """Converts a terminology dict to string."""
+def _terminology_entry_to_string(terminology: dict) -> str:
+    """Convert a terminology dictionary back to the Slicer ``TerminologyEntry`` tag string."""
     terminology_str = ""
 
     if "contextName" in terminology:
@@ -601,9 +610,8 @@ def _terminology_entry_to_string(terminology):
     return terminology_str
 
 
-def _generate_unique_segment_id(existing_segment_ids):
-    """Generate a unique segment ID, i.e., an ID that is not among existing_segment_ids.
-    It follows DICOM convention to allow using this ID in DICOM Segmentation objects."""
+def _generate_unique_segment_id(existing_segment_ids: set) -> str:
+    """Generate a DICOM-compatible UUID-based segment ID not present in *existing_segment_ids*."""
     import uuid
 
     while True:
@@ -612,7 +620,15 @@ def _generate_unique_segment_id(existing_segment_ids):
             return segment_id
 
 
-def remove_not_supported_values(nrrd_dict: dict):
+def remove_not_supported_values(nrrd_dict: dict) -> None:
+    """Strip NRRD fields that cannot be round-tripped through the current writer.
+
+    Removes ``"conversionParameters"`` from the top-level dict and ``"extent"``
+    from each segment entry, as these are not reliably preserved.
+
+    Args:
+        nrrd_dict: Segmentation dictionary to clean in place.
+    """
     nrrd_dict.pop("conversionParameters", None)
 
     if "segments" in nrrd_dict:
@@ -621,14 +637,28 @@ def remove_not_supported_values(nrrd_dict: dict):
             i.pop("extent", None)
 
 
-def load_slicer_nrrd(filename, seg, skip_voxels=False, verbos=True) -> NII:
-    """
-    Load a 3D/4D Slicer NRRD segmentation and return a NII object (wrapper around NIfTI).
+def load_slicer_nrrd(filename: str | Path, seg: bool, skip_voxels: bool = False, verbos: bool = True) -> NII:
+    """Load a 3D Slicer ``.seg.nrrd`` segmentation file and return a NII wrapper.
+
+    Reads the NRRD header and optional voxel data, converts the LPS affine to
+    RAS for NIfTI compatibility, and packages the result as a ``NII`` object.
+
+    Args:
+        filename: Path to the ``.seg.nrrd`` file.
+        seg: Set to ``True`` when the file contains a segmentation (label map)
+            rather than raw intensity data.
+        skip_voxels: Read only the NRRD header without loading voxel data when
+            ``True``.  The returned ``NII`` will have ``None`` for its array.
+        verbos: Emit log messages for missing segment IDs when ``True``.
+
+    Returns:
+        A ``NII`` instance wrapping the loaded image with its affine, segment
+        metadata stored in ``NII.info``, and ``seg`` set accordingly.
 
-    :param filename: path to .seg.nrrd file
-    :param skip_voxels: if True, only metadata is read
-    :param logging: logger
-    :return: NII object with segmentation data
+    Raises:
+        ImportError: If the ``pynrrd`` package is not installed.
+        ValueError: If the file does not contain voxel data (when *skip_voxels*
+            is ``False``).
     """
     import nibabel as nib
     import numpy as np
@@ -662,16 +692,30 @@ def load_slicer_nrrd(filename, seg, skip_voxels=False, verbos=True) -> NII:
     return NII(nib_obj, seg=seg, c_val=c_val, desc="", info=nrrd_dict)
 
 
-def save_slicer_nrrd(nii: NII, file: str | Path, make_parents=True, verbose: logging = True, compression_level=9, index_order=None):
+def save_slicer_nrrd(
+    nii: NII,
+    file: str | Path,
+    make_parents: bool = True,
+    verbose: logging = True,
+    compression_level: int = 9,
+    index_order: str | None = None,
+) -> None:
+    """Save a NII image or segmentation to a 3D Slicer-compatible NRRD file.
+
+    Converts the NIfTI RAS affine to LPS as required by the NRRD/Slicer
+    convention, then delegates to ``_write_segmentation``.  If *file* does not
+    end with ``"nrrd"``, a ``.seg.nrrd`` (for segmentations) or ``.nrrd`` suffix
+    is appended automatically.
+
+    Args:
+        nii: ``NII`` object whose array and affine are to be saved.
+        file: Destination file path.
+        make_parents: Create missing parent directories when ``True``.
+        verbose: Print a save message to the logger when ``True``.
+        compression_level: gzip compression level (0-9). Defaults to 9.
+        index_order: NRRD index order (``"C"`` or ``"F"``). Defaults to ``"F"``
+            (Fortran / column-major, as expected by Slicer).
     """
-    Save a NII object (segmentation) to a Slicer-compatible NRRD file.
-
-    :param nii: NII object with seg=True
-    :param filename: path to save .seg.nrrd
-    :param compression_level: gzip compression level
-    :param index_order: NRRD index order, e.g., "F" for Fortran
-    """
-
     if not str(file).endswith("nrrd"):
         file = str(file) + (".seg.nrrd" if nii.seg else ".nrrd")
     if make_parents:
@@ -752,7 +796,7 @@ def save_slicer_nrrd(nii: NII, file: str | Path, make_parents=True, verbose: log
 
     slicerio_data = Path(__file__).parent / "slicerio_data"
 
-    def download_file(url: str, out_path: str):
+    def download_file(url: str, out_path: str) -> None:
         """Download a URL to a local file."""
         resp = requests.get(url, stream=True)
         resp.raise_for_status()
@@ -776,7 +820,8 @@ def download_file(url: str, out_path: str):
             download_file(url, out_local)
 
     # Test loading/saving
-    def test_file(path: str):
+    def test_file(path: str) -> None:
+        """Load a Slicer NRRD file, print its shape, and save a roundtrip copy."""
         print(f"\nTesting: {path}")
         seg = "seg." in path
         # Load
diff --git a/TPTBox/core/nii_poi_abstract.py b/TPTBox/core/nii_poi_abstract.py
index 9a8865b..d086180 100755
--- a/TPTBox/core/nii_poi_abstract.py
+++ b/TPTBox/core/nii_poi_abstract.py
@@ -3,7 +3,7 @@
 import sys
 import warnings
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import nibabel as nib
 import nibabel.orientations as nio
@@ -31,8 +31,11 @@
 )
 
 if TYPE_CHECKING:
+    from TPTBox import NII, POI
 
     class Grid_Proxy:
+        """Type-checking stub declaring the grid geometry attributes expected on NII and POI."""
+
         affine: AFFINE
         rotation: ROTATION
         zoom: ZOOMS
@@ -44,29 +47,45 @@ class Grid_Proxy:
 else:
 
     class Grid_Proxy:
-        pass
+        """Runtime placeholder for Grid_Proxy; real attribute declarations live in the TYPE_CHECKING branch."""
 
 
 class Has_Grid(Grid_Proxy):
-    """Parent class for methods that are shared by POI and NII"""
+    """Parent class for methods that are shared by POI and NII."""
 
     info: dict
 
     def to_gird(self) -> Grid:
+        """Convert this object's grid metadata into a standalone :class:`Grid` instance.
+
+        Returns:
+            Grid: A new ``Grid`` object populated with the same affine metadata.
+        """
         return Grid(**self._extract_affine())
 
     @property
-    def shape_int(self):
+    def shape_int(self) -> tuple[int, ...] | None:
+        """Return the image shape as a tuple of Python ints (rounded from float shapes).
+
+        Returns:
+            tuple[int, ...] | None: Integer shape tuple, or None if shape is not set.
+        """
         if self.shape is None:
             return None
         return tuple(np.rint(list(self.shape)).astype(int).tolist())
 
     @property
-    def spacing(self):
+    def spacing(self) -> ZOOMS:
+        """Voxel spacing (alias for :attr:`zoom`).
+
+        Returns:
+            ZOOMS: Voxel size in mm along each axis.
+        """
         return self.zoom
 
     @spacing.setter
     def spacing(self, value: ZOOMS):
+        """Set voxel spacing (alias for setting :attr:`zoom`)."""
         self.zoom = value
 
     def __str__(self) -> str:
@@ -83,7 +102,15 @@ def __str__(self) -> str:
         return f"shape={self.shape_int},spacing={zoom}, origin={origin}, ori={self.orientation}"  # type: ignore
 
     @property
-    def affine(self):
+    def affine(self) -> np.ndarray:
+        """Construct the 4x4 affine matrix from rotation, zoom, and origin.
+
+        Returns:
+            np.ndarray: 4x4 homogeneous affine matrix rounded to ``ROUNDING_LVL`` decimals.
+
+        Raises:
+            AssertionError: If any of ``zoom``, ``rotation``, or ``origin`` is not set.
+        """
         assert self.zoom is not None, "Attribute 'zoom' must be set before calling affine."
         assert self.rotation is not None, "Attribute 'rotation' must be set before calling affine."
         assert self.origin is not None, "Attribute 'origin' must be set before calling affine."
@@ -94,6 +121,11 @@ def affine(self):
 
     @affine.setter
     def affine(self, affine: np.ndarray):
+        """Decompose a 4x4 affine matrix and store rotation, zoom, and origin.
+
+        Args:
+            affine (np.ndarray): 4x4 homogeneous affine matrix.
+        """
         rotation_zoom = affine[:3, :3]
         zoom = np.sqrt(np.sum(rotation_zoom * rotation_zoom, axis=0))
         rotation_zoom = affine[:3, :3]
@@ -104,6 +136,7 @@ def affine(self, affine: np.ndarray):
         self.origin = origin.tolist()
 
     def _extract_affine(self: Has_Grid, rm_key=(), **args):
+        """Return a dict of affine metadata suitable for constructing a Grid or similar object."""
         shape = self.shape_int if self.shape is not None else None
         out = {
             "zoom": self.spacing,
@@ -124,9 +157,8 @@ def change_affine(
         scaling=None,
         degrees=True,
         inplace=False,
-    ):
-        """
-        Apply a transformation (scaling, rotation, translation) to the affine matrix.
+    ) -> Self:
+        """Apply a transformation (scaling, rotation, translation) to the affine matrix.
 
         Assumptions
         -----------
@@ -161,7 +193,7 @@ def change_affine(
         inplace : bool, default=False
             Whether to modify the object in place.
 
-        Returns
+        Returns:
         -------
         self or copy of self
             Object with updated affine.
@@ -195,7 +227,8 @@ def change_affine(
         self.affine = transform @ self.affine
         return self
 
-    def change_affine_(self, translation=None, rotation_degrees=None, scaling=None, degrees=True):
+    def change_affine_(self, translation=None, rotation_degrees=None, scaling=None, degrees=True) -> Self:
+        """In-place variant of `change_affine`."""
         return self.change_affine(
             translation=translation,
             rotation_degrees=rotation_degrees,
@@ -205,6 +238,14 @@ def change_affine_(self, translation=None, rotation_degrees=None, scaling=None,
         )
 
     def copy(self) -> Self:
+        """Return a deep copy of this object.
+
+        Returns:
+            Self: A new instance of the same type with the same attributes.
+
+        Raises:
+            NotImplementedError: Subclasses must override this method.
+        """
         raise NotImplementedError(
             "The copy method must be implemented in the subclass. It should return a new instance of the same type with the same attributes."
         )
@@ -225,8 +266,8 @@ def assert_affine(
         raise_error: bool = True,
         verbose: logging = False,
         text: str = "",
-    ):
-        """Checks if the different metadata is equal to some comparison entries
+    ) -> bool:
+        """Checks if the different metadata is equal to some comparison entries.
 
         Args:
             other (Has_Grid | None, optional): If set, will assert each entry of that object instead. Defaults to None.
@@ -323,6 +364,7 @@ def get_plane(self, res_threshold: float | None = 1) -> str:
                 - 'cor': Coronal plane (along the y-axis).
                 - 'sag': Sagittal plane (along the x-axis).
                 - 'iso': Isotropic plane (if the image has equal zoom values along all axes).
+
         Examples:
             >>> nii = NII(nib.load("my_image.nii.gz"))
             >>> nii.get_plane()
@@ -342,12 +384,32 @@ def get_plane(self, res_threshold: float | None = 1) -> str:
             plane = "iso"
         return plane
 
-    def get_axis(self, direction: DIRECTIONS = "S"):
+    def get_axis(self, direction: DIRECTIONS = "S") -> int:
+        """Return the axis index corresponding to the given anatomical direction.
+
+        If the exact direction is not found in the orientation tuple, the
+        opposite direction is used (e.g. "S" falls back to "I").
+
+        Args:
+            direction (DIRECTIONS, optional): Anatomical direction code (e.g. ``"S"``,
+                ``"R"``, ``"A"``). Defaults to ``"S"``.
+
+        Returns:
+            int: Zero-based axis index (0, 1, or 2).
+        """
         if direction not in self.orientation:
             direction = _same_direction[direction]
         return self.orientation.index(direction)
 
-    def make_empty_POI(self, points: dict | None = None):
+    def make_empty_POI(self, points: dict | None = None) -> POI:
+        """Create an empty POI object sharing the same grid metadata as this object.
+
+        Args:
+            points (dict | None, optional): Initial point dictionary. Defaults to an empty dict.
+
+        Returns:
+            POI: A new POI instance with the same orientation, zoom, shape, rotation and origin.
+        """
         from TPTBox import POI
 
         p = {} if points is None else points
@@ -366,7 +428,21 @@ def make_empty_POI(self, points: dict | None = None):
             **args,
         )
 
-    def make_empty_nii(self, seg=False, _arr=None):
+    def make_empty_nii(self, seg=False, _arr=None) -> NII:
+        """Create a NII image filled with zeros (or a given array) using this object's grid.
+
+        Args:
+            seg (bool, optional): If True, mark the resulting NII as a segmentation.
+                Defaults to False.
+            _arr (np.ndarray | None, optional): Pre-built array to use as image data.
+                Must match ``shape_int`` if provided. Defaults to None (zeros).
+
+        Returns:
+            NII: New NII instance with the same affine and the given or zero-filled data.
+
+        Raises:
+            AssertionError: If ``_arr`` shape does not match ``shape_int``.
+        """
         from TPTBox import NII
 
         if _arr is None:
@@ -378,7 +454,7 @@ def make_empty_nii(self, seg=False, _arr=None):
         nii = nib.Nifti1Image(_arr, affine=self.affine)
         return NII(nii, seg=seg)
 
-    def make_nii(self, arr: np.ndarray | None = None, seg=False):
+    def make_nii(self, arr: np.ndarray | None = None, seg=False) -> NII:
         """Make a nii with the same grid as object. Shape must fit the Grid.
 
         Args:
@@ -392,15 +468,52 @@ def make_nii(self, arr: np.ndarray | None = None, seg=False):
             arr = np.zeros(self.shape_int)
         return self.make_empty_nii(_arr=arr, seg=seg)
 
-    def global_to_local(self, x: COORDINATE):
+    def global_to_local(self, x: COORDINATE) -> tuple:
+        """Convert world (RAS/LPS) coordinates to voxel (local) coordinates.
+
+        Applies the inverse affine transform: rotation-transpose times
+        (world_point - origin), then divided by voxel spacing.
+
+        Args:
+            x (COORDINATE): World-space coordinate as a 3-element sequence.
+
+        Returns:
+            tuple: Voxel-space coordinate rounded to 7 decimal places.
+        """
         a = self.rotation.T @ (np.array(x) - self.origin) / np.array(self.zoom)
         return tuple(round(float(v), 7) for v in a)
 
-    def local_to_global(self, x: COORDINATE):
+    def local_to_global(self, x: COORDINATE) -> tuple:
+        """Convert voxel (local) coordinates to world (RAS/LPS) coordinates.
+
+        Applies the forward affine transform: rotation times
+        (voxel_point * spacing) plus origin.
+
+        Args:
+            x (COORDINATE): Voxel-space coordinate as a 3-element sequence.
+
+        Returns:
+            tuple: World-space coordinate rounded to 7 decimal places.
+        """
         a = self.rotation @ (np.array(x) * np.array(self.zoom)) + self.origin
         return tuple(round(float(v), 7) for v in a)
 
-    def to_deepali_grid(self, align_corners: bool = True):
+    def to_deepali_grid(self, align_corners: bool = True) -> Any:
+        """Convert the grid metadata to a DeepALI ``Grid`` object.
+
+        Coordinates are converted from the NIfTI RAS convention to the ITK/LPS
+        convention used by DeepALI (the first two axes are negated).
+
+        Args:
+            align_corners (bool, optional): Passed to ``grid.align_corners_()``.
+                Defaults to True.
+
+        Returns:
+            deepali.core.Grid: DeepALI grid in LPS convention.
+
+        Raises:
+            ImportError: If the ``hf-deepali`` package is not installed.
+        """
         try:
             from deepali.core import Grid
         except Exception:
@@ -431,6 +544,20 @@ def to_deepali_grid(self, align_corners: bool = True):
 
     @classmethod
     def from_deepali_grid(cls, grid):
+        """Construct a :class:`Grid` from a DeepALI ``Grid`` object.
+
+        Coordinates are converted from the ITK/LPS convention used by DeepALI
+        back to the NIfTI RAS convention (the first two axes are negated).
+
+        Args:
+            grid (deepali.core.Grid): A DeepALI grid in LPS convention.
+
+        Returns:
+            Grid: A TPTBox ``Grid`` instance with RAS-convention affine metadata.
+
+        Raises:
+            ImportError: If the ``hf-deepali`` package is not installed.
+        """
         try:
             from deepali.core import Grid as dp_Grid
         except Exception:
@@ -453,12 +580,19 @@ def from_deepali_grid(cls, grid):
 
         return grid
 
-    def get_num_dims(self):
+    def get_num_dims(self) -> int:
+        """Return the number of spatial dimensions.
+
+        Returns:
+            int: Number of dimensions (typically 3 for 3-D medical images).
+        """
         return len(self.shape)
 
 
 @dataclass
 class Grid(Has_Grid):
+    """Concrete grid geometry object constructed from affine, zoom, orientation, and related keyword arguments."""
+
     def __init__(self, **qargs) -> None:
         super().__init__()
         for k, v in qargs.items():
diff --git a/TPTBox/core/nii_wrapper.py b/TPTBox/core/nii_wrapper.py
index f23717d..18c3710 100755
--- a/TPTBox/core/nii_wrapper.py
+++ b/TPTBox/core/nii_wrapper.py
@@ -77,7 +77,8 @@
 _formatwarning = warnings.formatwarning
 
 
-def formatwarning_tb(*args, **kwargs):
+def formatwarning_tb(*args, **kwargs) -> str:
+    """Custom warning formatter that appends the current call stack to the warning message."""
     s = "####################################\n"
     s += _formatwarning(*args, **kwargs)
     tb = traceback.format_stack()[:-3]
@@ -99,6 +100,7 @@ def formatwarning_tb(*args, **kwargs):
 
 
 def _check_if_nifty_is_lying_about_its_dtype(self: NII):
+    """Infers the correct dtype by inspecting the actual value range of the NIfTI dataobj."""
     change_dtype = False
     arr = self.nii.dataobj
     dtype = self._nii.dataobj.dtype  # type: ignore
@@ -175,8 +177,7 @@ def _check_if_nifty_is_lying_about_its_dtype(self: NII):
 # fmt: off
 
 class NII(NII_Math):
-    """
-    The `NII` class represents a NIfTI image and provides various methods for manipulating and analyzing NIfTI images. It supports loading and saving NIfTI images, rescaling and reorienting images, applying operations on segmentation masks, and more.
+    """The `NII` class represents a NIfTI image and provides various methods for manipulating and analyzing NIfTI images. It supports loading and saving NIfTI images, rescaling and reorienting images, applying operations on segmentation masks, and more.
 
     Example Usage:
     ```python
@@ -244,7 +245,38 @@ def __init__(self, nii: Nifti1Image|_unpacked_nii, seg=False,c_val=None, desc:st
 
 
     @classmethod
-    def load(cls, path: Image_Reference, seg, c_val=None)-> Self:
+    def from_numpy(cls, arr: np.ndarray, affine: np.ndarray, seg=False, c_val=None, desc:str|None=None, info=None) -> Self:
+        """Creates an NII instance from a numpy array and an affine matrix.
+
+        Args:
+            arr: The voxel data array (shape must match the spatial dimensions implied by affine).
+            affine: A (4, 4) affine transformation matrix mapping voxel indices to world coordinates.
+            seg: Whether the image is a segmentation mask (integer-labelled). Defaults to False.
+            c_val: Background / fill value used during resampling. Defaults to None (inferred
+                from data for images; 0 for segmentations).
+            desc: Optional description string stored in the NIfTI header ``descrip`` field.
+            info: Optional dict of arbitrary metadata attached to this instance.
+
+        Returns:
+            A new NII wrapping the given array and affine.
+        """
+        nii = nib.nifti1.Nifti1Image(arr,affine)
+        return NII(nii=nii, seg=seg, c_val=c_val, desc=desc, info=info)
+
+    @classmethod
+    def load(cls, path: Image_Reference, seg: bool, c_val: float | None = None) -> Self:
+        """Loads a NIfTI image from a file path or image reference.
+
+        Args:
+            path: File path (str or Path), an existing NII, a Nifti1Image, or a BIDS_FILE
+                pointing to the image to load.
+            seg: Whether the image is a segmentation mask. When True the array dtype is
+                coerced to the smallest unsigned integer type that can hold all values.
+            c_val: Background / fill value. Defaults to None.
+
+        Returns:
+            A new NII loaded from the given path.
+        """
         nii= to_nii(path,seg)
         if seg:
             nii = nii.set_dtype("smallest_uint")
@@ -253,8 +285,7 @@ def load(cls, path: Image_Reference, seg, c_val=None)-> Self:
 
     @classmethod
     def load_nrrd(cls, path: str | Path, seg: bool,verbos=False):
-        """
-        Load an NRRD file and convert it into a Nifti1Image object.
+        """Load an NRRD file and convert it into a Nifti1Image object.
 
         Args:
             path (str | Path): The file path to the NRRD file to be loaded.
@@ -271,7 +302,6 @@ def load_nrrd(cls, path: str | Path, seg: bool,verbos=False):
             >>> nii = cls.load_nrrd("example.nrrd", seg=True)
             >>> print(nii)
         """
-
         try:
             import nrrd  # pip install pynrrd, if pynrrd is not already installed
         except ModuleNotFoundError:
@@ -279,7 +309,23 @@ def load_nrrd(cls, path: str | Path, seg: bool,verbos=False):
         from TPTBox.core.internal.slicer_nrrd import load_slicer_nrrd
         return load_slicer_nrrd(path,seg,verbos=verbos)
     @classmethod
-    def load_bids(cls, nii_bids: bids_files.BIDS_FILE):
+    def load_bids(cls, nii_bids: bids_files.BIDS_FILE) -> NII:
+        """Loads an NII from a BIDS_FILE object, inferring seg and c_val from the format.
+
+        Supports ``.nii``, ``.nii.gz``, ``.nrrd``, and any format readable by SimpleITK.
+        The ``seg`` flag is set to True when the BIDS file's interpolation order is 0
+        (i.e., it is a label map). CT images default to ``c_val=-1024``; others to 0.
+
+        Args:
+            nii_bids: A BIDS_FILE whose ``file`` dict contains at least one of the
+                supported image format keys.
+
+        Returns:
+            A new NII loaded from the BIDS file.
+
+        Raises:
+            AssertionError: If no readable image format is found in ``nii_bids``.
+        """
         nifty = None
         if "nii" in nii_bids.file:
             path = nii_bids.file['nii']
@@ -309,7 +355,8 @@ def load_bids(cls, nii_bids: bids_files.BIDS_FILE):
             c_val = -1024 if "ct" in nii_bids.format.lower() else 0
         assert nifty is not None, f"could not find {nii_bids}"
         return NII(nifty,seg,c_val) # type: ignore
-    def _unpack(self):
+    def _unpack(self) -> None:
+        """Materialises the lazy nibabel dataobj into an in-memory numpy array."""
         try:
             if self.__unpacked:
                 return
@@ -341,12 +388,22 @@ def _unpack(self):
             raise EOFError(f"{self.nii.get_filename()}: {e!s}\nThe file is probably brocken beyond repair, due killing a software during nifty saving.") from None
     @property
     def nii_abstract(self) -> Nifti1Image|_unpacked_nii:
+        """Returns the internal representation without forcing reconstruction of the Nifti1Image.
+
+        If the data has been unpacked (loaded into memory), returns the ``(array, affine, header)``
+        tuple. Otherwise returns the raw ``Nifti1Image``.
+        """
         if self.__unpacked:
             return self._arr,self.affine,self.header
         return self._nii
 
     @property
     def nii(self) -> Nifti1Image:
+        """Returns the underlying Nifti1Image, reconstructing it if the in-memory array has diverged.
+
+        The reconstruction synchronises the header dtype and slope/intercept values with the
+        current array. Use ``nii_abstract`` if you want to avoid this reconstruction overhead.
+        """
         if self.__divergent:
             self._nii = Nifti1Image(self._arr,self.affine,self.header)
             if self.dtype == self._arr.dtype: #type: ignore
@@ -405,11 +462,13 @@ def nii(self,nii:Nifti1Image|_unpacked_nii):
 
     @property
     def shape(self) -> tuple[int, int, int]:
+        """Spatial shape of the image array (x, y, z), or more dims for 4-D images."""
         if self.__unpacked:
             return tuple(self._arr.shape) # type: ignore
         return self.nii.shape # type: ignore
     @property
-    def dtype(self)->type:
+    def dtype(self) -> type:
+        """NumPy dtype of the voxel data array."""
         if self.__unpacked:
             return self._arr.dtype # type: ignore
         return self.nii.dataobj.dtype #type: ignore
@@ -418,11 +477,13 @@ def dtype(self, dtype:type):
         self.set_dtype_(dtype)
     @property
     def header(self) -> Nifti1Header:
+        """NIfTI-1 header associated with this image."""
         if self.__unpacked:
             return self._header
         return self.nii.header  # type: ignore
     @property
-    def affine(self) -> np.ndarray:
+    def affine(self) -> AFFINE:
+        """(4, 4) affine matrix mapping voxel indices to world (mm) coordinates."""
         if self.__unpacked:
             return self._aff # type: ignore
         return self.nii.affine # type: ignore
@@ -434,17 +495,20 @@ def affine(self,affine:np.ndarray):
         self._aff = affine
     @property
     def orientation(self) -> AX_CODES:
+        """Axis codes describing the image orientation, e.g. ``('R', 'A', 'S')``."""
         ort = nio.io_orientation(self.affine)
         return nio.ornt2axcodes(ort) # type: ignore
     @orientation.setter
     def orientation(self, value: AX_CODES):
         self.reorient_(value, verbose=False)
     @property
-    def dims(self)->int:
+    def dims(self) -> int:
+        """Number of spatial dimensions (typically 3 for a standard NIfTI volume)."""
         self._unpack()
         return self.affine.shape[0]-1
     @property
     def zoom(self) -> ZOOMS:
+        """Voxel sizes in mm along each spatial axis, e.g. ``(1.0, 1.0, 1.5)``."""
         n = self.dims
         rotation_zoom = self.affine[:n, :n]
         zoom = np.sqrt(np.sum(rotation_zoom * rotation_zoom, axis=0)) if self.__divergent else self.header.get_zooms()
@@ -460,6 +524,7 @@ def zoom(self, value: tuple[float, float, float]):
 
     @property
     def origin(self) -> tuple[float, float, float]:
+        """World-space coordinates (in mm) of voxel index (0, 0, 0)."""
         n = self.dims
         z = tuple(np.round(self.affine[:n,n],7))
         assert len(z) == 3
@@ -473,7 +538,8 @@ def origin(self,x:tuple[float, float, float]):
         affine[:n,n] = np.array(x) # type: ignore
         self._aff = affine
     @property
-    def rotation(self)->np.ndarray:
+    def rotation(self) -> np.ndarray:
+        """Pure rotation matrix extracted from the affine (affine upper-left block divided by zoom)."""
         n = self.dims
         rotation_zoom = self.affine[:n, :n]
         zoom = np.array(self.zoom)
@@ -482,17 +548,28 @@ def rotation(self)->np.ndarray:
 
     @property
     def direction(self) -> list:
+        """Flattened rotation matrix as a list (row-major), compatible with ITK/SimpleITK conventions."""
         direction_matrix = self.rotation
         direction_flat = direction_matrix.flatten().tolist()
         return direction_flat
     @property
     def direction_itk(self) -> list:
+        """Flattened rotation matrix with ITK LPS sign convention (first two rows negated)."""
         a = np.array(self.direction)
         a[:len(a)//3*2]*=-1
         return a.tolist()
 
 
-    def split_4D_image_to_3D(self):
+    def split_4D_image_to_3D(self) -> list[NII]:
+        """Splits a 4-D NIfTI image into a list of 3-D NII objects, one per volume.
+
+        Returns:
+            A list of NII objects, each containing one 3-D volume from the 4-D image.
+            The affine, header, seg flag, and c_val are copied from the original.
+
+        Raises:
+            AssertionError: If the image is not 4-D.
+        """
         assert self.get_num_dims() == 4,self.get_num_dims()
         arr_4d = self.get_array()
         out:list[NII] = []
@@ -503,16 +580,35 @@ def split_4D_image_to_3D(self):
 
 
     @property
-    def orientation_ornt(self):
+    def orientation_ornt(self) -> np.ndarray:
+        """Nibabel orientation array (shape ``(ndim, 2)``) encoding axis permutation and flip."""
         return nio.io_orientation(self.affine)
 
-    def set_description(self,v:str|None):
+    def set_description(self, v: str | None) -> None:
+        """Writes a description string into the NIfTI header ``descrip`` field.
+
+        Args:
+            v: Description string. When None, defaults to ``"seg"`` for segmentations
+                and ``"img"`` for regular images.
+        """
         if v is None:
             self.header['descrip'] = "seg" if self.seg else "img"
         else:
             self.header['descrip'] = v
 
-    def get_c_val(self,default=None):
+    def get_c_val(self, default: float | None = None) -> float:
+        """Returns the background / fill value for this image.
+
+        For segmentations the fill value is always 0. For images it is resolved from
+        ``self.c_val``, the ``default`` argument, or the minimum value of the array
+        (computed lazily and cached), in that order.
+
+        Args:
+            default: Fallback value if ``self.c_val`` is None. Defaults to None.
+
+        Returns:
+            The background fill value as a float.
+        """
         if self.seg:
             return 0
         if self.c_val is not None:
@@ -524,6 +620,11 @@ def get_c_val(self,default=None):
         return self.__min
 
     def get_seg_array(self) -> np.ndarray:
+        """Returns a copy of the voxel array, emitting a warning if ``seg`` is False.
+
+        Returns:
+            A copy of the underlying numpy array interpreted as a segmentation mask.
+        """
         if not self.seg:
             warnings.warn(
                 "requested a segmentation array, but NII is not set as a segmentation", UserWarning, stacklevel=5
@@ -531,25 +632,40 @@ def get_seg_array(self) -> np.ndarray:
         self._unpack()
         return self._arr.copy() #type: ignore
     def get_array(self) -> np.ndarray:
+        """Returns a copy of the voxel data array.
+
+        Delegates to ``get_seg_array`` when ``seg=True`` (which adds a warning if
+        the flag is inconsistent), otherwise returns a plain copy.
+
+        Returns:
+            A copy of the underlying numpy array.
+        """
         if self.seg:
             return self.get_seg_array()
         self._unpack()
         return self._arr.copy()
-    def numpy(self, *_args):
+    def numpy(self, *_args) -> np.ndarray:
+        """Returns a copy of the voxel data as a numpy array (alias for ``get_array``)."""
         return self.get_array()
-    def set_array(self,arr:np.ndarray|Self, inplace=False,verbose:logging=False,seg=None)-> Self:  # noqa: ARG002
-        """Creates a NII where the array is replaces with the input array.
+    def set_array(self, arr: np.ndarray | Self, inplace=False, verbose: logging = False, seg=None) -> Self:  # noqa: ARG002
+        """Returns an NII whose voxel data is replaced by ``arr``, preserving affine and header.
 
-        Note: This function works "Out-of-place" by default, like all other methods.
+        Note: This function works out-of-place by default, like all other methods.
 
         Args:
-            arr (np.ndarray): _description_
-            inplace (bool, optional): _description_. Defaults to False.
+            arr: New voxel data. May be a numpy array or another NII (in which case
+                ``get_array()`` is called automatically). Boolean arrays are cast to
+                ``uint8``; float16 to float32; floating arrays are cast to int32 when
+                ``self.seg`` is True.
+            inplace: If True, modifies this NII in place and returns ``self``.
+                Defaults to False.
+            verbose: Controls verbosity of dtype-change log messages. Defaults to False.
+            seg: Override the ``seg`` flag on the returned/modified NII. Defaults to None
+                (keep the current value).
 
         Returns:
-            self
+            The modified NII (``self`` when ``inplace=True``, a new NII otherwise).
         """
-
         if hasattr(arr,"get_array"):
             arr = arr.get_array() # type: ignore
         if arr.dtype == bool:
@@ -577,9 +693,24 @@ def set_array(self,arr:np.ndarray|Self, inplace=False,verbose:logging=False,seg=
         else:
             return self.copy(nii,seg=seg) # type: ignore
 
-    def set_array_(self,arr:np.ndarray,verbose:logging=True):
+    def set_array_(self, arr: np.ndarray, verbose: logging = True) -> Self:
+        """In-place variant of `set_array`."""
         return self.set_array(arr,inplace=True,verbose=verbose)
-    def set_dtype(self,dtype:type|Literal['smallest_int','smallest_uint'] = np.float32,order:Literal["C","F","A","K"] ='K',casting:Literal["no","equiv","safe","same_kind","unsafe"] = "unsafe", inplace=False):
+    def set_dtype(self, dtype: type | Literal['smallest_int', 'smallest_uint'] = np.float32, order: Literal["C", "F", "A", "K"] = 'K', casting: Literal["no", "equiv", "safe", "same_kind", "unsafe"] = "unsafe", inplace=False) -> Self:
+        """Returns an NII with the voxel array cast to a different dtype.
+
+        Args:
+            dtype: Target dtype. The special strings ``"smallest_uint"`` and
+                ``"smallest_int"`` select the smallest unsigned or signed integer
+                type that can hold all values in the current array.
+                Defaults to ``np.float32``.
+            order: Memory layout order passed to ``ndarray.astype``. Defaults to ``"K"``.
+            casting: Casting rule passed to ``ndarray.astype``. Defaults to ``"unsafe"``.
+            inplace: If True, converts in place and returns ``self``. Defaults to False.
+
+        Returns:
+            The NII with the new dtype (``self`` when ``inplace=True``, a new NII otherwise).
+        """
         sel = self if inplace else self.copy()
         if dtype == "smallest_uint":
             arr = self.get_array()
@@ -607,19 +738,35 @@ def set_dtype(self,dtype:type|Literal['smallest_int','smallest_uint'] = np.float
                 sel.nii = Nifti1Image(self.get_array().astype(dtype,casting=casting,order=order),self.affine,self.header)
 
         return sel
-    def set_dtype_(self,dtype:type|Literal['smallest_uint','smallest_int'] = np.float32,order:Literal["C","F","A","K"] ='K',casting:Literal["no","equiv","safe","same_kind","unsafe"] = "unsafe"):
+    def set_dtype_(self, dtype: type | Literal['smallest_uint', 'smallest_int'] = np.float32, order: Literal["C", "F", "A", "K"] = 'K', casting: Literal["no", "equiv", "safe", "same_kind", "unsafe"] = "unsafe") -> Self:
+        """In-place variant of `set_dtype`."""
         return self.set_dtype(dtype=dtype,order=order,casting=casting, inplace=True)
 
-    def astype(self,dtype,order:Literal["C","F","A","K"] ='K', casting:Literal["no","equiv","safe","same_kind","unsafe"] = "unsafe",subok=True, copy=True)->Self:
-        ''' numpy wrapper '''
+    def astype(self, dtype, order: Literal["C", "F", "A", "K"] = 'K', casting: Literal["no", "equiv", "safe", "same_kind", "unsafe"] = "unsafe", subok=True, copy=True) -> Self:
+        """NumPy-compatible dtype conversion wrapper.
+
+        When ``subok=True`` (default), delegates to ``set_dtype`` and returns an NII.
+        When ``subok=False``, returns a plain numpy array.
+
+        Args:
+            dtype: Target dtype, forwarded to ``set_dtype`` or ``ndarray.astype``.
+            order: Memory layout order. Defaults to ``"K"``.
+            casting: Casting rule. Defaults to ``"unsafe"``.
+            subok: If True, returns an NII; if False, returns a numpy array.
+                Defaults to True.
+            copy: When ``subok=True`` this maps to ``inplace`` (copy=True → inplace=True).
+                Defaults to True.
+
+        Returns:
+            An NII or numpy array with the requested dtype.
+        """
         if subok:
             c = self.set_dtype(dtype,order=order,casting=casting, inplace=copy)
             return c
         else:
             return self.get_array().astype(dtype,order=order,casting=casting, subok=subok,copy=copy)
     def reorient(self:Self, axcodes_to: AX_CODES|str|None = ("P", "I", "R"), verbose:logging=False, inplace=False)-> Self:
-        """
-        Reorients the input Nifti image to the desired orientation, specified by the axis codes.
+        """Reorients the input Nifti image to the desired orientation, specified by the axis codes.
 
         Args:
             axcodes_to (tuple): A tuple of three strings representing the desired axis codes. Default value is ("P", "I", "R").
@@ -667,15 +814,15 @@ def reorient(self:Self, axcodes_to: AX_CODES|str|None = ("P", "I", "R"), verbose
             return self
 
         return self.copy(new_img) # type: ignore
-    def reorient_(self:Self, axcodes_to: AX_CODES|None = ("P", "I", "R"), verbose:logging=False) -> Self:
+    def reorient_(self: Self, axcodes_to: AX_CODES | None = ("P", "I", "R"), verbose: logging = False) -> Self:
+        """In-place variant of `reorient`."""
         if axcodes_to is None:
             return self
         return self.reorient(axcodes_to=axcodes_to, verbose=verbose,inplace=True)
 
 
     def compute_crop(self,minimum: float=0, dist: float = 0, use_mm=False, other_crop:tuple[slice,...]|None=None, maximum_size:tuple[slice,...]|int|tuple[int,...]|None=None, raise_error=True)->tuple[slice,slice,slice]:
-        """
-        Computes the minimum slice that removes unused space from the image and returns the corresponding slice tuple along with the origin shift required for centroids.
+        """Computes the minimum slice that removes unused space from the image and returns the corresponding slice tuple along with the origin shift required for centroids.
 
         Args:
             minimum (int): The minimum value of the array (0 for MRI, -1024 for CT). Default value is 0.
@@ -727,7 +874,18 @@ def compute_crop(self,minimum: float=0, dist: float = 0, use_mm=False, other_cro
         #origin_shift = tuple([int(ex_slice[i].start) for i in range(len(ex_slice))])
         return tuple(ex_slice)# type: ignore
 
-    def apply_center_crop(self, center_shape: tuple[int,int,int], inplace=False, verbose: bool = False):
+    def apply_center_crop(self, center_shape: tuple[int, int, int], inplace=False, verbose: bool = False) -> Self:
+        """Crops (and pads if necessary) the image to the given shape, centred on the image.
+
+        Args:
+            center_shape: Desired output shape ``(x, y, z)``. Axes smaller than the
+                current image are cropped; axes larger are zero-padded first.
+            inplace: If True, modifies this NII in place. Defaults to False.
+            verbose: If True, prints the crop/pad operations. Defaults to False.
+
+        Returns:
+            The NII cropped/padded to ``center_shape``.
+        """
         shp_x, shp_y, shp_z = self.shape
         crop_x, crop_y, crop_z = center_shape
         arr = self.get_array()
@@ -758,23 +916,25 @@ def apply_center_crop(self, center_shape: tuple[int,int,int], inplace=False, ver
         return self.set_array(arr_cropped, inplace=inplace)
         #return self.apply_crop(crop_slices, inplace=inplace)
 
-    def apply_crop_slice(self,*args,**qargs):
+    def apply_crop_slice(self, *args, **qargs) -> Self:
+        """Deprecated alias for `apply_crop`."""
         import warnings
         warnings.warn("apply_crop_slice id deprecated use apply_crop instead",stacklevel=5) #TODO remove in version 1.0
         return self.apply_crop(*args,**qargs)
 
-    def apply_crop_slice_(self,*args,**qargs):
+    def apply_crop_slice_(self, *args, **qargs) -> Self:
+        """Deprecated alias for `apply_crop_`."""
         import warnings
         warnings.warn("apply_crop_slice_ id deprecated use apply_crop_ instead",stacklevel=5) #TODO remove in version 1.0
         return self.apply_crop_(*args,**qargs)
 
-    def apply_crop(self,ex_slice:tuple[slice,slice,slice]|Sequence[slice]|None , inplace=False):
-        """
-        The apply_crop_slice function applies a given slice to reduce the Nifti image volume. If a list of slices is provided, it computes the minimum volume of all slices and applies it.
+    def apply_crop(self,ex_slice:tuple[slice,slice,slice]|Sequence[slice]|None , inplace=False) -> Self:
+        """The apply_crop_slice function applies a given slice to reduce the Nifti image volume. If a list of slices is provided, it computes the minimum volume of all slices and applies it.
 
         Args:
             ex_slice (tuple[slice,slice,slice] | list[tuple[slice,slice,slice]]): A tuple or a list of tuples, where each tuple represents a slice for each axis (x, y, z).
             inplace (bool, optional): If True, it applies the slice to the original image and returns it. If False, it returns a new NII object with the sliced image.
+
         Returns:
             NII: A new NII object containing the sliced image if inplace=False. Otherwise, it returns the original NII object after applying the slice.
         """
@@ -785,10 +945,25 @@ def apply_crop(self,ex_slice:tuple[slice,slice,slice]|Sequence[slice]|None , inp
         x= self.copy(nii)
         return x
 
-    def apply_crop_(self,ex_slice:tuple[slice,slice,slice]|Sequence[slice]):
+    def apply_crop_(self, ex_slice: tuple[slice, slice, slice] | Sequence[slice]) -> Self:
+        """In-place variant of `apply_crop`."""
         return self.apply_crop(ex_slice=ex_slice,inplace=True)
 
-    def pad_to(self,target_shape:list[int]|tuple[int,int,int] | Self, mode:MODES="constant",crop=False,inplace = False):
+    def pad_to(self, target_shape: list[int] | tuple[int, int, int] | Self, mode: MODES = "constant", crop=False, inplace=False) -> Self:
+        """Pads (and optionally crops) the image to match a target shape.
+
+        Args:
+            target_shape: Desired output shape ``(x, y, z)`` or another NII whose
+                shape is used as the target.
+            mode: Padding mode (``"constant"``, ``"nearest"``, ``"reflect"``,
+                or ``"wrap"``). Defaults to ``"constant"``.
+            crop: If True and the image is larger than ``target_shape`` along any
+                axis, that axis is cropped first. Defaults to False.
+            inplace: If True, modifies this NII in place. Defaults to False.
+
+        Returns:
+            The NII padded (and optionally cropped) to ``target_shape``.
+        """
         if isinstance(target_shape, NII):
             target_shape = target_shape.shape
         padding, crop, requires_crop = _pad_to_parameters(self.shape, target_shape)
@@ -797,15 +972,27 @@ def pad_to(self,target_shape:list[int]|tuple[int,int,int] | Self, mode:MODES="co
             s = s.apply_crop(tuple(crop),inplace=inplace)
         return s.apply_pad(padding,inplace=inplace,mode=mode)
 
+    def apply_pad(self, padd: Sequence[tuple[int | None, int | None]] | int | None, mode: MODES = "constant", inplace=False, verbose: logging = True,) -> Self:
+        """Pads the image with explicit per-axis ``(before, after)`` amounts.
 
-    def apply_pad(
-        self,
-        padd: Sequence[tuple[int | None, int | None]] | int | None,
-        mode: MODES = "constant",
-        inplace=False,
-        verbose: logging = True
-    ):
-        if padd is None or padd == 0:
+        The affine is updated so that the world-space origin is preserved (i.e. the
+        new voxel (0, 0, 0) corresponds to the same world coordinate as before).
+
+        Args:
+            padd: A sequence of ``(before, after)`` integer tuples, one per spatial
+                dimension. ``None`` as the ``before`` value means no padding on that
+                side. Pass ``None`` for the whole argument to skip padding entirely.
+            mode: Padding mode forwarded to ``numpy.pad``. Defaults to ``"constant"``.
+                In ``"constant"`` mode the fill value is ``self.get_c_val()``.
+            inplace: If True, modifies this NII in place. Defaults to False.
+            verbose: If True, logs the padding parameters. Defaults to True.
+
+        Returns:
+            The padded NII.
+        """
+        #TODO add other modes
+        #TODO add testcases and options for modes
+        if padd is None:
             return self if inplace else self.copy()
 
         if isinstance(padd, (int, float)):
@@ -866,8 +1053,22 @@ def apply_pad(
 
         return self.copy(nii)
 
-    def rescale_and_reorient(self, axcodes_to=None, voxel_spacing=(-1, -1, -1), verbose:logging=True, inplace=False,c_val:float|None=None,mode:MODES='nearest'):
+    def rescale_and_reorient(self, axcodes_to=None, voxel_spacing=(-1, -1, -1), verbose: logging = True, inplace=False, c_val: float | None = None, mode: MODES = 'nearest') -> Self:
+        """Reorients and then rescales the image in a single step.
+
+        Args:
+            axcodes_to: Target orientation axis codes, e.g. ``("P", "I", "R")``.
+                If None, keeps the current orientation. Defaults to None.
+            voxel_spacing: Target voxel spacing in mm. ``-1`` keeps the current spacing
+                for that axis. Defaults to ``(-1, -1, -1)``.
+            verbose: Verbosity flag. Defaults to True.
+            inplace: If True, modifies this NII in place. Defaults to False.
+            c_val: Background fill value for resampling. Defaults to None.
+            mode: Interpolation / boundary mode. Defaults to ``"nearest"``.
 
+        Returns:
+            The reoriented and rescaled NII.
+        """
         ## Resample and rotate and Save Tempfiles
         if axcodes_to is None:
             curr = self
@@ -877,17 +1078,29 @@ def rescale_and_reorient(self, axcodes_to=None, voxel_spacing=(-1, -1, -1), verb
             curr = self.reorient(axcodes_to=axcodes_to, verbose=verbose, inplace=inplace)
         return curr.rescale(voxel_spacing=voxel_spacing, verbose=verbose, inplace=inplace,c_val=c_val,mode=mode)
 
-    def rescale_and_reorient_(self,axcodes_to=None, voxel_spacing=(-1, -1, -1),c_val:float|None=None,mode:MODES='nearest', verbose:logging=True):
+    def rescale_and_reorient_(self, axcodes_to=None, voxel_spacing=(-1, -1, -1), c_val: float | None = None, mode: MODES = 'nearest', verbose: logging = True) -> Self:
+        """In-place variant of `rescale_and_reorient`."""
         return self.rescale_and_reorient(axcodes_to=axcodes_to,voxel_spacing=voxel_spacing,c_val=c_val,mode=mode,verbose=verbose,inplace=True)
 
-    def reorient_same_as(self, img_as: Nifti1Image | Self, verbose:logging=False, inplace=False) -> Self:
+    def reorient_same_as(self, img_as: Nifti1Image | Self, verbose: logging = False, inplace=False) -> Self:
+        """Reorients this image to match the orientation of another image.
+
+        Args:
+            img_as: Reference image whose orientation is used as the target.
+            verbose: If True, logs the orientation change. Defaults to False.
+            inplace: If True, modifies this NII in place. Defaults to False.
+
+        Returns:
+            The reoriented NII.
+        """
         axcodes_to: AX_CODES = nio.ornt2axcodes(nio.io_orientation(img_as.affine)) # type: ignore
         return self.reorient(axcodes_to=axcodes_to, verbose=verbose, inplace=inplace)
-    def reorient_same_as_(self, img_as: Nifti1Image | Self, verbose:logging=False) -> Self:
+
+    def reorient_same_as_(self, img_as: Nifti1Image | Self, verbose: logging = False) -> Self:
+        """In-place variant of `reorient_same_as`."""
         return self.reorient_same_as(img_as=img_as,verbose=verbose,inplace=True)
-    def rescale(self, voxel_spacing:float|tuple[float,...]=(1, 1, 1), c_val:float|None=None, verbose:logging=False, inplace=False,mode:MODES='nearest',order: int |None = None,align_corners:bool=False,atol=0.001):
-        """
-        Rescales the NIfTI image to a new voxel spacing.
+    def rescale(self, voxel_spacing:float|tuple[float,...]=(1, 1, 1), c_val:float|None=None, verbose:logging=False, inplace=False,mode:MODES='nearest',order: int |None = None,align_corners:bool=False,atol=0.001) -> Self:
+        """Rescales the NIfTI image to a new voxel spacing.
 
         Args:
             voxel_spacing (tuple[float, float, float] | float): The desired voxel spacing in millimeters (x, y, z). -1 is keep the voxel spacing.
@@ -939,11 +1152,13 @@ def rescale(self, voxel_spacing:float|tuple[float,...]=(1, 1, 1), c_val:float|No
             return self
         return self.copy(new_img)
 
-    def rescale_(self, voxel_spacing=(1, 1, 1), c_val:float|None=None, verbose:logging=False,mode:MODES='nearest'):
+    def rescale_(self, voxel_spacing=(1, 1, 1), c_val: float | None = None, verbose: logging = False, mode: MODES = 'nearest') -> Self:
+        """In-place variant of `rescale`."""
         return self.rescale( voxel_spacing=voxel_spacing, c_val=c_val, verbose=verbose,mode=mode, inplace=True)
 
-    def resample_from_to(self, to_vox_map:Image_Reference|Has_Grid|tuple[SHAPE,AFFINE,ZOOMS], mode:MODES='nearest', order: int |None=None, c_val=None, inplace = False,verbose:logging=True,align_corners:bool=False):
-        """self will be resampled in coordinate of given other image. Adheres to global space not to local pixel space
+    def resample_from_to(self, to_vox_map:Image_Reference|Has_Grid|tuple[SHAPE,AFFINE,ZOOMS], mode:MODES='nearest', order: int |None=None, c_val=None, inplace = False,verbose:logging=True,align_corners:bool=False) -> Self:
+        r"""Self will be resampled in coordinate of given other image. Adheres to global space not to local pixel space.
+
         Args:
             to_vox_map (Image_Reference|Proxy): If object, has attributes shape giving input voxel shape, and affine giving mapping of input voxels to output space. If length 2 sequence, elements are (shape, affine) with same meaning as above. The affine is a (4, 4) array-like.\n
             mode (str, optional): Points outside the boundaries of the input are filled according to the given mode ('constant', 'nearest', 'reflect' or 'wrap').Defaults to 'constant'.\n
@@ -1007,12 +1222,13 @@ def resample_from_to(self, to_vox_map:Image_Reference|Has_Grid|tuple[SHAPE,AFFIN
             return self
         else:
             return self.copy(nii)
-    def resample_from_to_(self, to_vox_map:Image_Reference|Has_Grid|tuple[SHAPE,AFFINE,ZOOMS], mode:MODES='nearest', c_val:float|None=None,verbose:logging=True,aline_corners=False):
+    def resample_from_to_(self, to_vox_map: Image_Reference | Has_Grid | tuple[SHAPE, AFFINE, ZOOMS], mode: MODES = 'nearest', c_val: float | None = None, verbose: logging = True, aline_corners=False) -> Self:
+        """In-place variant of `resample_from_to`."""
         return self.resample_from_to(to_vox_map,mode=mode,c_val=c_val,inplace=True,verbose=verbose,align_corners=aline_corners)
 
     @property
     def is_empty(self) -> bool:
-        """Checks if the array in the nifti is empty
+        """Checks if the array in the nifti is empty.
 
         Returns:
             bool: Whether the nifti is empty or not
@@ -1030,8 +1246,8 @@ def n4_bias_field_correction(
         weight_mask=None,
         crop=False,
         inplace=False
-    ):
-        """Runs a n4 bias field correction over the nifty
+    ) -> Self:
+        """Runs a n4 bias field correction over the nifty.
 
         Args:
             threshold (int, optional): If != 0, will mask the input based on the threshold. Defaults to 60.
@@ -1098,12 +1314,23 @@ def n4_bias_field_correction(
             return self
         return self.copy(out_nib).set_dtype_(dtype)
 
-    def n4_bias_field_correction_(self,threshold = 60,mask=None,shrink_factor=4,convergence=None,spline_param=200,verbose=False,weight_mask=None,crop=False):
+    def n4_bias_field_correction_(self, threshold=60, mask=None, shrink_factor=4, convergence=None, spline_param=200, verbose=False, weight_mask=None, crop=False) -> Self:
+        """In-place variant of `n4_bias_field_correction`."""
         if convergence is None:
             convergence = {"iters": [50, 50, 50, 50], "tol": 1e-07}
         return self.n4_bias_field_correction(mask=mask,shrink_factor=shrink_factor,convergence=convergence,spline_param=spline_param,verbose=verbose,weight_mask=weight_mask,crop=crop,inplace=True,threshold = threshold)
 
-    def normalize_to_range_(self, min_value: int = 0, max_value: int = 1500, verbose:logging=True):
+    def normalize_to_range_(self, min_value: int = 0, max_value: int = 1500, verbose: logging = True) -> None:
+        """In-place normalization that clips and scales intensity values to ``[min_value, max_value]``.
+
+        Args:
+            min_value: Desired minimum output value. Defaults to 0.
+            max_value: Desired maximum output value. Defaults to 1500.
+            verbose: If True, logs the before/after intensity range. Defaults to True.
+
+        Raises:
+            AssertionError: If this NII is a segmentation (``seg=True``).
+        """
         assert not self.seg
         mi, ma = self.min(), self.max()
         self += -mi + min_value  # min = 0
@@ -1114,7 +1341,7 @@ def normalize_to_range_(self, min_value: int = 0, max_value: int = 1500, verbose
             self.set_dtype_(self_dtype)
         log.print(f"Shifted from range {mi, ma} to range {self.min(), self.max()}", verbose=verbose)
 
-    def get_histogram(self, bins=256, hrange=None, density=False, c_val:float|None=None):
+    def get_histogram(self, bins=256, hrange=None, density=False, c_val:float|None=None) -> tuple[np.ndarray, np.ndarray]:
         """Returns the histogram of the image array.
 
         Args:
@@ -1131,7 +1358,22 @@ def get_histogram(self, bins=256, hrange=None, density=False, c_val:float|None=N
             arr[arr <= c_val] = c_val
         return np.histogram(arr, bins=bins, range=hrange, density=density)
 
-    def match_histograms(self, reference:Image_Reference,c_val = 0,inplace=False):
+    def match_histograms(self, reference: Image_Reference, c_val: float = 0, inplace=False) -> Self:
+        """Adjusts the intensity histogram of this image to match a reference image.
+
+        Args:
+            reference: Reference image whose histogram is used as the target.
+            c_val: Background value; voxels at or below this threshold are clamped
+                to ``c_val`` after matching. Defaults to 0.
+            inplace: If True, modifies this NII in place. Defaults to False.
+
+        Returns:
+            The histogram-matched NII.
+
+        Raises:
+            AssertionError: If either image has ``seg=True``.
+            ValueError: If ``c_val <= -999`` (CT-range backgrounds are not supported).
+        """
         assert not self.seg
         ref_nii = to_nii(reference)
         assert ref_nii.seg is False
@@ -1146,16 +1388,35 @@ def match_histograms(self, reference:Image_Reference,c_val = 0,inplace=False):
         matched[matched <= c_val] = c_val
         return self.set_array(matched, inplace=inplace,verbose=False)
 
-    def match_histograms_(self, reference:Image_Reference,c_val = 0):
+    def match_histograms_(self, reference: Image_Reference, c_val: float = 0) -> Self:
+        """In-place variant of `match_histograms`."""
         return self.match_histograms(reference,c_val = c_val,inplace=True)
 
-    def smooth_gaussian(self, sigma:float|list[float]|tuple[float],truncate:float=4.0,nth_derivative=0,inplace=False):
+    def smooth_gaussian(self, sigma: float | list[float] | tuple[float], truncate: float = 4.0, nth_derivative: int = 0, inplace=False) -> Self:
+        """Applies a Gaussian smoothing filter to the image.
+
+        Args:
+            sigma: Standard deviation of the Gaussian kernel. A scalar applies the
+                same sigma to all axes; a sequence sets per-axis values.
+            truncate: Truncate the filter at this many standard deviations.
+                Defaults to 4.0.
+            nth_derivative: Order of the derivative (0 = smoothing, 1 = gradient, …).
+                Defaults to 0.
+            inplace: If True, modifies this NII in place. Defaults to False.
+
+        Returns:
+            The smoothed NII.
+
+        Raises:
+            AssertionError: If ``seg=True`` (use ``smooth_gaussian_labelwise`` instead).
+        """
         assert self.seg is False, "You really want to smooth a segmentation? If yes, use smooth_gaussian_channelwise() instead"
         from scipy.ndimage import gaussian_filter
         arr = gaussian_filter(self.get_array(), sigma, order=nth_derivative,cval=self.get_c_val(), truncate=truncate)# radius=None, axes=None
         return self.set_array(arr,inplace,verbose=False)
 
-    def smooth_gaussian_(self, sigma:float|list[float]|tuple[float],truncate=4.0,nth_derivative=0):
+    def smooth_gaussian_(self, sigma: float | list[float] | tuple[float], truncate: float = 4.0, nth_derivative: int = 0) -> Self:
+        """In-place variant of `smooth_gaussian`."""
         return self.smooth_gaussian(sigma=sigma,truncate=truncate,nth_derivative=nth_derivative,inplace=True)
 
 
@@ -1173,7 +1434,7 @@ def smooth_gaussian_labelwise(
         background_threshold: float | None = None,
         inplace: bool = False,
         verbose:logging=False,
-    ):
+    ) -> Self:
         """Smoothes the segmentation mask by applying a gaussian filter label-wise and then using argmax to derive the smoothed segmentation labels again.
 
         Args:
@@ -1219,7 +1480,8 @@ def smooth_gaussian_labelwise_(
         dilate_channelwise: bool = False,
         smooth_background: bool = True,
         background_threshold: float | None = None,
-    ):
+    ) -> Self:
+        """In-place variant of `smooth_gaussian_labelwise`."""
         return self.smooth_gaussian_labelwise(
             label_to_smooth=label_to_smooth,
             sigma=sigma,
@@ -1234,7 +1496,15 @@ def smooth_gaussian_labelwise_(
             dilate_channelwise=dilate_channelwise,
         )
 
-    def to_ants(self):
+    def to_ants(self) -> Any:
+        """Converts this NII to an ANTs image (requires the ``antspyx`` package).
+
+        Returns:
+            An ``ants.ANTsImage`` corresponding to this NII.
+
+        Raises:
+            ImportError: If ``antspyx`` is not installed.
+        """
         try:
             import ants
         except Exception:
@@ -1243,11 +1513,23 @@ def to_ants(self):
             raise
         return ants.from_nibabel(self.nii)
 
-    def to_simpleITK(self):
+    def to_simpleITK(self) -> Any:
+        """Converts this NII to a SimpleITK image.
+
+        Returns:
+            A ``SimpleITK.Image`` corresponding to this NII.
+        """
         from TPTBox.core.sitk_utils import nii_to_sitk
         return nii_to_sitk(self)
+
     @classmethod
-    def from_deepali(cls, img,seg=False):
+    def from_deepali(cls, img, seg=False) -> NII:
+        """Construct a NII from a DeepALI ``Image`` object.
+
+        Args:
+            img: A ``deepali.data.Image`` instance.
+            seg: Mark the resulting NII as a segmentation mask.
+        """
         try:
             from deepali.data import Image as deepaliImage
         except Exception:
@@ -1261,7 +1543,20 @@ def from_deepali(cls, img,seg=False):
         arr = np.transpose(arr, axes=tuple(reversed(range(arr.ndim))))
         return  NII((nib.Nifti1Image(arr,grid.affine)),seg=seg)
 
-    def to_deepali(self,align_corners: bool = True,dtype=None,device:device|str = "cpu"):
+    def to_deepali(self, align_corners: bool = True, dtype=None, device: device | str = "cpu") -> Any:
+        """Converts this NII to a DeepALI ``Image`` tensor (requires the ``hf-deepali`` package).
+
+        Args:
+            align_corners: If True, aligns grid corners during conversion. Defaults to True.
+            dtype: Optional target torch dtype. Defaults to None (inferred).
+            device: Target torch device. Defaults to ``"cpu"``.
+
+        Returns:
+            A ``deepali.data.Image`` corresponding to this NII.
+
+        Raises:
+            ImportError: If ``hf-deepali`` is not installed.
+        """
         import torch
         try:
             from deepali.data import Image as deepaliImage  # type: ignore
@@ -1307,9 +1602,8 @@ def to_deepali(self,align_corners: bool = True,dtype=None,device:device|str = "c
         #   data = data.unsqueeze(0)
         return deepaliImage(data, grid, dtype=dtype, device=device)  # type: ignore
 
-    def erode_msk(self, n_pixel: int = 5, labels: LABEL_REFERENCE = None, connectivity: int = 3, inplace=False,verbose:logging=True,border_value=0, use_crop=True,ignore_direction:DIRECTIONS|int|None=None):
-        """
-        Erodes the binary segmentation mask by the specified number of voxels.
+    def erode_msk(self, n_pixel: int = 5, labels: LABEL_REFERENCE = None, connectivity: int = 3, inplace=False,verbose:logging=True,border_value=0, use_crop=True,ignore_direction:DIRECTIONS|int|None=None) -> Self:
+        """Erodes the binary segmentation mask by the specified number of voxels.
 
         Args:
             mm (int, optional): The number of voxels to erode the mask by. Defaults to 5.
@@ -1336,7 +1630,8 @@ def erode_msk(self, n_pixel: int = 5, labels: LABEL_REFERENCE = None, connectivi
         log.print("Mask eroded by", n_pixel, "voxels",verbose=verbose)
         return self.set_array(out,inplace=inplace)
 
-    def erode_msk_(self, n_pixel:int = 5, labels: LABEL_REFERENCE = None, connectivity: int=3, verbose:logging=True,border_value=0,use_crop=True,ignore_direction:DIRECTIONS|int|None=None):
+    def erode_msk_(self, n_pixel: int = 5, labels: LABEL_REFERENCE = None, connectivity: int = 3, verbose: logging = True, border_value=0, use_crop=True, ignore_direction: DIRECTIONS | int | None = None) -> Self:
+        """In-place variant of `erode_msk`."""
         return self.erode_msk(n_pixel=n_pixel, labels=labels, connectivity=connectivity, inplace=True, verbose=verbose,border_value=border_value,use_crop=use_crop,ignore_direction=ignore_direction)
     def erode_msk_euclid(
         self,
@@ -1345,10 +1640,9 @@ def erode_msk_euclid(
         mask: Self | None = None,
         inplace=False,
         verbose: logging = True,
-        use_crop=True
-    ):
-        """
-        Euclidean erodes (in voxel space) a segmentation mask by the specified number.
+        use_crop=True,
+    ) -> Self:
+        """Euclidean erodes (in voxel space) a segmentation mask by the specified number.
 
         Args:
             n_pixel (int, optional): The number of voxels to erode the mask by. Defaults to 5.
@@ -1385,9 +1679,8 @@ def erode_msk_euclid(
         log.print("Mask euclidean eroded by", n_pixel, "voxels", verbose=verbose)
 
         return self.set_array(out, inplace=inplace)
-    def dilate_msk_euclid(self, n_pixel: int = 5, labels: LABEL_REFERENCE = None,mask: Self | None = None, inplace=False, verbose:logging=True,use_crop=True):
-        """
-        euclidean Dilates (in voxel space) a segmentation mask by the specified number.
+    def dilate_msk_euclid(self, n_pixel: int = 5, labels: LABEL_REFERENCE = None, mask: Self | None = None, inplace=False, verbose: logging = True, use_crop=True) -> Self:
+        """Euclidean Dilates (in voxel space) a segmentation mask by the specified number.
 
         Args:
             n_pixel (int, optional): The number of voxels to dilate the mask by. Defaults to 5.
@@ -1414,9 +1707,9 @@ def dilate_msk_euclid(self, n_pixel: int = 5, labels: LABEL_REFERENCE = None,mas
         log.print("Mask euclidean dilated by", n_pixel, "voxels",verbose=verbose)
 
         return self.set_array(out,inplace=inplace)
-    def dilate_msk(self, n_pixel: int = 5, labels: LABEL_REFERENCE = None, connectivity: int = 3, mask: Self | None = None, inplace=False, verbose:logging=True,use_crop=True, ignore_direction:DIRECTIONS|int|None=None):
-        """
-        Dilates the binary segmentation mask by the specified number of voxels.
+
+    def dilate_msk(self, n_pixel: int = 5, labels: LABEL_REFERENCE = None, connectivity: int = 3, mask: Self | None = None, inplace=False, verbose:logging=True,use_crop=True, ignore_direction:DIRECTIONS|int|None=None) -> Self:
+        """Dilates the binary segmentation mask by the specified number of voxels.
 
         Args:
             n_pixel (int, optional): The number of voxels to dilate the mask by. Defaults to 5.
@@ -1446,12 +1739,13 @@ def dilate_msk(self, n_pixel: int = 5, labels: LABEL_REFERENCE = None, connectiv
         log.print("Mask dilated by", n_pixel, "voxels",verbose=verbose)
         return self.set_array(out,inplace=inplace)
 
-    def dilate_msk_(self, n_pixel:int = 5, labels: LABEL_REFERENCE = None, connectivity: int=3, mask: Self | None = None, verbose:logging=True,use_crop=True,ignore_direction:DIRECTIONS|int|None=None):
+    def dilate_msk_(self, n_pixel: int = 5, labels: LABEL_REFERENCE = None, connectivity: int = 3, mask: Self | None = None, verbose: logging = True, use_crop=True, ignore_direction: DIRECTIONS | int | None = None) -> Self:
+        """In-place variant of `dilate_msk`."""
         return self.dilate_msk(n_pixel=n_pixel, labels=labels, connectivity=connectivity, mask=mask, inplace=True, verbose=verbose,use_crop=use_crop,ignore_direction=ignore_direction)
 
 
-    def fill_holes(self, labels: LABEL_REFERENCE = None, slice_wise_dim: int|str | None = None, verbose:logging=False, inplace=False,use_crop=True):  # noqa: ARG002
-        """Fills holes in segmentation
+    def fill_holes(self, labels: LABEL_REFERENCE = None, slice_wise_dim: int|str | None = None, verbose:logging=False, inplace=False,use_crop=True) -> Self:  # noqa: ARG002
+        """Fills holes in segmentation.
 
         Args:
             labels (LABEL_REFERENCE, optional): Labels that the hole-filling should be applied to. If none, applies on all labels found in arr. Defaults to None.
@@ -1477,7 +1771,8 @@ def fill_holes(self, labels: LABEL_REFERENCE = None, slice_wise_dim: int|str | N
         filled = np_fill_holes(seg_arr, label_ref=labels, slice_wise_dim=slice_wise_dim, use_crop=use_crop)
         return self.set_array(filled,inplace=inplace)
 
-    def fill_holes_(self, labels: LABEL_REFERENCE = None, slice_wise_dim: int |str| None = None, verbose:logging=True,use_crop=True):
+    def fill_holes_(self, labels: LABEL_REFERENCE = None, slice_wise_dim: int | str | None = None, verbose: logging = True, use_crop=True) -> Self:
+        """In-place variant of `fill_holes`."""
         return self.fill_holes(labels, slice_wise_dim, verbose, inplace=True,use_crop=use_crop)
 
     def calc_convex_hull(
@@ -1485,8 +1780,8 @@ def calc_convex_hull(
         axis: DIRECTIONS|None = "S",
         inplace: bool = False,
         verbose: bool = False
-    ):
-        """Calculates the convex hull of this segmentation nifty
+    ) -> Self:
+        """Calculates the convex hull of this segmentation nifty.
 
         Args:
             axis (int | None, optional): If given axis, will calculate convex hull along that axis (remaining dimension must be at least 2). Defaults to None.
@@ -1498,13 +1793,13 @@ def calc_convex_hull(
             return self.set_array_(convex_hull_arr)
         return self.set_array(convex_hull_arr)
 
-    def calc_convex_hull_(self, axis: None|DIRECTIONS="S", verbose: bool = False,):
+    def calc_convex_hull_(self, axis: None | DIRECTIONS = "S", verbose: bool = False) -> Self:
+        """In-place variant of `calc_convex_hull`."""
         return self.calc_convex_hull(axis=axis, inplace=True, verbose=verbose)
 
 
-    def boundary_mask(self, threshold: float,inplace = False):
-        """
-        Calculate a boundary mask based on the input image.
+    def boundary_mask(self, threshold: float,inplace = False) -> Self:
+        """Calculate a boundary mask based on the input image.
 
         Parameters:
         - img (NII): The image used to create the boundary mask.
@@ -1525,20 +1820,49 @@ def boundary_mask(self, threshold: float,inplace = False):
         """
         return self.set_array(np_calc_boundary_mask(self.get_array(),threshold),inplace=inplace,verbose=False)
 
-    def get_connected_components(self, labels: int |list[int]|None=None, connectivity: int = 3, include_zero: bool=False,inplace=False) -> Self:  # noqa: ARG002
+    def get_connected_components(self, labels: int | list[int] | None = None, connectivity: int = 3, include_zero: bool = False, inplace=False) -> Self:
+        """Replaces each label with a unique connected-component index.
+
+        Args:
+            labels: Labels to process. If None, processes all non-zero labels.
+            connectivity: Voxel connectivity (1 = face-adjacent, 3 = corner-adjacent).
+                Defaults to 3.
+            include_zero: If True, also labels the background (0) as components.
+                Defaults to False.
+            inplace: If True, modifies this NII in place. Defaults to False.
+
+        Returns:
+            An NII where each connected component has a unique integer label.
+
+        Raises:
+            AssertionError: If ``seg=False``.
+        """
         assert self.seg, "This only works on segmentations"
         out, _ = np_connected_components(self.get_seg_array(), label_ref=labels, connectivity=connectivity, include_zero=include_zero)
         return self.set_array(out,inplace=inplace)
 
-    def get_connected_components_per_label(self, labels: int |list[int], connectivity: int = 3, include_zero: bool=False) -> dict[int, Self]:  # noqa: ARG002
+    def get_connected_components_per_label(self, labels: int | list[int], connectivity: int = 3, include_zero: bool = False) -> dict[int, Self]:
+        """Returns a dict mapping each label to an NII containing only that label's connected components.
+
+        Args:
+            labels: Label(s) to process.
+            connectivity: Voxel connectivity (1 to 3). Defaults to 3.
+            include_zero: Whether to include the background. Defaults to False.
+
+        Returns:
+            A dict ``{label: NII}`` where each NII holds the component-indexed array
+            for that label.
+
+        Raises:
+            AssertionError: If ``seg=False``.
+        """
         assert self.seg, "This only works on segmentations"
         out = np_connected_components_per_label(self.get_seg_array(), label_ref=labels, connectivity=connectivity, include_zero=include_zero)
         cc = {i: self.set_array(k) for i,k in out.items()}
         return cc
 
-    def filter_connected_components(self, labels: int |list[int]|None=None,min_volume:int=0,max_volume:int|None=None, max_count_component = None, connectivity: int = 3,removed_to_label=0,keep_label=False, inplace=False,):
-        """
-        Filter connected components in a segmentation array based on specified volume constraints.
+    def filter_connected_components(self, labels: int |list[int]|None=None,min_volume:int=0,max_volume:int|None=None, max_count_component = None, connectivity: int = 3,removed_to_label=0,keep_label=False, inplace=False,) -> Self:
+        """Filter connected components in a segmentation array based on specified volume constraints.
 
         Parameters:
         labels (int | list[int]): The labels of the components to filter.
@@ -1565,19 +1889,24 @@ def filter_connected_components(self, labels: int |list[int]|None=None,min_volum
         #print("filter",nii.unique())
         #assert max_count_component is None or nii.max() <= max_count_component, nii.unique()
         return self.set_array(arr, inplace=inplace)
-    def filter_connected_components_(self, labels: int |list[int]|None=None,min_volume:int=0,max_volume:int|None=None, max_count_component = None, connectivity: int = 3,keep_label=False,removed_to_label=0):
+    def filter_connected_components_(self, labels: int | list[int] | None = None, min_volume: int = 0, max_volume: int | None = None, max_count_component=None, connectivity: int = 3, keep_label=False, removed_to_label=0) -> Self:
+        """In-place variant of `filter_connected_components`."""
         return self.filter_connected_components(labels,min_volume=min_volume,max_volume=max_volume, max_count_component = max_count_component, connectivity = connectivity,removed_to_label=removed_to_label,keep_label=keep_label,inplace=True)
 
     def get_segmentation_connected_components_center_of_mass(self, label: int, connectivity: int = 3, sort_by_axis: int | None = None) -> list[COORDINATE]:
-        """Calculates the center of mass of the different connected components of a given label in an array
+        """Calculates the center of mass of each connected component for a given label.
 
         Args:
-            label (int): the label of the connected components
-            connectivity (int, optional): Connectivity for the connected components. Defaults to 3.
-            sort_by_axis (int | None, optional): If not none, will sort the center of mass list by this axis values. Defaults to None.
+            label: The integer label whose connected components are analysed.
+            connectivity: Voxel connectivity (1 to 3). Defaults to 3.
+            sort_by_axis: If not None, the returned list is sorted by the voxel
+                coordinate along this axis. Defaults to None.
 
         Returns:
-            _type_: _description_
+            A list of ``(x, y, z)`` voxel coordinates, one per connected component.
+
+        Raises:
+            AssertionError: If ``seg=False``.
         """
         assert self.seg, "This only works on segmentations"
         arr = self.get_seg_array()
@@ -1585,7 +1914,7 @@ def get_segmentation_connected_components_center_of_mass(self, label: int, conne
 
 
     def get_largest_k_segmentation_connected_components(self, k: int | None, labels: int | list[int] | None = None, connectivity: int = 1, return_original_labels: bool = True,inplace=False,min_volume:int=0,max_volume:int|None=None,removed_to_label=0) -> Self:
-        """Finds the largest k connected components in a given array (does NOT work with zero as label!)
+        """Finds the largest k connected components in a given array (does NOT work with zero as label!).
 
         Args:
             arr (np.ndarray): input array
@@ -1599,7 +1928,7 @@ def get_largest_k_segmentation_connected_components(self, k: int | None, labels:
         return self.set_array(out,inplace=inplace)
 
     def compute_surface_mask(self, connectivity: int = 3, dilated_surface: bool = False) -> Self:
-        """ Removes everything but surface voxels
+        """Removes everything but surface voxels.
 
         Args:
             connectivity (int): Connectivity for surface calculation
@@ -1609,14 +1938,27 @@ def compute_surface_mask(self, connectivity: int = 3, dilated_surface: bool = Fa
         return self.set_array(np_compute_surface(self.get_seg_array(), connectivity=connectivity, dilated_surface=dilated_surface))
 
 
-    def compute_surface_points(self, connectivity: int = 3, dilated_surface: bool = False) -> list[tuple[int,int,int]]:
+    def compute_surface_points(self, connectivity: int = 3, dilated_surface: bool = False) -> list[tuple[int, int, int]]:
+        """Returns voxel coordinates of all surface voxels in the segmentation.
+
+        Args:
+            connectivity: Connectivity for surface calculation. Defaults to 3.
+            dilated_surface: If False, returns ``mask - eroded_mask``; if True,
+                returns ``dilated_mask - mask``. Defaults to False.
+
+        Returns:
+            A list of ``(x, y, z)`` voxel coordinate tuples for every surface voxel.
+
+        Raises:
+            AssertionError: If ``seg=False``.
+        """
         assert self.seg, "This only works on segmentations"
         surface = self.compute_surface_mask(connectivity, dilated_surface)
         return np_point_coordinates(surface.get_seg_array()) # type: ignore
 
 
     def fill_holes_global_with_majority_voting(self, connectivity: int = 3, inplace: bool = False, verbose: bool = False) -> Self:
-        """Fills 3D holes globally, and resolves inter-label conflicts with majority voting by neighbors
+        """Fills 3D holes globally, and resolves inter-label conflicts with majority voting by neighbors.
 
         Args:
             connectivity (int, optional): Connectivity of fill holes. Defaults to 3.
@@ -1632,7 +1974,7 @@ def fill_holes_global_with_majority_voting(self, connectivity: int = 3, inplace:
 
 
     def map_labels_based_on_majority_label_mask_overlap(self, label_mask: Self, labels: int | list[int] | None = None, dilate_pixel: int = 1, inplace: bool = False,no_match_label=0) -> Self:
-        """Relabels all individual labels from input array to the majority labels of a given label_mask
+        """Relabels all individual labels from input array to the majority labels of a given label_mask.
 
         Args:
             label_mask (np.ndarray): the mask from which to pull the target labels.
@@ -1648,7 +1990,7 @@ def map_labels_based_on_majority_label_mask_overlap(self, label_mask: Self, labe
 
 
     def get_segmentation_difference_to(self, mask_gt: Self, ignore_background_tp: bool = False) -> Self:
-        """Calculates an NII that represents the segmentation difference between self and given groundtruth mask
+        """Calculates an NII that represents the segmentation difference between self and given groundtruth mask.
 
         Args:
             mask_groundtruth (Self): The ground truth mask. Must match in orientation, zoom, and shape
@@ -1682,7 +2024,7 @@ def get_overlapping_labels_to(
         self,
         mask_other: Self
     ) -> list[tuple[int, int]]:
-        """Calculates the pairs of labels that are overlapping in at least one voxel (fast)
+        """Calculates the pairs of labels that are overlapping in at least one voxel (fast).
 
         Args:
             mask_other (NII): The array to be compared with.
@@ -1694,8 +2036,7 @@ def get_overlapping_labels_to(
         return np_calc_overlapping_labels(self.get_seg_array(), mask_other.get_seg_array())
 
     def is_segmentation_in_border(self,minimum=0, voxel_tolerance: int = 2,use_mm=False) -> bool:
-        """
-        Checks if the segmentation is touching the border of the image volume.
+        """Checks if the segmentation is touching the border of the image volume.
 
         Parameters:
         - minimum (int, optional): Minimum intensity threshold for segmentation. Defaults to 0.
@@ -1718,10 +2059,10 @@ def is_segmentation_in_border(self,minimum=0, voxel_tolerance: int = 2,use_mm=Fa
 
     def truncate_labels_beyond_reference_(
         self, idx: int | list[int] = 1, not_beyond: int | list[int] = 1, fill: int = 0,  axis: DIRECTIONS = "S", inclusion: bool = False, inplace: bool = True
-    ):
-        """
-        Modifies the NIfTI object to remove all voxels with the label `idx` beyond a reference label `not_beyond`
-        along a specified axis, replacing them with `fill (default = 0)`.
+    ) -> Self:
+        """Remove voxels with label ``idx`` beyond a reference label along a specified axis.
+
+        Replaces those voxels with ``fill`` (default 0).
 
         Parameters:
             nii (NII): The NIfTI-like object with 3D imaging data.
@@ -1783,21 +2124,37 @@ def truncate_labels_beyond_reference(
         fill: int = 0,
         axis: DIRECTIONS = "S",
         inclusion: bool = False,
-        inplace=False
-    ):
-        return self.truncate_labels_beyond_reference_(idx,not_beyond,fill,axis,inclusion,inplace=inplace)
+        inplace=False,
+    ) -> Self:
+        """Removes label ``idx`` voxels beyond the extent of ``not_beyond`` along ``axis``.
 
-    def infect(self: NII, reference_mask: NII, inplace=False,verbose=True,axis:int|str|None=None,max_depth=None, _do_crop=True):
+        This is the out-of-place counterpart of ``truncate_labels_beyond_reference_``.
+        See that method for full parameter documentation.
+
+        Returns:
+            The modified NII (new object by default).
         """
-        Expands labels from self_mask into regions of reference_mask == 1 via breadth-first diffusion.
+        return self.truncate_labels_beyond_reference_(idx,not_beyond,fill,axis,inclusion,inplace=inplace)
+
+    def infect(self: NII, reference_mask: NII, inplace=False, verbose=True, axis: int | str | None = None, max_depth=None, _do_crop=True) -> Self:
+        """Expands labels from this segmentation into a reference mask via breadth-first diffusion.
+
+        Starting from the surface voxels of this NII, the algorithm propagates existing
+        labels into neighbouring voxels where ``reference_mask == 1``, until no more
+        unlabelled neighbour voxels remain (or ``max_depth`` is reached).
 
         Args:
-            self_mask (ndarray): (H, W) or (D, H, W) integer-labeled array.
-            reference_mask (ndarray): Binary array of same shape as self_mask.
-            max_iters (int): Maximum number of propagation steps.
+            reference_mask: Binary NII that defines the region into which labels may
+                spread. Must have the same affine as ``self``.
+            inplace: If True, modifies this NII in place. Defaults to False.
+            verbose: If True, shows a tqdm progress bar. Defaults to True.
+            axis: If given, restricts diffusion to the plane perpendicular to this
+                axis (int or anatomical direction string). Defaults to None (3-D).
+            max_depth: Maximum number of propagation steps (layers). Defaults to None
+                (unlimited).
 
         Returns:
-            ndarray: Updated label mask.
+            The NII with expanded labels.
         """
         self.assert_affine(reference_mask)
         if _do_crop:
@@ -1876,12 +2233,13 @@ def _infect(a,b,c,v,d):
                 self_mask = arr
         return self.set_array(self_mask,inplace=inplace)
 
-    def infect_(self: NII, reference_mask: NII,verbose=True,axis:int|str|None=None,_do_crop=True):
+    def infect_(self: NII, reference_mask: NII, verbose=True, axis: int | str | None = None,_do_crop=True) -> Self:
+        """In-place variant of `infect`."""
         return self.infect(reference_mask, inplace=True,verbose=verbose,axis=axis,_do_crop=_do_crop)
 
-    def map_labels(self, label_map:LABEL_MAP , verbose:logging=True, inplace=False):
-        """
-        Maps labels in the given NIfTI image according to the label_map dictionary.
+    def map_labels(self, label_map:LABEL_MAP , verbose:logging=True, inplace=False) -> Self:
+        """Maps labels in the given NIfTI image according to the label_map dictionary.
+
         Args:
             label_map (dict): A dictionary that maps the original label values (str or int) to the new label values (int).
                 For example, `{"T1": 1, 2: 3, 4: 5}` will map the original labels "T1", 2, and 4 to the new labels 1, 3, and 5, respectively.
@@ -1918,16 +2276,42 @@ def map_labels(self, label_map:LABEL_MAP , verbose:logging=True, inplace=False):
             return self
         return self.copy(nii)
 
-    def map_labels_(self, label_map: LABEL_MAP, verbose:logging=True):
+    def map_labels_(self, label_map: LABEL_MAP, verbose: logging = True) -> Self:
+        """In-place variant of `map_labels`."""
         return self.map_labels(label_map,verbose=verbose,inplace=True)
 
-    def copy(self, nib:Nifti1Image|_unpacked_nii|None = None,seg=None):
+    def copy(self, nib: Nifti1Image | _unpacked_nii | None = None, seg=None) -> NII:
+        """Returns a deep copy of this NII, optionally with a replacement image.
+
+        Args:
+            nib: If provided, the copy will use this image data instead of copying
+                the current array. Accepts a ``Nifti1Image`` or an
+                ``(array, affine, header)`` tuple. Defaults to None (copy current data).
+            seg: Override the ``seg`` flag in the returned copy. Defaults to None
+                (keep the current value).
+
+        Returns:
+            A new NII with the same ``c_val`` and ``info`` as this instance.
+        """
         if nib is None:
             nib = (self.get_array().copy(), self.affine.copy(), self.header.copy())
         return NII(nib,seg=self.seg if seg is None else seg,c_val = self.c_val,info = self.info)
 
 
-    def flip(self, axis:int|str,keep_global_coords=True,inplace=False):
+    def flip(self, axis: int | str, keep_global_coords=True, inplace=False) -> Self:
+        """Flips the image along a spatial axis.
+
+        Args:
+            axis: The axis to flip, specified as an integer index or an anatomical
+                direction string (e.g. ``"S"``, ``"R"``).
+            keep_global_coords: If True, the flip is implemented via a reorientation
+                so that world-space coordinates are preserved. If False, the array is
+                flipped in-place without adjusting the affine. Defaults to True.
+            inplace: If True, modifies this NII in place. Defaults to False.
+
+        Returns:
+            The flipped NII.
+        """
         axis = self.get_axis(axis) if not isinstance(axis,int) else axis
         if keep_global_coords:
             orient = list(self.orientation)
@@ -1936,10 +2320,21 @@ def flip(self, axis:int|str,keep_global_coords=True,inplace=False):
         else:
             return self.set_array(np.flip(self.get_array(),axis),inplace=inplace)
 
-    def clone(self):
+    def clone(self) -> NII:
+        """Returns a deep copy of this NII (alias for ``copy()``)."""
         return self.copy()
     @secure_save
-    def save(self,file:str|Path,make_parents=True,verbose:logging=True, dtype = None):
+    def save(self, file: str | Path, make_parents=True, verbose: logging = True, dtype=None) -> None:
+        """Saves this NII to a NIfTI file on disk.
+
+        Args:
+            file: Destination file path (e.g. ``"/path/to/image.nii.gz"``).
+            make_parents: If True, parent directories are created automatically.
+                Defaults to True.
+            verbose: If True (or a non-zero int), logs the save path and dtype.
+                Defaults to True.
+            dtype: Override the on-disk dtype. Defaults to None (use the array dtype).
+        """
         if make_parents:
             Path(file).parent.mkdir(0o777,exist_ok=True,parents=True)
         if str(file).endswith(".nrrd"):
@@ -1962,9 +2357,8 @@ def save(self,file:str|Path,make_parents=True,verbose:logging=True, dtype = None
         log.print(f"Save {file} as {out.get_data_dtype()}",verbose=verbose,ltype=Log_Type.SAVE)
 
     @secure_save
-    def save_nrrd(self:Self, file: str | Path|bids_files.BIDS_FILE,make_parents=True,verbose:logging=True,**args):
-        """
-        Save an NII object to an NRRD file.
+    def save_nrrd(self:Self, file: str | Path|bids_files.BIDS_FILE,make_parents=True,verbose:logging=True,**args) -> None:
+        """Save an NII object to an NRRD file.
 
         Args:
             nii_obj (NII): The NII object to be saved.
@@ -1992,8 +2386,7 @@ def to_stls(
         include_normals: bool = False,
         number_path: bool | None = None,
     ) -> dict[int, Mesh]:
-        """
-        Convert all labels in a segmentation into STL meshes.
+        """Convert all labels in a segmentation into STL meshes.
 
         This function iterates over all unique labels in the segmentation and
         applies `to_stl_single` to each label independently.
@@ -2060,8 +2453,7 @@ def to_stl(
         include_normals: bool = False,
         number_path=False,
     ) -> Mesh:
-        """
-        Convert a binary segmentation label into an STL surface mesh using marching cubes.
+        """Convert a binary segmentation label into an STL surface mesh using marching cubes.
 
         The function extracts a single label from a segmentation, runs marching cubes
         to generate a triangular surface mesh, and optionally transforms the vertices
@@ -2106,7 +2498,6 @@ def to_stl(
             - STL format stores only triangle geometry and per-face normals; it does
             not support per-vertex attributes such as scalar values from marching cubes.
         """
-
         from stl import mesh
 
         seg = self.extract_label(label)
@@ -2203,16 +2594,30 @@ def __setitem__(self, key,value):
 
 
     @classmethod
-    def suppress_dtype_change_printout_in_set_array(cls, value=True):
+    def suppress_dtype_change_printout_in_set_array(cls, value=True) -> None:
+        """Globally suppresses the log message emitted when ``set_array`` changes the dtype.
+
+        Args:
+            value: Set to True to suppress the message, False to re-enable it.
+                Defaults to True.
+        """
         global suppress_dtype_change_printout_in_set_array  # noqa: PLW0603
         suppress_dtype_change_printout_in_set_array = value
     def is_intersecting_vertical(self, b: Self, min_overlap=40) -> bool:
-        '''
-        Test if the image intersect in global space.
-        assumes same Rotation
-        TODO: Testing
-        '''
+        """Tests whether this image and ``b`` overlap vertically in global (world) space.
+
+        Uses the z-axis extent of both images' affines. Assumes the same rotation.
 
+        Args:
+            b: The other NII to test intersection against.
+            min_overlap: Minimum number of mm that must overlap. Defaults to 40.
+
+        Returns:
+            True if the two images overlap by at least ``min_overlap`` mm along z.
+
+        Note:
+            This method is untested; prefer ``get_intersecting_volume`` for reliable results.
+        """
         #warnings.warn('is_intersecting is untested use get_intersecting_volume instead')
         x1 = self.affine.dot([0, 0, 0, 1])[:3] # type: ignore
         x2 = self.affine.dot((*self.shape, 1))[:3]# type: ignore
@@ -2232,9 +2637,17 @@ def is_intersecting_vertical(self, b: Self, min_overlap=40) -> bool:
         return min_v < x2[2] < max_v
 
     def get_intersecting_volume(self, b: Self) -> float:
-        '''
-        computes intersecting volume
-        '''
+        """Returns the number of voxels in ``self``'s grid that overlap with image ``b``.
+
+        ``b`` is binarised (all non-zero → 1) and resampled into ``self``'s voxel
+        grid using constant-mode (zero fill) before summing the overlap.
+
+        Args:
+            b: The other image whose spatial extent is tested for overlap.
+
+        Returns:
+            The count of overlapping voxels as a float.
+        """
         b = to_nii(b).copy() # type: ignore
         b.nii = Nifti1Image(b.get_array()*0+1,affine=b.affine)
         b.seg = True
@@ -2243,14 +2656,25 @@ def get_intersecting_volume(self, b: Self) -> float:
         b = b.resample_from_to(self,c_val=0,verbose=False,mode="constant") # type: ignore
         return b.get_array().sum()
 
-    def extract_background(self,inplace=False):
+    def extract_background(self, inplace=False) -> Self:
+        """Returns a binary mask where all background (0) voxels are set to 1.
+
+        Args:
+            inplace: If True, modifies this NII in place. Defaults to False.
+
+        Returns:
+            An NII with 1 where the original segmentation had 0, and 0 elsewhere.
+
+        Raises:
+            AssertionError: If ``seg=False``.
+        """
         assert self.seg, "extracting the background only makes sense for a segmentation mask"
         arr_bg = self.get_seg_array()
         arr_bg = np_extract_label(arr_bg, label=0, to_label=1)
         return self.set_array(arr_bg, inplace, False)
 
-    def extract_label(self,label:int|Enum|Sequence[int]|Sequence[Enum]|None, keep_label=False,inplace=False):
-        '''If this NII is a segmentation you can single out one label with [0,1].'''
+    def extract_label(self,label:int|Enum|Sequence[int]|Sequence[Enum]|None, keep_label=False,inplace=False) -> Self:
+        """If this NII is a segmentation you can single out one label with [0,1]."""
         assert self.seg, "extracting a label only makes sense for a segmentation mask"
         if label is None:
             if keep_label:
@@ -2274,10 +2698,11 @@ def extract_label(self,label:int|Enum|Sequence[int]|Sequence[Enum]|None, keep_la
         if keep_label:
             seg_arr = seg_arr * self.get_seg_array()
         return self.set_array(seg_arr,inplace=inplace)
-    def extract_label_(self,label:int|Enum|Sequence[int]|Sequence[Enum], keep_label=False):
+    def extract_label_(self, label: int | Enum | Sequence[int] | Sequence[Enum], keep_label=False) -> Self:
+        """In-place variant of `extract_label`."""
         return self.extract_label(label,keep_label,inplace=True)
-    def remove_labels(self,label:int|Enum|Sequence[int]|Sequence[Enum], inplace=False, verbose:logging=True, removed_to_label=0):
-        '''If this NII is a segmentation you can single out one label.'''
+    def remove_labels(self,label:int|Enum|Sequence[int]|Sequence[Enum], inplace=False, verbose:logging=True, removed_to_label=0) -> Self:
+        """If this NII is a segmentation you can single out one label."""
         assert label != 0, 'Zero label does not make sens.  This is the background'
         seg_arr = self.get_seg_array()
         if not isinstance(label,Sequence):
@@ -2289,18 +2714,32 @@ def remove_labels(self,label:int|Enum|Sequence[int]|Sequence[Enum], inplace=Fals
             else:
                 seg_arr[seg_arr == l] = removed_to_label
         return self.set_array(seg_arr,inplace=inplace, verbose=verbose)
-    def remove_labels_(self,label:int|Enum|Sequence[int]|Sequence[Enum],removed_to_label=0, verbose:logging=True):
+    def remove_labels_(self, label: int | Enum | Sequence[int] | Sequence[Enum], removed_to_label=0, verbose: logging = True) -> Self:
+        """In-place variant of `remove_labels`."""
         return self.remove_labels(label,inplace=True,removed_to_label=removed_to_label,verbose=verbose)
-    def apply_mask(self,mask:Self, inplace=False):
+    def apply_mask(self, mask: Self, inplace=False) -> Self:
+        """Zeros out all voxels in this image that are background (0) in ``mask``.
+
+        Args:
+            mask: A segmentation NII used as the mask. Any non-zero voxel in the
+                mask is treated as foreground (1). Must have the same shape as
+                this image.
+            inplace: If True, modifies this NII in place. Defaults to False.
+
+        Returns:
+            The masked NII.
+
+        Raises:
+            AssertionError: If shapes do not match.
+        """
         assert mask.shape == self.shape, f"[def apply_mask] Mask and Shape are not equal: \nMask - {mask},\nSelf - {self})"
         seg_arr = mask.get_seg_array()
         seg_arr[seg_arr != 0] = 1
         arr = self.get_array()
         return self.set_array(arr*seg_arr,inplace=inplace)
 
-    def unique(self,verbose:logging=False,crop=False):
-        '''Returns all integer labels WITHOUT 0. Must be performed only on a segmentation nii'''
-
+    def unique(self,verbose:logging=False,crop=False) -> list[int]:
+        """Returns all integer labels WITHOUT 0. Must be performed only on a segmentation nii."""
         arr = self.get_seg_array()
         if crop:
             try:
@@ -2310,13 +2749,13 @@ def unique(self,verbose:logging=False,crop=False):
         out = np_unique_withoutzero(arr)
         log.print(out,verbose=verbose)
         return out
-    def voxel_volume(self):
-
+    def voxel_volume(self) -> float:
+        """Returns the volume of a single voxel in mm³ (product of all zoom values)."""
         product = math.prod(self.spacing)
         return product
 
     def volumes(self, include_zero: bool = False, in_mm3=False,sort=False) -> dict[int, float]|dict[int, int]:
-        '''Returns a dict stating how many pixels are present for each label'''
+        """Returns a dict stating how many pixels are present for each label."""
         dic =  np_volume(self.get_seg_array(), include_zero=include_zero)
         if sort:
             dic = dict(sorted(dic.items()))
@@ -2329,10 +2768,11 @@ def translate_arr(
         translation_vector: tuple[int, int, int] | dict[str,int]| dict[DIRECTIONS,int],
         inplace: bool = False,
         verbose: bool = True
-    ):
-        """
-        Translates the NIfTI image array by a given vector. Translation can be specified as a tuple
-        or as a dict using anatomical directions ('S', 'I', 'R', 'L', 'P', 'A').
+    ) -> Self:
+        """Translate the NIfTI image array by a given vector.
+
+        The vector can be a tuple of voxel offsets or a dict keyed by anatomical
+        direction letters (``'S'``, ``'I'``, ``'R'``, ``'L'``, ``'P'``, ``'A'``).
 
         Args:
             translation_vector (tuple or dict): Vector to translate with. Can be a tuple of ints
@@ -2361,13 +2801,24 @@ def translate_arr(
         return self.set_array(arr_translated, inplace=inplace)
 
     def center_of_masses(self) -> dict[int, COORDINATE]:
-        '''Returns a dict stating the center of mass for each present label (not including zero!)'''
+        """Returns a dict stating the center of mass for each present label (not including zero!)."""
         return np_center_of_mass(self.get_seg_array())
 
 
 
 
-def to_nii_optional(img_bids: Image_Reference|None, seg=False, default=None) -> NII | None:
+def to_nii_optional(img_bids: Image_Reference | None, seg=False, default=None) -> NII | None:
+    """Converts an image reference to NII, returning ``default`` on failure.
+
+    Args:
+        img_bids: Image reference to convert. May be None.
+        seg: Whether the image is a segmentation. Defaults to False.
+        default: Value to return if ``img_bids`` is None or conversion fails.
+            Defaults to None.
+
+    Returns:
+        An NII instance, or ``default`` if conversion fails.
+    """
     if img_bids is None:
         return default
     try:
@@ -2379,6 +2830,21 @@ def to_nii_optional(img_bids: Image_Reference|None, seg=False, default=None) ->
 
 
 def to_nii(img_bids: Image_Reference, seg=False) -> NII:
+    """Converts any supported image reference type to an NII object.
+
+    Supported input types: NII, Nifti1Image, BIDS_FILE, str/Path to a NIfTI,
+    NRRD, or MHA file.
+
+    Args:
+        img_bids: The image to load/convert.
+        seg: Whether the image is a segmentation mask. Defaults to False.
+
+    Returns:
+        An NII wrapping the image data.
+
+    Raises:
+        TypeError: If ``img_bids`` is not a recognised image reference type.
+    """
     if isinstance(img_bids, Path):
         img_bids = str(img_bids)
     # ugly workaround due to module import issues with nii files
@@ -2403,10 +2869,32 @@ def to_nii(img_bids: Image_Reference, seg=False) -> NII:
         raise TypeError(type(img_bids))
 
 def to_nii_seg(img: Image_Reference) -> NII:
+    """Shorthand for ``to_nii(img, seg=True)``.
+
+    Args:
+        img: The image reference to load as a segmentation.
+
+    Returns:
+        An NII with ``seg=True``.
+    """
     return to_nii(img,seg=True)
 
-def to_nii_interpolateable(i_img:Interpolateable_Image_Reference) -> NII:
+def to_nii_interpolateable(i_img: Interpolateable_Image_Reference) -> NII:
+    """Converts an interpolateable image reference to NII.
+
+    Unlike ``to_nii``, this accepts ``(image, seg_bool)`` tuples so that the seg
+    flag can be specified inline. It does not copy an NII that is already loaded.
 
+    Args:
+        i_img: An NII, a BIDS_FILE, or a ``(image_ref, seg)`` tuple where the
+            first element is any path/Nifti1Image and the second is the seg flag.
+
+    Returns:
+        An NII corresponding to the input.
+
+    Raises:
+        TypeError: If the input type is not recognised.
+    """
     if isinstance(i_img,tuple):
         img, seg = i_img
         return to_nii(img,seg=seg)
@@ -2417,7 +2905,8 @@ def to_nii_interpolateable(i_img:Interpolateable_Image_Reference) -> NII:
     else:
         raise TypeError("to_nii_interpolateable",i_img)
 
-def _rescale_affine(affine, shape, zooms, new_shape=None):
+def _rescale_affine(affine: AFFINE, shape, zooms, new_shape=None) -> AFFINE:
+    """Computes a new affine after rescaling an image to a different voxel spacing."""
     shape = np.asarray(shape)
     new_shape = np.array(new_shape if new_shape is not None else shape)
     s = nib.affines.voxel_sizes(affine)
diff --git a/TPTBox/core/nii_wrapper_math.py b/TPTBox/core/nii_wrapper_math.py
index 9250084..c695ead 100755
--- a/TPTBox/core/nii_wrapper_math.py
+++ b/TPTBox/core/nii_wrapper_math.py
@@ -19,133 +19,242 @@
 
     from TPTBox import NII
     class NII_Proxy:
+        """Minimal NII interface stub for TYPE_CHECKING — never instantiated at runtime."""
+
         seg = True
         c_val = 0
+
         def get_array(self) -> np.ndarray:
+            """Return a copy of the underlying array."""
             ...
-        def set_array(self,arr:np.ndarray,inplace=False,verbose=True)->Self:
+
+        def set_array(self, arr: np.ndarray, inplace=False, verbose=True) -> Self:
+            """Replace the underlying array."""
             ...
+
         def get_seg_array(self) -> np.ndarray:
+            """Return a copy of the underlying segmentation array."""
             ...
+
         @property
         def shape(self) -> tuple[int, int, int]:
+            """Spatial shape of the image."""
             ...
+
         @property
-        def dtype(self)->type:
+        def dtype(self) -> type:
+            """Data type of the array."""
             ...
+
         @property
         def header(self) -> Nifti1Header:
+            """NIfTI header."""
             ...
 
         @property
         def affine(self) -> np.ndarray:
+            """4×4 affine matrix."""
             ...
-        def get_c_val(self)->int:
+
+        def get_c_val(self) -> int:
+            """Return the fill/background value."""
             ...
-        def unique(self)->list[int]:
+
+        def unique(self) -> list[int]:
+            """Return sorted list of unique label values."""
             ...
     C = Union[NII, Number, np.ndarray]
 else:
     class NII_Proxy:
-        pass
-    C = Union[Self,Number,np.ndarray]
+        """Runtime no-op placeholder for the TYPE_CHECKING NII_Proxy stub."""
+
+    C = Union[Self, Number, np.ndarray]
+
+
+class NII_Math(NII_Proxy, Has_Grid):
+    """Mixin that adds arithmetic, comparison, and statistical operations to ``NII``.
+
+    All operators return a new ``NII`` by default (out-of-place).  In-place variants
+    (ending in ``_``) modify ``self`` directly.
+    """
 
-class NII_Math(NII_Proxy,Has_Grid):
     __hash__ = None  # type: ignore # explicitly mark as unhashable
-    def _binary_opt(self, other:C, opt,inplace = False)-> Self:
+
+    def _binary_opt(self, other: C, opt, inplace=False) -> Self:
+        """Apply a binary operator element-wise between this array and ``other``."""
         if isinstance(other,NII_Math):
             other = other.get_array()
         return self.set_array(opt(self.get_array(),other),inplace=inplace,verbose=False)
     def _uni_opt(self, opt,inplace = False,**args)-> Self:
+        """Apply a unary operator element-wise to this array."""
         return self.set_array(opt(self.get_array(),**args),inplace=inplace,verbose=False)
     def __add__(self,p2):
+        """Element-wise addition."""
         return self._binary_opt(p2,operator.add)
     def __radd__(self,p2):
+        """Right-hand element-wise addition."""
         return self._binary_opt(p2,operator.add)
     def __sub__(self,p2):
+        """Element-wise subtraction."""
         return self._binary_opt(p2,operator.sub)
     def __rsub__(self,p2)->Self:
+        """Right-hand element-wise subtraction."""
         return (-self)._binary_opt(p2,operator.add)
     def __mul__(self,p2):
+        """Element-wise multiplication."""
         return self._binary_opt(p2,operator.mul)
     def __pow__(self,p2):
+        """Element-wise exponentiation."""
         return self._binary_opt(p2,operator.pow)
     def __truediv__(self,p2):
+        """Element-wise true division."""
         return self._binary_opt(p2,operator.truediv)
     def __floordiv__(self,p2):
+        """Element-wise floor division."""
         return self._binary_opt(p2,operator.floordiv)
     def __mod__(self,p2):
+        """Element-wise modulo."""
         return self._binary_opt(p2,operator.mod)
     def __lshift__(self,p2):
+        """Element-wise left bit-shift."""
         return self._binary_opt(p2,operator.lshift)
     def __rshift__(self,p2):
+        """Element-wise right bit-shift."""
         return self._binary_opt(p2,operator.rshift)
     def __and__(self,p2):
+        """Element-wise bitwise AND (integer arrays only).
+
+        Raises:
+            TypeError: If the underlying array is not an integer dtype.
+        """
         if not np.issubdtype(self.get_array().dtype, np.integer):
             raise TypeError("Bitwise operations require integer arrays")
         return self._binary_opt(p2,operator.and_)
     def __or__(self,p2):
+        """Element-wise bitwise OR (integer arrays only).
+
+        Raises:
+            TypeError: If the underlying array is not an integer dtype.
+        """
         if not np.issubdtype(self.get_array().dtype, np.integer):
             raise TypeError("Bitwise operations require integer arrays")
         return self._binary_opt(p2,operator.or_)
     def __xor__(self,p2):
+        """Element-wise bitwise XOR (integer arrays only).
+
+        Raises:
+            TypeError: If the underlying array is not an integer dtype.
+        """
         if not np.issubdtype(self.get_array().dtype, np.integer):
             raise TypeError("Bitwise operations require integer arrays")
         return self._binary_opt(p2,operator.xor)
     def __invert__(self):
+        """Element-wise bitwise inversion (integer arrays only).
+
+        Raises:
+            TypeError: If the underlying array is not an integer dtype.
+        """
         if not np.issubdtype(self.get_array().dtype, np.integer):
             raise TypeError("Bitwise operations require integer arrays")
         return self._uni_opt(operator.invert)
 
     def __lt__(self,p2):
+        """Element-wise less-than comparison."""
         return self._binary_opt(p2,operator.lt)
     def __le__(self,p2):
+            """Element-wise less-than-or-equal comparison."""
             return self._binary_opt(p2,operator.le)
     def __eq__(self,p2):
             return self._binary_opt(p2,operator.eq)
     def __ne__(self,p2):
             return self._binary_opt(p2,operator.ne)
     def __gt__(self,p2):
+            """Element-wise greater-than comparison."""
             return self._binary_opt(p2,operator.gt)
     def __ge__(self,p2):
+            """Element-wise greater-than-or-equal comparison."""
             return self._binary_opt(p2,operator.ge)
 
     def __iadd__(self,p2):
+        """In-place element-wise addition."""
         return self._binary_opt(p2,operator.add,inplace=True)
     def __isub__(self,p2:C):
+        """In-place element-wise subtraction."""
         return self._binary_opt(p2,operator.sub,inplace=True)
     def __imul__(self,p2):
+        """In-place element-wise multiplication."""
         return self._binary_opt(p2,operator.mul,inplace=True)
     def __ipow__(self,p2):
+        """In-place element-wise exponentiation."""
         return self._binary_opt(p2,operator.pow,inplace=True)
     def __itruediv__(self,p2):
+        """In-place element-wise true division."""
         return self._binary_opt(p2,operator.truediv,inplace=True)
     def __ifloordiv__(self,p2):
+        """In-place element-wise floor division."""
         return self._binary_opt(p2,operator.floordiv,inplace=True)
     def __imod__(self,p2):
+        """In-place element-wise modulo."""
         return self._binary_opt(p2,operator.mod,inplace=True)
 
     def __neg__(self):
+        """Element-wise arithmetic negation."""
         return self._uni_opt(operator.neg)
     def __pos__(self):
+        """Element-wise unary plus (no-op for most dtypes)."""
         return self._uni_opt(operator.pos)
     def __abs__(self):
+        """Element-wise absolute value."""
         return self._uni_opt(operator.abs)
 
     def __round__(self, decimals=0):
+        """Round array values to the given number of decimal places."""
         return self._uni_opt(np.round,decimals=decimals)
-    def round(self,decimals):
+    def round(self, decimals) -> Self:
+        """Round array values to ``decimals`` decimal places.
+
+        Args:
+            decimals (int): Number of decimal places to round to.
+
+        Returns:
+            Self: New instance with rounded values.
+        """
         return self.__round__(decimals=decimals)
     def __floor__(self):
+        """Element-wise floor (round down to nearest integer)."""
         return self._uni_opt(np.floor)
     def __ceil__(self):
+        """Element-wise ceiling (round up to nearest integer)."""
         return self._uni_opt(np.ceil)
     def max(self)->float:
+        """Return the maximum value in the array.
+
+        Returns:
+            float: Maximum voxel value.
+        """
         return self.get_array().max()
     def min(self)->float:
+        """Return the minimum value in the array.
+
+        Returns:
+            float: Minimum voxel value.
+        """
         return self.get_array().min()
 
     def clamp(self, min=None,max=None,inplace=False)->Self:  # noqa: A002
+        """Clamp array values to the interval [min, max].
+
+        Values at or below ``min`` are set to ``min``; values at or above
+        ``max`` are set to ``max``.  Either bound may be omitted.
+
+        Args:
+            min (float | None, optional): Lower bound. Values <= min are clamped. Defaults to None.
+            max (float | None, optional): Upper bound. Values >= max are clamped. Defaults to None.
+            inplace (bool, optional): If True, modify the array in place. Defaults to False.
+
+        Returns:
+            Self: Instance with clamped values.
+        """
         arr = self.get_array()
         if min is not None:
             arr[arr<= min] = min
@@ -153,10 +262,28 @@ def clamp(self, min=None,max=None,inplace=False)->Self:  # noqa: A002
             arr[arr>= max] = max
         return self.set_array(arr,inplace=inplace,verbose=False)
 
-    def clamp_(self, min=None,max=None):  # noqa: A002
+    def clamp_(self, min=None, max=None) -> Self:  # noqa: A002
+        """In-place variant of `clamp`."""
         return self.clamp(min,max,inplace=True)
 
-    def normalize(self,min_out = 0, max_out = 1, quantile = 1., clamp_lower:float|None=None,inplace=False):
+    def normalize(self,min_out = 0, max_out = 1, quantile = 1., clamp_lower:float|None=None,inplace=False)->Self:
+        """Normalize array values to the range [min_out, max_out].
+
+        Non-zero voxels are used to compute the upper percentile. Values are
+        optionally clamped from below before scaling.
+
+        Args:
+            min_out (float, optional): Minimum value of the output range. Defaults to 0.
+            max_out (float, optional): Maximum value of the output range. Defaults to 1.
+            quantile (float, optional): Upper quantile (over non-zero voxels) used as the
+                pre-clamp ceiling. Defaults to 1.0 (full maximum).
+            clamp_lower (float | None, optional): If set, clamp values below this threshold
+                before normalizing. Defaults to None.
+            inplace (bool, optional): If True, modify the array in place. Defaults to False.
+
+        Returns:
+            Self: Instance with normalized values in [min_out, max_out].
+        """
         arr = self.get_array()
         max_v = np.quantile(arr[arr>0],q=quantile)
         arr = self.clamp(clamp_lower,max_v,inplace=inplace)
@@ -165,35 +292,127 @@ def normalize(self,min_out = 0, max_out = 1, quantile = 1., clamp_lower:float|No
         assert arr.max() == max_out, f"{arr.max()} == {max_out}"
         assert arr.min() == min_out
         return self.set_array(arr.get_array(),inplace)
-    def normalize_(self,min_out = 0, max_out = 1, quantile = 1., clamp_lower:float|None=None):
+    def normalize_(self,min_out = 0, max_out = 1, quantile = 1., clamp_lower:float|None=None)->Self:
+        """In-place variant of `normalize`."""
         return self.normalize(min_out = min_out, max_out = max_out, quantile = quantile, clamp_lower=clamp_lower,inplace=True)
-    def normalize_mri(self,min_out = 0, max_out = 1, quantile = 0.99, inplace=False):
+    def normalize_mri(self,min_out = 0, max_out = 1, quantile = 0.99, inplace=False)->Self:
+        """Normalize an MRI volume by clamping negatives and applying quantile-based scaling.
+
+        Negative voxels are clamped to zero before normalization.  The upper
+        bound is set to the 99th percentile (by default) of positive voxels.
+
+        Args:
+            min_out (float, optional): Minimum value of the output range. Defaults to 0.
+            max_out (float, optional): Maximum value of the output range. Defaults to 1.
+            quantile (float, optional): Upper quantile used for clamping. Defaults to 0.99.
+            inplace (bool, optional): If True, modify the array in place. Defaults to False.
+
+        Returns:
+            Self: Instance with normalized values.
+        """
         a  = self.clamp(min=0,inplace=inplace)
         return a.normalize(min_out = min_out, max_out = max_out,quantile = quantile,clamp_lower=0,inplace=inplace)
-    def normalize_ct(self,min_out = 0, max_out = 1,inplace=False):
+    def normalize_ct(self,min_out = 0, max_out = 1,inplace=False)->Self:
+        """Normalize a CT volume by clamping to [-1024, 1024] HU before scaling.
+
+        Args:
+            min_out (float, optional): Minimum value of the output range. Defaults to 0.
+            max_out (float, optional): Maximum value of the output range. Defaults to 1.
+            inplace (bool, optional): If True, modify the array in place. Defaults to False.
+
+        Returns:
+            Self: Instance with normalized values.
+        """
         arr = self.clamp(min=-1024,max=1024,inplace=inplace)
         return arr.normalize(min_out = min_out, max_out = max_out, inplace=inplace)
 
     def sum(self,axis = None,keepdims=False,where = np._NoValue, **qargs)->float:  # type: ignore
+        """Compute the sum of array values, optionally restricted to a mask.
+
+        Args:
+            axis (int | tuple[int, ...] | None, optional): Axis or axes along which to sum.
+                If None, sum over all elements. Defaults to None.
+            keepdims (bool, optional): If True, retain reduced axes as size-one dimensions.
+                Defaults to False.
+            where (NII | np.ndarray | np._NoValue, optional): Boolean mask selecting elements
+                to include. Accepts an NII-like object or a NumPy array. Defaults to np._NoValue.
+            **qargs: Additional keyword arguments forwarded to ``numpy.sum``.
+
+        Returns:
+            float: Sum of the selected elements.
+        """
         if hasattr(where,"get_array"):
             where=where.get_array().astype(bool)
 
         return np.sum(self.get_array(),axis=axis,keepdims=keepdims,where=where,**qargs)
     def mean(self,axis = None,keepdims=False,where = np._NoValue, **qargs)->float:  # type: ignore
+        """Compute the arithmetic mean of array values, optionally restricted to a mask.
+
+        Args:
+            axis (int | tuple[int, ...] | None, optional): Axis or axes along which to average.
+                If None, average over all elements. Defaults to None.
+            keepdims (bool, optional): If True, retain reduced axes as size-one dimensions.
+                Defaults to False.
+            where (NII | np.ndarray | np._NoValue, optional): Boolean mask selecting elements
+                to include. Accepts an NII-like object or a NumPy array. Defaults to np._NoValue.
+            **qargs: Additional keyword arguments forwarded to ``numpy.mean``.
+
+        Returns:
+            float: Mean of the selected elements.
+        """
         if hasattr(where,"get_array"):
             where=where.get_array().astype(bool)
 
         return np.mean(self.get_array(),axis=axis,keepdims=keepdims,where=where,**qargs)
-    def median(self, axis=None, keepdims=False,  **qargs):  # type: ignore
+    def median(self, axis=None, keepdims=False,  **qargs)->float:  # type: ignore
+        """Compute the median of array values.
+
+        Args:
+            axis (int | tuple[int, ...] | None, optional): Axis or axes along which to compute
+                the median. If None, compute over all elements. Defaults to None.
+            keepdims (bool, optional): If True, retain reduced axes as size-one dimensions.
+                Defaults to False.
+            **qargs: Additional keyword arguments forwarded to ``numpy.median``.
+
+        Returns:
+            float: Median of the array.
+        """
         arr = self.get_array()
         return np.median(arr, axis=axis, keepdims=keepdims, **qargs)
 
     def std(self,axis = None,keepdims=False,where = np._NoValue, **qargs)->float:  # type: ignore
+        """Compute the standard deviation of array values, optionally restricted to a mask.
+
+        Args:
+            axis (int | tuple[int, ...] | None, optional): Axis or axes along which to compute
+                the standard deviation. If None, compute over all elements. Defaults to None.
+            keepdims (bool, optional): If True, retain reduced axes as size-one dimensions.
+                Defaults to False.
+            where (NII | np.ndarray | np._NoValue, optional): Boolean mask selecting elements
+                to include. Accepts an NII-like object or a NumPy array. Defaults to np._NoValue.
+            **qargs: Additional keyword arguments forwarded to ``numpy.std``.
+
+        Returns:
+            float: Standard deviation of the selected elements.
+        """
         if hasattr(where,"get_array"):
             where=where.get_array().astype(bool)
 
         return np.std(self.get_array(),axis=axis,keepdims=keepdims,where=where,**qargs)
-    def threshold(self,threshold=0.5, inplace=False):
+    def threshold(self,threshold=0.5, inplace=False)->Self:
+        """Binarise the array by applying a hard threshold.
+
+        Voxels with values greater than or equal to ``threshold`` are set to 1;
+        all others are set to 0.  The result is flagged as a segmentation
+        (``seg=True``) and cast to the smallest integer dtype.
+
+        Args:
+            threshold (float, optional): Cut-off value. Defaults to 0.5.
+            inplace (bool, optional): If True, modify the array in place. Defaults to False.
+
+        Returns:
+            Self: Binarised segmentation instance.
+        """
         arr = self.get_array()
         arr2 = arr.copy()
         arr[arr2>=threshold] = 1
@@ -205,10 +424,32 @@ def threshold(self,threshold=0.5, inplace=False):
         nii.set_dtype_('smallest_int')
         return nii
 
-    def nan_to_num(self, num=0,inplace=False):
+    def nan_to_num(self, num=0,inplace=False)->Self:
+        """Replace NaN values in the array with a constant.
+
+        Args:
+            num (float, optional): Replacement value for NaN entries. Defaults to 0.
+            inplace (bool, optional): If True, modify the array in place. Defaults to False.
+
+        Returns:
+            Self: Instance with NaN values replaced.
+        """
         arr = self.get_array()
         return self.set_array(np.nan_to_num(arr,nan=num), inplace=inplace)
-    def ssim(self, nii:NII_Proxy, min_v = 0):
+    def ssim(self, nii:NII_Proxy, min_v = 0)->float:
+        """Compute the Structural Similarity Index (SSIM) between this image and another.
+
+        Both images are shifted by ``min_v``, normalised to [0, 1] and
+        negative values are zeroed before the SSIM is calculated.
+
+        Args:
+            nii (NII_Proxy): Reference image to compare against.
+            min_v (float, optional): Value subtracted from both images before normalisation.
+                Defaults to 0.
+
+        Returns:
+            float: SSIM score in the range [-1, 1] (1 = identical).
+        """
         img_1 = nii.get_array() - min_v
         img_2 = self.get_array() - min_v
         img_1/= img_1.max()
@@ -219,7 +460,20 @@ def ssim(self, nii:NII_Proxy, min_v = 0):
         return ssim_value
 
 
-    def psnr(self,nii: NII_Proxy,min_v=0):
+    def psnr(self,nii: NII_Proxy,min_v=0)->float:
+        """Compute the Peak Signal-to-Noise Ratio (PSNR) between this image and another.
+
+        Both images are shifted by ``min_v``, normalised to [0, 1] and
+        negative values are zeroed before the PSNR is calculated.
+
+        Args:
+            nii (NII_Proxy): Reference image to compare against.
+            min_v (float, optional): Value subtracted from both images before normalisation.
+                Defaults to 0.
+
+        Returns:
+            float: PSNR score in dB (higher is better; inf when images are identical).
+        """
         img_1 = nii.get_array() - min_v
         img_2 = self.get_array() - min_v
         img_1/= img_1.max()
@@ -229,6 +483,16 @@ def psnr(self,nii: NII_Proxy,min_v=0):
         ssim_value = psnr(img_1, img_2,data_range=img_1.max() - img_1.min())
         return ssim_value
     def dice(self,nii: NII_Proxy,bar=True)->dict[int,float]:
+        """Compute per-label Dice similarity coefficients against another segmentation.
+
+        Args:
+            nii (NII_Proxy): Predicted segmentation to compare against (ground truth is
+                ``self``).
+            bar (bool, optional): If True, display a tqdm progress bar. Defaults to True.
+
+        Returns:
+            dict[int, float]: Mapping from integer label to Dice score in [0, 1].
+        """
         out:dict[int,float] = {}
         gt = self.get_seg_array()
         pred = nii.get_seg_array()
@@ -242,8 +506,7 @@ def dice(self,nii: NII_Proxy,bar=True)->dict[int,float]:
         return out
 
     def betti_numbers(self: NII,verbose=False) -> dict[int, tuple[int, int, int]]: # type: ignore
-        """
-        Calculate Betti numbers for connected components in a 3D image.
+        """Calculate Betti numbers for connected components in a 3D image.
 
         Parameters:
         - self (NII): An object representing a 3D image with labeled connected components.
diff --git a/TPTBox/core/np_utils.py b/TPTBox/core/np_utils.py
index 4c9924e..826a02a 100755
--- a/TPTBox/core/np_utils.py
+++ b/TPTBox/core/np_utils.py
@@ -42,16 +42,18 @@ def np_extract_label(
     to_label: int = 1,
     inplace: bool = True,
 ) -> np.ndarray:
-    """Extracts a label from an given arr (works with zero as well!)
+    """Extracts a label from an given arr (works with zero as well!).
 
     Args:
         arr (np.ndarray): input arr
-        label (int): label to be extracted (all other values are set to zero, label will be set to one, even if label==0!)
+        label (int): label to be extracted (all other values are set to zero,
+            label will be set to one, even if label==0!)
         to_label (int): the value of the entries that had the <label> value. Defaults to 1.
         inplace (bool, optional): If False, will make a copy of the arr. Defaults to True.
 
     Returns:
-        np.ndarray: _description_
+        np.ndarray: Binary array where the selected label is set to ``to_label``
+            and all other entries are zero.
     """
     if isinstance(label, int) and to_label == 1:
         return arr == label
@@ -84,8 +86,7 @@ def np_extract_label(
 
 
 def cc3dstatistics(arr: UINTARRAY, use_crop: bool = True) -> dict:
-    """
-    Computes connected component statistics for a labeled array using connected components 3D (cc3d).
+    """Computes connected component statistics for a labeled array using connected components 3D (cc3d).
 
     Args:
         arr (UINTARRAY): A 3D array of unsigned integers or booleans where each connected component
@@ -114,13 +115,15 @@ def cc3dstatistics(arr: UINTARRAY, use_crop: bool = True) -> dict:
 
 
 def np_volume(arr: UINTARRAY, include_zero: bool = False) -> dict[int, int]:
-    """Returns a dictionary mapping array label to voxel_count
+    """Returns a dictionary mapping each label in the array to its voxel count.
 
     Args:
-        arr (np.ndarray): _description_
+        arr (UINTARRAY): Input unsigned-integer label array.
+        include_zero (bool, optional): If True, also counts voxels with label 0
+            (background). Defaults to False.
 
     Returns:
-        dict[int, int]: _description_
+        dict[int, int]: Mapping from label value to number of voxels with that label.
     """
     if include_zero:
         return {idx: i for idx, i in dict(enumerate(cc3dstatistics(arr, use_crop=False)["voxel_counts"])).items() if i > 0}
@@ -129,7 +132,7 @@ def np_volume(arr: UINTARRAY, include_zero: bool = False) -> dict[int, int]:
 
 
 def np_is_empty(arr: UINTARRAY | INTARRAY) -> bool:
-    """Returns true if the array is empty (only zeros)
+    """Returns true if the array is empty (only zeros).
 
     Args:
         arr (UINTARRAY): input uint array
@@ -146,25 +149,29 @@ def np_is_empty(arr: UINTARRAY | INTARRAY) -> bool:
 
 
 def np_count_nonzero(arr: np.ndarray) -> int:
-    """Returns number of nonzero entries in the array
+    """Returns number of nonzero entries in the array.
 
     Args:
-        arr (np.ndarray): _description_
+        arr (np.ndarray): Input array.
 
     Returns:
-        int: _description_
+        int: Number of elements in ``arr`` that are not equal to zero.
     """
     return np.count_nonzero(arr)
 
 
 def np_unique(arr: np.ndarray) -> list[int]:
-    """Returns each existing label in the array (including zero!)
+    """Returns each existing label in the array (including zero!).
+
+    Uses cc3d statistics for unsigned-integer arrays for speed, and falls back
+    to ``numpy.unique`` for other dtypes.
 
     Args:
-        arr (np.ndarray): _description_
+        arr (np.ndarray): Input label array.
 
     Returns:
-        list[int]: _description_
+        list[int]: Sorted list of every distinct label value present in ``arr``,
+            including 0 (background).
     """
     if np.issubdtype(arr.dtype, np.unsignedinteger):
         try:
@@ -175,13 +182,14 @@ def np_unique(arr: np.ndarray) -> list[int]:
 
 
 def np_unique_withoutzero(arr: UINTARRAY) -> list[int]:
-    """Returns each existing label in the array (including zero!)
+    """Returns each existing non-zero label in the array (excluding background zero).
 
     Args:
-        arr (np.ndarray): _description_
+        arr (UINTARRAY): Input unsigned-integer label array.
 
     Returns:
-        list[int]: _description_
+        list[int]: Sorted list of every distinct label value present in ``arr``,
+            excluding 0 (background).
     """
     try:
         return [idx for idx, i in enumerate(cc3dstatistics(arr)["voxel_counts"]) if i > 0 and idx != 0]
@@ -191,13 +199,14 @@ def np_unique_withoutzero(arr: UINTARRAY) -> list[int]:
 
 
 def np_center_of_mass(arr: UINTARRAY) -> dict[int, COORDINATE]:
-    """Calculates center of mass, mapping label in array to a coordinate (float) (exluding zero)
+    """Calculates center of mass for each non-zero label in the array.
 
     Args:
-        arr (np.ndarray): _description_
+        arr (UINTARRAY): Input unsigned-integer label array.
 
     Returns:
-        dict[int, Coordinate]: _description_
+        dict[int, COORDINATE]: Mapping from each non-zero label to its
+            (x, y, z) center-of-mass coordinate as floats.
     """
     stats = cc3dstatistics(arr, use_crop=False)
     # Does not use the other calls for speed reasons
@@ -206,13 +215,15 @@ def np_center_of_mass(arr: UINTARRAY) -> dict[int, COORDINATE]:
 
 
 def np_bounding_boxes(arr: UINTARRAY) -> dict[int, tuple[slice, slice, slice]]:
-    """Calculates bounding boxes for each different label (not zero!) in the array, returning a mapping
+    """Calculates tight axis-aligned bounding boxes for each non-zero label in the array.
 
     Args:
-        arr (np.ndarray): _description_
+        arr (UINTARRAY): Input unsigned-integer label array.
 
     Returns:
-        dict[int, tuple[slice, slice, slice]]: _description_
+        dict[int, tuple[slice, slice, slice]]: Mapping from each non-zero label
+            to a 3-tuple of slices representing the bounding box of that label
+            in each spatial dimension.
     """
     stats = cc3dstatistics(arr)
     # Does not use the other calls for speed reasons
@@ -220,15 +231,17 @@ def np_bounding_boxes(arr: UINTARRAY) -> dict[int, tuple[slice, slice, slice]]:
     return {idx: v for idx, v in enumerate(stats["bounding_boxes"]) if idx in unique}
 
 
-def np_contacts(arr: UINTARRAY, connectivity: int):
-    """Calculates the contacting labels and the amount of touching voxels based on connectivity
+def np_contacts(arr: UINTARRAY, connectivity: int) -> dict[tuple[int, int], int]:
+    """Calculates the contacting labels and the amount of touching voxels based on connectivity.
 
     Args:
-        arr (UINTARRAY): _description_
-        connectivity (int): _description_
+        arr (UINTARRAY): Input 2D or 3D label array.
+        connectivity (int): Connectivity level in range [1, 3]. 1 = face-only,
+            2 = face+edge, 3 = face+edge+corner adjacency.
 
     Returns:
-        dict[tuple[int,int], int]: mapping touching labels as tuple to number of touching voxels
+        dict[tuple[int, int], int]: Mapping from a pair of touching labels to the
+            number of voxels where they touch.
     """
     assert 2 <= arr.ndim <= 3, f"expected 2D or 3D, but got {arr.ndim}"
     assert 1 <= connectivity <= 3, f"expected connectivity in [1,3], but got {connectivity}"
@@ -236,15 +249,17 @@ def np_contacts(arr: UINTARRAY, connectivity: int):
     return _contacts(arr, connectivity=connectivity)
 
 
-def np_region_graph(arr: UINTARRAY, connectivity: int):
-    """Returns the unique tuples of different labels in the array touching each other
+def np_region_graph(arr: UINTARRAY, connectivity: int) -> set[tuple[int, int]]:
+    """Returns the unique pairs of different labels that are adjacent in the array.
 
     Args:
-        arr (UINTARRAY): _description_
-        connectivity (int): _description_
+        arr (UINTARRAY): Input 2D or 3D label array.
+        connectivity (int): Connectivity level in range [1, 3]. 1 = face-only,
+            2 = face+edge, 3 = face+edge+corner adjacency.
 
     Returns:
-        set[tuple[int,int]]: touching labels in the array
+        set[tuple[int, int]]: Set of (label_a, label_b) pairs where each pair
+            indicates two labels that share at least one adjacent voxel.
     """
     assert 2 <= arr.ndim <= 3, f"expected 2D or 3D, but got {arr.ndim}"
     assert 1 <= connectivity <= 3, f"expected connectivity in [1,3], but got {connectivity}"
@@ -252,8 +267,8 @@ def np_region_graph(arr: UINTARRAY, connectivity: int):
     return _region_graph(arr, connectivity=connectivity)
 
 
-def np_voxel_connectivity_graph(arr: UINTARRAY, connectivity: int):
-    """Returns a voxel connectivity graph of the input array
+def np_voxel_connectivity_graph(arr: UINTARRAY, connectivity: int) -> np.ndarray:
+    """Returns a voxel connectivity graph of the input array.
 
     For 2D connectivity, the output is an 8-bit unsigned integer.
 
@@ -273,11 +288,13 @@ def np_voxel_connectivity_graph(arr: UINTARRAY, connectivity: int):
         26-32: unused (zeroed)
 
     Args:
-        arr (UINTARRAY): _description_
-        connectivity (int): _description_
+        arr (UINTARRAY): Input 2D or 3D label array.
+        connectivity (int): Connectivity level in range [1, 3]. 1 = face-only,
+            2 = face+edge, 3 = face+edge+corner adjacency.
 
     Returns:
-        uint8 or uint32 numpy array the same size as the input
+        np.ndarray: uint8 or uint32 array the same shape as the input, where
+            each value encodes which neighbors share the same label as that voxel.
     """
     assert 2 <= arr.ndim <= 3, f"expected 2D or 3D, but got {arr.ndim}"
     assert 1 <= connectivity <= 3, f"expected connectivity in [1,3], but got {connectivity}"
@@ -285,8 +302,8 @@ def np_voxel_connectivity_graph(arr: UINTARRAY, connectivity: int):
     return _voxel_connectivity_graph(arr, connectivity=connectivity)
 
 
-def np_dice(seg: np.ndarray, gt: np.ndarray, binary_compare: bool = False, label: int = 1):
-    """Calculates the dice similarity between two numpy arrays
+def np_dice(seg: np.ndarray, gt: np.ndarray, binary_compare: bool = False, label: int = 1) -> float:
+    """Calculates the dice similarity between two numpy arrays.
 
     Args:
         seg: segmentation array
@@ -315,11 +332,10 @@ def np_dice(seg: np.ndarray, gt: np.ndarray, binary_compare: bool = False, label
     return dice
 
 
-def np_erode_msk_euclid(arr: np.ndarray, n_pixel: int = 3, use_crop=True, labels=None, mask=None):
-    """
-    Fast approximate erosion:
-    - shrinks segmentation by k voxels
-    - removes voxels close to background
+def np_erode_msk_euclid(arr: np.ndarray, n_pixel: int = 3, use_crop=True, labels=None, mask=None) -> np.ndarray:
+    """Euclidean erosion: shrink each foreground label by ``n_pixel`` voxels via distance transform.
+
+    Removes voxels whose Euclidean distance to background is ≤ ``n_pixel``.
     """
     if use_crop:
         arr_bin = arr.copy()
@@ -362,11 +378,10 @@ def np_erode_msk_euclid(arr: np.ndarray, n_pixel: int = 3, use_crop=True, labels
     return arr
 
 
-def np_dilate_msk_euclid(arr: np.ndarray, n_pixel: int = 3, use_crop=True, labels=None, mask=None):
-    """
-    Fast approximate dilation:
-    - expands segmentation by k voxels
-    - assigns new voxels to nearest label
+def np_dilate_msk_euclid(arr: np.ndarray, n_pixel: int = 3, use_crop=True, labels=None, mask=None) -> np.ndarray:
+    """Euclidean dilation: expand each foreground label by ``n_pixel`` voxels via distance transform.
+
+    Assigns each newly covered voxel to the nearest existing label.
     """
     if use_crop:
         arr_bin = arr.copy()
@@ -415,20 +430,26 @@ def np_dilate_msk(
     mask: np.ndarray | None = None,
     ignore_axis: None | int = None,
 ) -> np.ndarray:
-    """
-    Dilates the given array by the specified number of voxels (not including the zero).
+    """Dilates the given array by the specified number of voxels (not including the zero label).
 
     Args:
-        mm (int, optional): The number of voxels to dilate the mask by. Defaults to 5.
-        connectivity (int, optional): Elements up to a squared distance of connectivity from the center are considered neighbors. connectivity may range from 1 (no diagonal elements are neighbors) to rank (all elements are neighbors).
-        mask (nparray, optional): If set, after each iteration, will zero out everything based on this mask
-        ignore_axis: This axis will be ignored. e. g. do 2d dilation in a 3d array
-    Returns:
-        nparray: The dilated mask.
-
-    Notes:
-        The method uses binary dilation with a 3D structuring element to dilate the mask by the specified number of voxels.
+        arr (np.ndarray): Input label array.
+        label_ref (LABEL_REFERENCE, optional): Label or list of labels to dilate.
+            If None, all non-zero labels are dilated. Defaults to None.
+        n_pixel (int, optional): Number of voxels to dilate by. Defaults to 5.
+        connectivity (int, optional): Elements up to a squared distance of
+            ``connectivity`` from the center are considered neighbors.
+            Ranges from 1 (no diagonal neighbors) to 3 (all neighbors). Defaults to 3.
+        use_crop (bool, optional): If True, crops to a bounding box before dilating
+            for speed. Defaults to True.
+        mask (np.ndarray | None, optional): If set, after each iteration all voxels
+            outside this mask are zeroed out. Defaults to None.
+        ignore_axis (int | None, optional): If set, dilation is performed in 2D
+            along all slices of this axis (e.g., 0 for slice-wise axial dilation).
+            Defaults to None.
 
+    Returns:
+        np.ndarray: The dilated label array.
     """
     labels: list[int] = _to_labels(arr, label_ref)
     # present_labels = np_unique(arr)
@@ -488,18 +509,25 @@ def np_erode_msk(
     border_value=0,
     ignore_axis: None | int = None,
 ) -> np.ndarray:
-    """
-    Erodes the given array by the specified number of voxels.
+    """Erodes the given array by the specified number of voxels.
 
     Args:
-        mm (int, optional): The number of voxels to erode the mask by. Defaults to 5.
-        connectivity (int, optional): Elements up to a squared distance of connectivity from the center are considered neighbors. connectivity may range from 1 (no diagonal elements are neighbors) to rank (all elements are neighbors).
-        ignore_axis: This axis will be ignored. e. g. do 2d erosion in a 3d array
-    Returns:
-        nparray: The eroded mask.
+        arr (np.ndarray): Input label array.
+        label_ref (LABEL_REFERENCE, optional): Label or list of labels to erode.
+            If None, all non-zero labels are eroded. Defaults to None.
+        n_pixel (int, optional): Number of voxels to erode by. Defaults to 5.
+        use_crop (bool, optional): If True, crops to a bounding box before eroding
+            for speed. Defaults to True.
+        connectivity (int, optional): Elements up to a squared distance of
+            ``connectivity`` from the center are considered neighbors.
+            Ranges from 1 (no diagonal neighbors) to 3 (all neighbors). Defaults to 3.
+        border_value (int, optional): Value to pad the border with during erosion.
+            Defaults to 0.
+        ignore_axis (int | None, optional): If set, erosion is performed in 2D
+            along all slices of this axis. Defaults to None.
 
-    Notes:
-        The method uses binary erosion with a 3D structuring element to erode the mask by the specified number of voxels.
+    Returns:
+        np.ndarray: The eroded label array.
     """
     labels: list[int] = _to_labels(arr, label_ref)
 
@@ -537,12 +565,16 @@ def np_erode_msk(
 
 
 def np_map_labels(arr: UINTARRAY, label_map: LABEL_MAP) -> np.ndarray:
-    """Maps labels in the given array according to the label_map dictionary.
+    """Maps labels in the given array according to a label-map dictionary.
+
     Args:
-        label_map (dict): A dictionary that maps the original label values (str or int) to the new label values (int).
+        arr (UINTARRAY): Input unsigned-integer label array to remap.
+        label_map (LABEL_MAP): Dictionary mapping original label values (int or str)
+            to new label values (int or str). Labels not present in the map are
+            left unchanged.
 
     Returns:
-        np.ndarray: Returns a copy of the remapped array
+        np.ndarray: A new array with labels remapped according to ``label_map``.
     """
     k = np.array(list(label_map.keys()))
     v = np.array(list(label_map.values()))
@@ -564,18 +596,21 @@ def np_calc_crop_around_centerpoint(
     cutout_size: tuple[int, ...],
     pad_to_size: Sequence[int] | np.ndarray | int = 0,
 ) -> tuple[np.ndarray, tuple[slice, slice, slice], tuple]:
-    """
+    """Crops a fixed-size region centred on a given point, optionally padding near-edge regions.
 
     Args:
-        poi: center point of cutout
-        arr: input array to cut
-        cutout_size: size of the image cutout
-        pad_to_size: additional padding amount
+        poi: Center point of the cutout, one coordinate per dimension.
+        arr: Input array to crop.
+        cutout_size: Desired size of the cutout in each dimension.
+        pad_to_size: Additional symmetric padding to add around the cutout.
+            Can be a single int (same for all dims) or a per-dim sequence.
+            Defaults to 0.
 
     Returns:
-        np.ndarray: cut array
-        tuple of the cutout coordinates
-        tuple of the paddings
+        tuple: A 3-element tuple containing:
+            - np.ndarray: The cropped (and padded) sub-array.
+            - tuple[slice, ...]: Slices used to extract the cutout from ``arr``.
+            - tuple: Per-dimension padding amounts applied as ``(pad_before, pad_after)``.
     """
     n_dim = len(poi)
     if isinstance(pad_to_size, int):
@@ -603,7 +638,7 @@ def np_calc_crop_around_centerpoint(
 
 
 def np_bbox_binary(img: np.ndarray, px_dist: int | Sequence[int] | np.ndarray = 0, raise_error=True) -> tuple[slice, ...]:
-    """calculates a bounding box in n dimensions given a image (factor ~2 times faster than compute_crop)
+    """Calculates a bounding box in n dimensions given a image (factor ~2 times faster than compute_crop).
 
     Args:
         img: input array
@@ -638,7 +673,7 @@ def np_bbox_binary(img: np.ndarray, px_dist: int | Sequence[int] | np.ndarray =
     return out
 
 
-def np_center_of_bbox_binary(img: np.ndarray, px_dist: int | Sequence[int] | np.ndarray = 0):
+def np_center_of_bbox_binary(img: np.ndarray, px_dist: int | Sequence[int] | np.ndarray = 0) -> list[int]:
     """Calculates the center coordinates of the bounding box around non-zero regions in a binary image.
 
     This function determines the bounding box of non-zero regions in a binary image,
@@ -668,7 +703,7 @@ def np_center_of_bbox_binary(img: np.ndarray, px_dist: int | Sequence[int] | np.
 
 
 def _np_get_min_max_pad(pos: int, img_size: int, cutout_size: int, add_pad_size: int = 0) -> tuple[int, int, int, int]:
-    """calc the min and max position around a center "pos" of a img and cutout size and whether it needs to be padded
+    """Calc the min and max position around a center "pos" of a img and cutout size and whether it needs to be padded.
 
     Args:
         pos: center position in one dim
@@ -694,7 +729,7 @@ def _np_get_min_max_pad(pos: int, img_size: int, cutout_size: int, add_pad_size:
 
 
 def np_find_index_of_k_max_values(arr: np.ndarray, k: int = 2) -> list[int]:
-    """Calculates the indices of the k-highest values in the given arr
+    """Calculates the indices of the k-highest values in the given arr.
 
     Args:
         arr: input array
@@ -708,7 +743,7 @@ def np_find_index_of_k_max_values(arr: np.ndarray, k: int = 2) -> list[int]:
     return list(indices)
 
 
-def np_compute_surface(arr: UINTARRAY, connectivity: int = 3, dilated_surface: bool = False):
+def np_compute_surface(arr: UINTARRAY, connectivity: int = 3, dilated_surface: bool = False) -> UINTARRAY:
     """Computes the surface of a binary array based on connectivity and dilation options.
 
     This function identifies the surface voxels of a binary array. If `dilated_surface`
@@ -741,7 +776,7 @@ def np_compute_surface(arr: UINTARRAY, connectivity: int = 3, dilated_surface: b
 
 def np_point_coordinates(
     arr: UINTARRAY,
-):
+) -> list[tuple[int, int, int]]:
     """Extracts the coordinates of non-zero points from a 3D binary array.
 
     This function locates all non-zero voxels within a 3D binary array and returns
@@ -769,7 +804,7 @@ def np_connected_components(
     connectivity: int = 3,
     include_zero: bool = False,
 ) -> tuple[UINTARRAY, int]:
-    """Calculates the connected components of a given array (works with zeros as well!)
+    """Calculates the connected components of a given array (works with zeros as well!).
 
     Args:
         arr: input arr
@@ -800,8 +835,10 @@ def np_connected_components_per_label(
     label_ref: LABEL_REFERENCE = None,
     include_zero: bool = False,
 ) -> dict[int, UINTARRAY]:
-    """Calculates the connected components of a given array for each label in label_ref (works with zeros as well!)
-    It returns a dictionary mapping the labels in label_ref to its corresponding connected components mask
+    """Calculates the connected components for each label in label_ref.
+
+    Returns a dictionary mapping each label to its connected-component mask.
+    Supports zero labels when ``include_zero=True``.
 
     Args:
         arr: input arr
@@ -812,7 +849,6 @@ def np_connected_components_per_label(
     Returns:
         subreg_cc: dict[label, cc_idx, arr], subreg_cc_N: dict[label, n_connected_components]
     """
-
     assert np.min(arr) == 0, f"min value of mask not zero, got {np.min(arr)}"
     assert np.max(arr) >= 0, f"wrong normalization, max value is not >= 0, got {np_unique(arr)}"
     assert 2 <= arr.ndim <= 3, f"expected 2D or 3D, but got {arr.ndim}"
@@ -851,7 +887,7 @@ def np_filter_connected_components(
     removed_to_label=0,
     k_larges_global=False,
 ) -> UINTARRAY:
-    """finds the largest k connected components in a given array (does NOT work with zero as label!)
+    """Finds the largest k connected components in a given array (does NOT work with zero as label!).
 
     Args:
         arr (np.ndarray): input array
@@ -863,7 +899,6 @@ def np_filter_connected_components(
     Returns:
         np.ndarray: array with the largest k connected components
     """
-
     assert largest_k_components is None or largest_k_components > 0
     assert 2 <= arr.ndim <= 3, f"expected 2D or 3D, but got {arr.ndim}"
     assert 1 <= connectivity <= 3, f"expected connectivity in [1,3], but got {connectivity}"
@@ -924,16 +959,19 @@ def np_filter_connected_components(
 def np_get_connected_components_center_of_mass(
     arr: UINTARRAY, label: int, connectivity: int = 3, sort_by_axis: int | None = None
 ) -> list[COORDINATE]:
-    """Calculates the center of mass of the different connected components of a given label in an array
+    """Calculates the center of mass of each connected component of a given label.
 
     Args:
-        arr (np.ndarray): input array
-        label (int): the label of the connected components
-        connectivity (int, optional): Connectivity for the connected components. Defaults to 3.
-        sort_by_axis (int | None, optional): If not none, will sort the center of mass list by this axis values. Defaults to None.
+        arr (UINTARRAY): Input label array.
+        label (int): The label whose connected components are analysed.
+        connectivity (int, optional): Connectivity for connected components in range
+            [1, 3]. Defaults to 3.
+        sort_by_axis (int | None, optional): If not None, the returned list is sorted
+            in ascending order of the coordinate along this axis. Defaults to None.
 
     Returns:
-        _type_: _description_
+        list[COORDINATE]: List of (x, y, z) center-of-mass coordinates, one per
+            connected component of ``label``.
     """
     # Per label argument true/false
     #
@@ -952,7 +990,7 @@ def np_get_connected_components_center_of_mass(
 
 
 def np_translate_to_center_of_array(image: np.ndarray) -> np.ndarray:
-    """Moves the nonzero values of an array so its center of mass is in the center of the array shape
+    """Moves the nonzero values of an array so its center of mass is in the center of the array shape.
 
     Args:
         image: input array
@@ -1014,7 +1052,7 @@ def np_fill_holes(
     use_crop: bool = True,
     pbar: bool = False,
 ) -> np.ndarray:
-    """Fills holes in segmentations
+    """Fills holes in segmentations.
 
     Args:
         arr (np.ndarray): Input segmentation array
@@ -1079,8 +1117,7 @@ def np_smooth_gaussian_labelwise(
     smooth_background: bool = True,
     background_threshold: float | None = None,
 ) -> UINTARRAY:
-    """Smoothes selected labels in a segmentation mask using Gaussian filtering,
-    while keeping other labels unaffected.
+    """Smooth selected labels in a segmentation mask using Gaussian filtering, leaving other labels unaffected.
 
     Internal Description:
         1. Ensures label(s) to be smoothed are present in the segmentation.
@@ -1178,12 +1215,20 @@ def np_calc_convex_hull(
     arr: INTARRAY,
     axis: int | None = None,
     verbose: bool = False,
-):
-    """Calculates the convex hull of a given array, returning the array filled with its convex hull
+) -> INTARRAY:
+    """Calculates the convex hull of a given array and returns a filled binary mask.
 
     Args:
-        arr (INTARRAY): Input array
-        axis (int | None, optional): If given axis, will calculate convex hull along that axis (remaining dimension must be at least 2). Defaults to None.
+        arr (INTARRAY): Input integer array (non-zero voxels define the point set).
+        axis (int | None, optional): If given, computes the convex hull slice-by-slice
+            along this axis (remaining dimensions must be at least 2D). If None,
+            computes the hull over the full 2D or 3D volume. Defaults to None.
+        verbose (bool, optional): If True, prints warnings for degenerate cases.
+            Defaults to False.
+
+    Returns:
+        INTARRAY: Binary array of the same shape as ``arr`` with 1 inside the
+            convex hull and 0 outside.
     """
     n_dims = arr.ndim
     if axis is None:
@@ -1206,6 +1251,7 @@ def np_calc_convex_hull(
 
 
 def _select_axis_dynamically(axis: int, index: int | slice, n_dims: int = 3):
+    """Build an n-dimensional index tuple that selects a single slice along ``axis``."""
     slices = tuple([slice(None) if i != axis else index for i in range(n_dims)])
     return slices
 
@@ -1214,13 +1260,17 @@ def _convex_hull(
     arr: INTARRAY,
     verbose: bool = False,
 ):
-    """Calculates the convex hull of a given array (all labels are taken)
+    """Calculates the convex hull of a given array (all non-zero voxels are treated as points).
 
     Args:
-        arr (INTARRAY): integer array
+        arr (INTARRAY): Integer array; all non-zero voxels contribute to the hull.
+        verbose (bool, optional): If True, prints a warning when there are too few
+            points to form a hull. Defaults to False.
 
     Returns:
-        _type_: out_img, hull
+        tuple: A 2-element tuple ``(out_img, hull)`` where ``out_img`` is a binary
+            array filled inside the convex hull and ``hull`` is the
+            ``scipy.spatial.ConvexHull`` object.
     """
     points = np.transpose(np.where(arr))
     if len(points) <= 3:
@@ -1239,9 +1289,8 @@ def np_calc_boundary_mask(
     img: np.ndarray,
     threshold: float = 0,
     adjust_intensity_for_ct=False,
-):
-    """
-    Calculate a boundary mask based on the input image.
+) -> np.ndarray:
+    """Calculate a boundary mask based on the input image.
 
     Parameters:
     - img (NII): The image used to create the boundary mask.
@@ -1314,19 +1363,25 @@ def infect(x, y, z):
 
 
 def np_betti_numbers(img: np.ndarray, verbose=False) -> tuple[int, int, int]:
-    """
-    calculates the Betti number B0, B1, and B2 for a 3D img
-    from the Euler characteristic number
+    """Calculates the Betti numbers B0, B1, and B2 for a 3D binary image.
+
+    Uses the Euler characteristic to derive the counts from connected-component
+    analysis of both the foreground (26-connected) and background (6-connected).
 
-    B0: Number of connected compotes
-    B1: Number of holes
-    B2: Number of fully engulfed empty spaces
+    B0: Number of connected components.
+    B1: Number of loops / handles (tunnels).
+    B2: Number of fully enclosed voids.
 
-    code prototyped by
-    - Martin Menten (Imperial College)
-    - Suprosanna Shit (Technical University Munich)
-    - Johannes C. Paetzold (Imperial College)
+    Code prototyped by Martin Menten (Imperial College), Suprosanna Shit (TU Munich),
+    and Johannes C. Paetzold (Imperial College).
     Source: https://github.com/CoWBenchmark/TopCoW_Eval_Metrics/blob/master/metric_functions.py
+
+    Args:
+        img (np.ndarray): 3D binary array (values must be 0 or 1).
+        verbose (bool, optional): If True, prints the Betti numbers. Defaults to False.
+
+    Returns:
+        tuple[int, int, int]: ``(B0, B1, B2)`` — connected components, holes, and voids.
     """
     # make sure the image is 3D (for connectivity settings)
     assert len(img.shape) == 3
@@ -1359,7 +1414,7 @@ def np_calc_overlapping_labels(
     reference_arr: np.ndarray,
     prediction_arr: np.ndarray,
 ) -> list[tuple[int, int]]:
-    """Calculates the pairs of labels that are overlapping in at least one voxel (fast)
+    """Calculates the pairs of labels that are overlapping in at least one voxel (fast).
 
     Args:
         prediction_arr (np.ndarray): Numpy array containing the prediction labels.
@@ -1382,6 +1437,17 @@ def np_calc_overlapping_labels(
 
 
 def np_normalize_to_range(arr: np.ndarray, min_value: float = 0, max_value: float = 1500) -> np.ndarray:
+    """Normalize array values so the minimum maps to ``min_value`` and the maximum is capped at ``max_value``.
+
+    Args:
+        arr (np.ndarray): Input array to normalize. Modified in-place.
+        min_value (float, optional): Target minimum value after shift. Defaults to 0.
+        max_value (float, optional): Upper bound; if the original maximum exceeds
+            this, values are scaled down proportionally. Defaults to 1500.
+
+    Returns:
+        np.ndarray: The normalized array (same object as input, modified in-place).
+    """
     mi, ma = arr.min(), arr.max()
     arr += -mi + min_value  # min = 0
     max_value2 = ma
@@ -1392,8 +1458,8 @@ def np_normalize_to_range(arr: np.ndarray, min_value: float = 0, max_value: floa
     return arr
 
 
-def np_fill_holes_global_with_majority_voting(arr: UINTARRAY, connectivity: int = 3, inplace: bool = False, verbose=False):  # noqa: ARG001
-    """Fill holes globaly (across labels) and resolves inter-label conflicts with majority voting of neighbors
+def np_fill_holes_global_with_majority_voting(arr: UINTARRAY, connectivity: int = 3, inplace: bool = False, verbose=False) -> UINTARRAY:  # noqa: ARG001
+    """Fill holes globaly (across labels) and resolves inter-label conflicts with majority voting of neighbors.
 
     Args:
         arr (UINTARRAY): input array
@@ -1434,8 +1500,8 @@ def np_map_labels_based_on_majority_label_mask_overlap(
     dilate_pixel: int = 1,
     inplace: bool = False,
     no_match_label=0,
-):
-    """Relabels all individual labels from input array to the majority labels of a given label_mask
+) -> UINTARRAY:
+    """Relabels all individual labels from input array to the majority labels of a given label_mask.
 
     Args:
         arr (UINTARRAY): input array to be relabeled
@@ -1476,7 +1542,7 @@ def _pad_to_parameters(
     origin_shape: list[int] | tuple[int, int, int],
     target_shape: list[int] | tuple[int, int, int],
 ):
-    """Returns the parameter to pad the input to the target shape
+    """Returns the parameter to pad the input to the target shape.
 
     Args:
         arr (np.ndarray): input array
@@ -1504,6 +1570,7 @@ def _pad_to_parameters(
 
 
 def _to_labels(arr: np.ndarray, label_ref: LABEL_REFERENCE = None) -> Sequence[int]:
+    """Resolve ``label_ref`` to a list of integer labels present in ``arr``."""
     if label_ref is None:
         label_ref = list(np_unique_withoutzero(arr))
     if not isinstance(label_ref, Sequence):
@@ -1512,6 +1579,7 @@ def _to_labels(arr: np.ndarray, label_ref: LABEL_REFERENCE = None) -> Sequence[i
 
 
 def _generate_binary_structure(n_dim: int, connectivity: int, kernel_size: int = 3):
+    """Generate a binary structuring element for morphological operations with an extended kernel size."""
     assert kernel_size >= 3, f"kernel_size must be >= 3, got {kernel_size}"
     assert kernel_size % 2 == 1, f"kernel_size must be an odd number, got {kernel_size}"
     connectivity = max(connectivity, 1)
@@ -1524,7 +1592,8 @@ def _generate_binary_structure(n_dim: int, connectivity: int, kernel_size: int =
 
 
 # Fast Binary Morphological operations (taken from https://github.com/shoheiogawa/binmorphopy/blob/master/binmorphopy/morphology.py)
-def _binary_dilation(image: np.ndarray, struct=None):
+def _binary_dilation(image: np.ndarray, struct=None) -> np.ndarray:
+    """Fast binary dilation using perimeter-based iteration (1D, 2D, and 3D)."""
     selem = struct
     dim = image.ndim
     if not isinstance(image, np.ndarray):
@@ -1585,6 +1654,7 @@ def _binary_dilation(image: np.ndarray, struct=None):
 
 
 def _binary_erosion(image: np.ndarray, struct=None) -> np.ndarray:
+    """Fast binary erosion implemented as complement-dilation of the complement image."""
     image = image.astype(bool)
     image = np.pad(image, 1, constant_values=0)
     out_image = _binary_dilation(~image, struct)
@@ -1595,6 +1665,7 @@ def _binary_erosion(image: np.ndarray, struct=None) -> np.ndarray:
 
 
 def _unpad(image: np.ndarray, pad_width: tuple[tuple[int, int], ...] | int):
+    """Remove padding from an array, reversing a prior ``np.pad`` call."""
     slices = []
     if isinstance(pad_width, int):
         ndim = image.ndim
@@ -1606,17 +1677,19 @@ def _unpad(image: np.ndarray, pad_width: tuple[tuple[int, int], ...] | int):
 
 
 def _binary_closing(image: np.ndarray, struct=None):
+    """Fast binary closing: dilation followed by erosion."""
     out_image = _binary_erosion(_binary_dilation(image, struct), struct)
     return out_image
 
 
 def _binary_opening(image, struct=None):
+    """Fast binary opening: erosion followed by dilation."""
     out_image = _binary_dilation(_binary_erosion(image, struct), struct)
     return out_image
 
 
 def _get_perimeter_image(image):
-    """Return the image of the perimeter structure of the input image
+    """Return the image of the perimeter structure of the input image.
 
     Args:
         image (Numpy array): Image data as an array
@@ -1676,7 +1749,7 @@ def _get_perimeter_image(image):
 
 
 def _generate_array_indices(selem_center, selem_radius, selem_length, result_length):
-    """Return the correct indices for slicing considering near-edge regions
+    """Return the correct indices for slicing considering near-edge regions.
 
     Args:
         selem_center (int): The index of the structuring element's center
diff --git a/TPTBox/core/poi.py b/TPTBox/core/poi.py
index 81bf6a9..6a3d53a 100755
--- a/TPTBox/core/poi.py
+++ b/TPTBox/core/poi.py
@@ -6,7 +6,10 @@
 from copy import deepcopy
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import TypeVar, Union
+from typing import TYPE_CHECKING, TypeVar, Union
+
+if TYPE_CHECKING:
+    from TPTBox.core.poi_fun.poi_global import POI_Global
 
 import nibabel as nib
 import nibabel.orientations as nio
@@ -51,8 +54,7 @@
 
 @dataclass
 class POI(Abstract_POI, Has_Grid):
-    """
-    This class represents a collection of POIs used to define points of interest in medical imaging data.
+    """This class represents a collection of POIs used to define points of interest in medical imaging data.
 
     Attributes:
         orientation (Ax_Codes): A tuple of three string values representing the orientation of the image.
@@ -120,7 +122,8 @@ class POI(Abstract_POI, Has_Grid):
     _zoom: ZOOMS = field(init=False, default=(1, 1, 1), repr=False, compare=False)
     _vert_orientation_pir = {}  # Elusive; will not be saved; will not be copied. For Buffering results  # noqa: RUF012
 
-    def _set_inplace(self, poi: Self):
+    def _set_inplace(self, poi: Self) -> Self:
+        """Copy all grid/affine attributes and centroids from ``poi`` into ``self``."""
         self.orientation = poi.orientation
         self.centroids = poi.centroids
         self.zoom = poi.zoom
@@ -130,19 +133,23 @@ def _set_inplace(self, poi: Self):
         return self
 
     @property
-    def is_global(self):
+    def is_global(self) -> bool:
+        """Always False for voxel-space POIs; True only for POI_Global objects."""
         return False
 
     @property
-    def rotation(self):
+    def rotation(self) -> ROTATION:
+        """3×3 rotation matrix of the image grid, or None if not set."""
         return self._rotation
 
     @property
-    def zoom(self):
+    def zoom(self) -> ZOOMS:
+        """Voxel spacing in mm along each axis, or None if not set."""
         return self._zoom
 
     @property
-    def spacing(self):
+    def spacing(self) -> ZOOMS:
+        """Alias for :attr:`zoom`."""
         return self._zoom
 
     @rotation.setter
@@ -167,7 +174,8 @@ def zoom(self, value):
     def spacing(self, value):
         self.zoom = value
 
-    def clone(self, **qargs):
+    def clone(self, **qargs) -> Self:
+        """Return a copy of this POI; alias for :meth:`copy`."""
         return self.copy(**qargs)
 
     __hash__ = None  # type: ignore # explicitly mark as unhashable
@@ -196,6 +204,7 @@ def copy(
                 Defaults to Sentinel(), in which case the original rotation matrix will be used.
             origin (Coordinate | None | Sentinel, optional): The origin coordinates to use in the copied object.
                 Defaults to Sentinel(), in which case the original origin coordinates will be used.
+
         Returns:
             POI: A new POI object with the specified attribute overrides.
 
@@ -286,17 +295,18 @@ def apply_crop_reverse(
         o_shift: tuple[slice, slice, slice] | Sequence[slice],
         shape: tuple[int, int, int] | Sequence[int],
         inplace=False,
-    ):
-        """A Poi crop can be trivially reversed with out any loss. See apply_crop for more information"""
+    ) -> Self:
+        """A Poi crop can be trivially reversed with out any loss. See apply_crop for more information."""
         return self.apply_crop(
             tuple(slice(-shift.start, sh - shift.start) for shift, sh in zip_strict(o_shift, shape)),
             inplace=inplace,
         )
 
-    def apply_crop(self: Self, o_shift: tuple[slice, slice, slice] | Sequence[slice], inplace=False):
-        """When you crop an image, you have to also crop the POIs.
-        There are actually no boundary to be moved, but the origin must be moved to the new 0,0,0
-        Points outside the frame are NOT removed. See NII.compute_crop_slice()
+    def apply_crop(self: Self, o_shift: tuple[slice, slice, slice] | Sequence[slice], inplace=False) -> Self:
+        """Adjust POI coordinates after a crop operation by shifting the origin.
+
+        Points outside the cropped frame are NOT removed.
+        See :meth:`~TPTBox.NII.compute_crop_slice`.
 
         Args:
             o_shift (tuple[slice, slice, slice]): translation of the origin, cause by the crop
@@ -381,15 +391,30 @@ def shift2(x, y, z):
         out = self.copy(centroids=poi_out.centroids, shape=shape, rotation=self.rotation, origin=origin)
         return out
 
-    def apply_crop_(self, o_shift: tuple[slice, slice, slice] | Sequence[slice]):
+    def apply_crop_(self, o_shift: tuple[slice, slice, slice] | Sequence[slice]) -> Self:
+        """In-place variant of :meth:`apply_crop`."""
         return self.apply_crop(o_shift, inplace=True)
 
-    def shift_all_coordinates(self, translation_vector: tuple[slice, slice, slice] | Sequence[slice] | None, inplace=True, **kwargs):
+    def shift_all_coordinates(
+        self, translation_vector: tuple[slice, slice, slice] | Sequence[slice] | None, inplace=True, **kwargs
+    ) -> Self:
+        """Shift all POI coordinates by a translation expressed as crop slices.
+
+        Args:
+            translation_vector: Per-axis slices encoding the origin shift, or ``None``
+                to return ``self`` unchanged.
+            inplace (bool, optional): Whether to modify in place. Defaults to True.
+
+        Returns:
+            Self: The updated POI (same object when ``inplace=True``).
+        """
         if translation_vector is None:
             return self
         return self.apply_crop(translation_vector, inplace=inplace, **kwargs)
 
-    def reorient(self, axcodes_to: AX_CODES = ("P", "I", "R"), decimals=ROUNDING_LVL, verbose: logging = False, inplace=False, _shape=None):
+    def reorient(
+        self, axcodes_to: AX_CODES = ("P", "I", "R"), decimals=ROUNDING_LVL, verbose: logging = False, inplace=False, _shape=None
+    ) -> Self:
         """Reorients the POIs of an image from the current orientation to the specified orientation.
 
         This method updates the position of the POIs, zoom level, and shape of the image accordingly.
@@ -489,7 +514,8 @@ def reorient(self, axcodes_to: AX_CODES = ("P", "I", "R"), decimals=ROUNDING_LVL
             return self
         return self.copy(orientation=axcodes_to, centroids=points, zoom=zoom, shape=shape, origin=origin, rotation=rotation)
 
-    def reorient_(self, axcodes_to: AX_CODES = ("P", "I", "R"), decimals=3, verbose: logging = False, _shape=None):
+    def reorient_(self, axcodes_to: AX_CODES = ("P", "I", "R"), decimals=3, verbose: logging = False, _shape=None) -> Self:
+        """In-place variant of :meth:`reorient`."""
         return self.reorient(axcodes_to, decimals=decimals, verbose=verbose, inplace=True, _shape=_shape)
 
     def rescale(self, voxel_spacing: ZOOMS = (1, 1, 1), decimals=ROUNDING_LVL, verbose: logging = True, inplace=False) -> Self:
@@ -546,9 +572,10 @@ def rescale(self, voxel_spacing: ZOOMS = (1, 1, 1), decimals=ROUNDING_LVL, verbo
         return self.copy(centroids=points, zoom=voxel_spacing, shape=shp)
 
     def rescale_(self, voxel_spacing: ZOOMS = (1, 1, 1), decimals=3, verbose: logging = False) -> Self:
+        """In-place variant of :meth:`rescale`."""
         return self.rescale(voxel_spacing=voxel_spacing, decimals=decimals, verbose=verbose, inplace=True)
 
-    def to_global(self, itk_coords=False):
+    def to_global(self, itk_coords=False) -> POI_Global:
         """Converts the Centroids object to a global POI_Global object.
 
         This method converts the local POI coordinates to global coordinates using the Centroids' zoom,
@@ -567,10 +594,19 @@ def to_global(self, itk_coords=False):
             self, itk_coords=itk_coords, level_one_info=self.level_one_info, level_two_info=self.level_two_info, info=self.info.copy()
         )
 
-    def resample_from_to(self, ref: Has_Grid):
+    def resample_from_to(self, ref: Has_Grid) -> POI:
+        """Resample this POI to the grid of another image by converting to global and back.
+
+        Args:
+            ref (Has_Grid): Target image grid (any object providing affine/orientation info).
+
+        Returns:
+            POI: A new POI in the voxel space of ``ref``.
+        """
         return self.to_global().to_other(ref)
 
-    def resample_from_to_(self, ref: Has_Grid):
+    def resample_from_to_(self, ref: Has_Grid) -> Self:
+        """In-place variant of :meth:`resample_from_to`."""
         return self._set_inplace(self.resample_from_to(ref))
 
     def save(
@@ -582,8 +618,7 @@ def save(
         resample_reference: Has_Grid | None = None,
         verbose: logging = True,
     ) -> None:
-        """
-        Saves the POIs to a JSON file.
+        """Saves the POIs to a JSON file.
 
         Args:
             out_path (Path | str): The path where the JSON file will be saved.
@@ -591,6 +626,7 @@ def save(
                 Defaults to False.
             verbose (bool, optional): If True, print status messages to the console. Defaults to True.
             save_hint: 0 Default, 1 Gruber, 2 POI (readable), 10 ISO-POI (outdated)
+
         Returns:
             None
 
@@ -605,7 +641,7 @@ def save(
             self, out_path, make_parents, additional_info, verbose=verbose, save_hint=save_hint, resample_reference=resample_reference
         )
 
-    def make_point_cloud_nii(self, affine=None, s=8, sphere=False):
+    def make_point_cloud_nii(self, affine=None, s=8, sphere=False) -> tuple[NII, NII]:
         """Create point cloud NIfTI images from the POI coordinates.
 
         This method generates two NIfTI images, one for the regions and another for the subregions,
@@ -627,7 +663,6 @@ def make_point_cloud_nii(self, affine=None, s=8, sphere=False):
             >>> neighborhood_size = 10
             >>> region_cloud, subregion_cloud = POI_obj.make_point_cloud_nii(s=neighborhood_size)
         """
-
         assert self.shape is not None, "need shape information"
         assert self.zoom is not None, "need shape information"
         if affine is None:
@@ -799,13 +834,15 @@ def __eq__(self, value: object) -> bool:
         return self.centroids == value2.centroids
 
 
-def _loc2int(i: int | Abstract_lvl):
+def _loc2int(i: int | Abstract_lvl) -> int:
+    """Convert a location enum member or integer to its integer value."""
     if isinstance(i, int):
         return i
     return i.value
 
 
-def _loc2int_list(i: int | Abstract_lvl | Sequence[int | Abstract_lvl]):
+def _loc2int_list(i: int | Abstract_lvl | Sequence[int | Abstract_lvl]) -> list[int]:
+    """Convert a location or sequence of locations to a list of integer values."""
     if isinstance(i, Sequence):
         return [_loc2int(j) for j in i]
     if isinstance(i, int):
@@ -816,6 +853,7 @@ def _loc2int_list(i: int | Abstract_lvl | Sequence[int | Abstract_lvl]):
 def _int2loc(
     i: int | Abstract_lvl | Sequence[int | Abstract_lvl] | Sequence[Abstract_lvl] | Sequence[int],
 ) -> Abstract_lvl | Sequence[Abstract_lvl]:
+    """Convert an integer (or sequence of integers) to the corresponding :class:`Location` enum member(s)."""
     if isinstance(i, Sequence):
         return [_int2loc(j) for j in i]  # type: ignore
     elif isinstance(i, int):
@@ -835,13 +873,10 @@ def calc_poi_from_two_segs(
     check_every_point=True,
     # use_vertebra_special_action=True,
 ) -> POI:
-    """
-    Computes the centroids of the given mask `msk_reference` with respect to the given subregion `subreg_reference`,
-    and saves them to a file at `out_path` (if `override=False` and the file already exists, the function loads and returns
-    the existing centroids from the file).
+    """Compute centroids of a mask within each subregion and optionally save/load from file.
 
-    If `out_path` is None and `msk_reference` is a `BIDS.bids_files.BIDS_FILE` object, the function generates a path to
-    save the centroids file based on the `label` attribute of the file and the given `subreg_id`.
+    If ``out_path`` is ``None`` and ``msk_reference`` is a :class:`~TPTBox.BIDS_FILE`, a path is
+    generated automatically from its label attribute and ``subreg_id``.
 
     If `subreg_reference` is None, the function computes the centroids using only `msk_reference`.
 
@@ -911,7 +946,13 @@ def calc_poi_from_two_segs(
 
 
 def _buffer_it(func):
-    """Decorator that reports the execution time."""
+    """Decorator that enables disk-based buffering of partial POI results.
+
+    If ``buffer_file`` kwarg points to an existing file the decorated function
+    loads the previously saved POI as ``extend_to`` before calling ``func``.
+    When ``save_buffer_file=True`` and the result has grown, it saves the result
+    back to ``buffer_file``.
+    """
 
     @functools.wraps(func)
     def wrap(*args, **kwargs):
@@ -952,8 +993,8 @@ def calc_poi_from_subreg_vert(
     _print_phases=False,
     _orientation_version=0,
 ) -> POI:
-    """
-    Calculates the POIs of a subregion within a vertebral mask. This function is spine opinionated, the general implementation is "calc_poi_from_two_masks".
+    """Calculates the POIs of a subregion within a vertebral mask. This function is spine opinionated, the general implementation is "calc_poi_from_two_masks".
+
     Args:
         vert_msk (Image_Reference): A vertebral mask image reference.
         subreg (Image_Reference): An image reference for the subregion of interest.
@@ -963,6 +1004,7 @@ def calc_poi_from_subreg_vert(
         verbose (bool, optional): Whether to print progress messages. Defaults to False.
         fixed_offset (int, optional): A fixed offset value to add to the calculated POI coordinates. Defaults to 0.
         extend_to (POI | None, optional): An existing POI object to extend with the new POI values. Defaults to None.
+
     Returns:
         POI: A POI object containing the calculated POI coordinates.
     """
@@ -1102,9 +1144,8 @@ def calc_centroids_from_two_masks(
     limit_ids_of_lvl_2: int | Sequence[int] | None = None,
     verbose: bool = True,
     extend_to: POI | None = None,
-):
-    """
-    Calculates the centroids of two masks, representing a hierarchical relationship.
+) -> POI:
+    """Calculates the centroids of two masks, representing a hierarchical relationship.
 
     Args:
         lvl_1_msk (Image_Reference): An image reference representing the higher-level mask (instance).
@@ -1162,7 +1203,12 @@ def calc_centroids_from_two_masks(
     return poi
 
 
-def _is_not_yet_computed(ids_in_arr: Sequence[int], extend_to: POI | None, subreg_id: int):
+def _is_not_yet_computed(ids_in_arr: Sequence[int], extend_to: POI | None, subreg_id: int) -> bool:
+    """Check whether any (region, subreg_id) pair in ``ids_in_arr`` is missing from ``extend_to``.
+
+    Returns True if at least one entry still needs to be computed, False if all
+    entries for ``subreg_id`` are already present in ``extend_to``.
+    """
     is_not_yet_computed = True
     if extend_to is not None and subreg_id in extend_to.centroids.keys_subregion():
         is_not_yet_computed = False
@@ -1186,8 +1232,7 @@ def calc_centroids(
     bar=False,
     _crop=True,
 ) -> POI:
-    """
-    Calculates the centroid coordinates of each region in the given mask image.
+    """Calculates the centroid coordinates of each region in the given mask image.
 
     Args:
         msk (Image_Reference): An `Image_Reference` object representing the input mask image.
@@ -1258,13 +1303,19 @@ def calc_centroids(
 
 
 def calc_poi_average(pois: list[POI], keep_points_not_present_in_all_pois: bool = False) -> POI:
-    """Calculates average of POI across list of POIs and removes all points that are not fully present in all given POIs
+    """Compute the element-wise average of POI coordinates across a list of POIs.
 
     Args:
-        pois (list[POI]): _description_
+        pois (list[POI]): List of POI objects to average.  All POIs must share the
+            same orientation, zoom, shape, and rotation.
+        keep_points_not_present_in_all_pois (bool, optional): If True, include
+            points that appear in at least one POI (missing entries are excluded
+            from the average for that key).  If False, only include points that
+            are present in every POI. Defaults to False.
 
     Returns:
-        POI: _description_
+        POI: A new POI whose coordinates are the mean of the corresponding
+            coordinates across all input POIs.
     """
     # Get the keys that are present in all POIs
     keys = set(pois[0].keys())
@@ -1282,7 +1333,8 @@ def calc_poi_average(pois: list[POI], keep_points_not_present_in_all_pois: bool
     return POI(centroids=ctd, orientation=pois[0].orientation, zoom=pois[0].zoom, shape=pois[0].shape, rotation=pois[0].rotation)
 
 
-def _load_from_POI_spine_r(data: dict):
+def _load_from_POI_spine_r(data: dict) -> POI:
+    """Parse an old POI-spine-R JSON dict format and return a POI object."""
     orientation = None
     centroids = POI_Descriptor()
     for d in data["centroids"]["centroids"]:
diff --git a/TPTBox/core/poi_fun/README.md b/TPTBox/core/poi_fun/README.md
new file mode 100644
index 0000000..9e2de67
--- /dev/null
+++ b/TPTBox/core/poi_fun/README.md
@@ -0,0 +1,35 @@
+# POI Strategies (`core/poi_fun`)
+
+Internal subpackage implementing the different strategies for computing Points of Interest (POIs)
+from NIfTI segmentation volumes.  End users typically call the high-level helpers in `poi.py` and
+`vert_constants.py`; the modules here provide the underlying algorithms.
+
+## Modules
+
+| Module | Description |
+|---|---|
+| `ray_casting.py` | Casts rays through a volume to find surface-intersection points |
+| `vertebra_direction.py` | Derives superior/inferior/anterior/posterior unit vectors per vertebra |
+| `vertebra_pois_non_centroids.py` | Computes non-centroid anatomical landmarks (process tips, endplates) |
+| `pixel_based_point_finder.py` | Locates extreme/boundary pixels within a label for POI placement |
+| `strategies.py` | Pluggable strategy objects for POI computation |
+| `save_load.py` | JSON serialisation/deserialisation for `POI` objects |
+| `save_mkr.py` | Export POIs as 3D Slicer markup files (`.fcsv`, `.mrk.json`) |
+| `poi_abstract.py` | Abstract base classes shared across POI modules |
+| `poi_global.py` | `POI_Global` — POI container in world-coordinate (mm) space |
+| `_help.py` | Internal helpers (not part of the public API) |
+
+## Key symbols
+
+| Symbol | Module | Description |
+|---|---|---|
+| `POI_Global` | `poi_global.py` | World-space POI container; used after `POI.to_global()` |
+| `save_poi` | `save_load.py` | Serialise a `POI` to a JSON file |
+| `load_poi` | `save_load.py` | Deserialise a `POI` from a JSON file |
+| `save_poi_as_slicer_markup` | `save_mkr.py` | Write POIs as a 3D Slicer `.mrk.json` markup file |
+
+## Coordinate system
+
+POIs inside this package use the same convention as `poi.py`:
+- **Local** (`is_global() == False`): voxel indices `(i, j, k)` into the reference NIfTI
+- **Global** (`is_global() == True`): world coordinates in mm, consistent with the NIfTI affine
diff --git a/TPTBox/core/poi_fun/_help.py b/TPTBox/core/poi_fun/_help.py
index b69815b..334d0f5 100644
--- a/TPTBox/core/poi_fun/_help.py
+++ b/TPTBox/core/poi_fun/_help.py
@@ -15,7 +15,34 @@
 sacrum_w_o_direction = (Vertebra_Instance.COCC.value,)
 
 
-def to_local_np(loc: Location, bb: tuple[slice, slice, slice] | None, poi: POI, label, log: Logger_Interface, verbose=True):
+def to_local_np(
+    loc: Location,
+    bb: tuple[slice, slice, slice] | None,
+    poi: POI,
+    label: int,
+    log: Logger_Interface,
+    verbose: bool = True,
+) -> np.ndarray | None:
+    """Retrieve a POI coordinate in local (bounding-box) voxel space.
+
+    Looks up ``(label, loc.value)`` in ``poi``.  When a bounding box ``bb`` is
+    provided the global coordinate is shifted to the local sub-volume origin by
+    subtracting each slice's start.
+
+    Args:
+        loc: ``Location`` enum member identifying the subregion.
+        bb: Bounding-box slices used to convert global to local coordinates.
+            Pass ``None`` to return the raw global coordinate.
+        poi: ``POI`` object containing the landmark data.
+        label: Region (vertebra) integer label.
+        log: Logger used for failure messages.
+        verbose: Emit a failure log message when the POI is missing.
+            Defaults to ``True``.
+
+    Returns:
+        1-D numpy array ``(x, y, z)`` in local coordinates, or ``None`` when
+        the requested POI is not present in ``poi``.
+    """
     if (label, loc.value) in poi:
         if bb is None:
             return np.asarray(poi[label, loc.value])
@@ -26,7 +53,31 @@ def to_local_np(loc: Location, bb: tuple[slice, slice, slice] | None, poi: POI,
     return None
 
 
-def paint_into_NII(poi: POI, a: NII, l=None, idxs=None, rays: None | list[tuple[Location, Location]] = None):
+def paint_into_NII(
+    poi: POI,
+    a: NII,
+    l: list[Location] | None = None,
+    idxs: list[int] | None = None,
+    rays: list[tuple[Location, Location]] | None = None,
+) -> NII:
+    """Paint POI landmarks and connecting rays into a segmentation NII image.
+
+    Draws centroid markers for each location in ``l`` and (optionally) rays
+    connecting pairs of POI locations onto ``a``.
+
+    Args:
+        poi: ``POI`` object with the landmarks to draw.
+        a: Target ``NII`` image that will be modified in place.
+        l: List of ``Location`` members whose centroids are drawn.  Defaults to
+            ``[Location.Vertebra_Disc_Inferior, Location.Vertebra_Disc_Superior]``.
+        idxs: Region (vertebra) labels to include.  Defaults to all regions
+            in ``poi``, sorted.
+        rays: List of ``(start_loc, end_loc)`` pairs that define direction rays
+            to paint.  Defaults to IVD disc start/end connections.
+
+    Returns:
+        The modified ``NII`` image ``a`` with landmarks and rays painted in.
+    """
     from TPTBox.core.poi_fun.ray_casting import add_ray_to_img
 
     if l is None:
@@ -64,6 +115,8 @@ def paint_into_NII(poi: POI, a: NII, l=None, idxs=None, rays: None | list[tuple[
 
 
 def timing(f):
+    """Decorator that logs the wall-clock execution time of the wrapped function."""
+
     @wraps(f)
     def wrap(*args, **kw):
         ts = time()
@@ -75,7 +128,19 @@ def wrap(*args, **kw):
     return wrap
 
 
-def make_spine_plot(pois: POI, body_spline, vert_nii: NII, filenames):
+def make_spine_plot(pois: POI, body_spline: np.ndarray, vert_nii: NII, filenames: str) -> None:
+    """Render a 2-D maximum-intensity-projection plot of the spine with the fitted spline.
+
+    Projects the vertebra mask onto the sagittal plane and overlays the POI
+    centroid positions and the spline curve.  The figure is saved to ``filenames``.
+
+    Args:
+        pois: ``POI`` object with vertebra centroids.
+        body_spline: Array of shape ``(N, 3)`` with the spline sample points in
+            isotropic reoriented space.
+        vert_nii: Vertebra segmentation ``NII`` used as the background image.
+        filenames: Output file path passed to ``matplotlib.pyplot.savefig``.
+    """
     from matplotlib import pyplot as plt
 
     pois = pois.reorient()
diff --git a/TPTBox/core/poi_fun/pixel_based_point_finder.py b/TPTBox/core/poi_fun/pixel_based_point_finder.py
index 27abc16..25cee24 100644
--- a/TPTBox/core/poi_fun/pixel_based_point_finder.py
+++ b/TPTBox/core/poi_fun/pixel_based_point_finder.py
@@ -15,16 +15,22 @@
 
 
 #### Pixel Level functions ####
-def get_nearest_neighbor(p, sr_msk, region_label):
-    """
-    get the coordinates of point x from sr_mask's provided region_label which is closest to point p
-
-    inputs:
-        p: the chose point of interest (as array)
-        sr_msk: an array containing the subregion mask
-        region_label: the label if the region of interest in sr_msk
-    output:
-        out_point: the point from sr_msk[region_label] closest to point p (as array)
+def get_nearest_neighbor(
+    p: np.ndarray,
+    sr_msk: np.ndarray,
+    region_label: int,
+) -> np.ndarray:
+    """Return the voxel in a label mask that is closest to a query point.
+
+    Args:
+        p: Query point as a 1-D or column array of shape ``(3,)`` or ``(3, 1)``.
+        sr_msk: 3-D integer array containing segmentation labels.
+        region_label: Label value whose voxels are searched for the nearest
+            neighbour.
+
+    Returns:
+        1-D integer array ``(x, y, z)`` of the voxel in ``sr_msk`` with label
+        ``region_label`` that minimises the Euclidean distance to ``p``.
     """
     if len(p.shape) == 1:
         p = np.expand_dims(p, 1)
@@ -44,7 +50,7 @@ def max_distance_ray_cast_pixel_level(
     start_point: Location | np.ndarray = Location.Vertebra_Corpus,
     two_sided=False,
     log: Logger_Interface = _log,
-):
+) -> tuple[int, ...] | None:
     """Calculate the maximum distance ray cast in a region.
 
     Args:
@@ -87,27 +93,36 @@ def ray_cast_pixel_level_from_poi(
     normal_vector_points: tuple[Location, Location] | DIRECTIONS = "R",
     start_point: Location | np.ndarray = Location.Vertebra_Corpus,
     log: Logger_Interface = _log,
-    two_sided=False,
+    two_sided: bool = False,
 ) -> tuple[np.ndarray | None, np.ndarray | None]:
-    from TPTBox.core.poi_fun.ray_casting import ray_cast_pixel_lvl
+    """Perform pixel-level ray casting in a region using POI-derived direction.
 
-    """Perform ray casting in a region.
+    Resolves the ray start coordinate and direction vector from the ``POI``
+    object, then delegates to :func:`~TPTBox.core.poi_fun.ray_casting.ray_cast_pixel_lvl`
+    to enumerate all voxels along the ray at integer resolution.
 
     Args:
-        poi (POI): Point of interest.
-        region (NII): Region to cast rays in.
-        vert_id (int): Vertex ID.
-        bb (Tuple[slice, slice, slice]): Bounding box coordinates.
-        normal_vector_points (Union[Tuple[Location, Location], DIRECTIONS], optional):
-            Points defining the normal vector or the direction. Defaults to "R".
-        start_point (Union[Location, np.ndarray], optional): Starting point of the ray.
-            Defaults to Location.Vertebra_Corpus.
-        log (Logger_Interface, optional): Logger interface. Defaults to _log.
-        two_sided (bool, optional): Whether to perform two-sided ray casting. Defaults to False.
+        poi: ``POI`` object providing landmark coordinates and orientation.
+        region: ``NII`` image defining the volume shape for boundary clipping.
+        vert_id: Vertebra identifier (integer label).
+        bb: Bounding-box slices mapping global POI coordinates to local
+            sub-volume indices.
+        normal_vector_points: Ray direction — a ``DIRECTIONS`` string resolved
+            from the vertebra orientation, or a 2-tuple of ``Location`` members
+            whose difference defines the direction.  Defaults to ``"R"``.
+        start_point: Ray origin — a ``Location`` member resolved from ``poi``
+            or a pre-computed numpy coordinate.  Defaults to
+            ``Location.Vertebra_Corpus``.
+        log: Logger for warning and error messages.
+        two_sided: Cast the ray in both directions.  Defaults to ``False``.
 
     Returns:
-        Tuple[Optional[np.ndarray], Optional[np.ndarray]]: Plane coordinates and arange values.
+        ``(plane_coords, arange)`` where ``plane_coords`` is an integer array of
+        shape ``(N, 3)`` with visited voxel indices and ``arange`` is a float
+        array of distance values, or ``(None, None)`` on failure.
     """
+    from TPTBox.core.poi_fun.ray_casting import ray_cast_pixel_lvl
+
     start_point_np = to_local_np(start_point, bb, poi, vert_id, log) if isinstance(start_point, Location) else start_point
     if start_point_np is None:
         return None, None
@@ -134,22 +149,38 @@ def ray_cast_pixel_level_from_poi(
 def get_extreme_point_by_vert_direction(
     poi: POI,
     region: NII,
-    vert_id,
+    vert_id: int,
     direction: Sequence[DIRECTIONS] | DIRECTIONS | tuple[DIRECTIONS, float] | Sequence[tuple[DIRECTIONS, float]] = "I",
-):
-    """
-    Get the extreme point in a specified direction.
+) -> np.ndarray | None:
+    """Find the voxel in a binary region that is most extreme along a vertebra-relative direction.
+
+    Projects all nonzero voxels in ``region`` into the vertebra PIR frame and
+    returns the voxel index with the maximum weighted score along the requested
+    direction(s).
 
     Args:
-        poi (POI): The chosen point of interest represented as an array.
-        region (NII): An array containing the subregion mask.
-        vert_id: The ID of the vertex.
-        direction (Union[Sequence[DIRECTIONS], DIRECTIONS], optional): The direction(s) to search for the extreme point.
-            Defaults to "I" (positive direction along the secondary axis).
+        poi: ``POI`` object providing the vertebra orientation matrix for
+            ``vert_id``.
+        region: Binary ``NII`` image (value 1 for foreground) aligned to the
+            same space as ``poi``.
+        vert_id: Vertebra identifier used to look up the orientation matrix.
+        direction: Anatomical direction(s) to optimise.  May be:
+
+            * A single direction letter (e.g. ``"I"``).
+            * A sequence of direction letters (e.g. ``["P", "I"]``).
+            * A ``(direction, weight)`` tuple or a sequence of such tuples for
+              weighted combinations.
+
+            Defaults to ``"I"``.
+
+    Returns:
+        Integer voxel index array ``(x, y, z)`` of the most extreme point, or
+        ``None`` if the orientation matrix cannot be retrieved.
 
     Note:
-        Assumes `region` contains binary values indicating the presence of points.
-        Uses `_get_sub_array_by_direction` internally.
+        ``region`` must contain binary values (1 for foreground, 0 for
+        background).  Zoom scaling from ``poi`` is applied to ensure
+        physically meaningful distances.
     """
     direction_: Sequence[DIRECTIONS] | Sequence[tuple[DIRECTIONS, float]] = direction if isinstance(direction, Sequence) else (direction,)  # type: ignore
 
@@ -222,5 +253,18 @@ def project_pois_onto_set_of_points(poi: POI, point_set: list[COORDINATE]) -> PO
     return poi_n
 
 
-def cdist_to_point(point, a):
+def cdist_to_point(
+    point: COORDINATE | np.ndarray,
+    a: np.ndarray,
+) -> np.ndarray:
+    """Compute Euclidean distances from a single point to every row in an array.
+
+    Args:
+        point: Query point as a sequence or 1-D array of length 3.
+        a: Array of shape ``(N, 3)`` containing the candidate points.
+
+    Returns:
+        1-D float array of shape ``(N,)`` with the Euclidean distance from
+        ``point`` to each row of ``a``.
+    """
     return cdist([point], a)[0]
diff --git a/TPTBox/core/poi_fun/poi_abstract.py b/TPTBox/core/poi_fun/poi_abstract.py
index 0c277bf..d8c558b 100755
--- a/TPTBox/core/poi_fun/poi_abstract.py
+++ b/TPTBox/core/poi_fun/poi_abstract.py
@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import json
-from collections.abc import Callable, MutableMapping, Sequence
+from collections.abc import Callable, ItemsView, Iterator, MutableMapping, Sequence
 from collections.abc import Set as AbstractSet
 from dataclasses import dataclass, field
 from enum import Enum
@@ -38,7 +38,11 @@
 DIMENSIONS = 3
 
 
-def _flatten(vert_label):
+def _flatten(vert_label) -> list:
+    """Flatten a (possibly nested) sequence of labels into a flat list of ints.
+
+    Enum members are replaced by their ``.value``.
+    """
     return [
         item.value if isinstance(item, Enum) else item
         for sublist in vert_label
@@ -47,13 +51,20 @@ def _flatten(vert_label):
 
 
 class _Abstract_POI_Definition:
+    """Bidirectional name-to-integer mapping for region and subregion labels.
+
+    Supports loading the mapping from a JSON file or from pre-built dicts.
+    Used internally by :class:`POI_Descriptor` to convert human-readable label
+    names to integer IDs and back.
+    """
+
     def __init__(
         self,
         path: str | Path | None = None,
         region: dict[int, str] | None = None,
         subregion: dict[int, str] | None = None,
     ) -> None:
-        """Place holder class to move string names to integer with multiple definitions"""
+        """Placeholder class to move string names to integers with multiple definitions."""
         if path is not None:
             with open(path) as f:
                 info = json.load(f)
@@ -69,6 +80,19 @@ def __init__(
 
 
 def unpack_poi_id(key: POI_ID, definition: _Abstract_POI_Definition) -> tuple[int, int]:
+    """Convert any supported POI key type to a ``(region, subregion)`` integer pair.
+
+    Accepted key forms: plain integer (packed label), ``slice(region, subregion)``,
+    2-tuple of ints, 2-tuple of ``Abstract_lvl`` / ``Enum`` members, or mixed tuples.
+    String values are resolved via ``definition``'s name-to-index mappings.
+
+    Args:
+        key: POI identifier in any of the supported formats.
+        definition: Name-to-integer mapping used to resolve string labels.
+
+    Returns:
+        ``(region, subregion)`` tuple of plain Python integers.
+    """
     if isinstance(key, (int, np.integer)):
         region = int(key % vert_constants.LABEL_MAX)
         subregion = int(key // vert_constants.LABEL_MAX)
@@ -95,7 +119,19 @@ def unpack_poi_id(key: POI_ID, definition: _Abstract_POI_Definition) -> tuple[in
 
 
 class POI_Descriptor(AbstractSet, MutableMapping):
-    """A Object that holds the coordinate data and the two step dictionary. The implementation storage of the dictionary is the sole responsibility of this class."""
+    """Two-level dictionary that maps ``(region, subregion)`` pairs to 3-D coordinates.
+
+    Acts simultaneously as a ``MutableMapping`` and an ``AbstractSet`` so that
+    POI keys can be tested for membership with ``in``.  The underlying storage
+    is a nested plain-Python dict ``{region: {subregion: (x, y, z)}}``.
+    All coordinate values are stored as ``tuple[float, float, float]``.
+
+    Args:
+        default: Initial nested coordinate dict.  Defaults to an empty dict.
+        definition: Name-to-integer mapping for string label resolution.
+            Defaults to the spine vertebra / subregion mapping from
+            ``vert_constants``.
+    """
 
     def __init__(
         self,
@@ -116,26 +152,30 @@ def __init__(
 
     __hash__ = None  # explicitly mark as unhashable
 
-    def __set_name__(self, owner, name):
+    def __set_name__(self, owner, name: str) -> None:
+        """Store the descriptor's attribute name so ``__get__`` / ``__set__`` can use it."""
         self._name = "_" + name
 
-    def __get__(self, obj, _):
+    def __get__(self, obj, _) -> POI_Descriptor | dict:
+        """Return the descriptor value from the owner instance, or the raw dict when accessed on the class."""
         if obj is None:
             return self.pois
 
         return getattr(obj, self._name, self.pois)
 
-    def __set__(self, obj, value):
+    def __set__(self, obj, value) -> None:
+        """Set the descriptor value on the owner instance."""
         self._len = None
         setattr(obj, self._name, int(value))
 
-    def copy(self):
+    def copy(self) -> POI_Descriptor:
+        """Return a deep copy of this descriptor."""
         from copy import deepcopy
 
         return POI_Descriptor(default=deepcopy(self.pois))
 
     def _sort(self: Self, inplace=True, order_dict: dict | None = None):
-        """Sort vertebra dictionary by sorting_list"""
+        """Sort vertebra dictionary by sorting_list."""
         if order_dict is None:
             order_dict = {}
 
@@ -153,7 +193,8 @@ def order_cardinal(elem: tuple[int, ...]):
             return self
         return POI_Descriptor(default=poi_new)
 
-    def items(self):
+    def items(self) -> Iterator[tuple[int, int, COORDINATE]]:
+        """Yield ``(region, subregion, coordinate)`` triples for all stored points."""
         i = 0
         for region, sub in self.pois.items():
             for subregion, coords in sub.items():
@@ -161,26 +202,32 @@ def items(self):
                 yield region, subregion, coords
         self._len = i
 
-    def items_2d(self):
+    def items_2d(self) -> ItemsView[int, dict[int, COORDINATE]]:
+        """Return a view of the top-level ``{region: {subregion: coord}}`` dict."""
         return self.pois.copy().items()
 
-    def _apply_all(self, fun: Callable[[float, float, float], COORDINATE], inplace=False):
+    def _apply_all(self, fun: Callable[[float, float, float], COORDINATE], inplace: bool = False) -> POI_Descriptor:
+        """Apply a coordinate transform ``fun`` to every stored point."""
         out = self if inplace else POI_Descriptor()
         for region, subregion, cord in self.items():
             out[region:subregion] = fun(*cord)
 
         return out
 
-    def values(self):
+    def values(self) -> list[COORDINATE]:
+        """Return a list of all stored ``(x, y, z)`` coordinate tuples."""
         return [y for x1, x2, y in self.items()]
 
-    def keys(self):
+    def keys(self) -> list[tuple[int, int]]:
+        """Return a list of all ``(region, subregion)`` key pairs."""
         return [(x1, x2) for x1, x2, y in self.items()]
 
-    def keys_region(self):
+    def keys_region(self) -> list[int]:
+        """Return a list of all unique region (vertebra) IDs."""
         return list(self.pois.keys())
 
-    def keys_subregion(self):
+    def keys_subregion(self) -> set[int]:
+        """Return the set of all unique subregion IDs across all regions."""
         return {x2 for x1, x2, y in self.items()}
 
     def __getitem__(self, key: POI_ID) -> COORDINATE:
@@ -190,7 +237,8 @@ def __getitem__(self, key: POI_ID) -> COORDINATE:
         except KeyError:
             raise KeyError(region, subregion, "not in", list(self.keys()))  # noqa: B904
 
-    def get(self, key: POI_ID):
+    def get(self, key: POI_ID) -> np.ndarray:
+        """Return the coordinate for ``key`` as a numpy array."""
         return np.array(self[key])
 
     def __setitem__(self, key: POI_ID, value: COORDINATE):
@@ -220,7 +268,21 @@ def __contains__(self, key: POI_ID) -> bool:
             return subregion in self.pois[region]
         return False
 
-    def str_to_int(self, key: str, subregion: bool):
+    def str_to_int(self, key: str, subregion: bool) -> int:
+        """Convert a label name string to its integer ID.
+
+        Args:
+            key: Name string to look up.
+            subregion: If ``True``, search in the subregion mapping; otherwise
+                search in the region mapping.
+
+        Returns:
+            Integer label ID.
+
+        Raises:
+            KeyError: If ``key`` is not found in the mapping and cannot be cast
+                to ``int``.
+        """
         try:
             return self.definition.subregion_name2idx[key] if subregion else self.definition.region_name2idx[key]
         except Exception:
@@ -236,7 +298,18 @@ def str_to_int(self, key: str, subregion: bool):
             )
             raise
 
-    def str_to_int_list(self, *keys: int | str, subregion=False):
+    def str_to_int_list(self, *keys: int | str, subregion: bool = False) -> list[int]:
+        """Convert a sequence of label names or IDs to a flat list of integer IDs.
+
+        Args:
+            *keys: Label names (str) or integer IDs.  Nested lists are
+                flattened automatically.
+            subregion: If ``True``, resolve strings as subregion names;
+                otherwise as region names.  Defaults to ``False``.
+
+        Returns:
+            Flat list of integer label IDs.
+        """
         keys = _flatten(keys)
         out: list[int] = []
         for k in keys:
@@ -245,7 +318,18 @@ def str_to_int_list(self, *keys: int | str, subregion=False):
             out.append(k)
         return out
 
-    def str_to_int_dict(self, d: MAPPING, subregion=False):
+    def str_to_int_dict(self, d: MAPPING, subregion: bool = False) -> dict[int, int | None]:
+        """Convert a label-map dict's string keys/values to integer IDs.
+
+        Args:
+            d: Mapping from label names or IDs to target names, IDs, or
+                ``None``.  If ``None`` an empty dict is returned.
+            subregion: If ``True``, resolve strings as subregion names;
+                otherwise as region names.  Defaults to ``False``.
+
+        Returns:
+            Dict with all keys and non-``None`` values converted to integers.
+        """
         out: dict[int, int | None] = {}
         if d is None:
             return out
@@ -276,10 +360,28 @@ def __len__(self) -> int:
         return self._len
 
     def __iter__(self):
+        """Iterate over all ``(region, subregion)`` key pairs."""
         return iter(self.keys())
 
     @classmethod
-    def normalize_input_data(cls, dic: dict):
+    def normalize_input_data(cls, dic: dict) -> POI_Descriptor:
+        """Convert a raw dict of various formats into a ``POI_Descriptor``.
+
+        Accepted dict formats:
+
+        * ``{(region, subregion): (x, y, z)}``
+        * ``{int_label: (x, y, z)}`` (treated as ``region=0``)
+        * ``{region: {subregion: (x, y, z)}}``
+
+        Args:
+            dic: Input dict.
+
+        Returns:
+            Populated ``POI_Descriptor`` instance.
+
+        Raises:
+            ValueError: If a key/value pair cannot be interpreted.
+        """
         _centroids = cls()
         for k, v in dic.items():
             if isinstance(k, (tuple, list)) and isinstance(v, (tuple, list, np.ndarray)) and len(v) == DIMENSIONS:
@@ -293,7 +395,18 @@ def normalize_input_data(cls, dic: dict):
                 raise ValueError(k, type(k), v, tuple(v))
         return _centroids
 
-    def pop(self, key: POI_ID, default):
+    def pop(self, key: POI_ID, default: COORDINATE | None) -> COORDINATE | None:
+        """Remove and return the coordinate for ``key``, or ``default`` if absent.
+
+        Also removes the region entry if it becomes empty after the deletion.
+
+        Args:
+            key: ``(region, subregion)`` pair or any supported ``POI_ID`` form.
+            default: Value to return when ``key`` is not present.
+
+        Returns:
+            The removed coordinate tuple, or ``default``.
+        """
         region, subregion = unpack_poi_id(key, self.definition)
         if region not in self.pois:
             return default
@@ -306,6 +419,22 @@ def pop(self, key: POI_ID, default):
 
 @dataclass
 class Abstract_POI:
+    """Abstract base for POI containers.
+
+    Stores a two-level ``(region, subregion)`` → coordinate mapping and
+    provides geometry operations (coordinate transforms, spline fitting,
+    set operations) that are shared by both the local ``POI`` and the global
+    ``POI_Global`` classes.
+
+    Attributes:
+        _centroids: Internal ``POI_Descriptor`` storage.
+        centroids: Public descriptor property backed by ``_centroids``.
+        format: Integer format tag identifying how the data was saved / loaded.
+        level_one_info: Enum class mapping region integer IDs to names.
+        level_two_info: Enum class mapping subregion integer IDs to names.
+        info: Arbitrary metadata dict persisted alongside the coordinates.
+    """
+
     _centroids: POI_Descriptor = field(default_factory=lambda: POI_Descriptor(), repr=False)
     centroids: POI_Descriptor = field(repr=False, hash=False, compare=False, default=None)  # type: ignore
     format: int | None = field(default=None, repr=False, compare=False)
@@ -319,10 +448,12 @@ def __post_init__(self):
 
     @property
     def centroids(self) -> POI_Descriptor:
+        """Return the underlying POI_Descriptor storing all centroid coordinates."""
         return self._centroids  # type: ignore
 
     @centroids.setter
     def centroids(self, value):
+        """Set the underlying POI_Descriptor, accepting a dict or POI_Descriptor."""
         if isinstance(value, property):
             return
         if isinstance(value, POI_Descriptor):
@@ -333,21 +464,36 @@ def centroids(self, value):
             raise TypeError(value, type(value), "Expected: POI_Descriptor")
 
     def _get_centroids(self) -> POI_Descriptor:
+        """Return the raw ``POI_Descriptor`` (subclasses may override for lazy loading)."""
         return self.centroids  # type: ignore
 
-    def apply_all(self, fun: Callable[[float, float, float], COORDINATE], inplace=False):
+    def apply_all(self, fun: Callable[[float, float, float], COORDINATE], inplace: bool = False) -> Self:
+        """Apply a coordinate transform to every stored point.
+
+        Args:
+            fun: Callable that accepts ``(x, y, z)`` and returns a new
+                3-element coordinate.
+            inplace: Modify this object in place.  Defaults to ``False``.
+
+        Returns:
+            The transformed POI (``self`` when ``inplace=True``, a new object
+            otherwise).
+        """
         ctd = self._get_centroids()._apply_all(fun, inplace)
         if inplace:
             return self
         return self.copy(ctd)
 
     @property
-    def is_global(self) -> bool: ...
+    def is_global(self) -> bool:
+        """Return True if coordinates are in world/global space, False if in voxel space."""
 
-    def clone(self, **qargs):
+    def clone(self, **qargs) -> Self:
+        """Alias for :meth:`copy`; returns a copy of this POI."""
         return self.copy(**qargs)
 
-    def copy(self, centroids: POI_Descriptor | None = None, **qargs) -> Self: ...
+    def copy(self, centroids: POI_Descriptor | None = None, **qargs) -> Self:
+        """Return a shallow copy of this POI, optionally replacing the centroids."""
 
     def map_labels(
         self,
@@ -357,8 +503,7 @@ def map_labels(
         verbose: logging = False,
         inplace=False,
     ) -> Self:
-        """
-        Maps regions and subregions to new regions and subregions based on a label map dictionary.
+        """Maps regions and subregions to new regions and subregions based on a label map dictionary.
 
         Args:
             label_map_full (dict[tuple[int, int], tuple[int, int]] | None, optional): A dictionary that maps individual points (regions and subregions) to new values. Defaults to None.
@@ -426,7 +571,8 @@ def map_labels_(
         label_map_region: MAPPING = None,
         label_map_subregion: MAPPING = None,
         verbose: logging = False,
-    ):
+    ) -> Self:
+        """In-place alias for :meth:`map_labels`; modifies this object and returns it."""
         if label_map_subregion is None:
             label_map_subregion = {}
         if label_map_region is None:
@@ -439,8 +585,21 @@ def map_labels_(
             inplace=True,
         )
 
-    def sort(self, inplace=True, order_dict: dict | None = None) -> Self:
-        """Sort vertebra dictionary by sorting_list"""
+    def sort(self, inplace: bool = True, order_dict: dict | None = None) -> Self:
+        """Sort the internal centroid dictionary by vertebra ordering.
+
+        Uses ``level_one_info.order_dict()`` when available, falling back to
+        the provided ``order_dict`` or insertion order.
+
+        Args:
+            inplace: Sort in place.  Defaults to ``True``.
+            order_dict: Custom ordering mapping ``{region_id: sort_key}``.
+                When ``None`` and ``level_one_info`` is set, the info class's
+                own ordering is used.
+
+        Returns:
+            The sorted POI (``self`` when ``inplace=True``, a copy otherwise).
+        """
         if self.level_one_info is not None and self.level_one_info != Any:
             order_dict = self.level_one_info.order_dict()
         poi = self.centroids._sort(inplace=inplace, order_dict=order_dict)
@@ -456,8 +615,7 @@ def fit_spline(
         location: int | Abstract_lvl = Location.Vertebra_Corpus,
         vertebra=False,
     ) -> tuple[np.ndarray, np.ndarray]:
-        """
-        Fits a spline interpolation through a set of centroids and calculates the first derivative of the spline curve.
+        """Fits a spline interpolation through a set of centroids and calculates the first derivative of the spline curve.
 
         Args:
             centroids (POI): A set of centroids to interpolate.
@@ -515,6 +673,7 @@ def fit_spline(
         )
 
     def __iter__(self):
+        """Iterate over all ``(region, subregion)`` key pairs."""
         return iter(self.centroids.keys())
 
     def __contains__(self, key: POI_ID) -> bool:
@@ -524,7 +683,7 @@ def __contains__(self, key: POI_ID) -> bool:
     def __getitem__(self, key: POI_ID) -> COORDINATE:
         return tuple(self.centroids[key])
 
-    def __setitem__(self, key: POI_ID, value: tuple[float, float, float] | Sequence[float] | np.ndarray):
+    def __setitem__(self, key: POI_ID, value: tuple[float, float, float] | Sequence[float] | np.ndarray) -> None:
         if len(value) != DIMENSIONS:
             raise ValueError(value)
         self.centroids[key] = tuple(value)
@@ -532,46 +691,85 @@ def __setitem__(self, key: POI_ID, value: tuple[float, float, float] | Sequence[
     def __len__(self) -> int:
         return self.centroids.__len__()
 
-    def items(self, sort=True):
+    def items(self, sort: bool = True) -> Iterator[tuple[int, int, COORDINATE]]:
+        """Yield ``(region, subregion, coordinate)`` triples, optionally sorted.
+
+        Args:
+            sort: Sort by vertebra ordering before yielding.  Defaults to
+                ``True``.
+        """
         if sort:
             self.sort()
         return self.centroids.items()
 
-    def items_2D(self, sort=True):
+    def items_2D(self, sort: bool = True) -> ItemsView[int, dict[int, COORDINATE]]:
+        """Return the top-level ``{region: {subregion: coord}}`` dict view, optionally sorted.
+
+        Args:
+            sort: Sort by vertebra ordering first.  Defaults to ``True``.
+        """
         if sort:
             self.sort()
         return self.centroids.items_2d()
 
-    def items_flatten(self, sort=True):
+    def items_flatten(self, sort: bool = True) -> Iterator[tuple[int, COORDINATE]]:
+        """Yield ``(packed_label, coordinate)`` pairs using the legacy packed-int encoding.
+
+        Args:
+            sort: Sort by vertebra ordering before yielding.  Defaults to
+                ``True``.
+        """
         if sort:
             self.sort()
         for x1, x2, y in self.centroids.items():
             yield x2 * vert_constants.LABEL_MAX + x1, y
 
-    def keys(self, sort=False):
+    def keys(self, sort: bool = False) -> list[tuple[int, int]]:
+        """Return all ``(region, subregion)`` key pairs.
+
+        Args:
+            sort: Sort by vertebra ordering first.  Defaults to ``False``.
+        """
         if sort:
             self.sort()
         return self.centroids.keys()
 
-    def keys_region(self, sort=False):
+    def keys_region(self, sort: bool = False) -> list[int]:
+        """Return all unique region (vertebra) IDs.
+
+        Args:
+            sort: Sort by vertebra ordering first.  Defaults to ``False``.
+        """
         if sort:
             self.sort()
         return self.centroids.keys_region()
 
-    def keys_subregion(self, sort=False):
+    def keys_subregion(self, sort: bool = False) -> list[int]:
+        """Return all unique subregion IDs as a sorted list.
+
+        Args:
+            sort: Sort by vertebra ordering first.  Defaults to ``False``.
+        """
         if sort:
             self.sort()
         return list(self.centroids.keys_subregion())
 
-    def values(self, sort=False) -> list[COORDINATE]:
+    def values(self, sort: bool = False) -> list[COORDINATE]:
+        """Return all stored ``(x, y, z)`` coordinate tuples.
+
+        Args:
+            sort: Sort by vertebra ordering first.  Defaults to ``False``.
+        """
         if sort:
             self.sort()
         return self.centroids.values()
 
-    def remove_centroid_(self, *label: tuple[int, int]):
+    def remove_centroid_(self, *label: tuple[int, int]) -> Self:
+        """Deprecated in-place removal — use :meth:`remove_` instead."""
         return self.remove_centroid(*label, inplace=True)
 
-    def remove_centroid(self, *label: tuple[int, int], inplace=False):
+    def remove_centroid(self, *label: tuple[int, int], inplace: bool = False) -> Self:
+        """Deprecated — use :meth:`remove` instead."""
         import warnings
 
         warnings.warn("remove_centroid id deprecated use remove instead", stacklevel=5)  # TODO remove in version 1.0
@@ -583,10 +781,21 @@ def remove_centroid(self, *label: tuple[int, int], inplace=False):
             obj.centroids.pop(loc, None)
         return obj
 
-    def remove_(self, *label: tuple[int, int]):
+    def remove_(self, *label: tuple[int, int]) -> Self:
+        """In-place alias for :meth:`remove`."""
         return self.remove(*label, inplace=True)
 
-    def remove(self, *label: tuple[int, int], inplace=False):
+    def remove(self, *label: tuple[int, int], inplace: bool = False) -> Self:
+        """Remove one or more ``(region, subregion)`` entries from this POI.
+
+        Args:
+            *label: One or more ``(region, subregion)`` tuples or
+                ``Abstract_lvl`` members to remove.
+            inplace: Modify this object in place.  Defaults to ``False``.
+
+        Returns:
+            The modified POI (``self`` when ``inplace=True``, a copy otherwise).
+        """
         obj: Self = self.copy() if inplace is False else self
         for loc in label:
             if isinstance(loc, Abstract_lvl):
@@ -594,7 +803,16 @@ def remove(self, *label: tuple[int, int], inplace=False):
             obj.centroids.pop(loc, None)
         return obj
 
-    def extract_subregion(self, *location: Abstract_lvl | int, inplace=False):
+    def extract_subregion(self, *location: Abstract_lvl | int, inplace: bool = False) -> Self:
+        """Return a POI containing only the specified subregion(s).
+
+        Args:
+            *location: One or more subregion IDs or ``Abstract_lvl`` members.
+            inplace: Filter in place.  Defaults to ``False``.
+
+        Returns:
+            Filtered POI.
+        """
         location = _flatten(location)
 
         location_values = tuple(l if isinstance(l, int) else l.value for l in location)
@@ -607,19 +825,32 @@ def extract_subregion(self, *location: Abstract_lvl | int, inplace=False):
             return self
         return self.copy(centroids=extracted_centroids)
 
-    def extract_subregion_(self, *location: Abstract_lvl | int):
+    def extract_subregion_(self, *location: Abstract_lvl | int) -> Self:
+        """In-place alias for :meth:`extract_subregion`."""
         return self.extract_subregion(*location, inplace=True)
 
-    def extract_vert(self, *vert_label: int, inplace=False):
+    def extract_vert(self, *vert_label: int, inplace: bool = False) -> Self:
+        """Deprecated — use :meth:`extract_region` instead."""
         import warnings
 
         warnings.warn("extract_vert id deprecated use extract_region instead", stacklevel=5)  # TODO remove in version 2.0
         return self.extract_region(*vert_label, inplace=inplace)
 
-    def extract_vert_(self, *vert_label: int):
+    def extract_vert_(self, *vert_label: int) -> Self:
+        """Deprecated in-place alias — use :meth:`extract_region_` instead."""
         return self.extract_vert(*vert_label, inplace=True)
 
-    def extract_region(self, *vert_label: int | list[int] | Enum, inplace=False):
+    def extract_region(self, *vert_label: int | list[int] | Enum, inplace: bool = False) -> Self:
+        """Return a POI containing only the specified region(s) (vertebrae).
+
+        Args:
+            *vert_label: One or more region IDs, lists of IDs, or ``Enum``
+                members to retain.
+            inplace: Filter in place.  Defaults to ``False``.
+
+        Returns:
+            Filtered POI.
+        """
         # flatten list
         vert_label = _flatten(vert_label)
         vert_labels = tuple(vert_label)
@@ -632,10 +863,11 @@ def extract_region(self, *vert_label: int | list[int] | Enum, inplace=False):
             return self
         return self.copy(centroids=extracted_centroids)
 
-    def extract_region_(self, *vert_label: int):
+    def extract_region_(self, *vert_label: int) -> Self:
+        """In-place alias for :meth:`extract_region`."""
         return self.extract_region(*vert_label, inplace=True)
 
-    def round(self, ndigits, inplace=False):
+    def round(self, ndigits, inplace=False) -> Self:
         """Round the centroid coordinates to a specified number of digits.
 
         This method rounds the x, y, and z coordinates of all centroids to the given number of digits.
@@ -666,7 +898,8 @@ def round(self, ndigits, inplace=False):
             return self
         return self.copy(out)
 
-    def round_(self, ndigits):
+    def round_(self, ndigits: int) -> Self:
+        """In-place alias for :meth:`round`."""
         return self.round(ndigits=ndigits, inplace=True)
 
     # def assert_affine(self, nii: NII | Self):
@@ -701,7 +934,6 @@ def calculate_distances_poi(self, target_point: Self, keep_zoom=False) -> dict[t
             The keys are tuples of two integers representing the region and subregion labels of the centroids,
             and the values are the distances (in millimeters) between the target point and each centroid.
         """
-
         assert self.is_global == target_point.is_global
         if not keep_zoom and not self.is_global:
             self = self.to_global()  # type: ignore  # noqa: PLW0642
@@ -718,9 +950,23 @@ def calculate_distances_poi(self, target_point: Self, keep_zoom=False) -> dict[t
             distances[(region, subregion)] = float(distance)
         return distances
 
-    def calculate_distances_poi_any_2_any(self, target_point: Self, keep_zoom=False) -> dict[tuple[int, int], dict[tuple[int, int], float]]:
-        """Calculate the distances between all points and each centroid in local spacing of the first POI."""
+    def calculate_distances_poi_any_2_any(
+        self, target_point: Self, keep_zoom: bool = False
+    ) -> dict[tuple[int, int], dict[tuple[int, int], float]]:
+        """Calculate pairwise Euclidean distances between every point in ``self`` and every point in ``target_point``.
+
+        Both POIs are first converted to global (mm) space unless
+        ``keep_zoom=True``.
+
+        Args:
+            target_point: Reference POI to measure distances to.
+            keep_zoom: When ``True``, skip the global conversion and require both
+                POIs to share the same affine.  Defaults to ``False``.
 
+        Returns:
+            Nested dict ``{(r2, s2): {(r, s): distance_mm}}`` covering every
+            combination.
+        """
         if not keep_zoom:
             self = self.to_global()  # type: ignore  # noqa: PLW0642
             target_point = target_point.to_global()
@@ -773,9 +1019,7 @@ def calculate_distances_poi_across_regions(
         return distances2target
 
     def join_left(self, pois: Self, inplace=False, _right_join=False) -> Self:
-        """
-        Left join operation to combine the centroids from another set of points into the current set.
-        Existing values are NOT overwritten
+        """Left-join another POI set into this one without overwriting existing values.
 
         Args:
             pois (Self): Another set of points (centroids) to be combined.
@@ -796,25 +1040,28 @@ def join_left(self, pois: Self, inplace=False, _right_join=False) -> Self:
             return self
         return self.copy(ctd_list)
 
-    def join_left_(self, pois: Self):
+    def join_left_(self, pois: Self) -> Self:
+        """In-place alias for :meth:`join_left`."""
         return self.join_left(pois, inplace=True)
 
-    def __lshift__(self, other):
+    def __lshift__(self, other) -> Self:
+        """Operator ``<<``: left join (existing values not overwritten)."""
         return self.join_left(other)
 
-    def __add__(self, other):
+    def __add__(self, other) -> Self:
+        """Operator ``+``: left join (existing values not overwritten)."""
         return self.join_left(other)
 
-    def __rshift__(self, other):
+    def __rshift__(self, other) -> Self:
+        """Operator ``>>``: right join (existing values are overwritten)."""
         return self.join_right(other)
 
-    def join_right_(self, pois: Self):
+    def join_right_(self, pois: Self) -> Self:
+        """In-place alias for :meth:`join_right`."""
         return self.join_left(pois, inplace=True, _right_join=True)
 
-    def join_right(self, *args, **qargs):
-        """
-        Rights join operation to combine the centroids from another set of points into the current set.
-        Existing values are overwritten.
+    def join_right(self, *args, **qargs) -> Self:
+        """Right-join another POI set into this one, overwriting existing values.
 
         Args:
             pois (Self): Another set of points (centroids) to be combined.
@@ -826,9 +1073,8 @@ def join_right(self, *args, **qargs):
         """
         return self.join_left(*args, **qargs, _right_join=True)
 
-    def intersect(self, pois: Self, inplace=False):
-        """
-        Intersect operation to find common centroids between two sets of points and update the current set.
+    def intersect(self, pois: Self, inplace=False) -> Self:
+        """Intersect operation to find common centroids between two sets of points and update the current set.
 
         Args:
             pois (Self): Another set of points (centroids) to find the intersection with.
@@ -846,21 +1092,23 @@ def intersect(self, pois: Self, inplace=False):
             return self
         return self.copy(filtered_centroids)
 
-    def intersect_(self, pois: Self):
+    def intersect_(self, pois: Self) -> Self:
+        """In-place alias for :meth:`intersect`."""
         return self.intersect(pois, inplace=True)
 
-    def __and__(self, poi):
+    def __and__(self, poi) -> Self:
+        """Operator ``&``: intersect (keep only points present in both POIs)."""
         return self.intersect(poi)
 
-    def subtract(self, pois: Self, inplace=False):
-        """
-        Intersect operation to find common centroids between two sets of points and update the current set.
+    def subtract(self, pois: Self, inplace: bool = False) -> Self:
+        """Return a POI with all points that are NOT present in ``pois`` removed.
 
         Args:
-            pois (Self): Another set of points (centroids) to find the intersection with.
-            inplace (bool, optional): If True, the operation is performed in-place on the current set.
-                                    If False, a new set is created. Default is False.
+            pois: POI whose keys act as a rejection set.
+            inplace: Modify this object in place.  Defaults to ``False``.
 
+        Returns:
+            POI containing only keys absent from ``pois``.
         """
         filtered_centroids = POI_Descriptor()
 
@@ -872,5 +1120,6 @@ def subtract(self, pois: Self, inplace=False):
             return self
         return self.copy(filtered_centroids)
 
-    def __sub__(self, poi):
+    def __sub__(self, poi) -> Self:
+        """Operator ``-``: subtract (keep only points NOT in ``poi``)."""
         return self.subtract(poi)
diff --git a/TPTBox/core/poi_fun/poi_global.py b/TPTBox/core/poi_fun/poi_global.py
index 2613e9b..4c1ba8d 100755
--- a/TPTBox/core/poi_fun/poi_global.py
+++ b/TPTBox/core/poi_fun/poi_global.py
@@ -16,9 +16,10 @@
 
 
 class POI_Global(Abstract_POI):
-    """
-    Represents a global Point of Interest (POI) in a coordinate system.
-    Inherits from the `Abstract_POI` class and contains methods for converting the POI to different coordinate systems.
+    """POI container stored in world (mm) coordinates rather than voxel space.
+
+    Extends :class:`~TPTBox.core.poi_fun.poi_abstract.Abstract_POI` with coordinate-system
+    conversion methods.
     """
 
     def __init__(
@@ -64,23 +65,30 @@ def __str__(self) -> str:
         return str(self._centroids)
 
     @property
-    def zoom(self):
+    def zoom(self) -> tuple[int, int, int]:
+        """Always returns ``(1, 1, 1)`` — global POIs are in mm so zoom is unity."""
         return (1, 1, 1)
 
     @property
-    def origin(self):
+    def origin(self) -> tuple[int, int, int]:
+        """Always returns ``(0, 0, 0)`` — global POIs use a world origin."""
         return (0, 0, 0)
 
     @property
-    def orientation(self):
+    def orientation(self) -> tuple[str, str, str]:
+        """Return the axis-code orientation for the active coordinate system.
+
+        Returns:
+            ``("L", "A", "S")`` for ITK/LPS coordinates, ``("R", "P", "S")``
+            for NIfTI/RAS coordinates.
+        """
         if self.itk_coords:
             return ("L", "A", "S")
         return ("R", "P", "S")
 
     @property
     def is_global(self) -> bool:
-        """
-        Check if the POI is global.
+        """Check if the POI is global.
 
         Returns:
             bool: True if the POI is global, False otherwise.
@@ -88,8 +96,7 @@ def is_global(self) -> bool:
         return True
 
     def to_other_nii(self, ref: poi.Image_Reference) -> poi.POI | poi.NII:
-        """
-        Convert the POI to another NII file.
+        """Convert the POI to another NII file.
 
         Args:
             ref (poi.Image_Reference): The reference to the NII file.
@@ -99,9 +106,8 @@ def to_other_nii(self, ref: poi.Image_Reference) -> poi.POI | poi.NII:
         """
         return self.to_other(poi.to_nii(ref))
 
-    def to_other_poi(self, ref: poi.POI | Self):
-        """
-        Convert the POI to another POI.
+    def to_other_poi(self, ref: poi.POI | Self) -> poi.POI | Self | None:
+        """Convert the POI to another POI.
 
         Args:
             ref (poi.Centroid_Reference): The reference to the other POI.
@@ -115,16 +121,45 @@ def to_other_poi(self, ref: poi.POI | Self):
         elif isinstance(ref, Self):
             return self.to_cord_system(ref.itk_coords)
 
-    def to_global(self, itk_coords: bool | None = None):
+    def to_global(self, itk_coords: bool | None = None) -> Self:
+        """Return this object unchanged (already in global coordinates)."""
         return self.to_cord_system(itk_coords) if itk_coords is not None else self.copy()
 
-    def to_local(self, msk: Has_Grid):
+    def to_local(self, msk: Has_Grid) -> poi.POI:
+        """Convert this global POI to the voxel space of ``msk``.
+
+        Args:
+            msk: Reference grid (``NII`` or ``POI``) defining the target affine.
+
+        Returns:
+            ``POI`` in the local voxel coordinate system of ``msk``.
+        """
         return self.resample_from_to(msk)
 
-    def resample_from_to(self, msk: Has_Grid):
+    def resample_from_to(self, msk: Has_Grid) -> poi.POI:
+        """Alias for :meth:`to_local` / :meth:`to_other`.
+
+        Args:
+            msk: Reference grid defining the target affine.
+
+        Returns:
+            ``POI`` in the local coordinate system of ``msk``.
+        """
         return self.to_other(msk)
 
-    def to_cord_system(self, itk_coords: bool, inplace=False):
+    def to_cord_system(self, itk_coords: bool, inplace: bool = False) -> Self:
+        """Convert between ITK (LPS) and NIfTI (RAS) coordinate systems.
+
+        Flips the first two coordinate axes when switching between the two
+        systems (LPS ↔ RAS only differs in the sign of x and y).
+
+        Args:
+            itk_coords: ``True`` for ITK/LPS output, ``False`` for NIfTI/RAS.
+            inplace: Convert in place.  Defaults to ``False``.
+
+        Returns:
+            ``POI_Global`` in the requested coordinate system.
+        """
         out = self if inplace else self.copy()
         if self.itk_coords == itk_coords:
             return out
@@ -134,8 +169,7 @@ def to_cord_system(self, itk_coords: bool, inplace=False):
         return out
 
     def to_other(self, msk: Has_Grid, verbose=False) -> poi.POI:
-        """
-        Convert the POI to another coordinate system.
+        """Convert the POI to another coordinate system.
 
         Args:
             msk (Union[poi.POI, poi.NII]): The reference to the other coordinate system.
@@ -156,6 +190,15 @@ def to_other(self, msk: Has_Grid, verbose=False) -> poi.POI:
         return poi.POI(centroids=out, **msk._extract_affine(), info=self.info, format=self.format)
 
     def copy(self, centroids: POI_Descriptor | None = None) -> Self:
+        """Return a deep copy of this ``POI_Global``.
+
+        Args:
+            centroids: Optional replacement ``POI_Descriptor``.  When ``None``
+                the current centroids are deep-copied.
+
+        Returns:
+            New ``POI_Global`` with the same metadata as this object.
+        """
         if centroids is None:
             centroids = self.centroids.copy()
         p = POI_Global(centroids)
@@ -168,6 +211,22 @@ def copy(self, centroids: POI_Descriptor | None = None) -> Self:
 
     @classmethod
     def load(cls, poi: poi.POI_Reference, itk_coords: bool | None = None) -> Self:
+        """Load a ``POI_Global`` from a file or POI reference.
+
+        Args:
+            poi: Path to a JSON or ``.mrk.json`` file, or any supported
+                ``POI_Reference`` type.
+            itk_coords: When ``None`` the coordinate system is inferred from
+                the file.  When ``True`` or ``False``, the loaded POI is
+                asserted to match.
+
+        Returns:
+            ``POI_Global`` in the requested coordinate system.
+
+        Raises:
+            AssertionError: If ``itk_coords`` is set and does not match the
+                file's coordinate system.
+        """
         poi_obj = load_poi(poi)
 
         if not poi_obj.is_global or itk_coords is not None:
@@ -177,12 +236,24 @@ def load(cls, poi: poi.POI_Reference, itk_coords: bool | None = None) -> Self:
     def save(
         self,
         out_path: str | Path,
-        make_parents=False,
+        make_parents: bool = False,
         additional_info: dict | None = None,
-        save_hint=FORMAT_GLOBAL,
+        save_hint: int = FORMAT_GLOBAL,
         resample_reference: Has_Grid | None = None,
         verbose: logging = True,
-    ):
+    ) -> None:
+        """Save this ``POI_Global`` to a JSON file.
+
+        Args:
+            out_path: Output path (must end with ``.json``).
+            make_parents: Create parent directories if missing.
+                Defaults to ``False``.
+            additional_info: Extra key-value pairs added to the file header.
+            save_hint: Format identifier.  Defaults to ``FORMAT_GLOBAL``.
+            resample_reference: When set, convert to local coordinates of this
+                grid before saving.
+            verbose: Emit a save log message.  Defaults to ``True``.
+        """
         return save_poi(
             self, out_path, make_parents, additional_info, save_hint=save_hint, resample_reference=resample_reference, verbose=verbose
         )
@@ -190,16 +261,36 @@ def save(
     def save_mrk(
         self: Self,
         filepath: str | Path,
-        color=None,
-        split_by_region=False,
-        split_by_subregion=False,
+        color: list[float] | None = None,
+        split_by_region: bool = False,
+        split_by_subregion: bool = False,
         add_points: bool = True,
         add_lines: list[save_mkr.MKR_Lines] | None = None,
         display: save_mkr.MKR_Display | dict = None,  # type: ignore
-        pointLabelsVisibility=False,
-        glyphScale=5.0,
-        main_key="Point",
-    ):
+        pointLabelsVisibility: bool = False,
+        glyphScale: float = 5.0,
+        main_key: str = "Point",
+    ) -> None:
+        """Save this ``POI_Global`` as a 3D Slicer ``.mrk.json`` markup file.
+
+        Delegates to :func:`~TPTBox.core.poi_fun.save_mkr._save_mrk`.
+
+        Args:
+            filepath: Output path.  The extension is forced to ``.mrk.json``.
+            color: Default group colour (RGB in ``[0, 1]`` range).
+            split_by_region: Separate markup group per region.
+                Defaults to ``False``.
+            split_by_subregion: Separate markup group per subregion.
+                Defaults to ``False``.
+            add_points: Include Fiducial markups.  Defaults to ``True``.
+            add_lines: Optional ``MKR_Lines`` definitions to add as line
+                markups.
+            display: Base display property overrides.
+            pointLabelsVisibility: Show point labels in the 3D view.
+                Defaults to ``False``.
+            glyphScale: Glyph size factor.  Defaults to ``5.0``.
+            main_key: Base markup group key.  Defaults to ``"Point"``.
+        """
         save_mkr._save_mrk(
             poi=self,
             filepath=filepath,
diff --git a/TPTBox/core/poi_fun/ray_casting.py b/TPTBox/core/poi_fun/ray_casting.py
index 1f8424a..08c6140 100644
--- a/TPTBox/core/poi_fun/ray_casting.py
+++ b/TPTBox/core/poi_fun/ray_casting.py
@@ -16,13 +16,25 @@
 _log = Print_Logger()
 
 
-def unit_vector(vector):
+def unit_vector(vector: np.ndarray) -> np.ndarray:
     """Returns the unit vector of the vector."""
     return vector / np.linalg.norm(vector)
 
 
 # @njit(fastmath=True)
-def trilinear_interpolate(volume, x, y, z):
+def trilinear_interpolate(volume: np.ndarray, x: float, y: float, z: float) -> float:
+    """Perform trilinear interpolation of a 3D volume at a sub-voxel coordinate.
+
+    Args:
+        volume: 3D array to interpolate.
+        x: Sub-voxel coordinate along the first axis.
+        y: Sub-voxel coordinate along the second axis.
+        z: Sub-voxel coordinate along the third axis.
+
+    Returns:
+        Interpolated scalar value at (x, y, z), or 0.0 if the point is outside
+        the valid interior of the volume.
+    """
     xi, yi, zi = np.floor(x).astype(int), np.floor(y).astype(int), np.floor(z).astype(int)
     if xi < 0 or yi < 0 or zi < 0 or xi >= volume.shape[0] - 1 or yi >= volume.shape[1] - 1 or zi >= volume.shape[2] - 1:
         return 0.0
@@ -51,8 +63,28 @@ def max_distance_ray_cast_convex_npfast(
     region_array: np.ndarray,
     start_coord: np.ndarray,
     direction_vector: np.ndarray,
-    acc_delta=0.00005,
-):
+    acc_delta: float = 0.00005,
+) -> np.ndarray:
+    """Find the exit point of a ray inside a convex region using bisection (fast path).
+
+    Uses trilinear interpolation and bisection search to locate the last point
+    inside the region along the given direction.  Prints a debug line at each
+    bisection step (development helper — see ``max_distance_ray_cast_convex_np``
+    for the production version without debug output).
+
+    Args:
+        region_array: Binary 3D numpy array where nonzero voxels define the region.
+        start_coord: Starting coordinate ``(x, y, z)`` of the ray (must be inside
+            the region).
+        direction_vector: Direction of the ray; need not be a unit vector.
+        acc_delta: Bisection stops when the bracket width falls below this value.
+            Defaults to 0.00005.
+
+    Returns:
+        3-element array with the approximate exit coordinate along the ray.
+        If ``start_coord`` is already outside the region the start coordinate is
+        returned unchanged.
+    """
     # Normalize direction
     norm_vec = direction_vector / np.sqrt((direction_vector**2).sum())
 
@@ -93,18 +125,26 @@ def max_distance_ray_cast_convex_np(
     direction_vector: np.ndarray,
     acc_delta: float = 0.00005,
     max_v: int | None = None,
-):
-    """
-    Computes the maximum distance a ray can travel inside a convex region before exiting.
-
-    Parameters:
-    region (NII): The region of interest as a 3D NIfTI image.
-    start_coord (COORDINATE | np.ndarray): The starting coordinate of the ray.
-    direction_vector (np.ndarray): The direction vector of the ray.
-    acc_delta (float, optional): The accuracy threshold for bisection search. Default is 0.00005.
+) -> np.ndarray | None:
+    """Find the exit point of a ray inside a convex region (numpy array input).
+
+    Uses ``RegularGridInterpolator`` and bisection to locate the boundary of a
+    convex binary region along the given direction vector.
+
+    Args:
+        region: Binary 3D numpy array where values > 0.5 are considered inside.
+        start_coord: Starting coordinate ``(x, y, z)`` of the ray.  If already
+            outside the region the start coordinate is returned unchanged.
+        direction_vector: Direction of the ray; will be normalised internally.
+        acc_delta: Bisection convergence threshold in voxel units.
+            Defaults to 0.00005.
+        max_v: Upper bound for the bisection search (in voxels along the ray).
+            Defaults to ``sum(region.shape)`` when ``None``.
 
     Returns:
-    np.ndarray: The exit coordinate of the ray within the region.
+        3-element numpy array with the approximate exit coordinate, or the start
+        coordinate if it lies outside the region.  Returns ``None`` when
+        ``start_coord`` is ``None``.
     """
     start_point_np = np.asarray(start_coord)
     if start_point_np is None:
@@ -150,18 +190,25 @@ def max_distance_ray_cast_convex(
     start_coord: COORDINATE | np.ndarray,
     direction_vector: np.ndarray,
     acc_delta: float = 0.00005,
-):
-    """
-    Computes the maximum distance a ray can travel inside a convex region before exiting.
+) -> np.ndarray | None:
+    """Find the exit point of a ray inside a convex NII region.
 
-    Parameters:
-    region (NII): The region of interest as a 3D NIfTI image.
-    start_coord (COORDINATE | np.ndarray): The starting coordinate of the ray.
-    direction_vector (np.ndarray): The direction vector of the ray.
-    acc_delta (float, optional): The accuracy threshold for bisection search. Default is 0.00005.
+    Wraps the underlying numpy logic by extracting the voxel array from an
+    ``NII`` object and delegating to bisection-based ray casting.
+
+    Args:
+        region: ``NII`` object whose nonzero voxels define the convex region.
+        start_coord: Starting coordinate ``(x, y, z)`` of the ray in voxel
+            space.  If already outside the region, the start coordinate is
+            returned unchanged.
+        direction_vector: Direction of the ray; will be normalised internally.
+        acc_delta: Bisection convergence threshold in voxel units.
+            Defaults to 0.00005.
 
     Returns:
-    np.ndarray: The exit coordinate of the ray within the region.
+        3-element numpy array with the approximate exit coordinate, or the start
+        coordinate if it lies outside the region.  Returns ``None`` when
+        ``start_coord`` is ``None``.
     """
     start_point_np = np.asarray(start_coord)
     if start_point_np is None:
@@ -205,8 +252,31 @@ def ray_cast_pixel_lvl(
     start_point_np: np.ndarray,
     normal_vector: np.ndarray,
     shape: np.ndarray | tuple[int, ...],
-    two_sided=False,
+    two_sided: bool = False,
 ) -> tuple[np.ndarray | None, np.ndarray | None]:
+    """Cast a ray at pixel/voxel resolution and return all integer voxel coordinates along it.
+
+    Traces the ray starting at ``start_point_np`` in the direction of
+    ``normal_vector`` until it exits the volume defined by ``shape``.  When
+    ``two_sided`` is ``True``, the ray is also cast in the opposite direction and
+    the two halves are concatenated.
+
+    Args:
+        start_point_np: Starting voxel coordinate ``(x, y, z)`` of the ray.
+        normal_vector: Direction vector of the ray; will be normalised to a
+            unit vector internally.
+        shape: Volume shape ``(dim0, dim1, dim2)`` used to clip the ray.
+        two_sided: When ``True``, cast the ray in both directions and concatenate
+            the results.  Defaults to ``False``.
+
+    Returns:
+        A tuple ``(plane_coords, arange)`` where
+
+        * ``plane_coords`` is an integer array of shape ``(N, 3)`` with the
+          voxel indices visited by the ray, or ``None`` on failure.
+        * ``arange`` is a float array of shape ``(N,)`` with the distance
+          values along the ray for each voxel, or ``None`` on failure.
+    """
     normal_vector = unit_vector(normal_vector)
 
     def _calc_pixels(normal_vector, start_point_np):
@@ -243,11 +313,37 @@ def add_ray_to_img(
     start_point: np.ndarray | COORDINATE,
     normal_vector: np.ndarray,
     seg: NII,
-    add_to_img=True,
-    inplace=False,
-    value=0,
-    dilate=1,
-):
+    add_to_img: bool = True,
+    inplace: bool = False,
+    value: int = 0,
+    dilate: int = 1,
+) -> NII | None:
+    """Paint a ray into a segmentation NII image.
+
+    Casts a ray from ``start_point`` along ``normal_vector`` at voxel
+    resolution, fills the visited voxels with distance values (or a fixed
+    ``value``), optionally dilates the ray, and optionally composites it onto
+    the source segmentation.
+
+    Args:
+        start_point: Starting voxel coordinate of the ray.
+        normal_vector: Direction of the ray.
+        seg: Segmentation ``NII`` that defines the volume shape and is used as
+            the base when ``add_to_img`` is ``True``.
+        add_to_img: If ``True``, the ray is overlaid on ``seg`` and the
+            composite image is returned.  If ``False``, only the ray image is
+            returned.  Defaults to ``True``.
+        inplace: Modify ``seg`` in place when ``add_to_img`` is ``True``.
+            Defaults to ``False``.
+        value: Fixed voxel value written along the ray.  When 0, distance
+            values along the ray are used instead.  Defaults to 0.
+        dilate: Morphological dilation radius applied to the ray image.
+            Set to 0 to skip dilation.  Defaults to 1.
+
+    Returns:
+        The modified ``NII`` image, or ``None`` if the ray cast produced no
+        valid coordinates.
+    """
     start_point = np.array(start_point)
     plane_coords, arange = ray_cast_pixel_lvl(start_point, normal_vector, shape=seg.shape)
     if plane_coords is None:
@@ -268,12 +364,33 @@ def add_ray_to_img(
 def add_spline_to_img(
     seg: NII,
     poi: POI,
-    location=50,
-    add_to_img=True,
-    override_seg=True,
-    value=100,
-    dilate=2,
-):
+    location: int = 50,
+    add_to_img: bool = True,
+    override_seg: bool = True,
+    value: int = 100,
+    dilate: int = 2,
+) -> NII:
+    """Fit and paint a POI spline onto a segmentation NII image.
+
+    Computes a cubic spline through the POI centroids at ``location``,
+    converts it to voxel coordinates, paints each spline point with ``value``,
+    dilates the result, and (optionally) composites it onto ``seg``.
+
+    Args:
+        seg: Base segmentation ``NII`` image used for shape and affine.
+        poi: ``POI`` object from which the spline is computed.
+        location: Subregion ID used as the spline anchor points.
+            Defaults to 50 (``Vertebra_Corpus``).
+        add_to_img: If ``True``, the spline is overlaid on ``seg``.
+            Defaults to ``True``.
+        override_seg: When overlaying, whether to overwrite existing nonzero
+            voxels in ``seg``.  Defaults to ``True``.
+        value: Voxel label written along the spline.  Defaults to 100.
+        dilate: Morphological dilation radius.  Defaults to 2.
+
+    Returns:
+        The composite or standalone spline ``NII`` image.
+    """
     cor, _ = poi.fit_spline(location=location, vertebra=True)
     spline = seg.copy() * 0
     # spline.rescale_()
@@ -294,11 +411,35 @@ def add_spline_to_img(
 def shift_point(
     poi: POI,
     vert_id: int,
-    bb,
+    bb: tuple[slice, slice, slice] | None,
     start_point: Location = Location.Vertebra_Corpus,
     direction: DIRECTIONS | None = "R",
     log: Logger_Interface = _log,
-):
+) -> np.ndarray | None:
+    """Shift a POI start point laterally by a fraction of the vertebra width.
+
+    Estimates the vertebra width from articular-process or costal-process POIs
+    and returns a new coordinate displaced from ``start_point`` along
+    ``direction`` by a scaled fraction of that width.  Sacrum vertebrae without
+    arcus are skipped.
+
+    Args:
+        poi: ``POI`` object with pre-computed anatomical landmarks.
+        vert_id: Vertebra identifier (integer label).
+        bb: Bounding-box slices used to convert global POI coordinates to local
+            coordinates within the cropped sub-volume.
+        start_point: Location enum member or already-resolved numpy coordinate
+            from which the shift originates.  Defaults to
+            ``Location.Vertebra_Corpus``.
+        direction: Anatomical direction letter (``"R"``, ``"L"``, etc.) for the
+            shift, or ``None`` to return the raw local start point without
+            shifting.  Defaults to ``"R"``.
+        log: Logger used for warning and error messages.
+
+    Returns:
+        Shifted voxel coordinate as a 3-element numpy array, or ``None`` when
+        required POIs are missing or the vertebra is excluded.
+    """
     if vert_id in sacrum_w_o_arcus:
         return
 
@@ -342,24 +483,36 @@ def max_distance_ray_cast_convex_poi(
     start_point: Location | np.ndarray = Location.Vertebra_Corpus,
     log: Logger_Interface = _log,
     acc_delta: float = 0.00005,
-):
-    """
-    Computes the maximum distance a ray can travel inside a convex region for a point of interest (POI).
-
-    Parameters:
-    poi (POI): The point of interest.
-    region (NII): The region of interest as a 3D NIfTI image.
-    vert_id (int): The vertebra identifier.
-    bb (tuple[slice, slice, slice] | None): Bounding box constraints.
-    normal_vector_points (tuple[Location, Location] | DIRECTIONS, optional):
-        Two locations defining the normal vector or a predefined direction. Default is "R".
-    start_point (Location | np.ndarray, optional):
-        The starting location or coordinate of the ray. Default is Location.Vertebra_Corpus.
-    log (Logger_Interface, optional): Logger instance for error handling. Default is _log.
-    acc_delta (float, optional): The accuracy threshold for bisection search. Default is 0.00005.
+) -> np.ndarray | None:
+    """Find the boundary point of a convex region along a direction derived from POI landmarks.
+
+    Resolves the ray start coordinate and direction vector from the ``POI``
+    object, then delegates to :func:`max_distance_ray_cast_convex` to locate
+    the exit point.
+
+    Args:
+        poi: ``POI`` object with pre-computed anatomical landmarks and direction
+            vectors.
+        region: ``NII`` image whose nonzero voxels define the convex region to
+            cast the ray into.
+        vert_id: Vertebra identifier (integer label).
+        bb: Bounding-box slices that map between global POI coordinates and the
+            local sub-volume coordinate system.
+        normal_vector_points: Either a ``DIRECTIONS`` string (e.g. ``"R"``,
+            ``"P"``) that is resolved from the vertebra orientation, or a
+            2-tuple of ``Location`` members whose vector difference defines the
+            ray direction.  Defaults to ``"R"``.
+        start_point: Starting point of the ray: a ``Location`` enum member
+            (resolved via the POI) or a pre-computed numpy coordinate.
+            Defaults to ``Location.Vertebra_Corpus``.
+        log: Logger used for warning and error messages.
+        acc_delta: Bisection convergence threshold in voxel units.
+            Defaults to 0.00005.
 
     Returns:
-    np.ndarray: The exit coordinate of the ray within the region.
+        3-element numpy array with the approximate exit coordinate in the local
+        sub-volume coordinate system, or ``None`` when the start point or
+        direction cannot be resolved.
     """
     start_point_np = to_local_np(start_point, bb, poi, vert_id, log) if isinstance(start_point, Location) else start_point
     if start_point_np is None:
@@ -392,9 +545,13 @@ def max_distance_ray_cast_convex_poi(
     return max_distance_ray_cast_convex(region, start_point_np, normal_vector, acc_delta)
 
 
-def calculate_pca_normal_np(segmentation: np.ndarray, pca_component, zoom=None, verbose=False):
-    """
-    Computes the normal vector of a segmented region using Principal Component Analysis (PCA).
+def calculate_pca_normal_np(
+    segmentation: np.ndarray,
+    pca_component: int,
+    zoom: tuple[float, ...] | np.ndarray | None = None,
+    verbose: bool = False,
+) -> np.ndarray:
+    """Computes the normal vector of a segmented region using Principal Component Analysis (PCA).
 
     Parameters:
     ----------
@@ -439,16 +596,15 @@ def calculate_pca_normal_np(segmentation: np.ndarray, pca_component, zoom=None,
 
 def set_label_above_3_point_plane(
     array: NII | np.ndarray,
-    p1,
-    p2,
-    p3,
-    value=0,
+    p1: np.ndarray | list[float],
+    p2: np.ndarray | list[float],
+    p3: np.ndarray | list[float],
+    value: float = 0,
     invert: Literal[-1, 1] = 1,
     mask: np.ndarray | NII | bool = True,
-    inplace=False,
-):
-    """
-    Set all values in a 3D array above a plane defined by three non-collinear points to a specified value.
+    inplace: bool = False,
+) -> NII | np.ndarray:
+    """Set all values in a 3D array above a plane defined by three non-collinear points to a specified value.
 
     Parameters:
     -----------
diff --git a/TPTBox/core/poi_fun/save_load.py b/TPTBox/core/poi_fun/save_load.py
index 54e87d3..6dd9cff 100644
--- a/TPTBox/core/poi_fun/save_load.py
+++ b/TPTBox/core/poi_fun/save_load.py
@@ -52,7 +52,8 @@ class _Orientation(TypedDict):
 
 
 ######## Saving #######
-def _is_Point3D(obj) -> TypeGuard[_Point3D]:
+def _is_Point3D(obj: object) -> TypeGuard[_Point3D]:
+    """Return ``True`` when ``obj`` looks like a ``_Point3D`` dict."""
     return "label" in obj and "X" in obj and "Y" in obj and "Z" in obj
 
 
@@ -89,8 +90,7 @@ def save_poi(
     verbose: logging = True,
     save_hint=2,
 ) -> None:
-    """
-    Saves the POIs to a JSON file.
+    """Saves the POIs to a JSON file.
 
     Args:
         out_path (Path | str): The path where the JSON file will be saved.
@@ -98,6 +98,7 @@ def save_poi(
             Defaults to False.
         verbose (bool, optional): If True, print status messages to the console. Defaults to True.
         save_hint: 0 Default, 1 Gruber, 2 POI (readable), 10 ISO-POI (outdated)
+
     Returns:
         None
 
@@ -142,10 +143,29 @@ def convert(o):
 def _poi_to_dict_list(  # noqa: C901
     ctd: POI | POI_Global,
     additional_info: dict | None,
-    save_hint=0,
+    save_hint: int = 0,
     resample_reference: Has_Grid | None = None,
     verbose: logging = False,
-):
+) -> tuple[list, str]:
+    """Serialise a ``POI`` or ``POI_Global`` to a JSON-compatible list.
+
+    Converts the POI and its metadata into the list format used by
+    :func:`save_poi`.  Handles all supported ``FORMAT_*`` variants.
+
+    Args:
+        ctd: POI object to serialise.
+        additional_info: Extra key-value pairs merged into the header dict.
+        save_hint: Format constant (``FORMAT_DOCKER``, ``FORMAT_GRUBER``,
+            ``FORMAT_POI``, ``FORMAT_GLOBAL``, or ``FORMAT_OLD_POI``).
+            Defaults to ``FORMAT_DOCKER`` (0).
+        resample_reference: When set, the POI is first resampled to this
+            grid's coordinate system before serialisation.
+        verbose: Forward to coordinate-conversion methods.
+
+    Returns:
+        Tuple ``(dict_list, print_str)`` where ``dict_list`` is the list to
+        JSON-dump and ``print_str`` is a short human-readable format label.
+    """
     from TPTBox import POI, POI_Global
 
     if isinstance(ctd, POI_Global) and resample_reference is None:
@@ -231,6 +251,24 @@ def _poi_to_dict_list(  # noqa: C901
 
 
 def _open_file(ctd_path: Union[Path, str, bids_files.BIDS_FILE]) -> dict | list:
+    """Open a POI file and return its parsed content.
+
+    Handles BIDS file objects, plain JSON files, and landmark TXT files.
+
+    Args:
+        ctd_path: Path to the file (``str``, ``pathlib.Path``, or
+            ``BIDS_FILE``).  For ``BIDS_FILE`` objects the ``json`` or ``txt``
+            sub-file is selected automatically.
+
+    Returns:
+        Parsed file contents — either a ``dict`` (for Slicer markup JSON) or a
+        ``list`` (for the standard POI JSON or landmark TXT format).
+
+    Raises:
+        OSError: If the file cannot be opened.
+        ValueError: If the file is neither valid JSON nor a recognised landmark
+            TXT format.
+    """
     # BIDS JSON
     if isinstance(ctd_path, bids_files.BIDS_FILE):
         if "json" in ctd_path.file:
@@ -267,8 +305,7 @@ def _open_file(ctd_path: Union[Path, str, bids_files.BIDS_FILE]) -> dict | list:
 
 ######### Load  #############
 def load_poi(ctd_path: POI_Reference, verbose=True) -> POI | POI_Global:  # noqa: ARG001
-    """
-    Load POIs from a file or a BIDS file object.
+    """Load POIs from a file or a BIDS file object.
 
     Args:
         ctd_path (Centroid_Reference): Path to a file or BIDS file object from which to load POIs.
@@ -354,7 +391,8 @@ def load_poi(ctd_path: POI_Reference, verbose=True) -> POI | POI_Global:  # noqa
     )  # type: ignore
 
 
-def _load_docker_centroids(dict_list, centroids: POI_Descriptor, format_):  # noqa: ARG001
+def _load_docker_centroids(dict_list: list, centroids: POI_Descriptor, format_: int | None) -> None:  # noqa: ARG001
+    """Populate ``centroids`` from a docker/legacy-format POI dict list."""
     for d in dict_list[1:]:
         assert "direction" not in d, f'File format error: only first index can be a "direction" but got {dict_list[0]}'
         if "nan" in str(d):  # skipping NaN POIs
@@ -380,7 +418,20 @@ def _load_docker_centroids(dict_list, centroids: POI_Descriptor, format_):  # no
             raise ValueError(d)
 
 
-def _load_format_POI_old(dict_list):
+def _load_format_POI_old(dict_list: list) -> POI:
+    """Load a deprecated old-format POI file into a ``POI`` object.
+
+    The old format stores each vertebra as a dict with a ``"vert_label"`` key
+    and subregion IDs as additional string keys whose values are
+    ``"(x, y, z)"`` strings.
+
+    Args:
+        dict_list: Parsed JSON list from the old POI file (no header entry).
+
+    Returns:
+        ``POI`` object in ``("R", "P", "I")`` orientation with 1 mm isotropic
+        zoom (the stored coordinate space of the old format).
+    """
     # [
     # {
     #    "vert_label": "8",
@@ -405,7 +456,17 @@ def _load_format_POI_old(dict_list):
     return POI(centroids, orientation=("R", "P", "I"), zoom=(1, 1, 1), shape=None, format=FORMAT_OLD_POI, rotation=None)  # type: ignore
 
 
-def _load_form_POI_spine_r2(data: dict):
+def _load_form_POI_spine_r2(data: dict) -> POI:
+    """Load a spine-r2 format POI dict into a ``POI`` object.
+
+    Args:
+        data: Top-level dict from a spine-r2 JSON file, containing a nested
+            ``"centroids"`` key with centroid entries.
+
+    Returns:
+        ``POI`` object constructed from the centroid data and affine metadata
+        present in ``data``.
+    """
     from TPTBox import POI
 
     orientation = None
@@ -431,11 +492,21 @@ def _load_form_POI_spine_r2(data: dict):
 
 
 def _load_POI_centroids(
-    dict_list,
+    dict_list: list,
     centroids: POI_Descriptor,
     level_one_info: Abstract_lvl,
     level_two_info: Abstract_lvl,
-):
+) -> None:
+    """Populate ``centroids`` from a ``FORMAT_POI`` or ``FORMAT_GLOBAL`` dict list.
+
+    Args:
+        dict_list: Two-element list where the second element is a nested dict
+            ``{region_name: {subregion_name: (x, y, z)}}``.
+        centroids: ``POI_Descriptor`` to populate in place.
+        level_one_info: Registry class used to resolve region name/ID mappings.
+        level_two_info: Registry class used to resolve subregion name/ID
+            mappings.
+    """
     assert len(dict_list) == 2
     d: dict[int | str, dict[int | str, tuple[float, float, float]]] = dict_list[1]
     for vert_id, v in d.items():
@@ -445,7 +516,21 @@ def _load_POI_centroids(
             centroids[vert_id, sub_id] = tuple(t)
 
 
-def _get_poi_idx_from_text(idx: str, label: str, centroids):
+def _get_poi_idx_from_text(idx: str, label: str, centroids: POI_Descriptor) -> tuple[int, int]:
+    """Parse a Slicer markup control-point ID and label into a ``(region, subregion)`` integer pair.
+
+    Tries several strategies in order: splitting by ``"-"``, converting to int,
+    and looking up via the ``Any`` registry.  Handles collisions by incrementing
+    ``subregion`` until the slot is free.
+
+    Args:
+        idx: Control-point ``id`` field from the Slicer markup JSON.
+        label: Control-point ``label`` field (used as a fallback).
+        centroids: Existing ``POI_Descriptor`` used to detect collisions.
+
+    Returns:
+        A ``(region, subregion)`` integer tuple unique within ``centroids``.
+    """
     has_ids = False
     if "-" in label:
         try:
@@ -497,7 +582,21 @@ def _get_poi_idx_from_text(idx: str, label: str, centroids):
     return region, subregion
 
 
-def _load_mkr_POI(dict_mkr: dict):
+def _load_mkr_POI(dict_mkr: dict) -> POI_Global:
+    """Load a 3D Slicer ``.mrk.json`` markup file into a ``POI_Global`` object.
+
+    Args:
+        dict_mkr: Parsed JSON dict from a Slicer markup file containing a
+            ``"markups"`` key with Fiducial control points.
+
+    Returns:
+        ``POI_Global`` object in the coordinate system declared by the markup
+        (``"LPS"`` → ``itk_coords=True``; ``"RAS"`` → ``itk_coords=False``).
+
+    Raises:
+        ValueError: If the ``"markups"`` key is absent or ``itk_coords`` cannot
+            be determined from the file.
+    """
     centroids = POI_Descriptor()
 
     if "@schema" not in dict_mkr or "markups-schema-v1.0.3" not in dict_mkr["@schema"]:
@@ -561,8 +660,17 @@ def _load_mkr_POI(dict_mkr: dict):
 
 
 def _parse_coords(coord_str: str) -> list[float]:
-    """
-    Parse '(x, y, z)' → [x, y, z]
+    """Parse a ``'(x, y, z)'`` coordinate string into a list of three floats.
+
+    Args:
+        coord_str: Coordinate string in the form ``"(x, y, z)"``.
+
+    Returns:
+        List of three floats ``[x, y, z]``.
+
+    Raises:
+        ValueError: If the string is not in the expected format or does not
+            contain exactly three comma-separated values.
     """
     coord_str = coord_str.strip()
 
@@ -577,18 +685,25 @@ def _parse_coords(coord_str: str) -> list[float]:
     return [float(v.strip()) for v in values]
 
 
-def _parse_header_value(value: str):
-    """
-    Parse header values into numbers, lists, or nested lists if possible.
+def _parse_header_value(value: str) -> int | float | list | str:
+    """Parse a header value string into a Python scalar or list.
+
+    Args:
+        value: Raw string value from the landmark TXT header.
+
+    Returns:
+        Parsed value — one of:
+
+        * ``int`` or ``float`` for a single numeric token.
+        * ``list`` (possibly nested) for bracketed or space-separated sequences.
+        * ``str`` unchanged when no conversion applies.
 
     Examples:
-        "3.14" -> 3.14
-        "256 931 27" -> [256, 931, 27]
-        "[1, 2, 3]" -> [1, 2, 3]
-        "[[1, 0, 0], [0, 1, 0]]" -> [[1, 0, 0], [0, 1, 0]]
-        "-3.5e-12" -> -3.5e-12
+        ``"3.14"`` → ``3.14``; ``"256 931 27"`` → ``[256, 931, 27]``;
+        ``"[1, 2, 3]"`` → ``[1, 2, 3]``;
+        ``"[[1, 0, 0], [0, 1, 0]]"`` → ``[[1, 0, 0], [0, 1, 0]]``;
+        ``"-3.5e-12"`` → ``-3.5e-12``.
     """
-
     value = value.strip()
 
     # --- single number ---
@@ -641,7 +756,25 @@ def _parse_header_value(value: str):
     return value
 
 
-def _load_landmark_txt(path: Path):
+def _load_landmark_txt(path: Path) -> list:
+    """Parse a plain-text landmark file into a two-element ``[header, points]`` list.
+
+    The file format uses colon-separated ``key: value`` lines.  Group headers
+    are bare names followed by a colon (empty value).  Coordinate entries look
+    like ``landmark_name: (x, y, z)``.
+
+    Args:
+        path: Path to the ``.txt`` landmark file.
+
+    Returns:
+        Two-element list ``[header_dict, points_dict]`` compatible with the
+        ``FORMAT_PLST`` loader:
+
+        * ``header_dict``: metadata dict including ``format``,
+          ``coordinate_system``, and optional ``label_name`` /
+          ``label_group_name``.
+        * ``points_dict``: nested dict ``{group_id: {point_id: [x, y, z]}}``.
+    """
     header: dict = {
         "format": format_key[FORMAT_PLST],
         "coordinate_system": "nib",
diff --git a/TPTBox/core/poi_fun/save_mkr.py b/TPTBox/core/poi_fun/save_mkr.py
index 73ce8e9..9783aa3 100644
--- a/TPTBox/core/poi_fun/save_mkr.py
+++ b/TPTBox/core/poi_fun/save_mkr.py
@@ -22,6 +22,8 @@
 
 
 class MKR_Display(TypedDict, total=False):
+    """TypedDict for 3D Slicer markup display properties."""
+
     visibility: NotRequired[bool]
     opacity: NotRequired[float]
     color: NotRequired[list[float]]
@@ -53,6 +55,8 @@ class MKR_Display(TypedDict, total=False):
 
 
 class ControlPoint(TypedDict, total=False):
+    """TypedDict representing a single Slicer markup control point."""
+
     id: str
     label: str
     description: str
@@ -66,6 +70,8 @@ class ControlPoint(TypedDict, total=False):
 
 
 class MKR_Lines(TypedDict):
+    """TypedDict defining a Slicer line markup connecting a list of POI key points."""
+
     key_points: list[tuple[int, int]]
     color: NotRequired[list[float]]
     name: NotRequired[str]
@@ -74,6 +80,8 @@ class MKR_Lines(TypedDict):
 
 
 class Markup(TypedDict, total=False):
+    """TypedDict representing a single 3D Slicer markup node."""
+
     type: MarkupType
     name: str
     coordinateSystem: CoordinateSystem
@@ -102,6 +110,8 @@ class Markup(TypedDict, total=False):
 
 
 class MeasurementVolumeMarkup(Markup, total=False):
+    """Markup subtype carrying volume, surface area, and bounding-box measurements."""
+
     type: Literal["MeasurementVolume"]
     volume: float
     volumeUnit: VolumeUnit
@@ -114,12 +124,30 @@ class MeasurementVolumeMarkup(Markup, total=False):
 
 def _get_display_dict(
     display: MKR_Display | dict,
-    color=None,
-    selectedColor=None,
-    activeColor=None,
-    pointLabelsVisibility=False,
-    glyphScale=1.0,
-):
+    color: list[float] | None = None,
+    selectedColor: list[float] | None = None,
+    activeColor: list[float] | None = None,
+    pointLabelsVisibility: bool = False,
+    glyphScale: float = 1.0,
+) -> dict:
+    """Build a complete Slicer markup display dict with sensible defaults.
+
+    Args:
+        display: Partial display dict whose entries take precedence over the
+            defaults.
+        color: Default fiducial colour as an RGB list in ``[0, 1]`` range.
+            Defaults to cyan ``[0.4, 1.0, 1.0]``.
+        selectedColor: Colour when the point is selected.  Defaults to
+            ``[1.0, 0.5, 0.5]``.
+        activeColor: Colour when the point is active.  Defaults to
+            ``[0.4, 1.0, 0.0]``.
+        pointLabelsVisibility: Whether to show point labels in the 3D view.
+            Defaults to ``False``.
+        glyphScale: Glyph scale factor.  Defaults to ``1.0``.
+
+    Returns:
+        Complete ``MKR_Display``-compatible dict with all Slicer-required keys.
+    """
     if activeColor is None:
         activeColor = [0.4, 1.0, 0.0]
     if selectedColor is None:
@@ -162,11 +190,30 @@ def _get_display_dict(
 
 def _get_markup_color(
     definition: MKR_DEFINITION,
-    region,
-    subregion,
-    split_by_region=False,
-    split_by_subregion=False,
-):
+    region: int,
+    subregion: int,
+    split_by_region: bool = False,
+    split_by_subregion: bool = False,
+) -> list[float]:
+    """Resolve the display colour for a POI markup group.
+
+    Priority: explicit colour in ``definition`` > colour derived from region or
+    subregion ID > random colour.
+
+    Args:
+        definition: Markup definition dict that may contain a ``"color"`` key.
+        region: Region (vertebra) integer label used when
+            ``split_by_region`` is ``True``.
+        subregion: Subregion integer label used when ``split_by_subregion`` is
+            ``True``.
+        split_by_region: Assign distinct colours per region.
+            Defaults to ``False``.
+        split_by_subregion: Assign distinct colours per subregion.
+            Defaults to ``False``.
+
+    Returns:
+        RGB colour as a list of three floats in the ``[0.0, 1.0]`` range.
+    """
     color = definition.get("color", None)
     if color is None:
         if split_by_region:
@@ -184,7 +231,30 @@ def _get_markup_color(
     return color
 
 
-def _get_control_point(cp: ControlPoint, position, id_name="", label="", name="", name2="") -> ControlPoint:
+def _get_control_point(
+    cp: ControlPoint,
+    position: list[float],
+    id_name: str = "",
+    label: str = "",
+    name: str = "",
+    name2: str = "",
+) -> ControlPoint:
+    """Build a Slicer markup control-point dict, falling back to provided defaults.
+
+    Args:
+        cp: Partial ``ControlPoint`` dict whose entries take precedence over the
+            defaults below.
+        position: 3-element ``[x, y, z]`` coordinate list in the markup's
+            coordinate system.
+        id_name: Default control-point ID string.
+        label: Default short label shown in the viewer.
+        name: Default description string (used as ``description`` field).
+        name2: Default ``associatedNodeID`` string.
+
+    Returns:
+        Complete ``ControlPoint`` dict ready for inclusion in a markup's
+        ``controlPoints`` list.
+    """
     return {
         "id": cp.get("id", id_name),
         "label": cp.get("label", label),
@@ -201,11 +271,27 @@ def _get_control_point(cp: ControlPoint, position, id_name="", label="", name=""
 
 def _make_default_markup(
     markup_type: MarkupType,
-    name,
+    name: str | None,
     coordinateSystem: CoordinateSystem,
-    controlPoints=None,
-    display=None,
+    controlPoints: list[ControlPoint] | None = None,
+    display: MKR_Display | dict | None = None,
 ) -> Markup | MeasurementVolumeMarkup:
+    """Construct a default Slicer markup dict for the given type.
+
+    Args:
+        markup_type: Slicer markup type string (e.g. ``"Fiducial"``,
+            ``"Line"``, ``"ROI"``, ``"Plane"``, ``"MeasurementVolume"``).
+        name: Optional markup name shown in the Slicer hierarchy.
+        coordinateSystem: Coordinate system of the control points
+            (``"LPS"`` or ``"RAS"``).
+        controlPoints: Initial list of control points.  Defaults to an empty
+            list.
+        display: Optional display property dict merged into the markup.
+
+    Returns:
+        A ``Markup`` or ``MeasurementVolumeMarkup`` dict ready for serialisation
+        into a ``.mrk.json`` file.
+    """
     if controlPoints is None:
         controlPoints = []
     base: Markup = {
@@ -250,10 +336,27 @@ def _get_markup_lines(
     definition: MKR_Lines,
     poi: POI_Global,
     coordinate_system: Literal["LPS", "RAS"],
-    split_by_region=False,
-    split_by_subregion=False,
-    display=None,
-):
+    split_by_region: bool = False,
+    split_by_subregion: bool = False,
+    display: MKR_Display | dict | None = None,
+) -> Markup:
+    """Build a Slicer ``"Line"`` markup dict from a ``MKR_Lines`` definition.
+
+    Args:
+        definition: Line definition containing ``key_points``, and optionally
+            ``color``, ``name``, and ``display`` overrides.
+        poi: ``POI_Global`` object providing coordinates and label metadata.
+        coordinate_system: Coordinate system of the POI data
+            (``"LPS"`` or ``"RAS"``).
+        split_by_region: Colour lines by region ID.  Defaults to ``False``.
+        split_by_subregion: Colour lines by subregion ID.  Defaults to
+            ``False``.
+        display: Base display properties to merge with ``definition``'s display
+            overrides.  Defaults to ``{}``.
+
+    Returns:
+        A ``Markup`` dict of type ``"Line"`` ready for serialisation.
+    """
     if display is None:
         display = {}
     key_points = definition.get("key_points")
@@ -283,7 +386,24 @@ def _get_markup_lines(
     )
 
 
-def get_desc(self: POI_Global, region, subregion):
+def get_desc(self: POI_Global, region: int, subregion: int) -> tuple[str, str, str]:
+    """Resolve the human-readable description strings for a POI.
+
+    Looks up the label name from ``self.info["label_name"]`` if available,
+    then falls back to the level-two-info enum name or the raw integer.
+    The group name (region) is resolved similarly from ``self.info["label_group_name"]``
+    or the level-one-info enum name.
+
+    Args:
+        self: The ``POI_Global`` instance providing ``info``,
+            ``level_one_info``, and ``level_two_info``.
+        region: Region (vertebra) integer label.
+        subregion: Subregion integer label.
+
+    Returns:
+        Tuple ``(name, name2, label)`` where ``name`` and ``name2`` are the
+        group/region name and ``label`` is the subregion label string.
+    """
     label = self.info.get("label_name", {}).get(str((region, subregion)))
     if label is None:
         label = str(subregion)
@@ -309,7 +429,25 @@ def get_desc(self: POI_Global, region, subregion):
     return name, name2, label
 
 
-def _get_key(region, subregion, split_by_region, split_by_subregion, main_key="POI"):
+def _get_key(
+    region: int,
+    subregion: int,
+    split_by_region: bool,
+    split_by_subregion: bool,
+    main_key: str = "POI",
+) -> str:
+    """Build the markup group key string for a (region, subregion) pair.
+
+    Args:
+        region: Region (vertebra) integer label.
+        subregion: Subregion integer label.
+        split_by_region: Append the region ID to the key.
+        split_by_subregion: Append the subregion ID to the key.
+        main_key: Base key string.  Defaults to ``"POI"``.
+
+    Returns:
+        Group key string used as the ``name`` field for the Slicer markup group.
+    """
     key = main_key
     if split_by_region:
         key += str(region) + "_"
@@ -322,22 +460,47 @@ def _get_key(region, subregion, split_by_region, split_by_subregion, main_key="P
 def _save_mrk(
     poi: POI_Global,
     filepath: str | Path,
-    color=None,
-    split_by_region=True,
-    split_by_subregion=False,
+    color: list[float] | None = None,
+    split_by_region: bool = True,
+    split_by_subregion: bool = False,
     add_points: bool = True,
     add_lines: list[MKR_Lines] | None = None,
     display: MKR_Display | dict = None,  # type: ignore
-    pointLabelsVisibility=False,
-    glyphScale=1.0,
-    main_key="P",
+    pointLabelsVisibility: bool = False,
+    glyphScale: float = 1.0,
+    main_key: str = "P",
     **args,
-):
-    """
-    Save the POI data to a .mrk.json file in Slicer Markups format.
-    Automatically sets coordinate system based on itk_coords.
-    Includes level_one_info and level_two_info in the description.
-    Preserves metadata from `info` dictionary.
+) -> None:
+    """Save a ``POI_Global`` to a 3D Slicer ``.mrk.json`` markup file.
+
+    The coordinate system is derived from ``poi.itk_coords`` (``"LPS"`` when
+    ``True``, ``"RAS"`` otherwise).  ``level_one_info`` and ``level_two_info``
+    names are embedded in the control-point description fields.  Metadata from
+    ``poi.info`` is not written to the file but the display colour and label
+    dictionaries are preserved.
+
+    Args:
+        poi: ``POI_Global`` object to serialise.
+        filepath: Output path.  The extension is forced to ``.mrk.json`` if not
+            already present.
+        color: Default colour for all markup groups (RGB in ``[0, 1]`` range).
+            When ``None`` the colour is derived from ``split_by_*`` flags or
+            set randomly per group.
+        split_by_region: Create a separate markup group per region (vertebra).
+            Defaults to ``True``.
+        split_by_subregion: Create a separate markup group per subregion.
+            Defaults to ``False``.
+        add_points: Include Fiducial control-point markups.
+            Defaults to ``True``.
+        add_lines: Optional list of ``MKR_Lines`` definitions to add as
+            ``"Line"`` markups.  Defaults to ``None`` (no lines).
+        display: Base display property overrides applied to every markup group.
+            Defaults to ``{}``.
+        pointLabelsVisibility: Show point label text in the 3D view.
+            Defaults to ``False``.
+        glyphScale: Glyph size scale factor.  Defaults to ``1.0``.
+        main_key: Base group key string.  Defaults to ``"P"``.
+        **args: Additional key-value pairs merged into the display dict.
     """
     if display is None:
         display = {}
diff --git a/TPTBox/core/poi_fun/strategies.py b/TPTBox/core/poi_fun/strategies.py
index 86bbee0..b0c2788 100644
--- a/TPTBox/core/poi_fun/strategies.py
+++ b/TPTBox/core/poi_fun/strategies.py
@@ -25,22 +25,30 @@ def strategy_extreme_points(
     direction: Sequence[DIRECTIONS] | DIRECTIONS,
     vert_id: int,
     subreg_id: Location | list[Location],
-    bb,
-    log=_log,
-):
-    """Strategy function to update extreme points of a point of interest based on direction.
+    bb: tuple[slice, slice, slice] | None,
+    log: Logger_Interface = _log,
+) -> None:
+    """Strategy: place a POI at the anatomically extreme voxel of a subregion.
+
+    Extracts the label(s) ``subreg_id`` from ``current_subreg``, finds the
+    voxel most extreme in ``direction`` relative to the vertebra orientation,
+    and stores the result in ``poi``.
 
     Args:
-        poi (POI): The point of interest.
-        current_subreg (NII): The current subregion.
-        location (Location): The location to update in the point of interest.
-        direction (Union[Sequence[DIRECTIONS], DIRECTIONS]): Direction(s) to search for the extreme point.
-        vert_id (int): The vertex ID.
-        subreg_id (Location): The subregion ID.
-        bb: The bounding box.
-        log (Logger_Interface, optional): The logger interface. Defaults to _log.
+        poi: ``POI`` object that will receive the new landmark at
+            ``(vert_id, location.value)``.
+        current_subreg: Cropped subregion ``NII`` aligned to the vertebra
+            bounding box.
+        location: Target ``Location`` enum member identifying the landmark slot.
+        direction: Anatomical direction(s) to optimise.  Accepts a single
+            direction string, a sequence of strings, or weighted
+            ``(direction, weight)`` tuples.
+        vert_id: Vertebra identifier (integer label).
+        subreg_id: Label(s) to extract from ``current_subreg`` before
+            searching for the extreme point.
+        bb: Bounding-box slices mapping local to global voxel coordinates.
+        log: Logger for warning and error messages.
     """
-
     region = current_subreg.extract_label(subreg_id)
     if region.sum() == 0:
         log.on_fail(f"reg={vert_id},subreg={subreg_id} is missing (extreme_points); {current_subreg.unique()}")
@@ -62,9 +70,33 @@ def strategy_line_cast(
     start_point: Location | np.ndarray,
     regions_loc: list[Location] | Location,
     normal_vector_points: tuple[Location, Location] | DIRECTIONS,
-    bb,
+    bb: tuple[slice, slice, slice] | None,
     log: Logger_Interface = _log,
-):
+) -> None:
+    """Strategy: place a POI at the ray-cast exit point of a subregion surface.
+
+    Extracts the combined label mask for ``regions_loc``, then casts a ray
+    from ``start_point`` along ``normal_vector_points`` using
+    :func:`~TPTBox.core.poi_fun.ray_casting.max_distance_ray_cast_convex_poi`
+    and stores the resulting boundary coordinate in ``poi``.
+
+    Args:
+        poi: ``POI`` object that will receive the new landmark at
+            ``(vert_id, location.value)``.
+        vert_id: Vertebra identifier (integer label).
+        current_subreg: Cropped subregion ``NII`` aligned to the vertebra
+            bounding box.
+        location: Target ``Location`` enum member identifying the landmark slot.
+        start_point: Ray origin — a ``Location`` member resolved from ``poi`` or
+            a pre-computed numpy coordinate.
+        regions_loc: Label(s) to extract from ``current_subreg`` as the region
+            to cast the ray into.
+        normal_vector_points: Ray direction, given either as a ``DIRECTIONS``
+            string or a pair of ``Location`` members whose difference defines
+            the direction.
+        bb: Bounding-box slices mapping local to global voxel coordinates.
+        log: Logger for warning and error messages.
+    """
     region = current_subreg.extract_label(regions_loc)
     # if legacy_code:
     #    horizontal_plane_landmarks_old(poi, region, label_id, bb, log)
@@ -84,10 +116,37 @@ def strategy_find_corner(
     location: Location,
     vec1: Location,
     vec2: Location,
-    start_point=Location.Vertebra_Corpus,
+    start_point: Location | np.ndarray = Location.Vertebra_Corpus,
     log: Logger_Interface = _log,
     shift_direction: DIRECTIONS | None = None,
-):
+) -> None:
+    """Strategy: place a POI at the corner of a vertebral body defined by two direction vectors.
+
+    Shifts the start point laterally if ``shift_direction`` is given, then
+    uses a 2-D bisection search within the vertebral body (``Vertebra_Corpus``
+    and ``Vertebra_Corpus_border``) to find the furthest reachable corner in
+    the directions of ``vec1`` and ``vec2``.
+
+    Args:
+        poi: ``POI`` object that will receive the new landmark at
+            ``(vert_id, location.value)``.
+        current_subreg: Cropped subregion ``NII`` aligned to the vertebra
+            bounding box.
+        vert_id: Vertebra identifier (integer label).
+        bb: Bounding-box slices mapping local to global voxel coordinates.
+        location: Target ``Location`` enum member identifying the landmark slot.
+        vec1: First direction ``Location`` (e.g. anterior or superior edge
+            point).
+        vec2: Second direction ``Location`` (e.g. superior or inferior edge
+            point).
+        start_point: Ray origin — a ``Location`` member resolved from ``poi``
+            or a pre-computed numpy coordinate.  Defaults to
+            ``Location.Vertebra_Corpus``.
+        log: Logger for warning and error messages.
+        shift_direction: Optional lateral shift direction applied to
+            ``start_point`` before the corner search (e.g. ``"R"`` for right).
+            ``None`` skips the shift.
+    """
     if vert_id in sacrum_w_o_arcus:
         return
 
@@ -105,8 +164,18 @@ def strategy_find_corner(
 
 # @timing
 def _find_corner_point(
-    poi: POI, region, vert_id, bb, start_point, vec1, vec2, log: Logger_Interface = _log, delta=0.00000005, location=None
-):
+    poi: POI,
+    region: NII,
+    vert_id: int,
+    bb: tuple[slice, slice, slice] | None,
+    start_point: Location | np.ndarray,
+    vec1: Location,
+    vec2: Location,
+    log: Logger_Interface = _log,
+    delta: float = 0.00000005,
+    location: Location | None = None,
+) -> np.ndarray | None:
+    """Bisection search for the corner point furthest along two direction vectors inside a region."""
     # Convert start point and vectors to local numpy coordinates
     start_point_np = to_local_np(start_point, bb, poi, vert_id, log) if isinstance(start_point, Location) else start_point
     if start_point_np is None:
@@ -169,10 +238,35 @@ def strategy_ligament_attachment_point_flava(
     location: Location,
     goal: Location | np.ndarray,
     log: Logger_Interface = _log,
-    delta=0.0000001,
+    delta: float = 0.0000001,
     shift_direction: Literal["S", "I"] = "S",
     dir2: Literal["A"] = "A",
-):
+) -> None:
+    """Strategy: place a ligamentum-flavum attachment POI on the arcus / spinosus surface.
+
+    Starting from the spinosus process (or arcus if spinosus is absent),
+    performs a 2-D bisection search moving in ``shift_direction`` and ``dir2``
+    while staying inside the arcus/spinosus mask and approaching ``goal``.
+    The search stops when the bracket width falls below ``delta``.
+
+    Args:
+        poi: ``POI`` object that will receive the new landmark at
+            ``(vert_id, location)``.
+        current_subreg: Cropped subregion ``NII`` aligned to the vertebra
+            bounding box (must contain arcus and spinosus labels).
+        vert_id: Vertebra identifier (integer label).
+        bb: Bounding-box slices mapping local to global voxel coordinates.
+        location: Target ``Location`` enum member identifying the landmark slot.
+        goal: Target ``Location`` or pre-computed coordinate toward which the
+            search advances (e.g. an anterior longitudinal ligament point).
+        log: Logger for warning and error messages.
+        delta: Convergence threshold for the bisection loop.
+            Defaults to 0.0000001.
+        shift_direction: Primary direction of search along the arcus
+            (``"S"`` = superior, ``"I"`` = inferior).  Defaults to ``"S"``.
+        dir2: Secondary search direction (always anterior, ``"A"``).
+            Defaults to ``"A"``.
+    """
     if vert_id in sacrum_w_o_arcus:
         return
     try:
@@ -239,14 +333,40 @@ def strategy_shifted_line_cast(
     current_subreg: NII,
     location: Location,
     vert_id: int,
-    bb,
+    bb: tuple[slice, slice, slice] | None,
     regions_loc: list[Location] | Location,
     normal_vector_points: tuple[Location, Location] | DIRECTIONS,
     start_point: Location = Location.Vertebra_Corpus,
-    log=_log,
+    log: Logger_Interface = _log,
     direction: DIRECTIONS = "R",
-    do_shift=True,
-):
+    do_shift: bool = True,
+) -> None:
+    """Strategy: lateral-shift a start point then ray-cast to the subregion surface.
+
+    Optionally displaces ``start_point`` laterally by a vertebra-width fraction
+    via :func:`~TPTBox.core.poi_fun.ray_casting.shift_point`, then delegates to
+    :func:`strategy_line_cast` to find the boundary along ``normal_vector_points``.
+
+    Args:
+        poi: ``POI`` object that will receive the new landmark at
+            ``(vert_id, location.value)``.
+        current_subreg: Cropped subregion ``NII`` aligned to the vertebra
+            bounding box.
+        location: Target ``Location`` enum member identifying the landmark slot.
+        vert_id: Vertebra identifier (integer label).
+        bb: Bounding-box slices mapping local to global voxel coordinates.
+        regions_loc: Label(s) to extract from ``current_subreg`` as the target
+            region for the ray cast.
+        normal_vector_points: Ray direction — a ``DIRECTIONS`` string or a pair
+            of ``Location`` members.
+        start_point: Ray origin before shifting.  Defaults to
+            ``Location.Vertebra_Corpus``.
+        log: Logger for warning and error messages.
+        direction: Lateral direction for the shift (``"R"`` or ``"L"``).
+            Defaults to ``"R"``.
+        do_shift: When ``False``, skip the lateral shift and use ``start_point``
+            directly.  Defaults to ``True``.
+    """
     if vert_id in sacrum_w_o_arcus:
         return
     try:
diff --git a/TPTBox/core/poi_fun/vertebra_direction.py b/TPTBox/core/poi_fun/vertebra_direction.py
index 712d574..b7ec316 100644
--- a/TPTBox/core/poi_fun/vertebra_direction.py
+++ b/TPTBox/core/poi_fun/vertebra_direction.py
@@ -171,15 +171,19 @@ def calc_orientation_of_vertebra_PIR(
 
 
 def _get_sub_array_by_direction(d: DIRECTIONS, cords: np.ndarray) -> np.ndarray:
-    """Get the sub-array of coordinates along a specified direction.
-    cords must be in PIR direction
+    """Return the signed row of ``cords`` corresponding to the anatomical direction ``d``.
+
+    Args:
+        d: Anatomical direction letter (``"P"``, ``"A"``, ``"I"``, ``"S"``,
+            ``"R"``, or ``"L"``).
+        cords: Coordinate array of shape ``(3, N)`` expressed in PIR
+            (Posterior-Inferior-Right) vertebra frame.
+
     Returns:
-        np.ndarray: Sub-array of coordinates along the specified direction.
+        1-D array of length ``N`` with signed projections along ``d``.
 
     Raises:
-        ValueError: If an invalid direction is provided.
-    Note:
-        Assumes the input `cords` array has shape (3, n), where n is the number of coordinates.
+        ValueError: If an unrecognised direction is provided.
     """
     if d == "P":
         return cords[0]
@@ -197,16 +201,26 @@ def _get_sub_array_by_direction(d: DIRECTIONS, cords: np.ndarray) -> np.ndarray:
         never_called(d)
 
 
-def get_direction(d: DIRECTIONS, poi: POI, vert_id: int, verbose=True) -> np.ndarray:
-    """Get the sub-array of coordinates along a specified direction.
-    cords must be in PIR direction
+def get_direction(d: DIRECTIONS, poi: POI, vert_id: int, verbose: bool = True) -> np.ndarray:
+    """Return the unit vector for an anatomical direction of a vertebra.
+
+    Retrieves the pre-computed PIR orientation vectors for vertebra ``vert_id``
+    from ``poi`` and returns the one corresponding to direction ``d``.  C1 has
+    no independent direction and falls back to C2.
+
+    Args:
+        d: Anatomical direction letter (``"P"``, ``"A"``, ``"I"``, ``"S"``,
+            ``"R"``, or ``"L"``).
+        poi: ``POI`` object with pre-computed ``Vertebra_Direction_*`` landmarks.
+        vert_id: Vertebra identifier.  If 1 (C1), direction is taken from C2.
+        verbose: Emit a warning when C1 falls back to C2.  Defaults to ``True``.
+
     Returns:
-        np.ndarray: Sub-array of coordinates along the specified direction.
+        Unit vector (3-element numpy array) pointing in direction ``d`` in the
+        image coordinate frame.
 
     Raises:
-        ValueError: If an invalid direction is provided.
-    Note:
-        Assumes the input `cords` array has shape (3, n), where n is the number of coordinates.
+        KeyError: If orientation data for the requested vertebra is absent.
     """
     if vert_id == 1:
         _log.on_warning("C1 has no direction computation use C2 as direction", verbose=verbose)
@@ -228,8 +242,28 @@ def get_direction(d: DIRECTIONS, poi: POI, vert_id: int, verbose=True) -> np.nda
         never_called(d)
 
 
-def get_vert_direction_PIR(poi: POI, vert_id, do_norm=True, to_pir=True) -> Vertebra_Orientation:
-    """Retive the vertebra orientation from the POI. Must be computed by calc_orientation_of_vertebra_PIR first."""
+def get_vert_direction_PIR(poi: POI, vert_id: int, do_norm: bool = True, to_pir: bool = True) -> Vertebra_Orientation:
+    """Retrieve the vertebra orientation vectors from the POI.
+
+    Must be called after :func:`calc_orientation_of_vertebra_PIR` has populated
+    the ``Vertebra_Direction_*`` POI entries.
+
+    Args:
+        poi: ``POI`` object with ``Vertebra_Corpus``,
+            ``Vertebra_Direction_Posterior``, ``Vertebra_Direction_Inferior``,
+            and ``Vertebra_Direction_Right`` entries for the given vertebra.
+        vert_id: Vertebra identifier (integer label).
+        do_norm: Normalise each direction vector to unit length.
+            Defaults to ``True``.
+        to_pir: Rescale and reorient the POI to isotropic PIR space before
+            computing the directions.  When ``True`` the result is also cached
+            in ``poi._vert_orientation_pir``.  Defaults to ``True``.
+
+    Returns:
+        Tuple of three unit vectors ``(P, I, R)`` representing the Posterior,
+        Inferior, and Right directions of the vertebra in the (optionally
+        reoriented) coordinate frame.
+    """
     if vert_id in poi._vert_orientation_pir and to_pir:
         return poi._vert_orientation_pir[vert_id]  # Elusive buffer of iso/PIR directions.
     poi = poi.extract_subregion(
@@ -255,7 +289,23 @@ def n(x):
     return out
 
 
-def get_vert_direction_matrix(poi: POI, vert_id: int, to_pir=False):
+def get_vert_direction_matrix(poi: POI, vert_id: int, to_pir: bool = False) -> tuple[np.ndarray, np.ndarray]:
+    """Return the change-of-basis matrices between the image frame and the vertebra PIR frame.
+
+    Args:
+        poi: ``POI`` object with pre-computed vertebra direction landmarks.
+        vert_id: Vertebra identifier (integer label).
+        to_pir: Whether to convert the POI to isotropic PIR space before
+            computing.  Defaults to ``False``.
+
+    Returns:
+        A tuple ``(to_vert_orient, from_vert_orient)`` where
+
+        * ``to_vert_orient`` transforms image-frame vectors into the vertebra
+          PIR frame (shape ``(3, 3)``).
+        * ``from_vert_orient`` transforms vertebra-frame vectors back into the
+          image frame (shape ``(3, 3)``).
+    """
     P, I, R = get_vert_direction_PIR(poi, vert_id=vert_id, to_pir=to_pir)  # noqa: N806
     from_vert_orient = np.stack([P, I, R], axis=1)
     to_vert_orient = np.linalg.inv(from_vert_orient)
@@ -272,8 +322,7 @@ def calc_center_spinal_cord(
     _fill_inplace: NII | None = None,
     add_dense=False,
 ) -> POI:
-    """
-    Calculate the center of the spinal cord within a specified region.
+    """Calculate the center of the spinal cord within a specified region.
 
     Parameters:
     - poi (POI): Point of Interest object containing relevant data.
diff --git a/TPTBox/core/poi_fun/vertebra_pois_non_centroids.py b/TPTBox/core/poi_fun/vertebra_pois_non_centroids.py
index e35d38f..ef1e025 100755
--- a/TPTBox/core/poi_fun/vertebra_pois_non_centroids.py
+++ b/TPTBox/core/poi_fun/vertebra_pois_non_centroids.py
@@ -24,16 +24,47 @@
 ivd_pois_list = (Location.Vertebra_Disc_Inferior, Location.Vertebra_Disc_Superior, Location.Vertebra_Disc)
 
 
-def run_poi_pipeline(vert: NII, subreg: NII, poi_path: Path, logger: Logger_Interface = _log):
+def run_poi_pipeline(vert: NII, subreg: NII, poi_path: Path, logger: Logger_Interface = _log) -> None:
+    """Compute all POIs from vertebra and subregion segmentations and save them to disk.
+
+    Wraps :func:`~TPTBox.calc_poi_from_subreg_vert` for every ``Location``
+    member and writes the result as a JSON file.
+
+    Args:
+        vert: Vertebra instance segmentation ``NII`` (one label per vertebra).
+        subreg: Subregion segmentation ``NII`` (spine substructure labels).
+        poi_path: Output path for the JSON POI file.  Used as a buffer file
+            so that an existing file is read and extended rather than
+            recomputed from scratch.
+        logger: Logger instance for progress and error messages.
+    """
     poi = calc_poi_from_subreg_vert(vert, subreg, buffer_file=poi_path, save_buffer_file=True, subreg_id=list(Location), verbose=logger)
     poi.save(poi_path)
 
 
-def _strategy_side_effect(*args, **qargs):  # noqa: ARG001
-    pass
+def _strategy_side_effect(*args, **qargs) -> None:  # noqa: ARG001
+    """No-op placeholder used by side-effect and pre-computed strategy entries."""
 
 
-def add_prerequisites(locs: Sequence[Location]):
+def add_prerequisites(locs: Sequence[Location]) -> list[Location]:
+    """Expand a list of ``Location`` members with all transitive prerequisites.
+
+    Walks the :data:`all_poi_functions` registry and iteratively adds any
+    ``Location`` entries that are required by the provided list (and their
+    requirements, and so on) until no new entries are found.
+
+    Args:
+        locs: Initial sequence of ``Location`` members for which POIs are to
+            be computed.
+
+    Returns:
+        Sorted list of ``Location`` members including all original entries and
+        every transitive prerequisite, ordered by ``Location.value``.
+
+    Raises:
+        UserWarning: If a dependency cycle is detected (loop limit of 1000
+            iterations reached).
+    """
     addendum = set()
     locs2 = set(locs)
     loop_var = locs2
@@ -122,6 +153,7 @@ def __call__(
         bb,
         log: Logger_Interface = _log,
     ):
+        """Execute the POI computation strategy for the given vertebra, returning the result or None on failure."""
         try:
             return self.strategy(
                 poi=poi,
@@ -136,17 +168,47 @@ def __call__(
             _log.print_error()
             return None
 
-    def prority(self):
+    def prority(self) -> int:
+        """Return the scheduling priority for this strategy (lower value runs first)."""
         return self.target.value + self._prio
 
 
 class Strategy_Pattern_Side_Effect(Strategy_Pattern):
+    """Strategy marker for POIs computed as a side effect of another strategy.
+
+    Registers ``target`` as a POI that does not need its own compute call
+    because it is produced implicitly when ``prerequisite`` is computed.  The
+    callable is a no-op; the dependency is tracked in
+    :data:`pois_computed_by_side_effect`.
+
+    Args:
+        target: The ``Location`` that is produced as a side effect.
+        prerequisite: The ``Location`` whose computation produces ``target``.
+        **args: Additional keyword arguments forwarded to
+            :class:`Strategy_Pattern`.
+    """
+
     def __init__(self, target: Location, prerequisite: Location, **args) -> None:
         super().__init__(target, _strategy_side_effect, {prerequisite}, **args)
         pois_computed_by_side_effect[target.value] = prerequisite
 
 
 class Strategy_Computed_Before(Strategy_Pattern):
+    """Strategy marker for POIs that must be computed before the pipeline runs.
+
+    Use this when a ``Location`` is computed by an earlier, separate step
+    (e.g. spinal canal centroids) rather than by a generic strategy function.
+    The callable is a no-op; the class simply registers the prerequisite
+    dependencies.
+
+    Args:
+        target: The ``Location`` that is already computed before the pipeline.
+        *prerequisite: One or more ``Location`` members that must be present
+            before ``target`` can be used.
+        **args: Additional keyword arguments forwarded to
+            :class:`Strategy_Pattern`.
+    """
+
     def __init__(self, target: Location, *prerequisite: Location, **args) -> None:
         super().__init__(target, _strategy_side_effect, set(prerequisite), **args)
 
@@ -246,8 +308,36 @@ def compute_non_centroid_pois(  # noqa: C901
     _vert_ids: Sequence[int] | None = None,
     log: Logger_Interface = _log,
     verbose: bool | None = True,
-    _orientation_version=0,
-):
+    _orientation_version: int = 0,
+) -> None:
+    """Compute all requested non-centroid anatomical landmarks and store them in ``poi`` in place.
+
+    Runs the full non-centroid POI pipeline:
+
+    1. Vertebra orientation (PIR direction vectors) — always computed first if
+       ``Location.Vertebra_Direction_Inferior`` is requested.
+    2. Global landmarks: spinal canal / cord centres, intervertebral disc
+       POIs, dense-axis tip.
+    3. Per-vertebra landmarks via the registered :class:`Strategy_Pattern`
+       functions (extreme points, ray casts, corner finders, etc.).
+    4. Intervertebral disc (IVD) POIs.
+
+    Args:
+        poi: ``POI`` object that will be modified in place.  Must contain
+            centroid information for ``vert`` and ``subreg``.
+        locations: One or more ``Location`` members identifying the POIs to
+            compute.  A single ``Location`` is accepted and converted to a
+            list internally.
+        vert: Vertebra instance segmentation ``NII`` (one label per vertebra).
+        subreg: Spine subregion segmentation ``NII``.
+        _vert_ids: Explicit list of vertebra integer labels to process.
+            When ``None``, all labels present in ``vert`` are used.
+        log: Logger for progress and error messages.
+        verbose: Verbosity passed to logging calls.  ``None`` silences
+            everything, ``True`` enables all messages.
+        _orientation_version: Internal version selector for the vertebra
+            orientation algorithm; keep at 0 (default) for production use.
+    """
     if _vert_ids is None:
         _vert_ids = vert.unique()
 
@@ -350,7 +440,8 @@ def compute_non_centroid_pois(  # noqa: C901
         poi = calculate_IVD_POI(vert, subreg, poi, ivd_location)
 
 
-def _print_prerequisites():
+def _print_prerequisites() -> None:
+    """Print a Graphviz DOT representation of all strategy prerequisites to stdout."""
     print("digraph G {")
     for source, strategy in all_poi_functions.items():
         for prereq in strategy.prerequisite:
diff --git a/TPTBox/core/sitk_utils.py b/TPTBox/core/sitk_utils.py
index 6758f8b..1734d20 100755
--- a/TPTBox/core/sitk_utils.py
+++ b/TPTBox/core/sitk_utils.py
@@ -12,14 +12,33 @@
 
 
 def nii_to_sitk(nii: NII) -> sitk.Image:
+    """Create a SimpleITK image from a TPTBox NII wrapper.
+
+    Args:
+        nii: Source ``NII`` object.
+
+    Returns:
+        A ``SimpleITK.Image`` with origin, spacing, and direction set from the
+        NIfTI affine.
+    """
     # https://github.com/fepegar/torchio/blob/5983f83f0e7f13f9c5056e25f8753b03426ae18a/src/torchio/data/io.py#L289
-    """Create a SimpleITK image from a Nifti."""
     return nib_to_sitk(nii.nii)
 
 
 def nib_to_sitk(nii: Nifti1Image) -> sitk.Image:
+    """Create a SimpleITK image from a nibabel ``Nifti1Image``.
+
+    Transposes the voxel array from nibabel's (X, Y, Z) memory layout to
+    SimpleITK's (Z, Y, X) convention and computes origin, spacing, and direction
+    from the RAS affine matrix.
+
+    Args:
+        nii: Source nibabel ``Nifti1Image``.
+
+    Returns:
+        A 3-D ``SimpleITK.Image`` with metadata derived from the NIfTI affine.
+    """
     # https://github.com/fepegar/torchio/blob/5983f83f0e7f13f9c5056e25f8753b03426ae18a/src/torchio/data/io.py#L289
-    """Create a SimpleITK image from a Nifti."""
     array = np.asarray(nii.dataobj)
     affine = np.asarray(nii.affine).astype(np.float64)
     assert array.ndim == 3
@@ -39,6 +58,17 @@ def nib_to_sitk(nii: Nifti1Image) -> sitk.Image:
 ###########################################################################################
 # Functions are simplified from https://github.com/fepegar/torchio
 def sitk_to_nib(image: sitk.Image) -> Nifti1Image:
+    """Convert a SimpleITK image to a nibabel ``Nifti1Image``.
+
+    Transposes the voxel array from SimpleITK's (Z, Y, X) convention back to
+    nibabel's (X, Y, Z) layout and reconstructs the RAS affine.
+
+    Args:
+        image: Source 3-D ``SimpleITK.Image``.
+
+    Returns:
+        A nibabel ``Nifti1Image`` with the corresponding RAS affine matrix.
+    """
     # https://github.com/fepegar/torchio/blob/5983f83f0e7f13f9c5056e25f8753b03426ae18a/src/torchio/data/io.py#L332
     data = sitk.GetArrayFromImage(image).transpose()
     assert image.GetNumberOfComponentsPerPixel() == 1
@@ -50,12 +80,41 @@ def sitk_to_nib(image: sitk.Image) -> Nifti1Image:
 
 
 def sitk_to_nii(image: sitk.Image, seg: bool) -> NII:
+    """Convert a SimpleITK image to a TPTBox ``NII`` wrapper.
+
+    Args:
+        image: Source 3-D ``SimpleITK.Image``.
+        seg: Set to ``True`` if the image is a segmentation label map.
+
+    Returns:
+        A ``NII`` instance wrapping the converted image.
+    """
     import TPTBox
 
     return TPTBox.NII(sitk_to_nib(image), seg)
 
 
-def transform_centroid(ctd: POI, transform: sitk.Transform, img_fixed: sitk.Image, img_moving: sitk.Image, reg_type):
+def transform_centroid(ctd: POI, transform: sitk.Transform, img_fixed: sitk.Image, img_moving: sitk.Image, reg_type: str) -> POI:
+    """Apply a SimpleITK registration transform to a set of POI centroids.
+
+    For deformable registration the transform is applied directly in world
+    coordinates.  For other registration types (e.g. rigid or affine) the point
+    is first mapped from moving-image voxel space to world space, then through
+    the inverse transform, and finally back to fixed-image voxel space.
+
+    Args:
+        ctd: Input POI object whose centroid coordinates (in voxel space) are to
+            be transformed.
+        transform: Fitted SimpleITK spatial transform.
+        img_fixed: Fixed reference SimpleITK image (defines the output voxel grid).
+        img_moving: Moving SimpleITK image (defines the input voxel-to-world mapping).
+        reg_type: Registration type string; use ``"deformable"`` for deformable
+            transforms and any other value for rigid/affine transforms.
+
+    Returns:
+        A new ``POI`` object resampled to the fixed-image grid with transformed
+        centroid coordinates.
+    """
     import TPTBox
 
     out = TPTBox.core.poi.POI_Descriptor()
@@ -75,7 +134,20 @@ def transform_centroid(ctd: POI, transform: sitk.Transform, img_fixed: sitk.Imag
     return nii.get_empty_POI(out)
 
 
-def get_sitk_metadata_from_ras_affine(affine: np.ndarray):
+def get_sitk_metadata_from_ras_affine(affine: np.ndarray) -> tuple[tuple, tuple, tuple]:
+    """Decompose a NIfTI RAS affine into SimpleITK metadata components.
+
+    SimpleITK uses LPS coordinates, so the origin and direction are converted
+    from RAS before being returned.
+
+    Args:
+        affine: 4x4 homogeneous RAS affine matrix.
+
+    Returns:
+        A 3-tuple ``(origin, spacing, direction)`` where *origin* and *direction*
+        are LPS tuples and *spacing* is an isotropic voxel-size tuple — all
+        suitable for direct use with ``sitk.Image.SetOrigin`` etc.
+    """
     # https://github.com/fepegar/torchio/blob/5983f83f0e7f13f9c5056e25f8753b03426ae18a/src/torchio/data/io.py#L385
     direction_ras, spacing_array = get_rotation_and_spacing_from_affine(affine)
     origin_ras = affine[:3, 3]
@@ -88,6 +160,15 @@ def get_sitk_metadata_from_ras_affine(affine: np.ndarray):
 
 
 def get_rotation_and_spacing_from_affine(affine: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Decompose a 4x4 affine into a unit rotation matrix and per-axis voxel spacing.
+
+    Args:
+        affine: 4x4 homogeneous affine matrix.
+
+    Returns:
+        A 2-tuple ``(rotation, spacing)`` where *rotation* is the 3x3 unit-norm
+        direction matrix and *spacing* is a 1-D array of voxel sizes in mm.
+    """
     # From https://github.com/nipy/nibabel/blob/master/nibabel/orientations.py
     rotation_zoom = affine[:3, :3]
     spacing = np.sqrt(np.sum(rotation_zoom * rotation_zoom, axis=0))
@@ -96,6 +177,22 @@ def get_rotation_and_spacing_from_affine(affine: np.ndarray) -> tuple[np.ndarray
 
 
 def get_ras_affine_from_sitk(sitk_object: sitk.Image | sitk.ImageFileReader) -> np.ndarray:
+    """Build a NIfTI RAS affine matrix from a SimpleITK image or file reader.
+
+    Handles 2-D (4-element direction), 3-D (9-element direction), and
+    degenerate 4-D (16-element direction) images.
+
+    Args:
+        sitk_object: A ``SimpleITK.Image`` or ``SimpleITK.ImageFileReader``
+            with spatial metadata set.
+
+    Returns:
+        A 4x4 homogeneous RAS affine matrix as a ``numpy.ndarray``.
+
+    Raises:
+        NotImplementedError: If the direction cosine array length is not 4, 9,
+            or 16.
+    """
     # https://github.com/fepegar/torchio/blob/5983f83f0e7f13f9c5056e25f8753b03426ae18a/src/torchio/data/io.py#L357
     spacing = np.array(sitk_object.GetSpacing())
     direction_lps = np.array(sitk_object.GetDirection())
@@ -129,6 +226,25 @@ def get_ras_affine_from_sitk_meta(
     direction_lps: np.ndarray | tuple,
     origin_lps: np.ndarray | tuple,
 ) -> np.ndarray:
+    """Build a NIfTI RAS affine matrix from explicit SimpleITK metadata values.
+
+    Accepts the individual spacing, direction-cosine, and origin values rather
+    than a ``SimpleITK.Image`` object.  Handles the same dimensionality edge
+    cases as :func:`get_ras_affine_from_sitk`.
+
+    Args:
+        spacing: Per-axis voxel sizes (length 2, 3, or 4 depending on image
+            dimensionality).
+        direction_lps: Flattened LPS direction cosine matrix (length 4, 9, or 16).
+        origin_lps: LPS physical origin of the image (length 2, 3, or 4).
+
+    Returns:
+        A 4x4 homogeneous RAS affine matrix as a ``numpy.ndarray``.
+
+    Raises:
+        NotImplementedError: If the direction cosine array length is not 4, 9,
+            or 16.
+    """
     # https://github.com/fepegar/torchio/blob/5983f83f0e7f13f9c5056e25f8753b03426ae18a/src/torchio/data/io.py#L357
     spacing = np.array(spacing)
     direction_lps = np.array(direction_lps)
diff --git a/TPTBox/core/vert_constants.py b/TPTBox/core/vert_constants.py
index 688fba5..c5603c0 100755
--- a/TPTBox/core/vert_constants.py
+++ b/TPTBox/core/vert_constants.py
@@ -1,3 +1,29 @@
+"""Vertebra constants, enumerations, and label-mapping utilities for TPTBox.
+
+Vertebra numbering convention
+------------------------------
+Integer label IDs follow the TPTBox spine segmentation scheme:
+
+- **Cervical** (C1–C7):   labels 1–7
+- **Thoracic** (T1–T12):  labels 8–19;  T13 is label 28
+- **Lumbar**   (L1–L6):   labels 20–25
+- **Sacrum**   (S1):      label 26;  S2–S6: labels 29–33;  Coccyx: label 27
+
+Associated structures use fixed offsets from the vertebra label:
+
+- **Rib**:      label + 32  (``VERTEBRA_INSTANCE_RIB_LABEL_OFFSET = 40 - 8``)
+- **IVD**:      label + 100 (``VERTEBRA_INSTANCE_IVD_LABEL_OFFSET``)
+- **Endplate**: label + 200 (``VERTEBRA_INSTANCE_ENDPLATE_LABEL_OFFSET``)
+
+Key exports
+-----------
+- :class:`Vertebra_Instance` — IntEnum of all vertebra instances with rib/IVD helpers.
+- :class:`Location`          — IntEnum of vertebra subregion labels (POI types).
+- :data:`v_name2idx`         — ``dict[str, int]`` mapping name (e.g. ``"L1"``) → label.
+- :data:`v_idx2name`         — ``dict[int, str]`` mapping label → name.
+- :data:`v_idx_order`        — List of label IDs in anatomical cranio-caudal order.
+"""
+
 from __future__ import annotations
 
 from collections.abc import Sequence
@@ -58,11 +84,12 @@
 
 
 def never_called(args: NoReturn) -> NoReturn:  # noqa: ARG001
+    """Raise ``NotImplementedError``; used to mark branches that should be unreachable."""
     raise NotImplementedError()
 
 
 class Sentinel:
-    pass
+    """Unique sentinel object used as a default argument to distinguish *not provided* from ``None``."""
 
 
 # get range of all ribs
@@ -78,19 +105,29 @@ class Sentinel:
 
 
 class Abstract_lvl(Enum):
+    """Base class for all TPTBox label-level enumerations.
+
+    Subclasses are automatically registered in the global ``_register_lvl`` dict
+    so that cross-enum name resolution works.  Override :meth:`save_as_name` to
+    control whether values are serialised as human-readable names or raw integers.
+    """
+
     def __init_subclass__(cls, **kwargs):
         _register_lvl[str(cls.__name__)] = cls
 
     @classmethod
     def save_as_name(cls) -> bool:
+        """Return True if enum members should be saved using their name rather than their integer value."""
         return True
 
     @classmethod
     def order_dict(cls) -> dict[int, int]:
+        """Return a mapping from enum value to sort position; empty dict means natural integer order."""
         return {}  # Default integer order
 
     @classmethod
     def _get_name(cls, i: int, no_raise=True) -> str:
+        """Resolve an integer label to its enum name (or raw string if not found)."""
         if cls.save_as_name():
             try:
                 return cls(i).name
@@ -101,6 +138,7 @@ def _get_name(cls, i: int, no_raise=True) -> str:
 
     @classmethod
     def _get_id(cls, s: str | int, no_raise=True) -> int:
+        """Resolve a name or integer to its integer enum value."""
         if isinstance(s, int):
             return s
         try:
@@ -115,19 +153,29 @@ def _get_id(cls, s: str | int, no_raise=True) -> int:
 
 
 class Any(Abstract_lvl):
+    """Wildcard label-level that resolves names by searching all registered enums.
+
+    Unlike :class:`Abstract_lvl`, ``Any`` does not save member names — values are
+    always serialised as plain integers.  Name resolution for :meth:`_get_id` tries
+    every registered enum class until a match is found.
+    """
+
     def __init_subclass__(cls, **kwargs):
         _register_lvl[str(cls.__name__)] = cls
 
     @classmethod
     def save_as_name(cls) -> bool:
+        """Always returns False; values are serialised as integers."""
         return False
 
     @classmethod
     def _get_name(cls, i: int, no_raise=True) -> str:  # noqa: ARG003
+        """Return the string representation of integer ``i`` without enum lookup."""
         return str(i)
 
     @classmethod
     def _get_id(cls, s: str | int, no_raise=True) -> int:  # noqa: ARG003
+        """Resolve ``s`` by searching all registered enum classes; falls back to ``int(s)``."""
         self_name = str(cls.__name__)
         for n, cl in _register_lvl.items():
             if n == self_name:
@@ -141,6 +189,14 @@ def _get_id(cls, s: str | int, no_raise=True) -> int:  # noqa: ARG003
 
 
 class Full_Body_Instance_Vibe(Abstract_lvl):
+    """Enum of whole-body anatomy labels in the VIBESeg segmentation scheme.
+
+    Similar to :class:`Full_Body_Instance` but uses a different numbering that
+    matches the VIBESeg model output.  Provides a class method
+    :meth:`get_Full_Body_Instance_mapping` to convert from
+    :class:`Full_Body_Instance` labels.
+    """
+
     spleen = 1
     kidney_right = 2
     kidney_left = 3
@@ -215,7 +271,8 @@ class Full_Body_Instance_Vibe(Abstract_lvl):
     bone_other = 72
 
     @classmethod
-    def get_Full_Body_Instance_mapping(cls):
+    def get_Full_Body_Instance_mapping(cls) -> dict[int, int]:
+        """Return a mapping from ``Full_Body_Instance`` label values to ``Full_Body_Instance_Vibe`` label values."""
         return {
             Full_Body_Instance.spleen.value: cls.spleen.value,  # spleen
             Full_Body_Instance.kidney_right.value: cls.kidney_right.value,  # kidney_right
@@ -294,6 +351,13 @@ def get_Full_Body_Instance_mapping(cls):
 
 
 class Full_Body_Instance(Abstract_lvl):
+    """Enum of full-body anatomy instance labels used in whole-body segmentation.
+
+    Each member represents a distinct anatomical structure identified in a
+    whole-body scan.  Left/right pairs use an offset of 100 (right has the lower
+    value, left adds 100 where applicable).
+    """
+
     skull = 1
     clavicula_right = 2
     clavicula_left = 102
@@ -389,7 +453,8 @@ class Full_Body_Instance(Abstract_lvl):
     ignore = 63
 
     @classmethod
-    def bone(cls):
+    def bone(cls) -> list[Full_Body_Instance]:
+        """Return all skeletal bone instance labels."""
         return [
             Full_Body_Instance.skull,
             Full_Body_Instance.clavicula_right,
@@ -434,7 +499,8 @@ def bone(cls):
         ]
 
     @classmethod
-    def feet(cls):
+    def feet(cls) -> list:
+        """Return the list of foot-level instances (talus and calcaneus, left and right)."""
         return [
             Full_Body_Instance.talus_right,
             Full_Body_Instance.talus_left,
@@ -449,7 +515,8 @@ def feet(cls):
         ]
 
     @classmethod
-    def lung_system(cls):
+    def lung_system(cls) -> list[Full_Body_Instance]:
+        """Return trachea and lung instance labels."""
         return [
             Full_Body_Instance.trachea,
             Full_Body_Instance.lung_right,
@@ -457,7 +524,8 @@ def lung_system(cls):
         ]
 
     @classmethod
-    def organs(cls):
+    def organs(cls) -> list[Full_Body_Instance]:
+        """Return solid abdominal and thoracic organ instance labels."""
         return [
             Full_Body_Instance.heart,
             Full_Body_Instance.kidney_right,
@@ -473,7 +541,8 @@ def organs(cls):
         ]
 
     @classmethod
-    def digestion(cls):
+    def digestion(cls) -> list[Full_Body_Instance]:
+        """Return gastrointestinal organ instance labels."""
         return [
             Full_Body_Instance.stomach,
             Full_Body_Instance.pancreas,
@@ -483,7 +552,8 @@ def digestion(cls):
         ]
 
     @classmethod
-    def vessels(cls):
+    def vessels(cls) -> list[Full_Body_Instance]:
+        """Return vascular structure instance labels."""
         return [
             Full_Body_Instance.aorta,
             Full_Body_Instance.pulmonary_vein,
@@ -505,7 +575,8 @@ def vessels(cls):
         ]
 
     @classmethod
-    def full_spine(cls):
+    def full_spine(cls) -> list[Full_Body_Instance]:
+        """Return spinal structure instance labels (channel, IVD, vertebra, sacrum)."""
         return [
             Full_Body_Instance.channel,
             Full_Body_Instance.ivd,
@@ -515,7 +586,8 @@ def full_spine(cls):
         ]
 
     @classmethod
-    def muscle(cls):
+    def muscle(cls) -> list[Full_Body_Instance]:
+        """Return individually segmented muscle group instance labels."""
         return [
             Full_Body_Instance.gluteus_maximus_right,
             Full_Body_Instance.gluteus_maximus_left,
@@ -530,7 +602,8 @@ def muscle(cls):
         ]
 
     @classmethod
-    def body_comp(cls):
+    def body_comp(cls) -> list[Full_Body_Instance]:
+        """Return body composition instance labels (fat, generic muscle, and named muscles)."""
         return [
             Full_Body_Instance.subcutaneous_fat,
             Full_Body_Instance.muscle_other,
@@ -539,7 +612,8 @@ def body_comp(cls):
         ]
 
     @classmethod
-    def get_VIBESeg_mapping(cls):
+    def get_VIBESeg_mapping(cls) -> dict[int, int]:
+        """Return a mapping from VIBESeg label indices to ``Full_Body_Instance`` label values."""
         return {
             1: Full_Body_Instance.spleen.value,  # spleen
             2: Full_Body_Instance.kidney_right.value,  # kidney_right
@@ -619,7 +693,8 @@ def get_VIBESeg_mapping(cls):
         }
 
     @classmethod
-    def get_to_VIBESeg(cls):
+    def get_to_VIBESeg(cls) -> dict[int, int]:
+        """Return a mapping from ``Full_Body_Instance`` label values to VIBESeg label indices."""
         return {
             Full_Body_Instance.skull.value: 0,
             Full_Body_Instance.clavicula_right.value: 47,
@@ -718,6 +793,11 @@ def get_to_VIBESeg(cls):
 
 
 class Lower_Body(Abstract_lvl):
+    """Points-of-interest labels for lower body structures (patella, femur, tibia, fibula).
+
+    Members define anatomical landmark positions used in lower-extremity analysis.
+    """
+
     # Patella
     PATELLA_PROXIMAL_POLE = 1
     PATELLA_DISTAL_POLE = 2
@@ -763,7 +843,8 @@ class Lower_Body(Abstract_lvl):
     LATERAL_MALLEOLUS = 32
 
     @classmethod
-    def get_mapping(cls):
+    def get_mapping(cls) -> dict[str, tuple]:
+        """Return the abbreviation-to-enum mapping for lower body landmarks."""
         return _ABBREVIATION_TO_ENUM
 
 
@@ -820,7 +901,24 @@ def get_mapping(cls):
 
 
 class Vertebra_Instance(Abstract_lvl):
+    """Enum of individual vertebra instances with associated rib, IVD, and endplate labels.
+
+    Each member represents one vertebra identified by its integer label (see module
+    docstring for the full numbering scheme).  Associated structure labels are
+    computed from fixed offsets and exposed as properties:
+
+    - :attr:`VERTEBRA` — the raw vertebra label value.
+    - :attr:`RIB`      — rib label (only for T1–T12 and C6–C7).
+    - :attr:`IVD`      — intervertebral disc label (label + 100).
+    - :attr:`ENDPLATE` — endplate label (label + 200).
+
+    Class methods :meth:`cervical`, :meth:`thoracic`, :meth:`lumbar`, and
+    :meth:`sacrum` return tuples of members for each spinal region.
+    :meth:`order` provides the full cranio-caudal sequence.
+    """
+
     def __new__(cls, *args):
+        """Create a new Vertebra_Instance enum member, storing the vertebra label as its value."""
         obj = object.__new__(cls)
         obj._value_ = args[0]
         return obj
@@ -847,6 +945,7 @@ def __init__(
 
     @classmethod
     def vertebra_label_without_sacrum(cls) -> list[int]:
+        """Return the list of vertebra label integers excluding sacrum/coccyx (C1–L6 + T13)."""
         # TODO add sacrum label and similar flags into init (also C, T, L)
         l = list(range(1, 26))
         l.append(28)
@@ -854,15 +953,22 @@ def vertebra_label_without_sacrum(cls) -> list[int]:
 
     @classmethod
     def rib_label(cls) -> list[int]:
+        """Return all rib label integers for vertebrae that have ribs."""
         return [i._rib for i in Vertebra_Instance if i._rib is not None]
 
     @classmethod
     def endplate_label(cls) -> list[int]:
+        """Return all endplate label integers for vertebrae that have endplates."""
         return [i._endplate for i in Vertebra_Instance if i._endplate is not None]
 
     # TODO maybe easier to have a nested enum where the inner enum stands for vertebra, rib, ivd, ... makes naming independent of hard-coded attribute names
     @classmethod
     def name2idx(cls) -> dict[str, int]:
+        """Return a cached mapping from vertebra/structure name to integer label.
+
+        Names include plain vertebra names (e.g. ``"L1"``) as well as derived names
+        for ribs, IVDs, and endplates (e.g. ``"L1_rib"``, ``"L1_ivd"``).
+        """
         global _vname2idx  # noqa: PLW0603
         if _vname2idx is not None:
             return _vname2idx
@@ -880,6 +986,7 @@ def name2idx(cls) -> dict[str, int]:
 
     @classmethod
     def idx2name(cls) -> dict[int, str]:
+        """Return a cached mapping from integer label to vertebra/structure name."""
         global _vidx2name  # noqa: PLW0603
         if _vidx2name is not None:
             return _vidx2name
@@ -887,7 +994,8 @@ def idx2name(cls) -> dict[int, str]:
         return _vidx2name
 
     @classmethod
-    def is_sacrum(cls, i: int):
+    def is_sacrum(cls, i: int) -> bool:
+        """Return True if integer label ``i`` corresponds to a sacral or coccyx vertebra."""
         try:
             return cls(i) in cls.sacrum()
         except KeyError:
@@ -896,11 +1004,13 @@ def is_sacrum(cls, i: int):
             return False
 
     @classmethod
-    def cervical(cls):
+    def cervical(cls) -> tuple[Vertebra_Instance, ...]:
+        """Return a tuple of all cervical vertebra members (C1–C7)."""
         return (cls.C1, cls.C2, cls.C3, cls.C4, cls.C5, cls.C6, cls.C7)
 
     @classmethod
-    def thoracic(cls):
+    def thoracic(cls) -> tuple[Vertebra_Instance, ...]:
+        """Return a tuple of all thoracic vertebra members (T1–T13)."""
         return (
             cls.T1,
             cls.T2,
@@ -918,22 +1028,36 @@ def thoracic(cls):
         )
 
     @classmethod
-    def lumbar(cls):
+    def lumbar(cls) -> tuple[Vertebra_Instance, ...]:
+        """Return a tuple of all lumbar vertebra members (L1–L6)."""
         return (cls.L1, cls.L2, cls.L3, cls.L4, cls.L5, cls.L6)
 
     @classmethod
-    def sacrum(cls):
+    def sacrum(cls) -> tuple[Vertebra_Instance, ...]:
+        """Return a tuple of sacral and coccyx members (S1–S6, COCC)."""
         return (cls.S1, cls.S2, cls.S3, cls.S4, cls.S5, cls.S6, cls.COCC)
 
     @classmethod
-    def order(cls):
+    def order(cls) -> tuple[Vertebra_Instance, ...]:
+        """Return all vertebra members in cranio-caudal anatomical order (C1 → COCC)."""
         return cls.cervical() + cls.thoracic() + cls.lumbar() + cls.sacrum()
 
     @classmethod
     def order_dict(cls) -> dict[int, int]:
+        """Return a mapping from vertebra label value to its position in :meth:`order`."""
         return {a.value: e for e, a in enumerate(cls.order())}
 
-    def get_next_poi(self, poi: POI | NII | list[int]):
+    def get_next_poi(self, poi: POI | NII | list[int]) -> Vertebra_Instance | None:
+        """Return the next vertebra (caudally) that is present in ``poi``.
+
+        Args:
+            poi: A POI container, NII segmentation, or list of label integers.
+                The method checks which vertebra labels are present.
+
+        Returns:
+            The next :class:`Vertebra_Instance` below ``self`` that is present
+            in ``poi``, or ``None`` if no such vertebra exists.
+        """
         r = poi if isinstance(poi, list) else poi.keys_region() if hasattr(poi, "keys_region") else poi.unique()  # type: ignore
         o = self.order()
         idx = o.index(self)
@@ -942,7 +1066,17 @@ def get_next_poi(self, poi: POI | NII | list[int]):
                 return vert
         return None
 
-    def get_previous_poi(self, poi: POI | NII | list[int]):
+    def get_previous_poi(self, poi: POI | NII | list[int]) -> Vertebra_Instance | None:
+        """Return the previous vertebra (cranially) that is present in ``poi``.
+
+        Args:
+            poi: A POI container, NII segmentation, or list of label integers.
+                The method checks which vertebra labels are present.
+
+        Returns:
+            The nearest :class:`Vertebra_Instance` above ``self`` that is present
+            in ``poi``, or ``None`` if no such vertebra exists.
+        """
         r = poi if isinstance(poi, list) else poi.keys_region() if hasattr(poi, "keys_region") else poi.unique()  # type: ignore
         o = self.order()
         idx = o.index(self)
@@ -987,25 +1121,52 @@ def get_previous_poi(self, poi: POI | NII | list[int]):
 
     @property
     def VERTEBRA(self) -> int:
+        """Integer label of this vertebra (same as ``self.value``)."""
         return self.value
 
     @property
     def RIB(self) -> int:
+        """Integer label of the rib associated with this vertebra.
+
+        Raises:
+            AssertionError: If this vertebra has no associated rib.
+        """
         assert self._rib is not None, (self.name, self.value)
         return self._rib
 
     @classmethod
     def rib2vert(cls, riblabel: int) -> int:
+        """Convert a rib label integer back to its parent vertebra label integer.
+
+        Args:
+            riblabel (int): A valid rib label from :meth:`rib_label`.
+
+        Returns:
+            int: The vertebra label corresponding to ``riblabel``.
+
+        Raises:
+            AssertionError: If ``riblabel`` is not a known rib label.
+        """
         assert riblabel in Vertebra_Instance.rib_label(), riblabel
         return riblabel - VERTEBRA_INSTANCE_RIB_LABEL_OFFSET if riblabel != 21 + VERTEBRA_INSTANCE_RIB_LABEL_OFFSET else 28
 
     @property
     def IVD(self) -> int:
+        """Integer label of the intervertebral disc at this level (vertebra label + 100).
+
+        Raises:
+            AssertionError: If this vertebra has no associated IVD.
+        """
         assert self._ivd is not None, (self.name, self.value)
         return self._ivd
 
     @property
     def ENDPLATE(self) -> int:
+        """Integer label of the endplate at this level (vertebra label + 200).
+
+        Raises:
+            AssertionError: If this vertebra has no associated endplate.
+        """
         assert self._endplate is not None, (self.name, self.value)
         return self._endplate
 
@@ -1014,8 +1175,20 @@ def __str__(self):
 
 
 class Location(Abstract_lvl):
+    """IntEnum of vertebra subregion and anatomical landmark labels used as POI subregion IDs.
+
+    Values below 100 correspond to anatomical subregions of the vertebra
+    (e.g. corpus, spinosus process, articular processes).  Values ≥ 100 are
+    used for computed locations such as intervertebral discs (100), endplates
+    superior (200–), and endplates inferior (300–).
+
+    Members are serialised as integers (not names) because :meth:`save_as_name`
+    returns ``False``.
+    """
+
     @classmethod
     def save_as_name(cls) -> bool:
+        """Always returns False; Location values are saved as integers."""
         return False
 
     Unknown = 0
@@ -1126,6 +1299,19 @@ def __repr__(self):
 
 
 def vert_subreg_labels(with_border: bool = True) -> list[Location]:
+    """Return the standard list of vertebra subregion :class:`Location` labels.
+
+    The returned labels cover the main anatomical subregions used in vertebra
+    segmentation: arcus, spinosus process, costal processes, articular processes,
+    and vertebra corpus.
+
+    Args:
+        with_border (bool, optional): If True, also includes
+            :attr:`Location.Vertebra_Corpus_border`. Defaults to True.
+
+    Returns:
+        list[Location]: Ordered list of vertebra subregion ``Location`` members.
+    """
     labels = [
         Location.Arcus_Vertebrae,
         Location.Spinosus_Process,
diff --git a/TPTBox/logger/README.md b/TPTBox/logger/README.md
new file mode 100644
index 0000000..f423b78
--- /dev/null
+++ b/TPTBox/logger/README.md
@@ -0,0 +1,48 @@
+# Logger (`TPTBox.logger`)
+
+Structured, consistent logging for long-running medical image processing pipelines.
+Provides a simple interface with configurable verbosity, message categories, and output targets.
+
+## Public API
+
+```python
+from TPTBox import Logger, Print_Logger, No_Logger, String_Logger, Log_Type
+```
+
+## Key classes
+
+| Class | Description |
+|---|---|
+| `Logger` | Base logger; prints to stdout with optional file output and timestamps |
+| `Print_Logger` | Always-verbose logger — prints every message regardless of `verbose` flag |
+| `No_Logger` | Silent logger — discards all messages; useful in batch/library code |
+| `String_Logger` | Accumulates messages into an in-memory string; useful for testing |
+| `Reflection_Logger` | Wraps another logger and mirrors its messages to a second logger |
+| `Logger_Interface` | Abstract base class for custom logger implementations |
+
+## Log_Type enum
+
+| Member | Meaning |
+|---|---|
+| `Log_Type.BOLD` | Highlighted/important message |
+| `Log_Type.OK` | Success confirmation |
+| `Log_Type.WARNING` | Non-fatal warning |
+| `Log_Type.FAIL` | Error or failure |
+| `Log_Type.TEXT` | Plain informational text |
+
+## Example
+
+```python
+from TPTBox import Logger, Log_Type
+
+log = Logger(path="run.log", log_filename="pipeline", default_verbose=True)
+
+log.print("Starting segmentation", Log_Type.BOLD)
+log.print("Loaded 42 subjects", Log_Type.OK)
+log.print("Missing T2w for sub-007", Log_Type.WARNING)
+
+# Suppress all output (e.g. in a library function)
+from TPTBox import No_Logger
+log = No_Logger()
+log.print("This is silently discarded")
+```
diff --git a/TPTBox/logger/log_constants.py b/TPTBox/logger/log_constants.py
index 8611173..f74e30a 100755
--- a/TPTBox/logger/log_constants.py
+++ b/TPTBox/logger/log_constants.py
@@ -7,7 +7,7 @@
 
 
 class Log_Type(Enum):
-    """The different types of Logs supported"""
+    """The different types of Logs supported."""
 
     TEXT = auto()
     NEUTRAL = auto()
@@ -28,7 +28,7 @@ class Log_Type(Enum):
 
 
 class bcolors:
-    """Terminal color symbols"""
+    """Terminal color symbols."""
 
     # Front Colors
     BLACK = "\033[30m"
@@ -90,31 +90,26 @@ class bcolors:
 }
 
 
-def datatype_to_string(text, log_type: Log_Type):
-    """Processes given text into a readable string
+def datatype_to_string(text: object, log_type: Log_Type) -> str:
+    """Convert an arbitrary value to its loggable string representation.
+
+    Dicts receive special colored formatting via :func:`_dict_to_string`; all
+    other types are converted with ``str()``.
 
     Args:
-        text (str): _description_
-        log_type (Log_Type): _description_
+        text: The value to convert.
+        log_type: Log type used for dict colorization.
 
     Returns:
-        _type_: _description_
+        A human-readable string representation of ``text``.
     """
     if isinstance(text, dict):
         return _dict_to_string(text, log_type)
     return str(text)
 
 
-def _dict_to_string(u_dict: dict, ltype: Log_Type = Log_Type.TEXT):
-    """Converts a dictionary into a readable string
-
-    Args:
-        u_dict (dict): dictionary to be logged
-        ltype (Log_Type, optional): Log_Type. Defaults to Log_Type.TEXT.
-
-    Returns:
-        _type_: string version of the dictionary
-    """
+def _dict_to_string(u_dict: dict, ltype: Log_Type = Log_Type.TEXT) -> str:
+    """Convert a dictionary into a colored, human-readable string for logging."""
     text = ""
     text += "{"
     for key, value in u_dict.items():
@@ -127,20 +122,31 @@ def _dict_to_string(u_dict: dict, ltype: Log_Type = Log_Type.TEXT):
     return text
 
 
-def get_formatted_time():
+def get_formatted_time() -> str:
+    """Return the current local time as a short formatted string."""
     return format_time_short(get_time())
 
 
 def get_time() -> struct_time:
+    """Return the current local time as a :class:`time.struct_time`."""
     t = time.localtime()
     return t
 
 
-def _format_time(t: struct_time):
+def _format_time(t: struct_time) -> str:
+    """Return a human-readable representation of a ``struct_time`` value."""
     return time.asctime(t)
 
 
 def format_time_short(t: struct_time) -> str:
+    """Format a ``struct_time`` as a compact ``date-YYYY-M-D_time-H-M-S`` string.
+
+    Args:
+        t: Local time struct to format.
+
+    Returns:
+        A string such as ``"date-2024-1-15_time-9-30-0"``.
+    """
     return (
         "date-"
         + str(t.tm_year)
@@ -157,29 +163,33 @@ def format_time_short(t: struct_time) -> str:
     )
 
 
-def _convert_seconds(seconds: float):
+def _convert_seconds(seconds: float) -> str:
+    """Convert a duration in seconds to a human-readable ``H:MM:SS h:mm:ss`` string."""
     return str(datetime.timedelta(seconds=seconds)) + " h:mm:ss"
 
 
-def color_log_text(ltype: Log_Type, text: str, end: Log_Type = Log_Type.TEXT):
-    """Colors text(str) based on given Log_Type
+def color_log_text(ltype: Log_Type, text: str, end: Log_Type = Log_Type.TEXT) -> str:
+    """Wrap ``text`` in the ANSI color codes corresponding to ``ltype``.
 
     Args:
-        ltype (Log_Type): Log_Type (defines the color being used)
-        text (str): Text to be colored
-        end (Log_Type, optional): What color should come after this text. Defaults to Log_Type.TEXT. (no color)
+        ltype: Log type that determines the opening color code.
+        text: The string to colorize.
+        end: Log type whose color code is applied after ``text``.
+            Defaults to ``Log_Type.TEXT`` (reset to default terminal color).
 
     Returns:
-        _type_: _description_
+        The colorized string with ANSI escape sequences.
     """
     return _color_text(color_char=type2bcolors[ltype][0], text=text, end=type2bcolors[end][0])
 
 
-def _color_text(text: str, color_char, end=bcolors.ENDC):
+def _color_text(text: str, color_char: str, end: str = bcolors.ENDC) -> str:
+    """Wrap text between an opening color code and a closing reset code."""
     return f"{color_char}{text}{bcolors.ENDC}{end}"
 
 
-def _clean_all_color_from_text(text: str):
+def _clean_all_color_from_text(text: str) -> str:
+    """Strip all ANSI escape sequences from a string."""
     import re
 
     ansi_escape = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
diff --git a/TPTBox/logger/log_file.py b/TPTBox/logger/log_file.py
index 6398e89..b6db6d6 100755
--- a/TPTBox/logger/log_file.py
+++ b/TPTBox/logger/log_file.py
@@ -27,7 +27,13 @@
 
 
 class Logger_Interface(Protocol):
-    """General Logger Interface"""
+    """Structural protocol defining the logging interface for medical imaging pipelines.
+
+    All concrete logger classes (``Logger``, ``No_Logger``, ``String_Logger``,
+    ``Reflection_Logger``) implement this protocol.  Client code should type-hint
+    against ``Logger_Interface`` to remain independent of the concrete
+    implementation.
+    """
 
     prefix: str | None = None
 
@@ -38,17 +44,15 @@ def print(
         ltype=Log_Type.TEXT,
         verbose: bool | None = None,
         ignore_prefix: bool = False,
-    ):
-        """
-        Args:
-            *text: Text to the printed/logged
-            end: end char (default: newline)
-            ltype: log type (Text, Warning,...). If it is contained in *text and not here, it will still work
-            verbose: true/false: prints to terminal (If none, uses default verbose)
-            ignore_prefix: If false, will set a prefix character based on Log_Type (e.g. [*], [!], ...)
-
+    ) -> None:
+        """Print text to the logger and optionally to the terminal.
 
-        logger.print() without arguments will result in an empty newline
+        Args:
+            *text: Text to be printed/logged.
+            end: End char (default: newline).
+            ltype: Log type (Text, Warning,...). If it is contained in *text and not here, it will still work.
+            verbose: true/false: prints to terminal (if None, uses default verbose).
+            ignore_prefix: If False, will set a prefix character based on Log_Type (e.g. [*], [!], ...).
         """
         if verbose is None:
             verbose = getattr(self, "default_verbose", False)
@@ -66,7 +70,7 @@ def print(
         self._log(_clean_all_color_from_text(string), end=end, ltype=ltype)
 
     def _preprocess_text(self, text: tuple[str, ...], ltype=Log_Type.TEXT, ignore_prefix: bool = False) -> str:
-        """Processes given text parts, converting manually specified datatypes, and adds the prefix and ltype corresponding color
+        """Processes given text parts, converting manually specified datatypes, and adds the prefix and ltype corresponding color.
 
         Args:
             text (tuple[str, ...]): _description_
@@ -92,7 +96,7 @@ def __exit__(self, exception_type, exception_value, exception_traceback):
         _set_indent(False)
 
     def _prefix_indentation_level(self) -> str:
-        """Returns the indentation as processed string
+        """Returns the indentation as processed string.
 
         Returns:
             str: indentantion string
@@ -104,7 +108,7 @@ def _prefix_indentation_level(self) -> str:
         return string
 
     def _get_logger_prefix(self, ltype: Log_Type = Log_Type.TEXT):
-        """Returns the prefix based on indentation level and log_type
+        """Returns the prefix based on indentation level and log_type.
 
         Args:
             type (Log_Type, optional): _description_. Defaults to Log_Type.TEXT.
@@ -119,14 +123,21 @@ def _get_logger_prefix(self, ltype: Log_Type = Log_Type.TEXT):
 
     def _log(self, text: str, end: str = "\n", ltype=Log_Type.TEXT): ...
 
-    def close(self): ...
+    def close(self) -> None:
+        """Release any resources held by this logger."""
+        ...
 
-    def flush(self): ...
+    def flush(self) -> None:
+        """Flush any buffered log content."""
+        ...
 
-    def flush_sub_logger(self, sublogger: String_Logger, closed=False): ...
+    def flush_sub_logger(self, sublogger: String_Logger, closed: bool = False) -> None:
+        """Flush or close a sub-logger attached to this logger."""
+        ...
 
     def add_sub_logger(self, name: str, default_verbose: bool = False) -> String_Logger | No_Logger:
         """Creates a sub-logger that only logs to string. Will be appended in this loggers log file as sub-logger.
+
         Args:
             name: name of the sub-logger
             default_verbose: default_verbose attribute for the sub-logger
@@ -148,12 +159,29 @@ def add_sub_logger(self, name: str, default_verbose: bool = False) -> String_Log
         else:
             return self  # type: ignore
 
-    def print_error(self, **args):
+    def print_error(self, **args) -> None:
+        """Log the current exception traceback with ``Log_Type.FAIL`` severity."""
         self.print(traceback.format_exc(), ltype=Log_Type.FAIL, **args)
 
     logging_state = None
 
-    def log_statistic(self, key, value, key2=None, verbose=True, round_print: int | None = 5):
+    def log_statistic(
+        self, key: str, value: float, key2: str | int | None = None, verbose: bool = True, round_print: int | None = 5
+    ) -> None:
+        """Record a scalar metric and log it as a neutral message.
+
+        Values are accumulated under ``key`` / ``key2`` and can later be
+        summarized with :meth:`print_statistic`.
+
+        Args:
+            key: Primary metric name (e.g. ``"dice"``).
+            value: Numeric value to record.
+            key2: Secondary key (e.g. sample name). Defaults to the current
+                count for ``key`` when None.
+            verbose: If True, prints the entry immediately.
+            round_print: Number of decimal places for display. Set to None to
+                disable rounding.
+        """
         if self.logging_state is None:
             self.logging_state = {}
         if key not in self.logging_state:
@@ -169,7 +197,12 @@ def log_statistic(self, key, value, key2=None, verbose=True, round_print: int |
     def _print_by_logger(self, *text, end="\n", verbose: bool | None = None, **qargs):
         self.print(*text, end=end, ltype=Log_Type.LOG, verbose=verbose, **qargs)
 
-    def print_statistic(self):
+    def print_statistic(self) -> None:
+        """Print a summary table of all accumulated statistics to the log.
+
+        Computes and logs the mean, standard deviation, median, and count for
+        every key previously recorded via :meth:`log_statistic`.
+        """
         if self.logging_state is None:
             self._print_by_logger("??? No Accumulated Statistics ???")
             return
@@ -184,48 +217,58 @@ def print_statistic(self):
             self._print_by_logger(f"{k:17} {mean:8}±{std:8} {median:8} {count:7}")
         self._print_by_logger("####################################################")
 
-    def on_fail(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def on_fail(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log a message with ``Log_Type.FAIL`` severity."""
         self.print(*text, end=end, ltype=Log_Type.FAIL, verbose=verbose, **qargs)
 
-    def on_log(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def on_log(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log a message with ``Log_Type.LOG`` severity."""
         self.print(*text, end=end, ltype=Log_Type.LOG, verbose=verbose, **qargs)
 
-    def on_bold(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def on_bold(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log a message with ``Log_Type.BOLD`` formatting."""
         self.print(*text, end=end, ltype=Log_Type.BOLD, verbose=verbose, **qargs)
 
-    def on_save(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def on_save(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log a message with ``Log_Type.SAVE`` severity."""
         self.print(*text, end=end, ltype=Log_Type.SAVE, verbose=verbose, **qargs)
 
-    def on_debug(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def on_debug(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log a message with ``Log_Type.STRANGE`` (debug) severity."""
         self.print(*text, end=end, ltype=Log_Type.STRANGE, verbose=verbose, **qargs)
 
-    def on_ok(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def on_ok(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log a message with ``Log_Type.OK`` severity."""
         self.print(*text, end=end, ltype=Log_Type.OK, verbose=verbose, **qargs)
 
-    def on_neutral(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def on_neutral(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log a message with ``Log_Type.NEUTRAL`` severity."""
         self.print(*text, end=end, ltype=Log_Type.NEUTRAL, verbose=verbose, **qargs)
 
-    def on_warning(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def on_warning(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log a message with ``Log_Type.WARNING`` severity."""
         self.print(*text, end=end, ltype=Log_Type.WARNING, verbose=verbose, **qargs)
 
-    def on_text(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def on_text(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log a message with default ``Log_Type.TEXT`` severity."""
         self.print(*text, end=end, ltype=Log_Type.TEXT, verbose=verbose, **qargs)
 
     # same logging as the python loger for drop in replacement
-    def warning(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def warning(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log a warning message (drop-in for Python's ``logging.warning``)."""
         return self.on_warning(*text, end=end, verbose=verbose, **qargs)
 
-    def error(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def error(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log an error message (drop-in for Python's ``logging.error``)."""
         return self.on_fail(*text, end=end, verbose=verbose, **qargs)
 
-    def info(self, *text, end="\n", verbose: bool | None = None, **qargs):
+    def info(self, *text, end: str = "\n", verbose: bool | None = None, **qargs) -> None:
+        """Log an informational message (alias for :meth:`on_text`)."""
         return self.on_text(*text, end=end, verbose=verbose, **qargs)
 
 
 class Logger(Logger_Interface):
-    """
-    Defines a logger object, that automatically creates a logs folder and file in it. Logs logger.print() calls to this file.
-    """
+    """Defines a logger object, that automatically creates a logs folder and file in it. Logs logger.print() calls to this file."""
 
     def __init__(
         self,
@@ -235,14 +278,14 @@ def __init__(
         log_arguments=None,
         prefix: str | None = None,
     ):
-        """
+        """Initialise a file-backed logger, creating the log directory and file automatically.
 
         Args:
-            path: path to the folder that needs logging (usual dataset with raw/der in it)
-            log_filename: the filename or the bids-conform key-value pairs as dict
-            default_verbose: default verbose behavior of not specified in calls
-            log_arguments: if set, will print the contents in a "run with arguments" section
-            prefix: if set, will use this string as prefix instead of the automatically chosen one based on log_type
+            path: Path to the folder that needs logging (usual dataset with raw/der in it).
+            log_filename: The filename or the bids-conform key-value pairs as dict.
+            default_verbose: Default verbose behavior when not specified in calls.
+            log_arguments: If set, will print the contents in a "run with arguments" section.
+            prefix: If set, will use this string as prefix instead of the automatically chosen one.
         """
         path = Path(path)  # ensure pathlib object
         # Get Start time
@@ -292,7 +335,7 @@ def create_from_bids(
         default_verbose: bool = False,
         override_prefix: str | None = None,
     ):
-        """Creates a logger object based on metadata from a BIDS_FILE
+        """Creates a logger object based on metadata from a BIDS_FILE.
 
         Args:
             bids_file (BIDS_FILE): _description_
@@ -305,14 +348,22 @@ def create_from_bids(
         path = bids_file.dataset
         return Logger(path, log_filename, default_verbose=default_verbose, prefix=override_prefix)
 
-    def _log(self, text: str, end: str = "\n", ltype=Log_Type.TEXT):  # noqa: ARG002
+    def _log(self, text: str, end: str = "\n", ltype=Log_Type.TEXT) -> None:  # noqa: ARG002
+        """Write a plain-text line to the log file."""
         self.f.write(str(text))
         self.f.write(end)
 
-    def flush(self):
+    def flush(self) -> None:
+        """Flush the underlying file buffer to disk."""
         self.f.flush()
 
-    def flush_sub_logger(self, sublogger: String_Logger, closed=False):
+    def flush_sub_logger(self, sublogger: String_Logger, closed: bool = False) -> None:
+        """Append a sub-logger's accumulated content into this log file.
+
+        Args:
+            sublogger: The sub-logger whose content should be flushed.
+            closed: If True, also removes ``sublogger`` from the tracked list.
+        """
         if sublogger in self.sub_loggers:
             self.sub_loggers.remove(sublogger) if closed else None
             self.print("Flushed sub logger:", verbose=False, ltype=Log_Type.LOG)
@@ -320,10 +371,12 @@ def flush_sub_logger(self, sublogger: String_Logger, closed=False):
             # Clear Sublogger
             sublogger.log_content = ""
 
-    def remove(self):
+    def remove(self) -> None:
+        """Trigger the finalizer to close and release the log file."""
         self._finalizer()
 
-    def close(self):
+    def close(self) -> None:
+        """Flush all sub-loggers, write timing information, and close the log file."""
         if not self.f.closed:
             self.sub_loggers = [s for s in self.sub_loggers if s.log_content != ""]
             if len(self.sub_loggers) > 0:
@@ -349,14 +402,13 @@ def close(self):
             self.f.close()
 
     @property
-    def removed(self):
+    def removed(self) -> bool:
+        """True if the log file has been closed and its finalizer is no longer alive."""
         return not self._finalizer.alive
 
 
 class No_Logger(Logger_Interface):
-    """
-    Does not create any logs, but instead verbose defaults to true, printing calls to the terminal
-    """
+    """Does not create any logs, but instead verbose defaults to true, printing calls to the terminal."""
 
     def __init__(
         self,
@@ -371,26 +423,26 @@ def __init__(
             start_time_short = format_time_short(self.start_time)
             self.print(f"Log started at: {start_time_short}\n", ltype=Log_Type.LOG)
 
-    def _log(self, text: str, end: str = "\n", ltype=Log_Type.TEXT):
-        pass  # self.print()
+    def _log(self, text: str, end: str = "\n", ltype: Log_Type = Log_Type.TEXT) -> None:
+        """No-op: No_Logger does not persist log entries."""
+        # self.print()
 
-    def flush(self):
-        pass
+    def flush(self) -> None:
+        """No-op: No_Logger has no buffer to flush."""
 
-    def flush_sub_logger(self, sublogger: String_Logger, closed=False):
-        pass
+    def flush_sub_logger(self, sublogger: String_Logger, closed: bool = False) -> None:
+        """No-op: No_Logger does not track sub-loggers."""
 
-    def close(self):
-        pass
+    def close(self) -> None:
+        """No-op: No_Logger has no resources to release."""
 
     def add_sub_logger(self, name: str, default_verbose: bool = False) -> Logger_Interface:  # noqa: ARG002
+        """Return self as No_Logger does not support sub-loggers."""
         return self
 
 
 class Reflection_Logger(No_Logger):
-    """
-    Does not create any logs, but instead verbose defaults to true, printing calls to the terminal. Accepts verbose to be a Logger_Interface. In that case, the given Logger_Interface calls their print function
-    """
+    """Logger that prints to the terminal and optionally delegates to another Logger_Interface."""
 
     def print(
         self,
@@ -399,17 +451,15 @@ def print(
         ltype=Log_Type.NEUTRAL,
         verbose: bool | Logger_Interface | None = True,
         ignore_prefix: bool = False,
-    ):
-        """
-        Args:
-            *text: Text to the printed/logged
-            end: end char
-            type: log type (Text, Warning,...)
-            verbose: true/false or other Logger: prints to terminal (If none, uses default verbose)
-            ignore_prefix: If false, will set a prefix character based on Log_Type (e.g. [*], [!], ...)
-
-        Returns:
+    ) -> None:
+        """Print to terminal or delegate to a Logger_Interface passed as ``verbose``.
 
+        Args:
+            *text: Text to be printed/logged.
+            end: End char.
+            ltype: Log type (Text, Warning,...).
+            verbose: true/false or another Logger; prints to terminal (if None, uses default verbose).
+            ignore_prefix: If False, will set a prefix character based on Log_Type (e.g. [*], [!], ...).
         """
         if isinstance(verbose, bool) or verbose is None:
             super().print(*text, end=end, ltype=ltype, verbose=verbose, ignore_prefix=ignore_prefix)
@@ -418,9 +468,7 @@ def print(
 
 
 class String_Logger(Logger_Interface):
-    """
-    Logger that logs only to a string object "log_content".
-    """
+    """Logger that logs only to a string object "log_content"."""
 
     def __init__(
         self,
@@ -440,20 +488,38 @@ def __init__(
 
     @classmethod
     def as_sub_logger(cls, head_logger: Logger_Interface, default_verbose: bool = False) -> String_Logger:
+        """Create a ``String_Logger`` that is wired to a parent ``Logger_Interface``.
+
+        When flushed or closed the content is forwarded to ``head_logger``.
+
+        Args:
+            head_logger: Parent logger that will receive this sub-logger's content.
+            default_verbose: Default verbosity for calls on the sub-logger.
+
+        Returns:
+            A new ``String_Logger`` instance with ``head_logger`` set.
+        """
         sub_logger = String_Logger(default_verbose=default_verbose, finalize=False)
         sub_logger.head_logger = head_logger
         return sub_logger
 
-    def _log(self, text: str, end: str = "\n", ltype=Log_Type.TEXT):
+    def _log(self, text: str, end: str = "\n", ltype: Log_Type = Log_Type.TEXT) -> None:
+        """Append a log entry to both the plain-text and colored string buffers."""
         self.log_content += text
         self.log_content += end
         self.log_content_colored += color_log_text(ltype=ltype, text=text + end)
 
-    def flush(self):
+    def flush(self) -> None:
+        """Forward accumulated content to the head logger without closing."""
         if self.head_logger is not None:
             self.head_logger.flush_sub_logger(self, closed=False)
 
-    def close(self):
+    def close(self) -> tuple[str, str]:
+        """Finalize the sub-logger and forward its content to the head logger.
+
+        Returns:
+            A 2-tuple of ``(log_content, log_content_colored)`` strings.
+        """
         if len(self.sub_loggers) > 0:
             self.print()
             self.print(
@@ -475,8 +541,8 @@ def close(self):
             self.head_logger.flush()
         return self.log_content, self.log_content_colored
 
-    def flush_sub_logger(self, sublogger, closed=False):
-        pass
+    def flush_sub_logger(self, sublogger: String_Logger, closed: bool = False) -> None:
+        """No-op: String_Logger does not flush nested sub-loggers."""
 
 
 #####################################
@@ -484,14 +550,38 @@ def flush_sub_logger(self, sublogger, closed=False):
 #####################################
 
 
-def print_to_terminal(text: str, end: str, ltype=Log_Type.TEXT) -> None:
+def print_to_terminal(text: str, end: str, ltype: Log_Type = Log_Type.TEXT) -> None:
+    r"""Print colored text to the terminal, or emit a warning for WARNING_THROW types.
+
+    Args:
+        text: The message string to display.
+        end: Line ending character (e.g. ``"\n"``).
+        ltype: Log type that controls the ANSI color applied to ``text``.
+    """
     if ltype == Log_Type.WARNING_THROW:
         warnings.warn(color_log_text(ltype=ltype, text=text), Warning, stacklevel=3)
     else:
         print(color_log_text(ltype=ltype, text=text), end=end)
 
 
-def sub_log_call_func(name, logger: Logger, function, default_verbose: bool | None = None, **kwargs):
+def sub_log_call_func(name: str, logger: Logger, function, default_verbose: bool | None = None, **kwargs) -> object:
+    """Call a function inside a sub-logger context and return its result.
+
+    Creates a sub-logger from ``logger``, then calls ``function`` passing
+    ``name`` and the sub-logger as keyword arguments.
+
+    Args:
+        name: Label for the sub-logger.
+        logger: Parent logger from which the sub-logger is created.
+        function: Callable to invoke. Must accept ``name`` and ``logger`` as
+            keyword arguments.
+        default_verbose: Verbosity for the sub-logger. Inherits from ``logger``
+            when None.
+        **kwargs: Additional keyword arguments forwarded to ``function``.
+
+    Returns:
+        Whatever ``function`` returns.
+    """
     if default_verbose is None:
         default_verbose = logger.default_verbose
     sub_logger = logger.add_sub_logger(name, default_verbose=default_verbose)
@@ -499,7 +589,7 @@ def sub_log_call_func(name, logger: Logger, function, default_verbose: bool | No
 
 
 def _set_indent(indent_change: int | bool):
-    """Changes the indentation level
+    """Changes the indentation level.
 
     Args:
         indent_change (int | bool): If bool, true/false == +1/-1, if int, sets to that int
diff --git a/TPTBox/mesh3D/README.md b/TPTBox/mesh3D/README.md
new file mode 100644
index 0000000..858f5f1
--- /dev/null
+++ b/TPTBox/mesh3D/README.md
@@ -0,0 +1,36 @@
+# Mesh 3D (`TPTBox.mesh3D`)
+
+3D surface mesh generation from segmentation NIfTI volumes and rendering of 3D snapshots.
+Requires `pyvista` and `vtk` (included in the `dev` extras).
+
+## Key symbols
+
+| Symbol | Module | Description |
+|---|---|---|
+| `Mesh` | `mesh.py` | Generates a surface mesh from a segmentation label using marching cubes |
+| `create_snapshot3D` | `snapshot3D.py` | Renders a 3D snapshot from a list of meshes to a PNG file |
+| `LABEL_COLORS` | `mesh_colors.py` | Default colour mapping for anatomical label IDs |
+| `label_to_color(label_id)` | `mesh_colors.py` | Look up the RGB colour for a given label |
+| `create_html_preview(meshes)` | `html_preview.py` | Generate an interactive HTML file with an embedded 3D viewer |
+
+## Example
+
+```python
+from TPTBox import NII
+from TPTBox.mesh3D.mesh import Mesh
+from TPTBox.mesh3D.snapshot3D import create_snapshot3D
+
+seg = NII.load("seg.nii.gz", seg=True)
+
+# Build meshes for all labels and render
+meshes = [Mesh(seg, label=lbl) for lbl in seg.unique_labels()]
+create_snapshot3D(meshes, to="snapshot3D.png")
+```
+
+## Installation
+
+```bash
+pip install pyvista vtk
+# or via the dev extras:
+poetry install --with dev
+```
diff --git a/TPTBox/mesh3D/html_preview.py b/TPTBox/mesh3D/html_preview.py
index a075ce5..195dcaa 100644
--- a/TPTBox/mesh3D/html_preview.py
+++ b/TPTBox/mesh3D/html_preview.py
@@ -13,7 +13,8 @@
 from TPTBox.mesh3D.mesh_colors import RGB_Color, get_color_by_label
 
 
-def _add_mesh(pl, mesh: pv.PolyData | SegmentationMesh, color: str | RGB_Color, opacity: float = 1.0):
+def _add_mesh(pl: pv.Plotter, mesh: pv.PolyData | SegmentationMesh, color: str | RGB_Color, opacity: float = 1.0) -> None:
+    """Add a mesh to a pyvista Plotter, normalizing Mesh3D and RGB_Color inputs."""
     if isinstance(mesh, Mesh3D):
         mesh = mesh.mesh
     if isinstance(color, RGB_Color):
@@ -24,8 +25,7 @@ def _add_mesh(pl, mesh: pv.PolyData | SegmentationMesh, color: str | RGB_Color,
 
 @dataclass
 class Preview_Settings:
-    """
-    Configuration for visualizing a `NII` or `POI` object as a mesh.
+    """Configuration for visualizing a `NII` or `POI` object as a mesh.
 
     Attributes:
         obj (NII | POI): The image or point-of-interest object to visualize.
@@ -48,8 +48,7 @@ def _get_mesh(
         default_color_nii="bisque",
         default_poi_nii="red",
     ):
-        """
-        Generates one or more meshes from the underlying image or POI.
+        """Generates one or more meshes from the underlying image or POI.
 
         Args:
             rescale_to_iso (bool): Whether to rescale to isotropic spacing.
@@ -106,9 +105,8 @@ def make_html_preview(
     default_poi_nii="red",
     ref_spacing: Has_Grid | None = None,
     auto_rescale_to_ref=False,
-):
-    """
-    Render NII or POI objects as meshes in an interactive 3D HTML viewer.
+) -> None:
+    """Render NII or POI objects as meshes in an interactive 3D HTML viewer.
 
     Args:
         images (list[NII | POI | Preview_Settings]): List of images or wrapped settings to visualize.
diff --git a/TPTBox/mesh3D/mesh.py b/TPTBox/mesh3D/mesh.py
index 073b338..9bd3e2d 100644
--- a/TPTBox/mesh3D/mesh.py
+++ b/TPTBox/mesh3D/mesh.py
@@ -21,14 +21,29 @@
 
 
 class MeshOutputType(Enum):
+    """Supported mesh output file formats."""
+
     PLY = "ply"
 
 
 class Mesh3D:
+    """Wrapper around a pyvista PolyData mesh providing save, load, and display utilities."""
+
     def __init__(self, mesh: pv.PolyData) -> None:
         self.mesh = mesh
 
-    def save(self, filepath: str | Path, mode: MeshOutputType = MeshOutputType.PLY, verbose: logging = True):
+    def save(self, filepath: str | Path, mode: MeshOutputType = MeshOutputType.PLY, verbose: logging = True) -> None:
+        """Save the mesh to disk in the specified format.
+
+        Args:
+            filepath: Destination file path. The appropriate extension is appended if absent.
+            mode: Output format. Currently only PLY is supported.
+            verbose: If True, prints a confirmation message after saving.
+
+        Raises:
+            FileNotFoundError: If the parent directory of ``filepath`` does not exist.
+            NotImplementedError: If ``mode`` is not supported.
+        """
         filepath = str(filepath)
         if not filepath.endswith(mode.value):
             filepath += "." + mode.value
@@ -47,13 +62,25 @@ def save(self, filepath: str | Path, mode: MeshOutputType = MeshOutputType.PLY,
         log.print(f"Saved mesh: {filepath}", Log_Type.SAVE, verbose=verbose)
 
     @classmethod
-    def load(cls, filepath: str | Path):
+    def load(cls, filepath: str | Path) -> Mesh3D:
+        """Load a mesh from a file supported by pyvista.
+
+        Args:
+            filepath: Path to the mesh file (e.g. PLY, OBJ, VTK).
+
+        Returns:
+            A new ``Mesh3D`` instance wrapping the loaded mesh.
+
+        Raises:
+            AssertionError: If ``filepath`` does not exist.
+        """
         assert Path(filepath).exists(), f"loading mesh from {filepath}, filepath does not exist"
         reader = pv.get_reader(str(filepath))
         mesh = reader.read()
         return Mesh3D(mesh)
 
-    def show(self):
+    def show(self) -> None:
+        """Display the mesh interactively in a pyvista window with a black background."""
         pv.start_xvfb()
         pl = pv.Plotter()
         pl.set_background("black", top=None)
@@ -64,7 +91,12 @@ def show(self):
         pl.add_mesh(self.mesh)
         pl.show()
 
-    def save_to_html(self, file_output: str | Path):
+    def save_to_html(self, file_output: str | Path) -> None:
+        """Export the mesh as an interactive HTML file via pyvista.
+
+        Args:
+            file_output: Destination path for the HTML file.
+        """
         pv.start_xvfb()
         pl = pv.Plotter()
         pl.set_background("black", top=None)
@@ -78,6 +110,8 @@ def save_to_html(self, file_output: str | Path):
 
 
 class SegmentationMesh(Mesh3D):
+    """Mesh generated from a segmentation volume using the marching-cubes algorithm."""
+
     def __init__(self, int_arr: np.ndarray | Image_Reference) -> None:
         if not isinstance(int_arr, np.ndarray):
             seg_nii = to_nii_seg(int_arr)
@@ -111,7 +145,15 @@ def __init__(self, int_arr: np.ndarray | Image_Reference) -> None:
         mesh["values"] = values
         self.mesh = mesh
 
-    def get_mesh_with_offset(self, offset: tuple[float, float, float]):
+    def get_mesh_with_offset(self, offset: tuple[float, float, float]) -> pv.PolyData:
+        """Return a copy of the mesh with all vertices shifted by the given offset.
+
+        Args:
+            offset: A (x, y, z) translation vector applied to every vertex.
+
+        Returns:
+            A new pyvista PolyData mesh with shifted vertex positions.
+        """
         vertices = self._vertices + offset
         vfaces = np.column_stack((np.ones(len(self._faces)) * 3, self._faces)).astype(int)
 
@@ -121,7 +163,20 @@ def get_mesh_with_offset(self, offset: tuple[float, float, float]):
         return mesh
 
     @classmethod
-    def from_segmentation_nii(cls, seg_nii: NII, rescale_to_iso: bool = True):
+    def from_segmentation_nii(cls, seg_nii: NII, rescale_to_iso: bool = True) -> SegmentationMesh:
+        """Construct a ``SegmentationMesh`` from a NIfTI segmentation image.
+
+        Args:
+            seg_nii: A NIfTI segmentation image. Must have ``seg=True``.
+            rescale_to_iso: If True, resamples the image to isotropic voxel spacing before
+                extracting the surface mesh.
+
+        Returns:
+            A new ``SegmentationMesh`` built from the segmentation array.
+
+        Raises:
+            AssertionError: If ``seg_nii.seg`` is False.
+        """
         assert seg_nii.seg, "NII is not a segmentation"
         seg_nii.reorient_()
         if rescale_to_iso:
@@ -131,6 +186,8 @@ def from_segmentation_nii(cls, seg_nii: NII, rescale_to_iso: bool = True):
 
 
 class POIMesh(Mesh3D):
+    """Mesh constructed from a set of POI (point-of-interest) coordinates rendered as spheres."""
+
     def __init__(
         self,
         poi: POI,
@@ -163,7 +220,15 @@ def __init__(
         glyphed = n.glyph(scale="radius", geom=geom, progress_bar=False, orient=False)
         self.mesh = glyphed
 
-    def get_mesh_with_offset(self, offset: tuple[float, float, float]):
+    def get_mesh_with_offset(self, offset: tuple[float, float, float]) -> pv.PolyData:
+        """Return a copy of the glyph mesh with all POI positions shifted by the given offset.
+
+        Args:
+            offset: A (x, y, z) translation vector applied to every point-of-interest coordinate.
+
+        Returns:
+            A new pyvista PolyData glyph mesh with shifted sphere positions.
+        """
         pois_shifted = [(x + offset[0], y + offset[1], z + offset[2]) for x, y, z in self.poi_extracted]
         n = pv.PolyData(pois_shifted)
         n["radius"] = np.ones(shape=len(pois_shifted)) * self.size_factor
diff --git a/TPTBox/mesh3D/mesh_colors.py b/TPTBox/mesh3D/mesh_colors.py
index f98c7bf..fed18bd 100755
--- a/TPTBox/mesh3D/mesh_colors.py
+++ b/TPTBox/mesh3D/mesh_colors.py
@@ -7,16 +7,40 @@
 
 
 class RGB_Color:
+    """An RGB color stored as a NumPy integer array with helpers for normalized access."""
+
     def __init__(self, rgb: tuple[int, int, int]):
         assert isinstance(rgb, tuple) and [isinstance(i, int) for i in rgb], "did not receive a tuple of 3 ints"
         self.rgb = np.array(rgb)
 
     @classmethod
-    def init_separate(cls, r: int, g: int, b: int):
+    def init_separate(cls, r: int, g: int, b: int) -> RGB_Color:
+        """Construct an ``RGB_Color`` from three separate channel values.
+
+        Args:
+            r: Red channel (0–255).
+            g: Green channel (0–255).
+            b: Blue channel (0–255).
+
+        Returns:
+            A new ``RGB_Color`` instance.
+        """
         return cls((r, g, b))
 
     @classmethod
-    def init_list(cls, rgb: list[int] | np.ndarray):
+    def init_list(cls, rgb: list[int] | np.ndarray) -> RGB_Color:
+        """Construct an ``RGB_Color`` from a list or NumPy array of three integers.
+
+        Args:
+            rgb: Sequence of three integers (R, G, B) each in the range 0–255.
+
+        Returns:
+            A new ``RGB_Color`` instance.
+
+        Raises:
+            AssertionError: If ``rgb`` does not contain exactly three elements or
+                the NumPy array dtype is not int.
+        """
         assert len(rgb) == 3, "rgb requires exactly three integers"
         if isinstance(rgb, np.ndarray):
             assert rgb.dtype == int, "rgb numpy array not of type int!"
@@ -28,16 +52,38 @@ def __repr__(self) -> str:
     def __str__(self) -> str:
         return "RGB_Color-" + str(self.rgb)
 
-    def __call__(self, normed: bool = False):
+    def __call__(self, normed: bool = False) -> np.ndarray:
+        """Return the RGB values as an array, optionally normalized to [0, 1].
+
+        Args:
+            normed: If True, divides each channel by 255.
+
+        Returns:
+            NumPy array of shape (3,) with either raw (0–255) or normalized (0–1) values.
+        """
         if normed:
             return self.rgb / 255.0
         return self.rgb
 
-    def __getitem__(self, item):
+    def __getitem__(self, item: int) -> float:
+        """Return a single normalized channel value.
+
+        Args:
+            item: Channel index (0=R, 1=G, 2=B).
+
+        Returns:
+            The channel value divided by 255.
+        """
         return self.rgb[item] / 255.0
 
 
 class Mesh_Color_List:
+    """Catalog of named RGB colors used for anatomical mesh visualization.
+
+    Contains general-purpose color constants and 201 ITK-style colors (``ITK_1``
+    through ``ITK_201``) matching the ITK-SNAP color table convention.
+    """
+
     # General Colors
     BEIGE = RGB_Color.init_list([255, 250, 200])
     MAROON = RGB_Color.init_list([128, 0, 0])
@@ -276,13 +322,30 @@ class Mesh_Color_List:
 _color_map_in_row = np.array([v.rgb for v in _color_mapping_by_label.values()])
 
 
-def get_color_by_label(label: int):
+def get_color_by_label(label: int) -> RGB_Color:
+    """Return the ``RGB_Color`` assigned to a given integer label.
+
+    Labels 1–149 have a fixed ITK-style color. Labels outside that range are
+    wrapped modulo 50 to stay within the defined palette.
+
+    Args:
+        label: Integer segmentation label (must be >= 1).
+
+    Returns:
+        The ``RGB_Color`` mapped to ``label``.
+    """
     if label not in _color_mapping_by_label:
         return _color_mapping_by_label[label % 50 + 1]
     return _color_mapping_by_label[label]
 
 
-def write_ctbl(path: str | Path = "ITK_ColorTable.ctbl"):
+def write_ctbl(path: str | Path = "ITK_ColorTable.ctbl") -> None:
+    """Write the ITK color table to a 3D Slicer-compatible ``.ctbl`` file.
+
+    Args:
+        path: Destination file path. Defaults to ``"ITK_ColorTable.ctbl"`` in the
+            current working directory.
+    """
     with open(path, "w") as f:
         f.write("# Color table file for 3D Slicer\n")
         f.write("# Name: ITK_ColorTable\n")
diff --git a/TPTBox/mesh3D/snapshot3D.py b/TPTBox/mesh3D/snapshot3D.py
index f90f46e..dffe31f 100644
--- a/TPTBox/mesh3D/snapshot3D.py
+++ b/TPTBox/mesh3D/snapshot3D.py
@@ -32,46 +32,39 @@ def make_snapshot3D(
     output_path: str | Path | None,
     view: VIEW | list[VIEW] = "A",
     ids_list: list[Sequence[int]] | None = None,
-    smoothing=20,
+    smoothing: int = 20,
     resolution: float | None = None,
     width_factor: float = 1.0,
     scale_factor: int = 1,
-    verbose=True,
-    crop=True,
-    png_magnify=1,
+    verbose: bool = True,
+    crop: bool = True,
+    png_magnify: int = 1,
 ) -> Image.Image:
-    """
-    Generate a 3D snapshot from a medical image and save it to the specified output path.
-
-    Parameters:
-    ----------
-    img : Image_Reference
-        The medical image reference from which to generate the snapshot.
-
-    output_path : str | Path | None
-        The file path where the snapshot will be saved.
-
-    view : VIEW | list[VIEW], optional
-        The orientation(s) for the snapshot. Default is "A" (Axial).
-        Can be a single orientation or a list of orientations.
-
-    ids_list : list[Sequence[int]] | None, optional
-        A list of lists containing the IDs of the structures to be included in the snapshot.
-        If None, all unique IDs in the image will be used. Default is None.
-
-    smoothing : int, optional
-        The smoothing factor to apply to the structures. Default is 20.
-
-    resolution : float | None, optional
-        The resolution to which the image should be rescaled. If None, the minimum zoom level of the image is used. Default is None.
-
-    width_factor : float, optional
-        A factor to adjust the width of the final snapshot. Default is 1.0.
+    """Generate a 3D surface-rendered snapshot from a segmentation image.
+
+    Renders each label in the segmentation with its ITK color, arranges the
+    specified views side-by-side, and saves the composite image as a PNG.
+
+    Args:
+        img: Source segmentation image reference (NIfTI path, NII, etc.).
+        output_path: Destination PNG path. If None, a temporary file is used and
+            the resulting image is returned without being saved permanently.
+        view: Camera direction(s) for the render. Accepts a single direction
+            string or a list. Valid values: ``"R"``, ``"A"``, ``"L"``, ``"P"``,
+            ``"S"``, ``"I"``.
+        ids_list: Per-view lists of label IDs to render. If None, all unique
+            non-zero labels are used for every view.
+        smoothing: Number of VTK smoothing iterations applied to each surface.
+        resolution: Isotropic voxel size (mm) to resample to before rendering.
+            Defaults to the minimum zoom of the image.
+        width_factor: Multiplier applied to the per-view pixel width.
+        scale_factor: PNG magnification factor passed to fury's record function.
+        verbose: If True, logs the output path after saving.
+        crop: If True, crops the image to its bounding box before rendering.
+        png_magnify: Window pixel density multiplier for the fury renderer.
 
     Returns:
-    -------
-    None
-        The function saves the generated snapshot to the specified output path.
+        The rendered snapshot as a PIL Image object.
     """
     is_tmp = output_path is None
     t = None
@@ -140,15 +133,31 @@ def make_snapshot3D_parallel(
     output_paths: list[Path | str],
     view: VIEW | list[VIEW] = "A",
     ids_list: list[Sequence[int]] | None = None,
-    smoothing=20,
+    smoothing: int = 20,
     resolution: float = 1,
-    cpus=10,
-    width_factor=1.0,
-    png_magnify=1,
+    cpus: int = 10,
+    width_factor: float = 1.0,
+    png_magnify: int = 1,
     scale_factor: int = 1,
-    override=True,
-    crop=True,
-):
+    override: bool = True,
+    crop: bool = True,
+) -> None:
+    """Run :func:`make_snapshot3D` in parallel across multiple images.
+
+    Args:
+        imgs: List of segmentation image references to render.
+        output_paths: Destination PNG paths, one per image in ``imgs``.
+        view: Camera direction(s) forwarded to :func:`make_snapshot3D`.
+        ids_list: Per-view label ID lists forwarded to :func:`make_snapshot3D`.
+        smoothing: VTK smoothing iterations forwarded to :func:`make_snapshot3D`.
+        resolution: Isotropic voxel size (mm) for resampling.
+        cpus: Number of worker processes in the multiprocessing pool.
+        width_factor: Per-view width multiplier.
+        png_magnify: Window pixel density multiplier.
+        scale_factor: PNG magnification factor.
+        override: If False, skips images whose output file already exists.
+        crop: If True, crops each image to its bounding box before rendering.
+    """
     ress = []
     with Pool(cpus) as p:  # type: ignore
         for out_path, img in zip_strict(output_paths, imgs):
@@ -179,7 +188,8 @@ def make_snapshot3D_parallel(
 make_sub_snapshot_parallel = make_snapshot3D_parallel
 
 
-def _plot_sub_seg(scene: window.Scene, nii: NII, x, y, smoothing, orientation: VIEW):
+def _plot_sub_seg(scene: window.Scene, nii: NII, x: int, y: int, smoothing: int, orientation: VIEW) -> None:
+    """Render all labels from a segmentation NII into the fury scene at the given viewport offset."""
     if orientation == "A":
         #               [  axis1(w)   ]  [  axis2(h)   ]  [  view in ]
         affine = np.array([[0, 0, 1, 0], [0, 1, 0, 0], [1, 0, 0, 0], [0, 0, 0, 1]])
@@ -215,13 +225,14 @@ def _plot_sub_seg(scene: window.Scene, nii: NII, x, y, smoothing, orientation: V
 
 def _plot_mask(
     nii: NII,
-    affine,
-    x_current,
-    y_current,
-    smoothing=10,
+    affine: np.ndarray,
+    x_current: int,
+    y_current: int,
+    smoothing: int = 10,
     color: list | np.ndarray = _red,
-    opacity=1,
-):
+    opacity: float = 1,
+) -> vtk.vtkActor:
+    """Create a smoothed surface actor for a binary mask and position it in the scene."""
     mask = nii.get_seg_array()
     cont_actor = _contour_from_roi_smooth(mask, affine=affine, color=color, opacity=opacity, smoothing=smoothing)
     cont_actor.SetPosition(x_current, y_current, 0)
@@ -231,9 +242,10 @@ def _plot_mask(
 def _set_input(
     vtk_object: vtk.vtkImageReslice | vtk.vtkPolyData | vtk.vtkImageData | vtk.vtkAlgorithmOutput,
     inp: vtk.vtkImageData | vtk.vtkAlgorithmOutput,
-):
-    """Set Generic input function which takes into account VTK 5 or 6.
-    This function is copied from dipy.viz.utils
+) -> vtk.vtkImageReslice | vtk.vtkPolyData | vtk.vtkImageData | vtk.vtkAlgorithmOutput:
+    """Set input data on a VTK object, compatible with VTK 5 and 6+ APIs.
+
+    Copied from dipy.viz.utils.
     """
     if isinstance(inp, (vtk.vtkPolyData, vtk.vtkImageData)):
         vtk_object.SetInputData(inp)  # type: ignore
@@ -243,29 +255,31 @@ def _set_input(
     return vtk_object
 
 
-def _contour_from_roi_smooth(data: np.ndarray, affine=None, color: np.ndarray | list = _red, opacity=1, smoothing=0):
-    """Generates surface actor from a binary ROI.
-    Code from dipy, but added awesome smoothing!
-
-    Parameters
-    ----------
-    data : array, shape (X, Y, Z)
-        An ROI file that will be binarized and displayed.
-    affine : array, shape (4, 4)
-        Grid to space (usually RAS 1mm) transformation matrix. Default is None.
-        If None then the identity matrix is used.
-    color : (1, 3) ndarray
-        RGB values in [0,1].
-    opacity : float
-        Opacity of surface between 0 and 1.
-    smoothing: int
-        Smoothing factor e.g. 10.
-    Returns
-    -------
-    contour_assembly : vtkAssembly
-        ROI surface object displayed in space
-        coordinates as calculated by the affine parameter.
+def _contour_from_roi_smooth(
+    data: np.ndarray,
+    affine: np.ndarray | None = None,
+    color: np.ndarray | list = _red,
+    opacity: float = 1,
+    smoothing: int = 0,
+) -> vtk.vtkActor:
+    """Generate a smoothed surface VTK actor from a binary 3-D ROI array.
+
+    Adapted from dipy.viz.utils with added VTK poly-data smoothing.
+
+    Args:
+        data: Binary array of shape (X, Y, Z) representing the region of interest.
+        affine: 4x4 grid-to-space transformation matrix (RAS 1 mm convention).
+            If None the identity matrix is used.
+        color: RGB values in [0, 1] with shape (3,).
+        opacity: Surface opacity between 0 (transparent) and 1 (opaque).
+        smoothing: Number of VTK smoothing iterations. 0 disables smoothing.
+
+    Returns:
+        A vtkActor ready to be added to a VTK scene, positioned in world space
+        as defined by ``affine``.
 
+    Raises:
+        ValueError: If ``data`` is not a 3-D array.
     """
     major_version = vtk.vtkVersion.GetVTKMajorVersion()
 
diff --git a/TPTBox/registration/README.md b/TPTBox/registration/README.md
new file mode 100644
index 0000000..16ac47d
--- /dev/null
+++ b/TPTBox/registration/README.md
@@ -0,0 +1,52 @@
+# Registration (`TPTBox.registration`)
+
+Image registration utilities supporting rigid (point- and intensity-based) and deformable
+registration.  Wraps ANTs (via SimpleITK) and the optional DeepALI deep learning backend.
+
+## Public API
+
+```python
+from TPTBox.registration import (
+    Point_Registration,
+    ridged_points_from_poi,
+    ridged_points_from_subreg_vert,
+    Deformable_Registration,
+    Template_Registration,
+    General_Registration,          # requires hf-deepali
+    Rigid_Elements_Registration,   # requires hf-deepali
+)
+```
+
+## Key symbols
+
+| Symbol | Module | Description |
+|---|---|---|
+| `Point_Registration` | `_ridged_points/point_registration.py` | Rigid registration from paired 3D landmark sets |
+| `ridged_points_from_poi(fixed, moving, poi_fixed, poi_moving)` | same | Convenience wrapper: align two NIIs using POI correspondences |
+| `ridged_points_from_subreg_vert(...)` | same | Same but derives POIs from vertebra+subregion segmentations automatically |
+| `Deformable_Registration` | `_deformable/deformable_reg.py` | ANTs-based deformable (SyN) registration |
+| `Template_Registration` | `_deformable/deformable_reg.py` | Deformable registration to an atlas/template |
+| `General_Registration` | `_deepali/` | DeepALI deep-learning registration (requires `hf-deepali`) |
+| `Rigid_Elements_Registration` | `_deepali/` | Per-element rigid registration via DeepALI |
+
+## Installation of optional dependency
+
+```bash
+pip install hf-deepali   # only needed for General_Registration / Rigid_Elements_Registration
+```
+
+## Example
+
+```python
+from TPTBox.registration import ridged_points_from_poi
+
+fixed_nii = NII.load("fixed.nii.gz", seg=False)
+moving_nii = NII.load("moving.nii.gz", seg=False)
+
+registered, transform = ridged_points_from_poi(
+    fixed_nii, moving_nii,
+    poi_fixed=poi_fixed,
+    poi_moving=poi_moving,
+)
+registered.save("registered.nii.gz")
+```
diff --git a/TPTBox/registration/_deepali/_hooks.py b/TPTBox/registration/_deepali/_hooks.py
index 532303c..59d4966 100644
--- a/TPTBox/registration/_deepali/_hooks.py
+++ b/TPTBox/registration/_deepali/_hooks.py
@@ -147,7 +147,6 @@ def fn(_: "DeepaliPairwiseImageTrainer", num_steps: int, num_eval: int, loss: fl
 
 def print_step_loss_hook_tqdm(level: int, max_steps: int) -> RegistrationStepHook:  # noqa: ARG001
     r"""Get callback function for printing loss after each step."""
-
     from tqdm import tqdm
 
     bar = tqdm(range(max_steps))
diff --git a/TPTBox/registration/_deepali/_utils.py b/TPTBox/registration/_deepali/_utils.py
index 988c6fc..ffddae1 100644
--- a/TPTBox/registration/_deepali/_utils.py
+++ b/TPTBox/registration/_deepali/_utils.py
@@ -37,7 +37,15 @@
 
 
 def get_device_config(device: Union[torch.device, str, int]) -> torch.device:
-    r"""Get configured PyTorch device."""
+    """Return a ``torch.device`` from a device specifier.
+
+    Args:
+        device: Device specifier as a ``torch.device``, a device string such as
+            ``"cpu"`` or ``"cuda:0"``, or an integer GPU index.
+
+    Returns:
+        Resolved ``torch.device`` object.
+    """
     if isinstance(device, int):
         device = f"cuda:{device}"
     elif device == "cuda":
@@ -48,9 +56,25 @@ def get_device_config(device: Union[torch.device, str, int]) -> torch.device:
 def get_post_transform(
     target_grid: Grid,
     source_grid: Grid,
-    align=False,
+    align: bool | dict | str | Path = False,
 ) -> SpatialTransform | None:
-    r"""Get constant rigid transformation between image grid domains."""
+    """Build a constant rigid pre-alignment transform between two image grid domains.
+
+    Args:
+        target_grid: Target (fixed) image grid.
+        source_grid: Source (moving) image grid.
+        align: Pre-alignment strategy.  ``False`` / ``None`` disables alignment.
+            ``True`` aligns both centres and directions.  A ``dict`` may contain
+            ``"centers"`` and ``"directions"`` boolean flags.  A ``str`` or
+            ``Path`` is treated as a file path and loaded via :func:`load_transform`.
+
+    Returns:
+        A ``SpatialTransform`` encoding the pre-alignment, or ``None`` if
+        *align* is ``False`` or ``None``.
+
+    Raises:
+        ValueError: If *align* is an unrecognised type or value.
+    """
     if align is False or align is None:
         return None
     if isinstance(align, (Path, str)):
@@ -128,13 +152,22 @@ def convert_matrix(matrix: Tensor, grid: Grid | None = None) -> Tensor:
 
 
 def slope_of_least_squares_fit(values: Sequence[float]) -> float:
-    r"""Compute slope of least squares fit of line to last n objective function values
+    """Compute the slope of a least-squares line fit through the given values.
+
+    Each element index is treated as the x-coordinate.  The formula avoids
+    explicit matrix construction for efficiency.
+
+    Args:
+        values: Sequence of scalar objective-function values (at least 2).
 
-    See also:
-    - https://www.che.udel.edu/pdf/FittingData.pdf
-    - https://en.wikipedia.org/wiki/1_%2B_2_%2B_3_%2B_4_%2B_%E2%8B%AF
-    - https://proofwiki.org/wiki/Sum_of_Sequence_of_Squares
+    Returns:
+        Slope of the fitted line, or ``float("nan")`` when fewer than 2 values
+        are provided.
 
+    See Also:
+        - https://www.che.udel.edu/pdf/FittingData.pdf
+        - https://en.wikipedia.org/wiki/1_%2B_2_%2B_3_%2B_4_%2B_%E2%8B%AF
+        - https://proofwiki.org/wiki/Sum_of_Sequence_of_Squares
     """
     n = len(values)
     if n < 2:
@@ -151,6 +184,16 @@ def slope_of_least_squares_fit(values: Sequence[float]) -> float:
 
 
 class OptimizerWrapper(ContextDecorator):
+    """Context manager that zeroes gradients on entry and steps the optimiser on clean exit.
+
+    Intended as a ``with``-statement body around a ``loss.backward()`` call.
+
+    Args:
+        optimizer: PyTorch optimiser to manage.
+        scheduler: Optional learning-rate scheduler stepped after each optimiser
+            update.
+    """
+
     def __init__(self, optimizer: torch.optim.Optimizer, scheduler=None):
         self.optimizer = optimizer
         self.scheduler = scheduler
@@ -167,7 +210,19 @@ def __exit__(self, exc_type, exc_value, traceback):
 
 
 def overlap_mask(source_mask: Tensor | None, target_mask: Tensor | None) -> Tensor | None:
-    r"""Overlap mask at which to evaluate pairwise data term."""
+    """Compute the element-wise AND of two binary masks.
+
+    Returns the logical overlap region at which a pairwise loss should be
+    evaluated.  If either mask is ``None``, the other is returned as-is.
+
+    Args:
+        source_mask: Binary mask for the source image, or ``None``.
+        target_mask: Binary mask for the target image, or ``None``.
+
+    Returns:
+        Combined binary mask as an ``int8`` tensor, or ``None`` if both inputs
+        are ``None``.
+    """
     if source_mask is None:
         return target_mask
     if target_mask is None:
@@ -177,14 +232,43 @@ def overlap_mask(source_mask: Tensor | None, target_mask: Tensor | None) -> Tens
     return mask
 
 
-def make_foreground_mask(image: Image, foreground_lower_threshold, foreground_upper_threshold):
+def make_foreground_mask(image: Image, foreground_lower_threshold: float, foreground_upper_threshold: float) -> Image:
+    """Create a binary foreground mask by thresholding image intensities.
+
+    Args:
+        image: Source deepali ``Image``.
+        foreground_lower_threshold: Minimum intensity value considered foreground.
+        foreground_upper_threshold: Maximum intensity value considered foreground.
+
+    Returns:
+        A deepali ``Image`` of dtype ``int8`` with 1 where the intensity is
+        within [*foreground_lower_threshold*, *foreground_upper_threshold*] and
+        0 elsewhere.
+    """
     data = image.tensor()
     mask = U.threshold(data, foreground_lower_threshold, foreground_upper_threshold).type(torch.int8)
     # data = torch.cat([data, mask.type(data.dtype)], dim=0)
     return Image(mask, image.grid())
 
 
-def normalize_img(image: Image, normalize_strategy: Literal["auto", "CT", "MRI"] | None):
+def normalize_img(image: Image, normalize_strategy: Literal["auto", "CT", "MRI"] | None) -> Image:
+    """Normalise image intensities to the [0, 1] range.
+
+    Args:
+        image: Source deepali ``Image`` to normalise.
+        normalize_strategy: Normalisation strategy to apply.
+
+            - ``None``: Return the image unchanged.
+            - ``"auto"``: Shift/scale by the observed min and max.
+            - ``"CT"``: Clamp and scale within [-500, 500] HU.
+            - ``"MRI"``: Scale by the 95th percentile of positive voxels.
+
+    Returns:
+        Normalised deepali ``Image`` (same grid, intensity values in [0, 1]).
+
+    Raises:
+        NotImplementedError: If *normalize_strategy* is an unrecognised string.
+    """
     if normalize_strategy is None:
         return image
     data = image.tensor()
@@ -211,7 +295,16 @@ def normalize_img(image: Image, normalize_strategy: Literal["auto", "CT", "MRI"]
     return Image(data, image.grid())
 
 
-def clamp_mask(image: Image | None):
+def clamp_mask(image: Image | None) -> Image | None:
+    """Clamp mask values in-place to the [0, 1] range.
+
+    Args:
+        image: Deepali ``Image`` whose tensor is clamped, or ``None``.
+
+    Returns:
+        The same image object with values clamped to [0, 1], or ``None`` if the
+        input was ``None``.
+    """
     if image is None:
         return image
     data = image.tensor()
@@ -220,7 +313,12 @@ def clamp_mask(image: Image | None):
 
 
 def print_pyramid_info(pyramid: dict[int, Image]) -> None:
-    r"""Print information of image resolution pyramid."""
+    """Print size, origin, extent, and domain info for each level of an image pyramid.
+
+    Args:
+        pyramid: Mapping from pyramid level index to deepali ``Image`` objects.
+            Level 0 is typically the finest resolution.
+    """
     levels = sorted(pyramid.keys())
     for level in reversed(levels):
         grid = pyramid[level].grid()
@@ -259,7 +357,27 @@ def new_loss(
     return cls(*args, **kwargs)  # type: ignore
 
 
-def parse_loss(loss_terms, weights):
+def parse_loss(loss_terms: list | dict, weights: list | dict | None) -> tuple[dict, dict]:
+    """Normalise loss-term and weight specifications to a pair of dictionaries.
+
+    Accepts flexible input formats (lists of loss instances or strings, dicts
+    mapping name to loss or to ``(name, args)`` tuples) and returns a
+    standardised mapping from term name to loss module and from term name to
+    per-pyramid-level weight.
+
+    Args:
+        loss_terms: Loss specification as a list of loss objects / names, or a
+            dict mapping term names to loss objects, name strings, or
+            ``(name, args)`` / ``(name, args, kwargs)`` tuples.
+        weights: Corresponding weights.  When *loss_terms* is a list this should
+            also be a list.  When it is a dict this should be a matching dict.
+            ``None`` defaults to equal weights of 1.
+
+    Returns:
+        A 2-tuple ``(loss_terms, weights)`` where both are plain dictionaries
+        keyed by term name and the values in *weights* are scalars or
+        reversed-order per-pyramid-level lists.
+    """
     if isinstance(loss_terms, Sequence):
         if weights is None:
             weights = {}
diff --git a/TPTBox/registration/_deepali/deepali_model.py b/TPTBox/registration/_deepali/deepali_model.py
index b535aa3..4646179 100644
--- a/TPTBox/registration/_deepali/deepali_model.py
+++ b/TPTBox/registration/_deepali/deepali_model.py
@@ -29,13 +29,24 @@
 )
 
 
-def center_of_mass(tensor):
+def center_of_mass(tensor: torch.Tensor) -> torch.Tensor:
+    """Compute the centre of mass of a tensor along all dimensions.
+
+    Args:
+        tensor: Input tensor with non-negative values (e.g. a probability map).
+
+    Returns:
+        1-D tensor of length ``tensor.ndim`` containing the weighted-mean index
+        along each dimension.
+    """
     grid = torch.meshgrid([torch.arange(s, device=tensor.device) for s in tensor.shape], indexing="ij")
     com = torch.stack([(tensor * g).sum() / tensor.sum() for g in grid])
     return com
 
 
 def time_it(func):
+    """Decorator that prints the wall-clock execution time of the wrapped function."""
+
     def wrapper(*args, **kwargs):
         start_time = time.time()
         result = func(*args, **kwargs)
@@ -46,8 +57,17 @@ def wrapper(*args, **kwargs):
     return wrapper
 
 
-def _load_config(path):
-    r"""Load registration parameters from configuration file."""
+def _load_config(path: str | Path) -> dict:
+    """Load registration parameters from a JSON or YAML configuration file.
+
+    Args:
+        path: Absolute or relative path to the configuration file.  Files with
+            a ``.json`` suffix are parsed as JSON; all other suffixes are
+            treated as YAML.
+
+    Returns:
+        Parsed configuration as a Python dictionary.
+    """
     config_path = Path(path).absolute()
     config_text = config_path.read_text()
     if config_path.suffix == ".json":
@@ -62,10 +82,23 @@ def _warp_image(
     source_image: deepaliImage,
     target_grid: Deepali_Grid,
     transform: SpatialTransform,
-    mode="linear",
-    device=default_device,
-    inverse=False,
+    mode: str = "linear",
+    device: torch.device = default_device,
+    inverse: bool = False,
 ) -> torch.Tensor:
+    """Warp a source image to the target grid using the given spatial transform.
+
+    Args:
+        source_image: Deepali ``Image`` to be warped.
+        target_grid: Target grid defining the output spatial domain.
+        transform: Fitted deepali ``SpatialTransform``.
+        mode: Interpolation mode (``"linear"`` or ``"nearest"``).
+        device: PyTorch device on which warping is performed.
+        inverse: Apply the inverse transform when ``True``.
+
+    Returns:
+        Warped image data as a ``torch.Tensor``.
+    """
     if inverse:
         transform = transform.inverse(update_buffers=True)
     warp_func = TransformImage(
@@ -83,10 +116,27 @@ def _warp_poi(
     poi_moving: POI,
     target_grid: TPTBox_Grid,
     transform: SpatialTransform,
-    align_corners,
-    device=default_device,
-    inverse=True,
+    align_corners: bool,
+    device: torch.device = default_device,
+    inverse: bool = True,
 ) -> POI:
+    """Apply a spatial transform to all centroids in a POI object.
+
+    Args:
+        poi_moving: Source ``POI`` whose centroid coordinates (voxel space) are
+            to be transformed.
+        target_grid: Output grid that defines the coordinate space of the returned
+            ``POI``.
+        transform: Fitted deepali ``SpatialTransform``.
+        align_corners: Whether voxel corners (``True``) or centres (``False``) are
+            aligned when converting between grid and world coordinates.
+        device: PyTorch device for computation.
+        inverse: Apply the inverse transform when ``True`` (default).
+
+    Returns:
+        A new ``POI`` object defined on *target_grid* with transformed centroid
+        coordinates.
+    """
     keys: list[tuple[int, int]] = []
     points = []
     for key, key2, (x, y, z) in poi_moving.items():
@@ -124,8 +174,8 @@ def _warp_points(
     device=default_device,
     inverse=True,
 ) -> torch.Tensor:
-    """
-    Warp points using a spatial transform.
+    """Warp points using a spatial transform.
+
     Args:
         points (list): List of points to warp: (b,n) b points with n coordinates.
         transform (SpatialTransform): Spatial transform to apply.
@@ -145,8 +195,7 @@ def _warp_points(
 
 
 class General_Registration(DeepaliPairwiseImageTrainer):
-    """
-    A class for performing deformable registration between a fixed and moving image.
+    """A class for performing deformable registration between a fixed and moving image.
 
     Attributes:
         transform (torch.Tensor): The transformation matrix resulting from the registration.
@@ -295,8 +344,7 @@ def __init__(
     #        # )
     #    return data.clone()
     def inverse(self) -> Self:
-        """
-        Invert the registration transformation.
+        """Invert the registration transformation.
 
         Returns:
             Self: The instance with the inverted transformation.
@@ -389,8 +437,7 @@ def transform_nii(
         align_corners=True,
         inverse=False,
     ) -> NII:
-        """
-        Apply the computed transformation to a given NII image.
+        """Apply the computed transformation to a given NII image.
 
         Args:
             img (NII): The NII image to be transformed.
@@ -421,9 +468,22 @@ def transform_poi(
         poi: POI,
         gpu: int | None = None,
         ddevice: DEVICES | None = None,
-        align_corners=True,
-        inverse=True,
-    ):
+        align_corners: bool = True,
+        inverse: bool = True,
+    ) -> POI:
+        """Apply the computed registration to a POI object.
+
+        Args:
+            poi: Source ``POI`` with centroid coordinates to transform.
+            gpu: GPU index override. Defaults to the device used during registration.
+            ddevice: Device type override (e.g. ``"cuda"``).
+            align_corners: Whether corners or centres are aligned during warping.
+            inverse: Apply the inverse transform when ``True`` (default, maps
+                moving centroids to fixed space).
+
+        Returns:
+            A new ``POI`` resampled to the target grid with transformed coordinates.
+        """
         if self._is_inverted:
             inverse = not inverse
         device = get_device(ddevice, 0 if gpu is None else gpu) if ddevice is not None else self.device
@@ -449,8 +509,8 @@ def transform_points(
         ddevice: DEVICES | None = None,
         inverse=True,
     ):
-        """
-        Transform a set of points using the registered transformation.
+        """Transform a set of points using the registered transformation.
+
         Args:
             points (list): List of points to warp: (b,n) b points with n coordinates.
             axes (Axes): Axes of the input points.
@@ -461,7 +521,6 @@ def transform_points(
             ddevice (DEVICES, optional): Device type. Defaults to "cuda".
             inverse (bool, optional): Whether to apply the inverse transformation. Defaults to True.
         """
-
         if self._is_inverted:
             inverse = not inverse
         if isinstance(grid, Has_Grid):
@@ -481,8 +540,7 @@ def transform_points(
         )
 
     def __call__(self, *args, **kwds) -> NII:
-        """
-        Call method to apply the transformation using the transform_nii method.
+        """Call method to apply the transformation using the transform_nii method.
 
         Args:
             *args: Positional arguments for the transform_nii method.
@@ -493,20 +551,50 @@ def __call__(self, *args, **kwds) -> NII:
         """
         return self.transform_nii(*args, **kwds)
 
-    def get_dump(self):
+    def get_dump(self) -> tuple:
+        """Return a serialisable tuple of the registration state for pickling.
+
+        Returns:
+            Tuple of ``(transform, target_grid, input_grid, _is_inverted)``.
+        """
         return (self.transform, self.target_grid, self.input_grid, self._is_inverted)
 
-    def save(self, path: str | Path):
+    def save(self, path: str | Path) -> None:
+        """Serialise the registration result to a pickle file.
+
+        Args:
+            path: Destination file path.
+        """
         with open(path, "wb") as w:
             pickle.dump(self.get_dump(), w)
 
     @classmethod
-    def load(cls, path, gpu=0, ddevice: DEVICES = "cuda"):
+    def load(cls, path: str | Path, gpu: int = 0, ddevice: DEVICES = "cuda") -> Self:
+        """Load a previously saved ``General_Registration`` from a pickle file.
+
+        Args:
+            path: Path to the pickle file written by :meth:`save`.
+            gpu: GPU index to map the transform to.
+            ddevice: Device type (e.g. ``"cuda"`` or ``"cpu"``).
+
+        Returns:
+            Reconstructed ``General_Registration`` instance.
+        """
         with open(path, "rb") as w:
             return cls.load_(pickle.load(w), gpu, ddevice)
 
     @classmethod
-    def load_(cls, w, gpu=0, ddevice: DEVICES = "cuda") -> Self:
+    def load_(cls, w: tuple, gpu: int = 0, ddevice: DEVICES = "cuda") -> Self:
+        """Reconstruct a ``General_Registration`` from a raw dump tuple.
+
+        Args:
+            w: Tuple as returned by :meth:`get_dump`.
+            gpu: GPU index for device placement.
+            ddevice: Device type string.
+
+        Returns:
+            Reconstructed ``General_Registration`` instance.
+        """
         transform, grid, mov, _is_inverted = w
         self = cls.__new__(cls)
         self.transform = transform
diff --git a/TPTBox/registration/_deepali/deepali_trainer.py b/TPTBox/registration/_deepali/deepali_trainer.py
index 8a44f05..d774986 100644
--- a/TPTBox/registration/_deepali/deepali_trainer.py
+++ b/TPTBox/registration/_deepali/deepali_trainer.py
@@ -109,8 +109,7 @@ def __init__(
         loss_terms: list[LOSS | str] | dict[str, LOSS] | dict[str, str] | dict[str, tuple[str, dict]] | None = None,
         weights: list[float] | dict[str, float | list[float]] | dict[str, list[float]] | None = None,
     ) -> None:
-        """
-        Initializes the DeepaliPairwiseImageTrainer for pairwise image registration.
+        """Initializes the DeepaliPairwiseImageTrainer for pairwise image registration.
 
         Args:
             source (Union[Image, PathStr]): The source image or file path.
diff --git a/TPTBox/registration/_deepali/spine_rigid_elements_reg.py b/TPTBox/registration/_deepali/spine_rigid_elements_reg.py
index 5c5f81e..e222501 100644
--- a/TPTBox/registration/_deepali/spine_rigid_elements_reg.py
+++ b/TPTBox/registration/_deepali/spine_rigid_elements_reg.py
@@ -24,7 +24,18 @@
 from TPTBox.registration._ridged_points import Point_Registration
 
 
-def not_exist_or_is_younger_than(path: Path | str, other_path: Path | str | None):
+def not_exist_or_is_younger_than(path: Path | str, other_path: Path | str | None) -> bool:
+    """Check whether *path* does not exist or was modified before *other_path*.
+
+    Args:
+        path: File path to test.
+        other_path: Reference file path for modification-time comparison, or
+            ``None`` to always return ``True`` when *path* does not exist.
+
+    Returns:
+        ``True`` if *path* does not exist, *other_path* is ``None``, or *path*
+        has an older modification time than *other_path``.  ``False`` otherwise.
+    """
     path = Path(path)
     if not path.exists():
         return True
@@ -35,7 +46,23 @@ def not_exist_or_is_younger_than(path: Path | str, other_path: Path | str | None
     return fileCreation < fileCreation_ref
 
 
-def _load_poi(fixed_poi_file, vert: NII, subreg: NII, save_pois):
+def _load_poi(fixed_poi_file: Path | None, vert: NII, subreg: NII, save_pois: bool) -> POI:
+    """Load or compute a POI object for a vertebra segmentation.
+
+    If *fixed_poi_file* is provided, that POI is loaded from disk (and its
+    affine is validated against *vert*).  The corpus, spinous process, and arcus
+    centroids are always (re-)computed from *vert* and *subreg* using
+    :func:`calc_poi_from_subreg_vert`, with the loaded file used as a buffer.
+
+    Args:
+        fixed_poi_file: Optional path to a pre-computed POI file.
+        vert: Vertebra segmentation ``NII``.
+        subreg: Subregion segmentation ``NII``.
+        save_pois: Save the computed POI to *fixed_poi_file* when ``True``.
+
+    Returns:
+        Computed ``POI`` object with corpus, spinous-process, and arcus centroids.
+    """
     buffer_file = None
     if fixed_poi_file is not None:
         poi = POI.load(fixed_poi_file)
@@ -51,11 +78,35 @@ def _load_poi(fixed_poi_file, vert: NII, subreg: NII, save_pois):
     return poi_ct
 
 
-def compute_distance(array, background: np.ndarray | int = 0, i=0) -> np.ndarray:
+def compute_distance(array: np.ndarray, background: np.ndarray | int = 0, i: int = 0) -> np.ndarray:
+    """Compute the Euclidean distance transform for label *i* excluding background.
+
+    Args:
+        array: Label array whose distance transform is computed.
+        background: Background mask; voxels where this equals 0 are excluded from
+            the distance computation.
+        i: Label value in *array* to treat as the foreground seed.
+
+    Returns:
+        Distance transform array of the same shape as *array*.
+    """
     return distance_transform_edt(np.logical_and(array == i, background == 0))  # type: ignore
 
 
-def compute_distance_cord(segmentation, query_coords, i=0):
+def compute_distance_cord(segmentation: np.ndarray, query_coords: np.ndarray, i: int = 0) -> np.ndarray:
+    """Compute the distance from each query coordinate to the nearest voxel of label *i*.
+
+    Uses a KD-tree for efficient nearest-neighbour lookup.
+
+    Args:
+        segmentation: Label array.
+        query_coords: Array of shape ``(N, ndim)`` with query coordinate positions.
+        i: Label value whose foreground voxels form the reference set.
+
+    Returns:
+        1-D array of length ``N`` with the distance from each query coordinate to
+        the nearest voxel labelled *i*.
+    """
     # List of (y, x) coordinates where we want distances & segmentation lookup
     # query_coords = np.array([(0.5, 0.5), (1.7, 3.2), (2.3, 2.3)])
 
@@ -69,6 +120,53 @@ def compute_distance_cord(segmentation, query_coords, i=0):
 
 
 class Rigid_Elements_Registration:
+    """Per-vertebra rigid registration using DeepALI.
+
+    Performs a two-stage spine registration pipeline:
+
+    1. Point-based pre-alignment using vertebra centroids (``Point_Registration``).
+    2. Per-element (per-vertebra) rigid intensity registration via
+       ``Rigid_Registration_with_Tether``.
+
+    A weighted-blending field is then computed from the individual vertebra
+    transformations using an inverse-distance weighting scheme and exposed
+    through :meth:`transform_nii` and :meth:`compute_weightings`.
+
+    Args:
+        fixed_image: Fixed (reference) image.
+        fixed_vert: Vertebra segmentation aligned to *fixed_image*.
+        fixed_subreg: Subregion segmentation aligned to *fixed_image*.
+        moving_image: Moving image to be registered.
+        moving_vert: Vertebra segmentation aligned to *moving_image*.
+        moving_subreg: Subregion segmentation aligned to *moving_image*.
+        fixed_poi: Optional path to a pre-computed fixed POI file.
+        moving_poi: Optional path to a pre-computed moving POI file.
+        crop_to_FOV: Crop images to the moving-image field of view when ``True``.
+        save_pois: Save computed POI files to disk when ``True``.
+        reference_image: Optional reference grid; defaults to *fixed_vert*.
+        device: PyTorch device; inferred from *ddevice*/*gpu* when ``None``.
+        gpu: GPU index used when *device* is ``None``.
+        ddevice: Device type string (e.g. ``"cuda"``).
+        pyramid_levels: Number of multi-resolution pyramid levels (``None`` = 1).
+        finest_level: Index of the finest pyramid level.
+        coarsest_level: Index of the coarsest pyramid level.
+        pyramid_finest_spacing: Target voxel spacing at the finest pyramid level.
+        pyramid_min_size: Minimum spatial extent per level.
+        dims: Spatial axes to optimise (default all three).
+        align: Pre-align grids before optimisation.
+        optim_name: Name of a ``torch.optim`` optimiser class.
+        lr: Optimiser learning rate.
+        optim_args: Additional optimiser keyword arguments (without ``lr``).
+        verbose: Verbosity level for progress output.
+        max_steps: Maximum number of optimisation steps per level.
+        max_history: Window size for convergence monitoring.
+        weights: Loss term weights.
+        patience: Early-stopping patience (number of steps without improvement).
+        patience_delta: Minimum loss improvement to reset patience.
+        my: Exponent for the inverse-distance weighting scheme (default 1.5).
+        orientation: Reorient all inputs to this orientation before registration.
+    """
+
     def __init__(
         self,
         fixed_image: Image_Reference,
@@ -161,7 +259,8 @@ def _resample_and_preReg(
         crop_to_FOV: bool,
         save_pois: bool,
         orientation,
-    ):
+    ) -> None:
+        """Load inputs, compute POIs, apply point-registration, and crop to FOV."""
         # Load
         # fixed_image = to_nii(fixed_image_)
         fixed_vert = to_nii(fixed_vert_, True)
@@ -240,19 +339,20 @@ def _run_rigid_reg(
         finest_level: int = 0,
         coarsest_level: int | None = None,
         pyramid_finest_spacing: Sequence[int] | torch.Tensor | None = None,
-        pyramid_min_size=16,
+        pyramid_min_size: int = 16,
         dims=("x", "y", "z"),
-        align=False,
-        optim_name="Adam",  # Optimizer name defined in torch.optim. or override on_optimizer finer control
-        lr=0.01,  # Learning rate
+        align: bool = False,
+        optim_name: str = "Adam",  # Optimizer name defined in torch.optim. or override on_optimizer finer control
+        lr: float = 0.01,  # Learning rate
         optim_args=None,  # args of Optimizer with out lr
-        verbose=99,
+        verbose: int = 99,
         max_steps: int | Sequence[int] = 10000,  # Early stopping.  override on_converged finer control
         max_history: int | None = None,
         weights: list[float] | None = None,
-        patience=100,
-        patience_delta=0.0,
-    ):
+        patience: int = 100,
+        patience_delta: float = 0.0,
+    ) -> None:
+        """Run per-vertebra rigid registration and store the fitted models."""
         self._rigid_registrations: list[Rigid_Registration_with_Tether] = []
         self._ids = []
         ids_fixed = self.fixed_vert.unique()
@@ -297,11 +397,34 @@ def _run_rigid_reg(
             self._ids.append(idx)
 
     @torch.no_grad()
-    def compute_weightings(self, my: float | None = None, coords: np.ndarray | None = None, device=None, align_corners=True):
-        """
-        weighting schema from https://www.sciencedirect.com/science/article/pii/S1077314297906081?ref=cra_js_challenge&fr=RR-1
-        if coords is None:
-            use ref image
+    def compute_weightings(
+        self,
+        my: float | None = None,
+        coords: np.ndarray | None = None,
+        device: torch.device | None = None,
+        align_corners: bool = True,
+    ) -> torch.Tensor:
+        """Compute the inverse-distance weighted blending field across all vertebrae.
+
+        Implements the weighting scheme from
+        https://www.sciencedirect.com/science/article/pii/S1077314297906081
+
+        Each vertebra's rigid transformation is blended using inverse-distance
+        weights computed from the Euclidean distance to the vertebra label.
+        Voxels inside a label are assigned weight 1 for their own vertebra and 0
+        for all others.
+
+        Args:
+            my: Exponent for the inverse-distance weighting (defaults to
+                ``self.my``).
+            coords: Optional array of query coordinates (shape ``(N, 3)``).
+                When ``None``, the full reference-image grid is used.
+            device: PyTorch device for computation; defaults to ``self.device``.
+            align_corners: Whether corners are aligned in grid-to-world mapping.
+
+        Returns:
+            Blended displacement field as a ``torch.Tensor`` containing the
+            weighted sum of per-vertebra transformed grid points.
         """
         if my is None:
             my = self.my
@@ -371,8 +494,30 @@ def compute_weightings(self, my: float | None = None, coords: np.ndarray | None
 
     @torch.no_grad()
     def transform_nii(
-        self, img: NII, gpu: int | None = None, ddevice: DEVICES | None = None, align_corners=True, padding=PaddingMode.ZEROS
+        self,
+        img: NII,
+        gpu: int | None = None,
+        ddevice: DEVICES | None = None,
+        align_corners: bool = True,
+        padding: PaddingMode = PaddingMode.ZEROS,
     ) -> NII:
+        """Apply the blended rigid warp to an arbitrary NII image.
+
+        The moving image is first pre-aligned via ``Point_Registration``, then
+        cropped to the field of view, and finally warped using the blended
+        displacement field stored in ``self.y_total``.
+
+        Args:
+            img: Input ``NII`` to transform (may be a different modality from
+                those used during registration).
+            gpu: GPU index override.
+            ddevice: Device type override.
+            align_corners: Whether corners are aligned during warping.
+            padding: Padding mode used outside the source image bounds.
+
+        Returns:
+            Transformed ``NII`` resampled to the reference grid.
+        """
         device = get_device(ddevice, 0 if gpu is None else gpu) if ddevice is not None else self.device
         if self.orientation:
             img = img.reorient(self.orientation)
@@ -391,7 +536,21 @@ def transform_nii(
         moved_data = np.transpose(moved_data.detach().cpu().numpy(), axes=tuple(reversed(range(moved_data.ndim)))).squeeze()
         return self.ref.make_empty_nii(img.seg, moved_data)
 
-    def transform_poi(self, poi: POI, gpu: int | None = None, ddevice: DEVICES | None = None, align_corners=True):
+    def transform_poi(self, poi: POI, gpu: int | None = None, ddevice: DEVICES | None = None, align_corners: bool = True) -> POI:
+        """Apply the blended rigid warp to a POI object (not yet tested).
+
+        Args:
+            poi: Input ``POI`` whose centroids are to be transformed.
+            gpu: GPU index override.
+            ddevice: Device type override.
+            align_corners: Whether corners are aligned during warping.
+
+        Returns:
+            Transformed ``POI`` on the reference grid.
+
+        Raises:
+            NotImplementedError: This method has not been validated yet.
+        """
         raise NotImplementedError("transform_poi is not tested")
         device = get_device(ddevice, 0 if gpu is None else gpu) if ddevice is not None else self.device
         # POINT REG
@@ -412,22 +571,51 @@ def transform_poi(self, poi: POI, gpu: int | None = None, ddevice: DEVICES | Non
         return out_poi
 
     def __call__(self, *args, **kwds) -> NII:
+        """Apply the registration by calling :meth:`transform_nii`."""
         return self.transform_nii(*args, **kwds)
 
-    def get_dump(self):
+    def get_dump(self) -> None:
+        """Return a serialisable representation of the registration (not implemented).
+
+        Raises:
+            NotImplementedError: Serialisation is not yet supported.
+        """
         raise NotImplementedError("transform_poi is not tested")
 
-    def save(self, path: str | Path):
+    def save(self, path: str | Path) -> None:
+        """Serialise the registration to a pickle file (not implemented).
+
+        Args:
+            path: Destination file path.
+
+        Raises:
+            NotImplementedError: Serialisation is not yet supported.
+        """
         with open(path, "wb") as w:
             pickle.dump(self.get_dump(), w)
 
     @classmethod
-    def load(cls, path, gpu=0, ddevice: DEVICES = "cuda"):
+    def load(cls, path: str | Path, gpu: int = 0, ddevice: DEVICES = "cuda"):
+        """Load a saved registration from a pickle file (not implemented).
+
+        Args:
+            path: Path to the pickle file.
+            gpu: GPU index.
+            ddevice: Device type string.
+
+        Raises:
+            NotImplementedError: Deserialisation is not yet supported.
+        """
         with open(path, "rb") as w:
             return cls.load_(pickle.load(w), gpu, ddevice)
 
     @classmethod
-    def load_(cls, w, gpu=0, ddevice: DEVICES = "cuda"):
+    def load_(cls, w, gpu: int = 0, ddevice: DEVICES = "cuda"):
+        """Reconstruct from a raw dump tuple (not implemented).
+
+        Raises:
+            NotImplementedError: Deserialisation is not yet supported.
+        """
         raise NotImplementedError("transform_poi is not tested")
 
 
diff --git a/TPTBox/registration/_deformable/_deepali/metrics.py b/TPTBox/registration/_deformable/_deepali/metrics.py
index dacc00b..cf1af84 100644
--- a/TPTBox/registration/_deformable/_deepali/metrics.py
+++ b/TPTBox/registration/_deformable/_deepali/metrics.py
@@ -87,10 +87,9 @@ def gaussian_window(x, bins, sigma):
 
 
 def calculate_dice(mask1, mask2, label_class=0):
-    """
-    from https://github.com/voxelmorph/
-    Dice score of a specified class between two label masks.
-    (classes are encoded but by label class number not one-hot )
+    """Compute the Dice score for a specified class between two label masks.
+
+    From https://github.com/voxelmorph/. Classes are encoded by label number, not one-hot.
 
     Args:
         mask1: (numpy.array, shape (N, 1, *sizes)) segmentation mask 1
@@ -116,9 +115,9 @@ def dice(a, b, label):
 
 
 def calculate_jacobian_metrics(disp):
-    """
-    Calculate Jacobian related regularity metrics.
-    from https://github.com/voxelmorph/
+    """Calculate Jacobian-based regularity metrics (folding ratio and gradient magnitude).
+
+    From https://github.com/voxelmorph/.
 
     Args:
         disp: (numpy.ndarray, shape (N, ndim, *sizes) Displacement field
@@ -138,9 +137,9 @@ def calculate_jacobian_metrics(disp):
 
 
 def calculate_jacobian_det(disp):
-    """
-    Calculate Jacobian determinant of displacement field of one image/volume (2D/3D)
-    from https://github.com/voxelmorph/
+    """Calculate the Jacobian determinant of a displacement field (2D or 3D).
+
+    From https://github.com/voxelmorph/.
 
     Args:
         disp: (numpy.ndarray, shape (*sizes, ndim)) Displacement field
diff --git a/TPTBox/registration/_deformable/_deepali/optim.py b/TPTBox/registration/_deformable/_deepali/optim.py
index 790254b..d3b0106 100644
--- a/TPTBox/registration/_deformable/_deepali/optim.py
+++ b/TPTBox/registration/_deformable/_deepali/optim.py
@@ -30,9 +30,9 @@ def new_optimizer(name: str, model: Module, **kwargs) -> Optimizer:
 
 
 def slope_of_least_squares_fit(values: Sequence[float]) -> float:
-    r"""Compute slope of least squares fit of line to last n objective function values
+    r"""Compute slope of least squares fit of line to last n objective function values.
 
-    See also:
+    See Also:
     - https://www.che.udel.edu/pdf/FittingData.pdf
     - https://en.wikipedia.org/wiki/1_%2B_2_%2B_3_%2B_4_%2B_%E2%8B%AF
     - https://proofwiki.org/wiki/Sum_of_Sequence_of_Squares
diff --git a/TPTBox/registration/_deformable/_grid_search_vert.py b/TPTBox/registration/_deformable/_grid_search_vert.py
index 27fc7f6..6815ce6 100644
--- a/TPTBox/registration/_deformable/_grid_search_vert.py
+++ b/TPTBox/registration/_deformable/_grid_search_vert.py
@@ -55,7 +55,7 @@ def main_vert_test():
 
 
 def get_femurs(img: Image_Reference, seg_id=13):
-    """Returns left (2) and right (1)
+    """Returns left (2) and right (1).
 
     Args:
         img (Image_Reference): _description_
diff --git a/TPTBox/registration/_deformable/deformable_reg.py b/TPTBox/registration/_deformable/deformable_reg.py
index f21dbdd..b0bebd0 100644
--- a/TPTBox/registration/_deformable/deformable_reg.py
+++ b/TPTBox/registration/_deformable/deformable_reg.py
@@ -18,14 +18,16 @@
 
 
 class Deformable_Registration(General_Registration):
-    """
-    A class for performing deformable registration between a fixed and moving image.
+    """Deformable registration between a fixed and moving image using deepali.
+
+    Wraps ``General_Registration`` with default loss terms (LNCC + BSpline bending
+    energy) and a Stationary Velocity Field Free-Form Deformation (SVFFD) transform.
 
     Attributes:
-        transform (torch.Tensor): The transformation matrix resulting from the registration.
-        ref_nii (NII): Reference NII object used for registration.
-        grid (torch.Tensor): Target grid for image warping.
-        mov (NII): Processed version of the moving image.
+        transform: The learned deformation field resulting from the registration.
+        ref_nii: Reference NII object used for registration.
+        grid: Target grid for image warping.
+        mov: Processed version of the moving image.
     """
 
     def __init__(
@@ -137,10 +139,7 @@ def __init__(
 
 
 def test1(run=False):
-    """
-    Main function to test the deformable registration process.
-    Loads reference and moving images, performs registration, and saves the output.
-    """
+    """Test deformable registration by loading reference and moving images, registering, and saving output."""
     from TPTBox import NII
 
     fixed = NII.load(
@@ -182,10 +181,7 @@ def test1(run=False):
 
 
 def test2(run=False):
-    """
-    Main function to test the deformable registration process.
-    Loads reference and moving images, performs registration, and saves the output.
-    """
+    """Test deformable registration by loading reference and moving images, registering, and saving output."""
     from TPTBox import NII
 
     # ref = NII.load("/media/data/robert/code/TPTBox/tmp/sub-100000_sequ-stitched_acq-ax_part-water_vibe.nii.gz", False)
diff --git a/TPTBox/registration/_deformable/deformable_reg_old.py b/TPTBox/registration/_deformable/deformable_reg_old.py
index 1489653..e0ed05d 100644
--- a/TPTBox/registration/_deformable/deformable_reg_old.py
+++ b/TPTBox/registration/_deformable/deformable_reg_old.py
@@ -82,8 +82,8 @@ def _warp_poi(
 
 
 class Deformable_Registration:
-    """
-    A class for performing deformable registration between a fixed and moving image.
+    """A class for performing deformable registration between a fixed and moving image.
+
     Attributes:
         transform (torch.Tensor): The transformation matrix resulting from the registration.
         ref_nii (NII): Reference NII object used for registration.
@@ -107,8 +107,8 @@ def __init__(
         gpu=0,
         ddevice: DEVICES = "cuda",
     ) -> None:
-        """
-        Initialize the deformable registration process.
+        """Initialize the deformable registration process.
+
         Args:
             fixed_image (Image_Reference): The fixed image to which the moving image is registered.
             moving_image (Image_Reference): The moving image to be registered.
@@ -172,10 +172,11 @@ def __init__(
 
     @torch.no_grad()
     def transform_nii(self, img: NII, gpu: int | None = None, ddevice: DEVICES | None = None, target: Has_Grid | None = None) -> NII:
-        """
-        Apply the computed transformation to a given NII image.
+        """Apply the computed transformation to a given NII image.
+
         Args:
             img (NII): The NII image to be transformed.
+
         Returns:
             NII: The transformed image as an NII object.
         """
@@ -212,11 +213,12 @@ def transform_poi(
         return data.resample_from_to(self.target_grid)
 
     def __call__(self, *args, **kwds) -> NII:
-        """
-        Call method to apply the transformation using the transform_nii method.
+        """Call method to apply the transformation using the transform_nii method.
+
         Args:
             *args: Positional arguments for the transform_nii method.
             **kwds: Keyword arguments for the transform_nii method.
+
         Returns:
             NII: The transformed image.
         """
@@ -248,10 +250,7 @@ def load_(cls, w, gpu=0, ddevice: DEVICES = "cuda"):
 
 
 def test1(run=False):
-    """
-    Main function to test the deformable registration process.
-    Loads reference and moving images, performs registration, and saves the output.
-    """
+    """Test deformable registration: load reference and moving images, register, and save output."""
     from TPTBox import NII
 
     fixed = NII.load(
@@ -293,10 +292,7 @@ def test1(run=False):
 
 
 def test2(run=False):
-    """
-    Main function to test the deformable registration process.
-    Loads reference and moving images, performs registration, and saves the output.
-    """
+    """Test deformable registration: load reference and moving images, register, and save output."""
     from TPTBox import NII
 
     # ref = NII.load("/media/data/robert/code/TPTBox/tmp/sub-100000_sequ-stitched_acq-ax_part-water_vibe.nii.gz", False)
diff --git a/TPTBox/registration/_deformable/grid_search.py b/TPTBox/registration/_deformable/grid_search.py
index 418679e..1f2526e 100644
--- a/TPTBox/registration/_deformable/grid_search.py
+++ b/TPTBox/registration/_deformable/grid_search.py
@@ -44,7 +44,13 @@ class Example:
     outfolder: Path
 
 
-def set_seed(seed):
+def set_seed(seed: int) -> None:
+    """Fix random seeds for reproducible registration experiments.
+
+    Args:
+        seed: Integer seed applied to PyTorch (CPU + CUDA), NumPy, and Python's
+            ``random`` module; also forces cuDNN into deterministic mode.
+    """
     torch.manual_seed(seed)
     torch.cuda.manual_seed(seed)
     np.random.seed(seed)
@@ -53,7 +59,19 @@ def set_seed(seed):
     torch.backends.cudnn.benchmark = False
 
 
-def update_config(config, loss, be, stride, lr):
+def update_config(config: dict, loss: str, be: float, stride: int, lr: float) -> dict:
+    """Patch a deformable registration config dict with the given hyper-parameters.
+
+    Args:
+        config: Base configuration dictionary loaded from a JSON settings file.
+        loss: Name of the image similarity loss term (e.g. ``"LNCC"``).
+        be: Weight for the BSpline bending energy regularisation term.
+        stride: Control-point stride for the deformation field.
+        lr: Optimiser learning rate.
+
+    Returns:
+        The updated configuration dictionary (mutated in place and returned).
+    """
     config["loss"]["config"]["seg"]["name"] = loss
     config["loss"]["weights"]["be"] = be
     config["model"]["args"]["stride"] = stride
@@ -62,7 +80,30 @@ def update_config(config, loss, be, stride, lr):
 
 
 @torch.no_grad()
-def pairwise(fixed, warped, fixed_seg, warped_seg, transform):
+def pairwise(
+    fixed: Image,
+    warped: Image,
+    fixed_seg: Image | None,
+    warped_seg: Image | None,
+    transform: Tensor,
+) -> dict:
+    """Compute pairwise image quality and deformation metrics between two images.
+
+    Evaluates PSNR, SSIM, NMI, Jacobian determinant statistics, and per-label
+    Dice scores (when segmentations are provided).
+
+    Args:
+        fixed: Fixed reference image (deepali ``Image``).
+        warped: Warped moving image aligned to *fixed*.
+        fixed_seg: Segmentation mask of the fixed image, or None.
+        warped_seg: Segmentation mask of the warped moving image, or None.
+        transform: Deformation field tensor used to compute Jacobian metrics.
+
+    Returns:
+        Dictionary with keys ``"psnr"``, ``"ssim"``, ``"nmi"``,
+        ``"folding_ratio"``, ``"jacobian"``, ``"dice scores"``, and
+        ``"avg_dice"``.
+    """
     # print(fixed.shape, warped.shape, fixed_seg.shape, warped_seg.shape)
     # print(type(fixed), type(warped), type(fixed_seg), type(warped_seg))
     fixed = np.expand_dims(fixed.numpy(), 0)
@@ -99,25 +140,26 @@ def pairwise(fixed, warped, fixed_seg, warped_seg, transform):
 
 def run_all(
     e: Example,
-    losses=(
-        # "SSD",
-        # "NMI",
-        # "HuberImageLoss",
-        "LNCC",
-        # "MSE",
-    ),
-    bes=(
-        1e-2,
-        # 1e-3,
-    ),
-    strides=(4, 8, 16),
-    lrs=(
-        # 1e-2,
-        1e-3,
-        1e-4,
-    ),
-    spacings=([], [2], [3], [4]),
-):
+    losses: tuple[str, ...] = ("LNCC",),
+    bes: tuple[float, ...] = (1e-2,),
+    strides: tuple[int, ...] = (4, 8, 16),
+    lrs: tuple[float, ...] = (1e-3, 1e-4),
+    spacings: tuple = ([], [2], [3], [4]),
+) -> None:
+    """Run an exhaustive grid search over deformable registration hyper-parameters.
+
+    All combinations of *losses*, *bes*, *strides* (applied identically to all
+    three spatial dimensions), *lrs*, and *spacings* are evaluated.  Results are
+    cached to a pickle buffer and exported to an Excel file after each run.
+
+    Args:
+        e: ``Example`` dataclass describing the image pair and output folder.
+        losses: Sequence of image similarity loss names to sweep.
+        bes: Sequence of bending-energy regularisation weights to sweep.
+        strides: Sequence of control-point strides (applied to each axis) to sweep.
+        lrs: Sequence of learning rates to sweep.
+        spacings: Sequence of spacing configurations to sweep.
+    """
     tests = []
     for loss in losses:
         for be in bes:
@@ -174,7 +216,21 @@ def run_all(
         df_.to_excel(e.outfolder / f"results_{e.name}.xlsx", index=False)
 
 
-def run(e: Example, loss, be, stride, lr, spacing=1, save=False):
+def run(e: Example, loss: str, be: float, stride: int | tuple, lr: float, spacing: int = 1, save: bool = False) -> dict:
+    """Run a single deformable registration experiment and return evaluation metrics.
+
+    Args:
+        e: ``Example`` dataclass describing the image pair and output folder.
+        loss: Image similarity loss name (e.g. ``"LNCC"``).
+        be: Bending-energy regularisation weight.
+        stride: Control-point stride (scalar or per-axis tuple).
+        lr: Optimiser learning rate.
+        spacing: Pyramid spacing type passed to ``Deformable_Registration``.
+        save: If True, save the warped images and segmentations to *e.outfolder*.
+
+    Returns:
+        Dictionary of evaluation metrics as returned by :func:`pairwise`.
+    """
     PATH_CONFIG = Path(__file__).parent / "settings.json"  # noqa: N806
     deformable_config = _load_config(PATH_CONFIG)
     deformable_config = update_config(deformable_config, loss, be, stride, lr)
diff --git a/TPTBox/registration/_deformable/multilabel_segmentation.py b/TPTBox/registration/_deformable/multilabel_segmentation.py
index 878b0d0..adb8861 100644
--- a/TPTBox/registration/_deformable/multilabel_segmentation.py
+++ b/TPTBox/registration/_deformable/multilabel_segmentation.py
@@ -13,12 +13,11 @@
 
 
 class Template_Registration:
-    """
-    Class to perform multi-stage registration between two multi-label segmentations, including optional
-    landmark (point-of-interest, POI) alignment and deformable registration. If not provided they will be computed on the fly.
+    """Multi-stage registration between two multi-label segmentations.
 
-    This is especially useful for aligning anatomical segmentations from MRI or CT between a target and an atlas,
-    optionally considering left/right flipping if segmentations are from different body sides.
+    Supports optional POI landmark alignment and deformable registration; landmarks are computed
+    on the fly if not provided.  Particularly useful for MRI/CT atlas alignment with optional
+    body-side flip handling.
 
     Attributes:
         same_side (bool): Whether the target and atlas represent the same anatomical side (e.g., both right sides).
@@ -57,8 +56,7 @@ def __init__(  # noqa: C901
         change_after_point_reg=lambda x, y, z, w: (x, y, z, w),
         **args,
     ):
-        """
-        Initialize a multi-stage registration pipeline from an atlas to a target image.
+        """Initialize a multi-stage registration pipeline from an atlas to a target image.
 
         Args:
             target (NII): Target image segmentation (e.g., from a subject).
@@ -81,6 +79,7 @@ def __init__(  # noqa: C901
             cms_ids (list | None): List of segmentation labels used to extract POI centroids.
             poi_target_cms (POI | None): Optional precomputed centroids for the target image.
             **args: Additional keyword arguments passed to Deformable_Registration.
+
         Raises:
             ValueError: If an invalid axis is detected during flipping.
         """
@@ -240,13 +239,12 @@ def __init__(  # noqa: C901
             **args,
         )
 
-    def get_dump(self):
-        """
-        Collect serializable state of the registration object.
+    def get_dump(self) -> tuple:
+        """Collect the serialisable state of this registration object.
 
         Returns:
-            tuple: Serialized components including version, rigid registration state, deformable state,
-                   and spatial metadata.
+            A tuple containing the version tag followed by all state components
+            needed to reconstruct the object via :meth:`load_`.
         """
         return (
             1,  # version
@@ -261,40 +259,37 @@ def get_dump(self):
             ),
         )
 
-    def save(self, path: str | Path):
-        """
-        Save the registration state to a file.
+    def save(self, path: str | Path) -> None:
+        """Serialise the registration state to a pickle file.
 
         Args:
-            path (str | Path): Path to save the pickle file.
+            path: Destination file path.
         """
         with open(path, "wb") as w:
             pickle.dump(self.get_dump(), w)
 
     @classmethod
-    def load(cls, path):
-        """
-        Load a previously saved registration state from a file.
+    def load(cls, path: str | Path) -> Template_Registration:
+        """Load a previously saved registration state from a pickle file.
 
         Args:
-            path (str | Path): Path to the pickle file.
+            path: Path to the pickle file created by :meth:`save`.
 
         Returns:
-            Register_Multi_Seg: Reconstructed instance of the class.
+            Reconstructed ``Template_Registration`` instance.
         """
         with open(path, "rb") as w:
             return cls.load_(pickle.load(w))
 
     @classmethod
-    def load_(cls, w):
-        """
-        Load a registration object from a deserialized state (as returned by `get_dump()`).
+    def load_(cls, w: tuple) -> Template_Registration:
+        """Reconstruct a ``Template_Registration`` from a raw state tuple (as returned by :meth:`get_dump`).
 
         Args:
-            w (tuple): Serialized state.
+            w: Serialised state tuple.
 
         Returns:
-            Register_Multi_Seg: Reconstructed instance of the class.
+            Reconstructed ``Template_Registration`` instance.
         """
         (version, t0, t1, x) = w
         assert version == 1, f"Version mismatch {version=}"
@@ -311,17 +306,17 @@ def load_(cls, w):
 
         return self
 
-    def transform_nii(self, nii_atlas: NII, allow_only_same_grid_as_moving=True, only_rigid=False):
-        """
-        Apply both rigid and deformable registration to a new NII object.
+    def transform_nii(self, nii_atlas: NII, allow_only_same_grid_as_moving: bool = True, only_rigid=False) -> NII:
+        """Apply both rigid and deformable registration to a NII image.
 
         Args:
-            nii_atlas (NII): New atlas image to be transformed.
+            nii_atlas: Atlas image to be transformed (must share the atlas grid).
+            allow_only_same_grid_as_moving: If True, assert that *nii_atlas* matches
+                the grid of the moving image used during point registration.
 
         Returns:
-            NII: Transformed image aligned with the original target image.
+            Transformed ``NII`` aligned with the original target image space.
         """
-
         nii_atlas = self.reg_point.transform_nii(nii_atlas, allow_only_same_grid_as_moving=allow_only_same_grid_as_moving)
         if only_rigid:
             return nii_atlas
@@ -345,15 +340,14 @@ def transform_nii(self, nii_atlas: NII, allow_only_same_grid_as_moving=True, onl
 
         return target
 
-    def transform_poi(self, poi_atlas: POI_Global | POI):
-        """
-        Apply both rigid and deformable registration to a POI (landmark) object.
+    def transform_poi(self, poi_atlas: POI_Global | POI) -> POI:
+        """Apply both rigid and deformable registration to a POI landmark set.
 
         Args:
-            poi_atlas (POI_Global | POI): Atlas landmarks to be transformed.
+            poi_atlas: Atlas landmarks to be transformed (defined in the atlas space).
 
         Returns:
-            POI: Transformed POIs aligned to the target space.
+            Transformed ``POI`` landmarks aligned to the target image space.
         """
         poi_atlas = poi_atlas.resample_from_to(self.atlas_org)
 
@@ -383,8 +377,7 @@ def transform_poi(self, poi_atlas: POI_Global | POI):
         return poi_reg_flip
 
     def transform_poi_inverse(self, poi_target: POI_Global | POI):
-        """
-        Transform POIs from target space back into atlas space.
+        """Transform POIs from target space back into atlas space.
 
         Args:
             poi_target (POI_Global | POI): POIs defined in target space.
@@ -392,7 +385,6 @@ def transform_poi_inverse(self, poi_target: POI_Global | POI):
         Returns:
             POI: POIs mapped back into atlas space.
         """
-
         poi = poi_target.copy()
 
         # --- undo left/right flip if needed ---
diff --git a/TPTBox/registration/_ridged_intensity/affine_deepali.py b/TPTBox/registration/_ridged_intensity/affine_deepali.py
index f75e89f..5f1777f 100644
--- a/TPTBox/registration/_ridged_intensity/affine_deepali.py
+++ b/TPTBox/registration/_ridged_intensity/affine_deepali.py
@@ -59,9 +59,9 @@ def forward(
 
 
 def center_of_mass_cc(tensor: torch.Tensor) -> torch.Tensor:
-    """
-    Computes the center of mass for each channel in a (B, C, X, Y, Z) tensor.
-    Returns a tensor of shape (B, C, 3) containing the (x, y, z) coordinates per channel.
+    """Compute the centre of mass for each channel in a ``(B, C, X, Y, Z)`` tensor.
+
+    Returns a tensor of shape ``(B, C, 3)`` with ``(x, y, z)`` coordinates per channel.
     """
     dtype = tensor.dtype
     B, C, *spatial_shape = tensor.shape
@@ -169,12 +169,9 @@ def forward(
 
 
 def subsample_coords(coords: torch.Tensor, k: int) -> torch.Tensor:
-    """
-    If `coords` has more than `k` rows, return a random subset of size `k`;
-    otherwise return `coords` unchanged.
+    """Return a random subset of ``k`` rows from ``coords``, or the full tensor if it has ≤ ``k`` rows.
 
-    Uses sampling *without* replacement (`torch.randperm`), so every
-    coordinate appears at most once.  Works entirely on-device.
+    Samples without replacement via ``torch.randperm``; works entirely on-device.
     """
     n = coords.size(0)
     if n <= k:
@@ -201,8 +198,7 @@ def forward(
         target: torch.Tensor,
         mask: torch.Tensor | None = None,  # noqa: ARG002
     ) -> torch.Tensor:
-        """
-        Chamfer-style distance loss for mis-labelled voxels.
+        """Chamfer-style distance loss for mis-labelled voxels.
 
         Parameters
         ----------
@@ -215,7 +211,7 @@ def forward(
             back to integer labels. Set to 1 if `source` and `target` are already
             integer encoded.
 
-        Returns
+        Returns:
         -------
         torch.Tensor  scalar
             The mean distance (in voxel units) from every wrongly predicted voxel
diff --git a/TPTBox/registration/_ridged_intensity/register.py b/TPTBox/registration/_ridged_intensity/register.py
index 0d8ed0c..f9c3db7 100644
--- a/TPTBox/registration/_ridged_intensity/register.py
+++ b/TPTBox/registration/_ridged_intensity/register.py
@@ -18,6 +18,8 @@
     err.on_fail("This subscript needs nipy as an additonal package")
     err.on_fail("Please install: pip install nipy")
     raise
+from typing_extensions import Self
+
 from TPTBox import AX_CODES, NII
 
 """
@@ -28,16 +30,39 @@
 
 
 class HiddenPrints:
-    def __enter__(self):
+    """Context manager that suppresses all stdout output while active."""
+
+    def __enter__(self) -> Self:
+        """Redirect stdout to /dev/null."""
         self._original_stdout = sys.stdout
         sys.stdout = open(os.devnull, "w")  # noqa: SIM115
+        return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb):
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Restore the original stdout."""
         sys.stdout.close()
         sys.stdout = self._original_stdout
 
 
-def registrate_ants(moving: NII, fixed: NII, type_of_transform="DenseRigid", verbose=False, **qargs):
+def registrate_ants(
+    moving: NII,
+    fixed: NII,
+    type_of_transform: str = "DenseRigid",
+    verbose: bool = False,
+    **qargs,
+) -> tuple[NII, list]:
+    """Register *moving* to *fixed* using ANTs and return the warped image plus forward transforms.
+
+    Args:
+        moving: Moving (source) image.
+        fixed: Fixed (target/reference) image.
+        type_of_transform: ANTs transform type string (e.g. ``"DenseRigid"``, ``"SyN"``).
+        verbose: If True, pass verbose output through ANTs.
+        **qargs: Additional keyword arguments forwarded to ``ants.registration``.
+
+    Returns:
+        A tuple of (warped_moving_NII, forward_transform_paths).
+    """
     import ants
 
     mytx = ants.registration(fixed=fixed.to_ants(), moving=moving.to_ants(), type_of_transform=type_of_transform, verbose=verbose, **qargs)
@@ -53,7 +78,23 @@ def registrate_nipy(
     similarity: Similarity_Measures = "cc",
     optimizer: Affine_Transforms = "rigid",
     other_moving: list[NII] | None = None,
-):
+) -> tuple[NII, Affine, list[NII]]:
+    """Register *moving* to *fixed* using nipy's histogram-based registration.
+
+    Args:
+        moving: Moving (source) image.
+        fixed: Fixed (target/reference) image.
+        similarity: Similarity metric used for histogram registration.  One of
+            ``"slr"``, ``"mi"``, ``"pmi"``, ``"dpmi"``, ``"cc"``, ``"cr"``,
+            ``"crl1"``.
+        optimizer: Affine transform family to optimise over.  One of
+            ``"affine"``, ``"affine2d"``, ``"similarity"``, ``"similarity2d"``,
+            ``"rigid"``, ``"rigid2d"``.
+        other_moving: Additional images to warp with the same transform.
+
+    Returns:
+        A tuple of (aligned_moving, transform, aligned_other_moving).
+    """
     if other_moving is None:
         other_moving = []
     hist_reg = nipy_reg.HistogramRegistration(fixed.nii, moving.nii, similarity=similarity)
@@ -66,14 +107,33 @@ def registrate_nipy(
     return aligned_img, transform, out_arr
 
 
-def only_change_affine(nii: NII, transform: Affine):
+def only_change_affine(nii: NII, transform: Affine) -> NII:
+    """Return a copy of *nii* whose affine matrix has been updated by *transform*.
+
+    Args:
+        nii: Source NIfTI image.
+        transform: nipy affine transform to compose with the existing affine.
+
+    Returns:
+        New ``NII`` with the modified affine and the original voxel data.
+    """
     aff = nii.affine
     t_affine = transform.as_affine()
     t_affine = np.dot(t_affine, aff)
     return NII(nib.nifti1.Nifti1Image(nii.get_array(), t_affine), nii.seg)
 
 
-def apply_registration_nipy(moving: NII, fixed: NII, transform: Affine):
+def apply_registration_nipy(moving: NII, fixed: NII, transform: Affine) -> NII:
+    """Apply a pre-computed nipy affine transform to resample *moving* into the *fixed* space.
+
+    Args:
+        moving: Moving (source) image to be resampled.
+        fixed: Fixed (target/reference) image that defines the output space.
+        transform: Pre-computed nipy affine transform.
+
+    Returns:
+        Resampled ``NII`` in the fixed image space.
+    """
     aligned_img = nipy_reg.resample(moving.nii, transform, fixed.nii, interp_order=0 if moving.seg else 3)
     aligned_img = fixed.set_array(aligned_img.get_data())
     aligned_img.seg = moving.seg
@@ -87,16 +147,26 @@ def register_native_res(
     optimizer: Affine_Transforms = "rigid",
     other_moving: list[NII] | None = None,
 ) -> tuple[NII, NII, Affine, list[NII]]:
-    """register an image to an other, with its native resolution of moving. Uses Global coordinates.
+    """Register *moving* to *fixed* at the native resolution of *moving*.
+
+    The fixed image is first resampled into *moving*'s voxel space before the
+    histogram registration is performed, so the alignment uses global (physical)
+    coordinates throughout.
 
     Args:
-        moving (NII): _description_
-        fixed (NII): _description_
-        similarity (Similarity_Measures, optional): _description_. Defaults to "cc".
-        optimizer (Affine_Transforms, optional): _description_. Defaults to "rigid".
+        moving: Moving (source) image.
+        fixed: Fixed (target/reference) image.
+        similarity: Similarity metric for histogram registration.  One of
+            ``"slr"``, ``"mi"``, ``"pmi"``, ``"dpmi"``, ``"cc"``, ``"cr"``,
+            ``"crl1"``.
+        optimizer: Affine transform family to optimise.  One of
+            ``"affine"``, ``"affine2d"``, ``"similarity"``, ``"similarity2d"``,
+            ``"rigid"``, ``"rigid2d"``.
+        other_moving: Additional images to warp with the same transform.
 
     Returns:
-        (NII,NII): _description_
+        A tuple of (aligned_moving, fixed_resampled_to_moving, transform,
+        aligned_other_moving).
     """
     if other_moving is None:
         other_moving = []
@@ -106,7 +176,16 @@ def register_native_res(
     return aligned_img, fixed_m_res, transform, out_arr
 
 
-def crop_shared_(a: NII, b: NII):
+def crop_shared_(a: NII, b: NII) -> tuple:
+    """Crop both images in-place to their shared non-background bounding box.
+
+    Args:
+        a: First NIfTI image (modified in place).
+        b: Second NIfTI image (modified in place).
+
+    Returns:
+        The crop slice tuple applied to both images.
+    """
     crop = a.compute_crop()
     crop = b.compute_crop(other_crop=crop)
     print(crop)
diff --git a/TPTBox/registration/_ridged_points/point_registration.py b/TPTBox/registration/_ridged_points/point_registration.py
index 102234e..b25f535 100644
--- a/TPTBox/registration/_ridged_points/point_registration.py
+++ b/TPTBox/registration/_ridged_points/point_registration.py
@@ -128,7 +128,17 @@ def __init__(
         self.input_poi: Has_Grid = poi_moving.to_gird()
         self.out_poi: Has_Grid = poi_fixed.to_gird()
 
-    def get_resampler(self, seg, c_val, output_space: NII | None = None) -> sitk.ResampleImageFilter:
+    def get_resampler(self, seg: bool, c_val: float, output_space: NII | None = None) -> sitk.ResampleImageFilter:
+        """Build a configured SimpleITK resampler for this registration transform.
+
+        Args:
+            seg: If True, use nearest-neighbour interpolation (segmentation mode).
+            c_val: Default fill value for background voxels (ignored when seg=True).
+            output_space: Optional target image space. Defaults to the fixed image space.
+
+        Returns:
+            A configured ``sitk.ResampleImageFilter`` ready to be executed.
+        """
         resampler: sitk.ResampleImageFilter = sitk.ResampleImageFilter()
         if output_space is None:
             resampler.SetReferenceImage(self._img_fixed)
@@ -144,13 +154,40 @@ def get_resampler(self, seg, c_val, output_space: NII | None = None) -> sitk.Res
         return resampler
 
     def transform(self, x: NII_or_POI) -> NII_or_POI:
+        """Apply the registration transform to a NII image or a POI landmark set.
+
+        Args:
+            x: A ``NII`` image or ``POI`` landmark set to transform.
+
+        Returns:
+            Transformed object of the same type as the input.
+
+        Raises:
+            ValueError: If *x* is neither a ``NII`` nor a ``POI``.
+        """
         if isinstance(x, POI):
             return self.transform_poi(x)
         if isinstance(x, NII):
             return self.transform_nii(x)
         raise ValueError
 
-    def transform_poi(self, poi_moving: POI, allow_only_same_grid_as_moving=True, output_space=None):
+    def transform_poi(
+        self,
+        poi_moving: POI,
+        allow_only_same_grid_as_moving: bool = True,
+        output_space: NII | POI | None = None,
+    ) -> POI:
+        """Transform a set of landmarks (POI) from the moving to the fixed image space.
+
+        Args:
+            poi_moving: Landmark set defined in the moving image space.
+            allow_only_same_grid_as_moving: If True, assert that *poi_moving* shares
+                the grid of the moving image used during registration.
+            output_space: Optional target space to resample the result into.
+
+        Returns:
+            Transformed ``POI`` in the fixed (or *output_space*) coordinate frame.
+        """
         # output_space: POI | NII | None = None,
         if allow_only_same_grid_as_moving:
             text = "input image must be in the same space as moving.  If you sure that this input is in same space as the moving image you can turn of 'only_allow_grid_as_moving'"
@@ -184,7 +221,17 @@ def transform_poi_inverse(self, poi_moving: POI, allow_only_same_grid_as_moving=
             poi = poi.resample_from_to(output_space)
         return poi
 
-    def transform_cord(self, cord: tuple[float, ...], out: sitk.Image | None = None):
+    def transform_cord(self, cord: tuple[float, ...], out: sitk.Image | None = None) -> np.ndarray:
+        """Transform a single voxel coordinate from moving to fixed image space.
+
+        Args:
+            cord: Voxel coordinate (x, y, z) in the moving image.
+            out: Reference SimpleITK image defining the output space.
+                Defaults to the fixed image used during registration.
+
+        Returns:
+            Transformed coordinate as a NumPy array of shape (3,).
+        """
         if out is None:
             out = self._img_fixed
         ctr_b = self._img_moving.TransformContinuousIndexToPhysicalPoint(cord)
@@ -192,7 +239,17 @@ def transform_cord(self, cord: tuple[float, ...], out: sitk.Image | None = None)
         ctr_b = out.TransformPhysicalPointToContinuousIndex(ctr_b)
         return np.array(ctr_b)
 
-    def transform_cord_inverse(self, cord: tuple[float, ...], out: sitk.Image | None = None):
+    def transform_cord_inverse(self, cord: tuple[float, ...], out: sitk.Image | None = None) -> np.ndarray:
+        """Transform a single voxel coordinate from fixed to moving image space (inverse direction).
+
+        Args:
+            cord: Voxel coordinate (x, y, z) in the fixed image.
+            out: Reference SimpleITK image defining the output space.
+                Defaults to the fixed image used during registration.
+
+        Returns:
+            Transformed coordinate as a NumPy array of shape (3,).
+        """
         if out is None:
             out = self._img_fixed
         ctr_b = out.TransformContinuousIndexToPhysicalPoint(cord)
@@ -203,10 +260,24 @@ def transform_cord_inverse(self, cord: tuple[float, ...], out: sitk.Image | None
     def transform_nii(
         self,
         moving_img_nii: NII,
-        allow_only_same_grid_as_moving=True,
+        allow_only_same_grid_as_moving: bool = True,
         output_space: NII | None = None,
         c_val: float | None = None,
-    ):
+    ) -> NII:
+        """Resample a NII image from the moving into the fixed image space.
+
+        Args:
+            moving_img_nii: Image defined in the moving image space.
+            allow_only_same_grid_as_moving: If True, assert that *moving_img_nii*
+                shares the grid of the moving image used during registration.
+            output_space: Optional target space for the resampled output.
+                Defaults to the fixed image space.
+            c_val: Background fill value. Derived from the image automatically
+                when not provided.
+
+        Returns:
+            Resampled ``NII`` in the fixed (or *output_space*) coordinate frame.
+        """
         if allow_only_same_grid_as_moving:
             text = "input image must be in the same space as moving.  If you sure that this input is in same space as the moving image you can turn of 'only_allow_grid_as_moving'"
             moving_img_nii.assert_affine(self.input_poi, text=text, shape_tolerance=0.9)
@@ -219,7 +290,15 @@ def transform_nii(
             transformed_img = sitk.Round(transformed_img)
         return sitk_to_nii(transformed_img, seg=moving_img_nii.seg)
 
-    def get_affine(self):
+    def get_affine(self) -> np.ndarray:
+        """Return the 4x4 affine matrix corresponding to the rigid registration transform.
+
+        The matrix follows the convention:
+            T(x) = A(x - c) + (t + c)
+
+        Returns:
+            A (4, 4) NumPy array representing the homogeneous affine transform.
+        """
         # VersorRigid3DTransform
         # T(x) = A ( x - c ) + (t + c)
         # T(x) = Ax (- Ac + t + c)
@@ -235,7 +314,13 @@ def get_affine(self):
         A[:3, 3] = trans  # Set translation part
         return A
 
-    def get_dump(self):
+    def get_dump(self) -> tuple:
+        """Collect the serialisable state of this registration object.
+
+        Returns:
+            A tuple containing the version tag followed by all state components
+            needed to reconstruct the object via :meth:`load_`.
+        """
         return (
             1,  # version
             sitk_to_nii(self._img_moving, True).to_gird(),
@@ -247,17 +332,38 @@ def get_dump(self):
             self.out_poi,
         )
 
-    def save(self, path: str | Path):
+    def save(self, path: str | Path) -> None:
+        """Serialise the registration state to a pickle file.
+
+        Args:
+            path: Destination file path.
+        """
         with open(path, "wb") as w:
             pickle.dump(self.get_dump(), w)
 
     @classmethod
-    def load(cls, path):
+    def load(cls, path: str | Path) -> Point_Registration:
+        """Load a ``Point_Registration`` from a previously saved pickle file.
+
+        Args:
+            path: Path to the pickle file created by :meth:`save`.
+
+        Returns:
+            Reconstructed ``Point_Registration`` instance.
+        """
         with open(path, "rb") as w:
             return cls.load_(pickle.load(w))
 
     @classmethod
-    def load_(cls, w):
+    def load_(cls, w: tuple) -> Point_Registration:
+        """Reconstruct a ``Point_Registration`` from a raw state tuple (as returned by :meth:`get_dump`).
+
+        Args:
+            w: Serialised state tuple.
+
+        Returns:
+            Reconstructed ``Point_Registration`` instance.
+        """
         self = cls.__new__(cls)
         (
             version,
@@ -294,14 +400,32 @@ def load_(cls, w):
 def ridged_points_from_poi(
     poi_fixed: POI,
     poi_moving: POI,
-    exclusion=None,
+    exclusion: list | None = None,
     log: Logger_Interface = No_Logger(),  # noqa: B008
-    verbose=True,
+    verbose: bool = True,
     ax_code=None,
     zooms=None,
-    c_val=None,
-    leave_worst_percent_out=0.0,
+    c_val: float | None = None,
+    leave_worst_percent_out: float = 0.0,
 ) -> Point_Registration:
+    """Compute a rigid point-based registration from two POI landmark sets.
+
+    Args:
+        poi_fixed: Landmark set in the fixed (target) image space.
+        poi_moving: Landmark set in the moving (source) image space.
+        exclusion: List of landmark keys to exclude from the alignment.
+        log: Logger used for progress and diagnostic output.
+        verbose: If True, print detailed per-landmark information.
+        ax_code: Optional orientation code to reorient *poi_fixed* before registration.
+        zooms: Optional target voxel spacing to rescale *poi_fixed* before registration.
+        c_val: Deprecated. Background fill value — has no effect and will trigger a
+            ``DeprecationWarning`` if supplied.
+        leave_worst_percent_out: Fraction (0–1) of worst-fitting landmarks to discard
+            before computing the final transform.
+
+    Returns:
+        Fitted ``Point_Registration`` object.
+    """
     if c_val is not None:
         warnings.warn(
             "c_val of ridged_points_from_poi is never used.",
@@ -326,12 +450,34 @@ def ridged_points_from_subreg_vert(
     subreg: POI_Reference,
     poi_target_buffer: Path | str | None = None,
     orientation=None,
-    zoom=(-1, -1, -1),
+    zoom: tuple[float, float, float] = (-1, -1, -1),
     subreg_id: int | Location | list[int | Location] | list[Location] | list[int] = 50,
-    c_val=-1050,
-    verbose=True,
-    save_buffer_file=True,
+    c_val: float = -1050,
+    verbose: bool = True,
+    save_buffer_file: bool = True,
 ) -> Point_Registration:
+    """Compute a rigid point-based registration using vertebra sub-region centroids.
+
+    Derives a fixed-space POI from instance and semantic segmentation masks, then
+    aligns it to a pre-computed moving-space POI.
+
+    Args:
+        poi_moving: POI landmark set (or loadable reference) for the moving image.
+        vert: Instance (vertebra label) segmentation in the fixed image space.
+        subreg: Semantic sub-region segmentation in the fixed image space.
+        poi_target_buffer: Optional path to cache / load the computed fixed POI.
+        orientation: Optional orientation code to reorient the fixed POI.
+        zoom: Target voxel spacing for rescaling the fixed POI.
+            Pass ``(-1, -1, -1)`` to skip rescaling.
+        subreg_id: Sub-region label(s) used to extract centroid landmarks.
+        c_val: Background fill value forwarded to the registration (currently unused
+            internally; kept for API compatibility).
+        verbose: If True, print progress information.
+        save_buffer_file: If True, save the computed fixed POI to *poi_target_buffer*.
+
+    Returns:
+        Fitted ``Point_Registration`` object.
+    """
     if not isinstance(subreg_id, (list, tuple)):
         subreg_id = [subreg_id]
     instance_nii = to_nii(vert, True).copy()
@@ -361,9 +507,10 @@ def _compute_versor(
     img_fixed: sitk.Image,
     ctd_m: POI,
     img_moving: sitk.Image,
-    verbose=False,
+    verbose: bool = False,
     log: Logger_Interface = No_Logger(),  # noqa: B008
-):
+) -> tuple[sitk.VersorRigid3DTransform, float, float, dict[tuple[int, int], float]]:
+    """Fit a VersorRigid3D transform from shared landmark pairs and report registration errors."""
     assert len(inter) >= 2, f"To few points: {inter}"
     # find shared points
     move_l = []
diff --git a/TPTBox/registration/ridged_intensity/affine_deepali.py b/TPTBox/registration/ridged_intensity/affine_deepali.py
index f75e89f..c3db154 100644
--- a/TPTBox/registration/ridged_intensity/affine_deepali.py
+++ b/TPTBox/registration/ridged_intensity/affine_deepali.py
@@ -27,15 +27,33 @@
 
 
 class PairwiseSegImageLoss(Module, metaclass=ABCMeta):
-    r"""Base class of pairwise image dissimilarity criteria."""
+    r"""Base class of pairwise image dissimilarity criteria for segmentation masks."""
 
     @abstractmethod
     def forward(self, source: Tensor, target: Tensor, mask: [Tensor] | None = None) -> Tensor:
-        r"""Evaluate image dissimilarity loss."""
+        r"""Evaluate image dissimilarity loss.
+
+        Args:
+            source: Warped source image/segmentation tensor.
+            target: Fixed target image/segmentation tensor.
+            mask: Optional spatial mask restricting the loss computation.
+
+        Returns:
+            Scalar loss tensor.
+        """
         raise NotImplementedError(f"{type(self).__name__}.forward()")
 
 
-def center_of_mass(tensor):
+def center_of_mass(tensor: torch.Tensor) -> torch.Tensor:
+    """Compute the centre of mass of a spatial tensor.
+
+    Args:
+        tensor: Arbitrary-shape float tensor treated as a spatial density map.
+
+    Returns:
+        1-D tensor of length ``tensor.ndim`` with the weighted-average
+        coordinate along each axis.
+    """
     grid = torch.meshgrid([torch.arange(s, device=tensor.device) for s in tensor.shape], indexing="ij")
     t = tensor / tensor.sum()
     com = torch.stack([(t * g).sum() for g in grid])
@@ -43,12 +61,20 @@ def center_of_mass(tensor):
 
 
 class Tether_single(PairwiseImageLoss):
+    """Centre-of-mass tethering loss for a single binary channel.
+
+    Penalises the Euclidean distance between the centre of mass of the warped
+    source and the fixed target. The penalty is zeroed out when the distance
+    is smaller than 10 voxels.
+    """
+
     def forward(
         self,
         source: torch.Tensor,
         target: torch.Tensor,
         mask: torch.Tensor | None = None,  # noqa: ARG002
     ) -> torch.Tensor:  # noqa: ARG002
+        """Compute the centre-of-mass distance loss between source and target."""
         com_fixed = center_of_mass(target)
         com_warped = center_of_mass(source)
         l_com = torch.norm(com_fixed - com_warped)
@@ -59,9 +85,9 @@ def forward(
 
 
 def center_of_mass_cc(tensor: torch.Tensor) -> torch.Tensor:
-    """
-    Computes the center of mass for each channel in a (B, C, X, Y, Z) tensor.
-    Returns a tensor of shape (B, C, 3) containing the (x, y, z) coordinates per channel.
+    """Compute the centre of mass for each channel in a ``(B, C, X, Y, Z)`` tensor.
+
+    Returns a tensor of shape ``(B, C, 3)`` with ``(x, y, z)`` coordinates per channel.
     """
     dtype = tensor.dtype
     B, C, *spatial_shape = tensor.shape
@@ -82,7 +108,19 @@ def center_of_mass_cc(tensor: torch.Tensor) -> torch.Tensor:
 
 
 class Tether_Seg(PairwiseSegImageLoss):
-    def __init__(self, delta=1, *args, **kwargs):
+    """Per-channel centre-of-mass tethering loss for multi-channel segmentation tensors.
+
+    Computes the mean normalised Euclidean distance between the centre of mass
+    of each channel in the warped source and the fixed target. Channels whose
+    displacement is smaller than ``delta`` (relative to the largest spatial
+    dimension) are ignored.
+
+    Args:
+        delta: Minimum relative displacement threshold below which a channel
+            contributes zero loss.
+    """
+
+    def __init__(self, delta: float = 1, *args, **kwargs):
         self.delta = delta
         super().__init__(*args, **kwargs)
 
@@ -92,6 +130,7 @@ def forward(
         target: torch.Tensor,  # shape: (B, C, X, Y, Z)
         mask: torch.Tensor | None = None,  # noqa: ARG002
     ) -> torch.Tensor:
+        """Compute the mean per-channel normalised centre-of-mass distance."""
         w = max(target.shape[2:])
         com_fixed = center_of_mass_cc(target)  # (B, C, 3)
         com_warped = center_of_mass_cc(source)  # (B, C, 3)
@@ -106,13 +145,26 @@ def forward(
 
 
 class Tether(PairwiseImageLoss):
+    """Centre-of-mass tethering loss with optional per-class and memory features.
+
+    Args:
+        delta: Minimum voxel distance below which the loss is zeroed. Prevents
+            penalising already-well-aligned structures.
+        uniq: If ``True``, compute separate centre-of-mass distances per unique
+            label value instead of the whole foreground mass.
+        remember: If ``True``, skip computing the loss for ``remember_c``
+            iterations after the loss is zeroed (early stopping memory).
+        remember_c: Number of iterations to skip after the loss drops to zero.
+        max_v: Scale factor mapping continuous output values to integer labels.
+    """
+
     def __init__(
         self,
-        delta=10,
-        uniq=False,
-        remember=False,
-        remember_c=10,
-        max_v=1,
+        delta: float = 10,
+        uniq: bool = False,
+        remember: bool = False,
+        remember_c: int = 10,
+        max_v: float = 1,
         *args,
         **kwargs,
     ) -> None:
@@ -130,6 +182,7 @@ def forward(
         target: torch.Tensor,
         mask: torch.Tensor | None = None,  # noqa: ARG002
     ) -> torch.Tensor:  # noqa: ARG002
+        """Compute the centre-of-mass tethering loss."""
         if self.count != 0:
             self.count -= 1
             return torch.zeros(1, device=source.device)
@@ -169,12 +222,9 @@ def forward(
 
 
 def subsample_coords(coords: torch.Tensor, k: int) -> torch.Tensor:
-    """
-    If `coords` has more than `k` rows, return a random subset of size `k`;
-    otherwise return `coords` unchanged.
+    """Return a random subset of ``k`` rows from ``coords``, or the full tensor if it has ≤ ``k`` rows.
 
-    Uses sampling *without* replacement (`torch.randperm`), so every
-    coordinate appears at most once.  Works entirely on-device.
+    Samples without replacement via ``torch.randperm``; works entirely on-device.
     """
     n = coords.size(0)
     if n <= k:
@@ -184,10 +234,22 @@ def subsample_coords(coords: torch.Tensor, k: int) -> torch.Tensor:
 
 
 class DISTANCE_to_TARGET(PairwiseImageLoss):
+    """Chamfer-style distance loss penalising mislabelled voxels.
+
+    For each foreground class, computes the mean minimum distance from
+    incorrectly predicted voxels to the nearest correct ground-truth voxel of
+    the same class.
+
+    Args:
+        max_v: Scale factor to convert continuous predictions to integer labels.
+        res_gt: Spatial downsampling factor applied to the ground-truth when
+            computing nearest-neighbour distances (reduces memory usage).
+    """
+
     def __init__(
         self,
-        max_v=1,
-        res_gt=4,
+        max_v: float = 1,
+        res_gt: int = 4,
         *args,
         **kwargs,
     ) -> None:
@@ -201,8 +263,7 @@ def forward(
         target: torch.Tensor,
         mask: torch.Tensor | None = None,  # noqa: ARG002
     ) -> torch.Tensor:
-        """
-        Chamfer-style distance loss for mis-labelled voxels.
+        """Chamfer-style distance loss for mis-labelled voxels.
 
         Parameters
         ----------
@@ -215,7 +276,7 @@ def forward(
             back to integer labels. Set to 1 if `source` and `target` are already
             integer encoded.
 
-        Returns
+        Returns:
         -------
         torch.Tensor  scalar
             The mean distance (in voxel units) from every wrongly predicted voxel
@@ -267,6 +328,51 @@ def forward(
 
 
 class Rigid_Registration_with_Tether(General_Registration):
+    """Rigid (or affine) image registration with an optional centre-of-mass tether.
+
+    Extends :class:`~TPTBox.registration._deepali.deepali_model.General_Registration`
+    with a patience-based early-stopping strategy and an additional
+    centre-of-mass regularisation term that keeps the warped image anchored
+    near the fixed image.
+
+    Args:
+        fixed_image: Reference (target) image.
+        moving_image: Image to be registered.
+        reference_image: Optional reference image defining the output grid.
+        device: PyTorch device for computation.
+        gpu: GPU index used when ``ddevice`` is ``"cuda"``.
+        ddevice: Device type string (``"cpu"``, ``"cuda"``, or ``"mps"``).
+        fixed_mask: Optional foreground mask for the fixed image.
+        moving_mask: Optional foreground mask for the moving image.
+        normalize_strategy: Intensity normalisation strategy
+            (``"auto"``, ``"CT"``, ``"MRI"``, or ``None``).
+        pyramid_levels: Number of multi-resolution pyramid levels.
+        finest_level: Index of the finest pyramid level (0 = full resolution).
+        coarsest_level: Index of the coarsest pyramid level.
+        pyramid_finest_spacing: Voxel spacing at the finest pyramid level.
+        pyramid_min_size: Minimum spatial size per axis at the coarsest level.
+        dims: Spatial dimensions to include in the transform.
+        align: If ``True``, initialise the transform to align image centres.
+        transform_name: Name of the spatial transform class from DeepALI.
+        transform_args: Extra keyword arguments for the transform constructor.
+        transform_init: Optional path to a pre-computed flow field for
+            warm-starting.
+        optim_name: PyTorch optimiser class name.
+        lr: Learning rate.
+        optim_args: Extra keyword arguments for the optimiser (excluding ``lr``).
+        smooth_grad: Gradient smoothing factor.
+        verbose: Verbosity level (0 = silent).
+        max_steps: Maximum optimisation steps per pyramid level.
+        max_history: History length for convergence checking.
+        min_value: Minimum loss value for early stopping.
+        min_delta: Minimum loss improvement for early stopping.
+        loss_terms: Tuple of loss functions (image similarity + regulariser).
+        weights: Corresponding loss weights.
+        patience: Number of steps without improvement before stopping.
+        patience_delta: Minimum loss change to reset patience counter.
+        desc: Description string shown in the progress bar.
+    """
+
     def __init__(
         self,
         fixed_image: Image_Reference,
@@ -353,9 +459,22 @@ def run_level(
         opt: torch.optim.Optimizer,
         lr_sq,  # noqa: ARG002
         level,  # noqa: ARG002
-        max_steps,
+        max_steps: int,
         sampling: Union[Sampling, str] = Sampling.LINEAR,  # noqa: ARG002
-    ):
+    ) -> None:
+        """Optimise the transform at a single pyramid level.
+
+        Args:
+            grid_transform: The spatial transform being optimised.
+            target_image: Fixed target image at the current resolution.
+            source_image: Moving source image at the current resolution.
+            opt: Initialised PyTorch optimiser.
+            lr_sq: Learning-rate scheduler (unused, kept for API compatibility).
+            level: Current pyramid level index (unused).
+            max_steps: Maximum number of gradient steps for this level.
+            sampling: Interpolation mode for image warping (unused at this
+                level; linear sampling is hard-coded).
+        """
         loss_list = []
         self.loss_values = loss_list
         self.transform = grid_transform
@@ -386,7 +505,12 @@ def run_level(
             pbar.desc = f"{self.desc} loss={l_mse.item() * lambda_mse:.5f}, center_of_mass={l_com * lambda_com:.5f}, {self.early_stopping=}, {self.best=}"
 
     def on_converged(self) -> bool:
-        r"""Check convergence criteria."""
+        """Check patience-based early-stopping convergence criterion.
+
+        Returns:
+            ``True`` when the patience counter exceeds the configured patience
+            limit and the best transform has been restored; ``False`` otherwise.
+        """
         values = self.loss_values
         if not values:
             return False
diff --git a/TPTBox/registration/script_ax2sag.py b/TPTBox/registration/script_ax2sag.py
index f44d99f..3809f8f 100755
--- a/TPTBox/registration/script_ax2sag.py
+++ b/TPTBox/registration/script_ax2sag.py
@@ -1,6 +1,4 @@
-"""
-This script assumes that there are aligned Sagittal data and poorly aligned axial data.
-"""
+"""This script assumes that there are aligned Sagittal data and poorly aligned axial data."""
 
 from __future__ import annotations
 
@@ -15,7 +13,28 @@
 from TPTBox.stitching import stitching
 
 
-def register_ax_and_stich_both(sub: Subject_Container, out_folder, buffer_path, verbose_stitching=True):
+def register_ax_and_stich_both(
+    sub: Subject_Container, out_folder: str | Path, buffer_path: str | Path, verbose_stitching: bool = True
+) -> dict:
+    """Register axial acquisitions to a sagittal reference and stitch all chunks.
+
+    For each session found in the subject, the function:
+        1. Stitches all sagittal chunks into a single volume.
+        2. Rigidly registers each axial chunk to the stitched sagittal volume.
+        3. Stitches the registered axial volumes.
+        4. Propagates the transforms to spinal-cord and lesion segmentations.
+
+    Args:
+        sub: BIDS subject container providing query access to the subject's files.
+        out_folder: Destination folder for stitched output files.
+        buffer_path: Path to the pickle file used for caching rigid transforms
+            between runs.
+        verbose_stitching: Pass verbosity flag to the stitching routine.
+
+    Returns:
+        A dictionary mapping each axial NIfTI path to its computed rigid
+        transform, suitable for merging into the persistent registration buffer.
+    """
     with open(buffer_path, "rb") as f:
         registration_buffer = pickle.load(f) if Path(buffer_path).exists() else {}
     new_reg_buffer = {}
@@ -124,18 +143,37 @@ def register_ax_and_stich_both(sub: Subject_Container, out_folder, buffer_path,
     return new_reg_buffer
 
 
-def save_registration_buffer(buffers: dict | list[dict], registration_buffer, buffer_path):
+def save_registration_buffer(buffers: dict | list[dict], registration_buffer: dict, buffer_path: str | Path) -> None:
+    """Merge new transform dicts into the global registration buffer and persist it.
+
+    Args:
+        buffers: One or more dicts mapping file paths to rigid transforms that
+            were computed in the current run.
+        registration_buffer: The existing global buffer dict to update in-place.
+        buffer_path: Path to the pickle file where the updated buffer is saved.
+    """
     if not isinstance(buffers, list):
         buffers = [buffers]
     assert buffers is not None
     for new_buffer in buffers:
-        for key, value in new_buffer.items():
-            registration_buffer[key] = value
+        registration_buffer.update(new_buffer)
     with open(buffer_path, "wb") as x:
         pickle.dump(registration_buffer, x)
 
 
-def run(root="/media/data/robert/datasets/dataset-McGinnes/", out_folder="rawdata_new", n_jobs=1, chunks=16):
+def run(
+    root: str = "/media/data/robert/datasets/dataset-McGinnes/", out_folder: str = "rawdata_new", n_jobs: int = 1, chunks: int = 16
+) -> None:
+    """Run the full axial-to-sagittal registration pipeline over a BIDS dataset.
+
+    Args:
+        root: Root directory of the BIDS dataset.
+        out_folder: Sub-folder name relative to ``root`` where stitched outputs
+            are written.
+        n_jobs: Number of parallel jobs. Set to ``1`` to run serially.
+        chunks: Batch size when ``n_jobs > 1`` (number of subjects processed
+            per parallel batch before the buffer is flushed to disk).
+    """
     bgi = BIDS_Global_info([root], parents=["rawdata"])
     registration_buffer = {}
     buffer_path = Path(root, "registration_affines.pkl")
diff --git a/TPTBox/segmentation/README.md b/TPTBox/segmentation/README.md
new file mode 100644
index 0000000..ee1bfdb
--- /dev/null
+++ b/TPTBox/segmentation/README.md
@@ -0,0 +1,50 @@
+# Segmentation (`TPTBox.segmentation`)
+
+Integration with external segmentation pipelines.  Provides a consistent `NII`-based interface
+over SPINEPS, VibeSeg/TotalVibeSeg, and nnU-Net.
+
+## Public API
+
+```python
+from TPTBox.segmentation import (
+    run_spineps,
+    run_vibeseg,
+    run_totalvibeseg,
+    run_nnunet,
+    run_inference_on_file,
+    extract_vertebra_bodies_from_VibeSeg,
+)
+```
+
+## Key functions
+
+| Function | Module | Description |
+|---|---|---|
+| `run_spineps(img_nii, model, ...)` | `spineps.py` | Run SPINEPS spine segmentation on a NIfTI; returns vertebra + subregion masks |
+| `run_vibeseg(img_nii, ...)` | `VibeSeg/vibeseg.py` | Run VibeSeg body composition segmentation |
+| `run_totalvibeseg(img_nii, ...)` | `VibeSeg/vibeseg.py` | Run TotalVibeSeg — extended label set |
+| `run_nnunet(img_nii, model_dir, ...)` | `VibeSeg/vibeseg.py` | Generic nnU-Net inference on a single NIfTI |
+| `run_inference_on_file(path, ...)` | `nnUnet_utils/inference_api.py` | Low-level nnU-Net inference on a file path |
+| `extract_vertebra_bodies_from_VibeSeg(seg)` | `VibeSeg/vibeseg.py` | Post-process VibeSeg output to isolate vertebra bodies |
+
+## Dependencies
+
+| Pipeline | Requirement |
+|---|---|
+| SPINEPS | `pip install spineps` + model weights |
+| VibeSeg / TotalVibeSeg | `pip install nnunetv2` + model weights (auto-downloaded on first run) |
+| Generic nnU-Net | `pip install nnunetv2` + custom model directory |
+
+All external tools are imported lazily — the core TPTBox package installs and imports cleanly
+without them.
+
+## Example
+
+```python
+from TPTBox import NII
+from TPTBox.segmentation import run_spineps
+
+ct = NII.load("ct.nii.gz", seg=False)
+vert_seg, subreg_seg = run_spineps(ct, model="small")
+vert_seg.save("vertebrae.nii.gz")
+```
diff --git a/TPTBox/segmentation/VibeSeg/auto_download.py b/TPTBox/segmentation/VibeSeg/auto_download.py
index afc96af..2a9bad8 100644
--- a/TPTBox/segmentation/VibeSeg/auto_download.py
+++ b/TPTBox/segmentation/VibeSeg/auto_download.py
@@ -29,7 +29,21 @@
 env_name = "VIBESEG_WEIGHTS_PATH"
 
 
-def get_weights_dir(idx, model_path: Path | None = None) -> Path:
+def get_weights_dir(idx: int, model_path: Path | None = None) -> Path:
+    """Resolve and return the directory where model weights for dataset ``idx`` are stored.
+
+    Priority: environment variable ``VIBESEG_WEIGHTS_PATH`` > ``model_path``
+    argument > default path relative to this file.
+
+    Args:
+        idx: Numeric dataset identifier (e.g. ``85`` for Dataset085).
+        model_path: Optional override for the base weights directory. Ignored
+            when the environment variable is set.
+
+    Returns:
+        Path to the dataset-specific weights directory (``<base>/Dataset<idx:03>``).
+        The directory and its parent are created if they do not exist.
+    """
     if env_name in os.environ:
         weights_dir: Path = Path(os.environ[env_name])
     elif model_path is not None and model_path.exists():
@@ -46,7 +60,16 @@ def get_weights_dir(idx, model_path: Path | None = None) -> Path:
     return weights_dir
 
 
-def read_config(idx) -> dict[str, float]:
+def read_config(idx: int) -> dict[str, float]:
+    """Read the ``dataset.json`` configuration for the given dataset index.
+
+    Args:
+        idx: Numeric dataset identifier.
+
+    Returns:
+        Parsed configuration dict, or ``{'dataset_release': 0.0}`` when the
+        file does not yet exist (weights not downloaded).
+    """
     weights_dir = get_weights_dir(idx)
     ds_path = weights_dir / "dataset.json"
     if ds_path.exists():
@@ -57,7 +80,8 @@ def read_config(idx) -> dict[str, float]:
         return {"dataset_release": 0.0}
 
 
-def _download_weights(idx=85, addendum="", first=True) -> None:
+def _download_weights(idx: int = 85, addendum: str = "", first: bool = True) -> None:
+    """Download and extract the zip archive for dataset ``idx`` from the release URL."""
     weights_dir = get_weights_dir(idx)
     weights_url = WEIGHTS_URL_ + f"{idx:03}{addendum}.zip"
     _download(weights_url, weights_dir, text="pretrained weights")
@@ -65,7 +89,8 @@ def _download_weights(idx=85, addendum="", first=True) -> None:
         addendum_download(idx)
 
 
-def _download(weights_url, weights_dir, text="", is_zip=True) -> None:
+def _download(weights_url: str, weights_dir: Path, text: str = "", is_zip: bool = True) -> None:
+    """Download a file from ``weights_url`` into ``weights_dir``, optionally extracting it."""
     try:
         # Retrieve file size
         with urllib.request.urlopen(str(weights_url)) as response:
@@ -92,7 +117,12 @@ def update_progress(block_num: int, block_size: int, total_size: int) -> None:
         os.remove(zip_path)  # noqa: PTH107
 
 
-def addendum_download(idx):
+def addendum_download(idx: int) -> None:
+    """Download any additional weight archives listed in ``other_downloads.json``.
+
+    Args:
+        idx: Numeric dataset identifier whose weights directory is inspected.
+    """
     weights_dir = get_weights_dir(idx)
     next_zip = weights_dir / "other_downloads.json"
     if next_zip.exists():
@@ -102,7 +132,16 @@ def addendum_download(idx):
         next_zip.unlink()
 
 
-def download_weights(idx, model_path: Path | None = None) -> Path:
+def download_weights(idx: int, model_path: Path | None = None) -> Path:
+    """Ensure model weights for dataset ``idx`` are present locally, downloading if needed.
+
+    Args:
+        idx: Numeric dataset identifier.
+        model_path: Optional base directory override for weight storage.
+
+    Returns:
+        Path to the dataset-specific weights directory.
+    """
     weights_dir = get_weights_dir(idx, model_path)
 
     # Check if weights are downloaded
diff --git a/TPTBox/segmentation/VibeSeg/inference_nnunet.py b/TPTBox/segmentation/VibeSeg/inference_nnunet.py
index 34979a2..26d6472 100644
--- a/TPTBox/segmentation/VibeSeg/inference_nnunet.py
+++ b/TPTBox/segmentation/VibeSeg/inference_nnunet.py
@@ -17,7 +17,19 @@
 _model_path_ = out_base / "nnUNet_results"
 
 
-def get_ds_info(idx, _model_path: str | Path | None = None, exit_one_fail=True, logger=logger) -> dict:
+def get_ds_info(idx: int, _model_path: str | Path | None = None, exit_one_fail: bool = True, logger=logger) -> dict:
+    """Load and return the ``dataset.json`` for the model with the given dataset index.
+
+    Args:
+        idx: Numeric dataset identifier (e.g. ``100`` for Dataset100).
+        _model_path: Optional base directory containing ``nnUNet_results``. If
+            ``None``, the bundled default path is used.
+        exit_one_fail: If ``True``, call :func:`sys.exit` when the dataset is
+            not found; otherwise return ``None``.
+
+    Returns:
+        Parsed ``dataset.json`` dictionary for the requested dataset.
+    """
     if _model_path is not None:
         _model_path = Path(_model_path)
         model_path = _model_path / "nnUNet_results"
@@ -41,7 +53,16 @@ def get_ds_info(idx, _model_path: str | Path | None = None, exit_one_fail=True,
     return ds_info
 
 
-def squash_so_it_fits_in_float16(x: NII):
+def squash_so_it_fits_in_float16(x: NII) -> NII:
+    """Scale image intensities so the maximum fits within the float16 range.
+
+    Args:
+        x: Input NIfTI image. Modified in-place when rescaling is necessary.
+
+    Returns:
+        The (potentially rescaled) image, with maximum capped at 1000 when the
+        original maximum exceeds 10000.
+    """
     m = x.max()
     if m > 10000:
         x /= m / 1000  # new max will be 1000
@@ -53,28 +74,74 @@ def run_inference_on_file(
     input_nii: list[NII],
     out_file: str | Path | None = None,
     orientation=None,
-    override=False,
+    override: bool = False,
     gpu=None,
-    keep_size=False,
-    fill_holes=False,
-    logits=False,
+    keep_size: bool = False,
+    fill_holes: bool = False,
+    logits: bool = False,
     mapping=None,
-    crop=False,
+    crop: bool = False,
     max_folds=None,
-    mode="nearest",
+    mode: str = "nearest",
     padd: int = 0,
     ddevice: Literal["cpu", "cuda", "mps"] = "cuda",
     model_path=None,
-    step_size=0.5,
-    memory_base=5000,  # Base memory in MB, default is 5GB
-    memory_factor=160,  # prod(shape)*memory_factor / 1000, 160 ~> 30 GB
-    memory_max=160000,  # in MB, default is 160GB
-    wait_till_gpu_percent_is_free=0.1,
-    verbose=True,
-    auto_download=False,
-    _key_ResEnc="__nnUNet*ResEnc",
+    step_size: float = 0.5,
+    memory_base: int = 5000,  # Base memory in MB, default is 5GB
+    memory_factor: int = 160,  # prod(shape)*memory_factor / 1000, 160 ~> 30 GB
+    memory_max: int = 160000,  # in MB, default is 160GB
+    wait_till_gpu_percent_is_free: float = 0.1,
+    verbose: bool = True,
+    auto_download: bool = False,
+    _key_ResEnc: str = "__nnUNet*ResEnc",
     logger=logger,
 ) -> tuple[Image_Reference, np.ndarray | None]:
+    """Load a VibeSeg model and run inference on the supplied NIfTI images.
+
+    Args:
+        idx: Either an integer dataset ID (model weights are auto-downloaded) or
+            a :class:`~pathlib.Path` pointing directly to a trained model folder.
+        input_nii: List of input NIfTI images (one per model input channel).
+        out_file: Optional path to save the segmentation. If the file already
+            exists and ``override`` is ``False``, returns early.
+        orientation: Three-letter orientation code to reorient inputs before
+            inference (e.g. ``("R", "A", "S")``). Inferred from the model's
+            ``dataset.json`` when ``None``.
+        override: Overwrite an existing ``out_file`` when ``True``.
+        gpu: GPU index to use. ``None`` lets the loader decide automatically.
+        keep_size: If ``True``, do not resample the segmentation back to the
+            original image size.
+        fill_holes: If ``True``, fill holes in the segmentation mask after
+            inference.
+        logits: If ``True``, also return the raw softmax logits array.
+        mapping: Optional label remapping dict applied to the segmentation after
+            inference.
+        crop: If ``True``, crop the input to its foreground bounding box before
+            inference and revert afterwards.
+        max_folds: Maximum number of folds to average. Accepts an ``int`` (use
+            the first N folds) or a list of specific fold names.
+        mode: Interpolation mode used when resampling the segmentation back to
+            the original space (default ``"nearest"``).
+        padd: Padding (in voxels) added on all sides before inference and
+            removed afterwards.
+        ddevice: Device to run inference on (``"cuda"``, ``"cpu"``, or
+            ``"mps"``).
+        model_path: Optional path to a directory containing ``nnUNet_results``.
+            Uses the bundled default when ``None``.
+        step_size: Sliding-window step size fraction (see
+            :class:`~TPTBox.segmentation.nnUnet_utils.predictor.nnUNetPredictor`).
+        memory_base: Base GPU memory reservation in MB.
+        memory_factor: Memory scaling factor per million voxels.
+        memory_max: Hard cap on assumed GPU memory in MB.
+        wait_till_gpu_percent_is_free: Minimum free GPU fraction to require
+            before starting inference.
+        verbose: Print progress information.
+
+    Returns:
+        A tuple ``(seg_nii, softmax_logits)`` where ``seg_nii`` is the
+        segmentation (as a :class:`~TPTBox.NII` or file path) and
+        ``softmax_logits`` is the raw logit array or ``None``.
+    """
     if model_path is None:
         auto_download = True
     if model_path is not None:
@@ -260,20 +327,53 @@ def to_int(a: str, k: None | int = None):
 def run_VibeSeg(
     img: Path | str | list[Path] | list[NII] | Image_Reference,
     out_path: str | Path | None,
-    override=False,
-    dataset_id=None,
+    override: bool = False,
+    dataset_id: int | None = None,
     gpu: int | None = None,
-    logits=False,
-    known_idx=idx_models,
-    keep_size=False,
-    fill_holes=False,
-    crop=False,
+    logits: bool = False,
+    known_idx: list[int] = idx_models,
+    keep_size: bool = False,
+    fill_holes: bool = False,
+    crop: bool = False,
     max_folds: int | None = None,
     _model_path=None,
-    step_size=0.5,
+    step_size: float = 0.5,
     logger: Print_Logger = logger,
     **_kargs,
-):
+) -> NII | Path | None:
+    """High-level entry point for running VibeSeg body-composition segmentation.
+
+    Automatically downloads model weights when needed, selects the appropriate
+    dataset, and delegates to :func:`run_inference_on_file`.
+
+    Args:
+        img: Input image(s). Accepts a single path/NII, or a list of paths/NIIs
+            for multi-channel models.
+        out_path: Output path for the segmentation file. Skipped when
+            ``None``; skips inference when the file exists and
+            ``override`` is ``False``.
+        override: Overwrite existing output file.
+        dataset_id: Explicit dataset ID to use. When ``None``, iterates
+            through ``known_idx`` to find the first available model.
+        gpu: GPU device index. ``None`` selects automatically.
+        logits: If ``True``, return raw softmax logits in addition to the
+            label map.
+        known_idx: List of dataset IDs to probe when ``dataset_id`` is
+            ``None``.
+        keep_size: Skip resampling the segmentation back to the input
+            resolution.
+        fill_holes: Fill holes in the output segmentation.
+        crop: Crop input images to their foreground bounding box.
+        max_folds: Limit the number of folds used for ensemble averaging.
+        _model_path: Override for the default model weights directory.
+        step_size: Sliding-window step size fraction.
+        **_kargs: Additional keyword arguments forwarded to
+            :func:`run_inference_on_file`.
+
+    Returns:
+        Path or :class:`~TPTBox.NII` of the saved segmentation, or ``None``
+        on failure.
+    """
     if isinstance(out_path, str):
         out_path = Path(out_path)
     if out_path is not None and out_path.exists() and not override:
diff --git a/TPTBox/segmentation/VibeSeg/vibeseg.py b/TPTBox/segmentation/VibeSeg/vibeseg.py
index 7e05924..087702f 100644
--- a/TPTBox/segmentation/VibeSeg/vibeseg.py
+++ b/TPTBox/segmentation/VibeSeg/vibeseg.py
@@ -1,11 +1,14 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 
 from TPTBox import Image_Reference, to_nii
 from TPTBox.segmentation.VibeSeg.inference_nnunet import run_inference_on_file
 
+if TYPE_CHECKING:
+    from TPTBox import NII, POI
+
 VibeSeg_map = {
     1: "spleen",
     2: "kidney_right",
@@ -85,14 +88,31 @@
 def run_vibeseg(
     i: Image_Reference,
     out_seg: str | Path,
-    override=False,
-    gpu=0,
+    override: bool = False,
+    gpu: int = 0,
     ddevice: Literal["cpu", "cuda", "mps"] = "cuda",
-    dataset_id=100,
-    padd=5,
-    keep_size=False,  # Keep size of the model Segmentation
+    dataset_id: int = 100,
+    padd: int = 5,
+    keep_size: bool = False,
     **args,
-):
+) -> NII:
+    """Run the VibeSeg whole-body segmentation model on a single image.
+
+    Args:
+        i: Input image reference (path, ``NII``, or ``BIDS_FILE``).
+        out_seg: Destination path for the segmentation output (NIfTI).
+        override: If True, recompute and overwrite an existing output file.
+        gpu: GPU device index to use for inference.
+        ddevice: Compute device: ``"cuda"``, ``"cpu"``, or ``"mps"``.
+        dataset_id: nnU-Net dataset identifier for the VibeSeg model.
+        padd: Number of voxels to pad the image before inference.
+        keep_size: If True, keep the model's native output resolution instead of
+            resampling back to the input image space.
+        **args: Additional keyword arguments forwarded to ``run_inference_on_file``.
+
+    Returns:
+        Segmentation ``NII`` saved at *out_seg*.
+    """
     return run_inference_on_file(
         dataset_id,
         [to_nii(i)] if not isinstance(i, (list, tuple)) else [to_nii(j) for j in i],
@@ -110,10 +130,10 @@ def run_nnunet(
     i: list[Image_Reference],
     out_seg: str | Path,
     *,
-    override=False,
-    gpu=0,
+    override: bool = False,
+    gpu: int = 0,
     ddevice: Literal["cpu", "cuda", "mps"] = "cuda",
-    dataset_id=80,
+    dataset_id: int = 80,
     model_path: str | Path | None = None,
     auto_download=False,  # set to True if model_path is None
     keep_size=False,
@@ -126,7 +146,18 @@ def run_nnunet(
     padd: int = 0,
     key_ResEnc="__nnUNet*ResEnc",
     **args,
-):
+) -> None:
+    """Run an nnU-Net model on a list of images (multi-channel) and save the segmentation.
+
+    Args:
+        i: List of input image references forming one multi-channel sample.
+        out_seg: Destination path for the segmentation output (NIfTI).
+        override: If True, recompute and overwrite an existing output file.
+        gpu: GPU device index to use for inference.
+        ddevice: Compute device: ``"cuda"``, ``"cpu"``, or ``"mps"``.
+        dataset_id: nnU-Net dataset identifier.
+        **args: Additional keyword arguments forwarded to ``run_inference_on_file``.
+    """
     run_inference_on_file(
         dataset_id,
         [to_nii(i) for i in i],
@@ -155,9 +186,8 @@ def extract_vertebra_bodies_from_VibeSeg(
     num_lumbar_verts: int = 5,
     out_path: str | Path | None = None,
     out_path_poi: str | Path | None = None,
-):
-    """
-    Extracts and labels vertebra bodies from a VibeSeg segmentation NIfTI file.
+) -> tuple[NII, POI]:
+    """Extracts and labels vertebra bodies from a VibeSeg segmentation NIfTI file.
 
     This function processes a segmentation mask containing vertebrae and intervertebral discs (IVDs).
     It separates individual vertebra bodies by eroding and splitting the mask at IVD regions, labels the vertebrae
@@ -181,6 +211,7 @@ def extract_vertebra_bodies_from_VibeSeg(
         - The output files, if saved, will include the mask and POI data:
           - Mask file: `<out_path>`
           - POI file: `<out_path>` with `_poi.json` suffix recommended.
+
     Example:
         >>> nii_vibeSeg = "/path/to/vibe_segmentation.nii.gz"
         >>> labeled_mask, centroids = extract_vertebra_bodies_from_nii_vibeSeg(nii_vibeSeg, out_path="output_mask.nii.gz")
@@ -212,7 +243,8 @@ def extract_vertebra_bodies_from_VibeSeg(
     )
 
     # Map centroids to labels based on thoracic and lumbar vertebra counts
-    def map_to_label(index):
+    def map_to_label(index: int) -> int:
+        """Map a bottom-up vertebra index to the corresponding anatomical label integer."""
         if index >= num_thoracic_verts + num_lumbar_verts:
             return 0  # Remove cervical vertebrae
         if index < num_lumbar_verts:
diff --git a/TPTBox/segmentation/_deface.py b/TPTBox/segmentation/_deface.py
index 79ea14a..84d507f 100644
--- a/TPTBox/segmentation/_deface.py
+++ b/TPTBox/segmentation/_deface.py
@@ -8,10 +8,7 @@
 
 
 def _compute_deface_mask_cta(ct_img: Image_Reference, outpath: str | Path | None = None, override=False, gpu=None, **args):
-    """
-    Mahmutoglu, M.A., Rastogi, A., Schell, M. et al. Deep learning-based defacing tool for CT angiography: CTA-DEFACE. Eur Radiol Exp 8, 111 (2024). https://doi.org/10.1186/s41747-024-00510-9
-
-    """
+    """Mahmutoglu, M.A., Rastogi, A., Schell, M. et al. Deep learning-based defacing tool for CT angiography: CTA-DEFACE. Eur Radiol Exp 8, 111 (2024). https://doi.org/10.1186/s41747-024-00510-9."""
     if isinstance(outpath, str):
         outpath = Path(outpath)
     if isinstance(ct_img, BIDS_FILE) and outpath is None:
@@ -22,8 +19,7 @@ def _compute_deface_mask_cta(ct_img: Image_Reference, outpath: str | Path | None
 
 
 def _extend_mask(mask: NII, n: int, direction: DIRECTIONS = "A") -> NII:
-    """
-    Extend a binary mask n voxels further in anterior (A) direction.
+    """Extend a binary mask n voxels further in anterior (A) direction.
 
     Parameters
     ----------
@@ -32,12 +28,11 @@ def _extend_mask(mask: NII, n: int, direction: DIRECTIONS = "A") -> NII:
     n : int
         Number of voxels to extend beyond the most anterior voxel
 
-    Returns
+    Returns:
     -------
     NII
         Extended mask
     """
-
     m = mask.copy()
     arr = m.extract_label(1).get_array()
 
@@ -83,10 +78,7 @@ def _extend_mask(mask: NII, n: int, direction: DIRECTIONS = "A") -> NII:
 def compute_deface_mask_cta(
     ct_img: Image_Reference, outpath: str | Path | None = None, override=False, gpu=None, partially_defaced=False, **args
 ):
-    """
-    Mahmutoglu, M.A., Rastogi, A., Schell, M. et al. Deep learning-based defacing tool for CT angiography: CTA-DEFACE. Eur Radiol Exp 8, 111 (2024). https://doi.org/10.1186/s41747-024-00510-9
-
-    """
+    """Mahmutoglu, M.A., Rastogi, A., Schell, M. et al. Deep learning-based defacing tool for CT angiography: CTA-DEFACE. Eur Radiol Exp 8, 111 (2024). https://doi.org/10.1186/s41747-024-00510-9."""
     if isinstance(outpath, str):
         outpath = Path(outpath)
     if isinstance(ct_img, BIDS_FILE) and outpath is None:
diff --git a/TPTBox/segmentation/nnUnet_utils/data_iterators.py b/TPTBox/segmentation/nnUnet_utils/data_iterators.py
index 8d29137..0af5e95 100755
--- a/TPTBox/segmentation/nnUnet_utils/data_iterators.py
+++ b/TPTBox/segmentation/nnUnet_utils/data_iterators.py
@@ -12,6 +12,30 @@
 
 
 class PreprocessAdapterFromNpy(DataLoader):
+    """DataLoader adapter that preprocesses raw numpy arrays on-the-fly for nnU-Net inference.
+
+    Wraps a list of image arrays and their metadata into a
+    :class:`~batchgenerators.dataloading.data_loader.DataLoader` that applies
+    the full nnU-Net preprocessing pipeline (crop, normalise, resample) via
+    :class:`~TPTBox.segmentation.nnUnet_utils.default_preprocessor.DefaultPreprocessor`.
+
+    Args:
+        list_of_images: Image arrays, each with shape ``(C, X, Y, Z)``.
+        list_of_segs_from_prev_stage: Optional cascade segmentation arrays
+            (one per image) to be stacked as one-hot channels. Pass ``None``
+            for all entries when not using the cascade.
+        list_of_image_properties: Per-image property dicts containing at
+            least a ``'spacing'`` key.
+        truncated_of_names: Optional output file stems for each image (used
+            downstream for saving). Pass ``None`` when not needed.
+        plans_manager: Plans manager for the loaded model.
+        dataset_json: Parsed ``dataset.json`` dictionary.
+        configuration_manager: Configuration-specific preprocessing parameters.
+        num_threads_in_multithreaded: Number of worker threads (passed to the
+            underlying :class:`DataLoader`).
+        verbose: If ``True``, print preprocessing progress information.
+    """
+
     def __init__(
         self,
         list_of_images: list[np.ndarray],
@@ -52,7 +76,16 @@ def __init__(
 
         self.indices = list(range(len(list_of_images)))
 
-    def generate_train_batch(self):
+    def generate_train_batch(self) -> dict:
+        """Preprocess the next sample and return it as a data dictionary.
+
+        Returns:
+            A dict with keys:
+                - ``'data'``: preprocessed image tensor ``(C, X, Y, Z)``.
+                - ``'data_properites'``: updated properties dict with cropping
+                  and resampling metadata.
+                - ``'ofile'``: output file stem (may be ``None``).
+        """
         idx = self.get_indices()[0]
         image = self._data[idx][0]
         seg_prev_stage = self._data[idx][1]
@@ -76,17 +109,24 @@ def generate_train_batch(self):
 def convert_labelmap_to_one_hot(
     segmentation: np.ndarray | torch.Tensor, all_labels: list | torch.Tensor | np.ndarray | tuple, output_dtype=None
 ) -> np.ndarray | torch.Tensor:
-    """
-    if output_dtype is None then we use np.uint8/torch.uint8
-    if input is torch.Tensor then output will be on the same device
+    """Convert an integer label map to a one-hot encoded array.
 
-    np.ndarray is faster than torch.Tensor
+    Args:
+        segmentation: Integer label array/tensor with shape ``(X, Y, Z)``. When
+            a :class:`torch.Tensor`, using ``LongTensor`` avoids an extra cast.
+        all_labels: Ordered sequence of all label values to encode. Labels must
+            be **consecutive integers** starting from 0 (e.g. ``[0, 1, 2, 3]``).
+            Non-consecutive labels (e.g. ``[0, 32, 255]``) are **not** supported.
+        output_dtype: Desired dtype for the output. Defaults to
+            ``np.uint8`` / ``torch.uint8`` when ``None``.
 
-    if segmentation is torch.Tensor, this function will be faster if it is LongTensor. If it is something else we have
-    to cast which takes time.
+    Returns:
+        One-hot encoded array/tensor with shape
+        ``(len(all_labels), X, Y, Z)``, on the same device as the input when
+        ``segmentation`` is a :class:`torch.Tensor`.
 
-    IMPORTANT: This function only works properly if your labels are consecutive integers, so something like 0, 1, 2, 3, ...
-    DO NOT use it with 0, 32, 123, 255, ... or whatever (fix your labels, yo)
+    Note:
+        NumPy arrays are processed faster than Torch tensors in this function.
     """
     if isinstance(segmentation, torch.Tensor):
         result = torch.zeros(
diff --git a/TPTBox/segmentation/nnUnet_utils/default_preprocessor.py b/TPTBox/segmentation/nnUnet_utils/default_preprocessor.py
index 766bb98..c65e3f7 100755
--- a/TPTBox/segmentation/nnUnet_utils/default_preprocessor.py
+++ b/TPTBox/segmentation/nnUnet_utils/default_preprocessor.py
@@ -20,11 +20,14 @@
 
 
 class DefaultPreprocessor:
+    """Default nnU-Net preprocessor: crops, resamples, and normalises a single case.
+
+    All configuration is supplied at call time via the plans and configuration
+    managers; nothing dataset-specific is stored on the instance.
+    """
+
     def __init__(self, verbose: bool = True):
         self.verbose = verbose
-        """
-        Everything we need is in the plans. Those are given when run() is called
-        """
 
     def run_case_npy(
         self,
@@ -34,7 +37,28 @@ def run_case_npy(
         plans_manager: PlansManager,
         configuration_manager: ConfigurationManager,
         dataset_json: dict | str,
-    ):
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """Preprocess one case given as numpy arrays.
+
+        Applies (in order): axis transposition, non-zero cropping, intensity
+        normalisation, and resampling to the target spacing.
+
+        Args:
+            data: Image array with shape ``(C, X, Y, Z)``.
+            seg: Segmentation array with shape ``(1, X, Y, Z)``, or ``None``
+                when no ground-truth is available.
+            properties: Mutable properties dict that will be updated in-place
+                with cropping / resampling metadata (required by the inference
+                pipeline to revert preprocessing).
+            plans_manager: Plans manager providing transpose directions and
+                intensity properties.
+            configuration_manager: Configuration-specific parameters such as
+                target spacing, normalization schemes, and resampling functions.
+            dataset_json: Parsed ``dataset.json`` dict, or a path to it.
+
+        Returns:
+            A tuple ``(data, seg)`` of preprocessed arrays ready for the network.
+        """
         # let's not mess up the inputs!
         data = np.copy(data)
         if seg is not None:
@@ -107,7 +131,8 @@ def run_case_npy(
     @staticmethod
     def _sample_foreground_locations(
         seg: np.ndarray, classes_or_regions: list[int] | list[tuple[int, ...]], seed: int = 1234, verbose: bool = False
-    ):
+    ) -> dict:
+        """Sample foreground voxel coordinates per class for oversampling during training."""
         num_samples = 10000
         min_percent_coverage = 0.01  # at least 1% of the class voxels need to be selected, otherwise it may be too
         # sparse
@@ -141,6 +166,7 @@ def _normalize(
         configuration_manager: ConfigurationManager,
         foreground_intensity_properties_per_channel: dict,
     ) -> np.ndarray:
+        """Apply per-channel intensity normalisation using the scheme specified in the configuration."""
         for c in range(data.shape[0]):
             scheme = configuration_manager.normalization_schemes[c]
 
@@ -165,6 +191,20 @@ def modify_seg_fn(
         dataset_json: dict,  # noqa: ARG002
         configuration_manager: ConfigurationManager,  # noqa: ARG002
     ) -> np.ndarray:
+        """Post-process the segmentation after resampling (identity by default).
+
+        Subclasses can override this to introduce label modifications (e.g.
+        sparse annotation experiments) without creating a new dataset.
+
+        Args:
+            seg: Resampled segmentation array.
+            plans_manager: Plans manager instance (unused in the base class).
+            dataset_json: Dataset metadata dict (unused in the base class).
+            configuration_manager: Configuration manager (unused in the base class).
+
+        Returns:
+            The (optionally modified) segmentation array.
+        """
         # this function will be called at the end of self.run_case. Can be used to change the segmentation
         # after resampling. Useful for experimenting with sparse annotations: I can introduce sparsity after resampling
         # and don't have to create a new dataset each time I modify my experiments
@@ -176,19 +216,36 @@ def compute_new_shape(
     old_spacing: tuple[float, ...] | list[float] | np.ndarray,
     new_spacing: tuple[float, ...] | list[float] | np.ndarray,
 ) -> np.ndarray:
+    """Compute the resampled image shape for a given spacing change.
+
+    Args:
+        old_shape: Spatial dimensions of the original image.
+        old_spacing: Voxel spacing (mm) of the original image.
+        new_spacing: Target voxel spacing (mm) after resampling.
+
+    Returns:
+        Integer array with the new spatial shape such that the physical extent
+        of the volume is preserved.
+    """
     assert len(old_spacing) == len(old_shape)
     assert len(old_shape) == len(new_spacing)
     new_shape = np.array([round(i / j * k) for i, j, k in zip(old_spacing, new_spacing, old_shape)])
     return new_shape
 
 
-def crop_to_nonzero(data, seg=None, nonzero_label=-1):
-    """
+def crop_to_nonzero(data: np.ndarray, seg: np.ndarray | None = None, nonzero_label: int = -1) -> tuple:
+    """Crop image and segmentation to the bounding box of non-zero image voxels.
+
+    Args:
+        data: Image array with shape ``(C, X, Y, Z)``.
+        seg: Optional segmentation array with the same spatial shape. Voxels
+            outside the non-zero mask receive ``nonzero_label``.
+        nonzero_label: Label value written into segmentation voxels that lie
+            outside the non-zero foreground mask.
 
-    :param data:
-    :param seg:
-    :param nonzero_label: this will be written into the segmentation map
-    :return:
+    Returns:
+        A tuple ``(data, seg, bbox)`` where ``data`` and ``seg`` are cropped
+        arrays and ``bbox`` is the bounding-box used for cropping.
     """
     nonzero_mask = create_nonzero_mask(data)
     bbox = get_bbox_from_mask(nonzero_mask)  # type: ignore
@@ -210,11 +267,16 @@ def crop_to_nonzero(data, seg=None, nonzero_label=-1):
     return data, seg, bbox
 
 
-def create_nonzero_mask(data):
-    """
+def create_nonzero_mask(data: np.ndarray) -> np.ndarray:
+    """Create a boolean mask that is ``True`` wherever any channel is non-zero.
+
+    Args:
+        data: Array with shape ``(C, X, Y, Z)`` or ``(C, X, Y)``.
 
-    :param data:
-    :return: the mask is True where the data is nonzero
+    Returns:
+        Boolean array with shape ``(X, Y, Z)`` (or ``(X, Y)``), filled with
+        ``True`` at voxels where at least one channel is non-zero. Holes in
+        the mask are filled with :func:`scipy.ndimage.binary_fill_holes`.
     """
     from scipy.ndimage import binary_fill_holes
 
diff --git a/TPTBox/segmentation/nnUnet_utils/export_prediction.py b/TPTBox/segmentation/nnUnet_utils/export_prediction.py
index 0163453..36ca786 100755
--- a/TPTBox/segmentation/nnUnet_utils/export_prediction.py
+++ b/TPTBox/segmentation/nnUnet_utils/export_prediction.py
@@ -20,7 +20,35 @@ def convert_predicted_logits_to_segmentation_with_correct_shape(
     properties_dict: dict,
     return_probabilities: bool = False,
     num_threads_torch: int = 8,
-):
+) -> np.ndarray:
+    """Revert all preprocessing steps and return a segmentation in the original image space.
+
+    Performs (in reverse order): resampling from network output spacing back to
+    the cropped shape, argmax / softmax conversion, padding to the pre-crop
+    shape, and axis transposition to restore the original orientation.
+
+    Args:
+        predicted_logits: Raw network output with shape
+            ``(num_classes, X', Y', Z')`` in the *preprocessed* space.
+        plans_manager: Plans manager carrying transpose information.
+        configuration_manager: Configuration manager carrying spacing and
+            resampling function references.
+        label_manager: Label manager used for converting logits to a
+            segmentation map.
+        properties_dict: Case properties dict as updated by
+            :meth:`DefaultPreprocessor.run_case_npy` (contains cropping bbox,
+            pre-crop shape, and original spacing).
+        return_probabilities: Reserved for future use. Raises
+            :class:`NotImplementedError` if ``True``.
+        num_threads_torch: Number of threads used by PyTorch during resampling.
+
+    Returns:
+        Integer segmentation array with dtype ``np.uint8`` or ``np.uint16``
+        in the original image space (before any preprocessing).
+
+    Raises:
+        NotImplementedError: If ``return_probabilities`` is ``True``.
+    """
     if return_probabilities:
         raise NotImplementedError()
     old_threads = torch.get_num_threads()
@@ -95,7 +123,30 @@ def export_prediction_from_logits(
     dataset_json_dict_or_file: dict | str,
     output_file_truncated: str,
     save_probabilities: bool = False,
-):
+) -> None:
+    """Convert logits to a segmentation and write it to disk.
+
+    Delegates shape reversion to
+    :func:`convert_predicted_logits_to_segmentation_with_correct_shape` and
+    then writes the result using the image reader/writer defined in the plans.
+
+    Args:
+        predicted_array_or_file: Raw logits array/tensor in the preprocessed
+            image space.
+        properties_dict: Case properties dict containing cropping and resampling
+            metadata.
+        configuration_manager: Configuration manager for the active plans
+            configuration.
+        plans_manager: Plans manager (provides image writer class and transpose
+            directions).
+        dataset_json_dict_or_file: Either a parsed ``dataset.json`` dict or a
+            path to the file.
+        output_file_truncated: Output path **without** file extension. The
+            correct extension is appended automatically from ``dataset_json``.
+        save_probabilities: If ``True``, also save softmax probability maps as
+            ``.npz``. Currently raises :class:`NotImplementedError` inside the
+            conversion step.
+    """
     # if isinstance(predicted_array_or_file, str):
     #     tmp = deepcopy(predicted_array_or_file)
     #     if predicted_array_or_file.endswith('.npy'):
diff --git a/TPTBox/segmentation/nnUnet_utils/get_network_from_plans.py b/TPTBox/segmentation/nnUnet_utils/get_network_from_plans.py
index b49e192..a7ae619 100755
--- a/TPTBox/segmentation/nnUnet_utils/get_network_from_plans.py
+++ b/TPTBox/segmentation/nnUnet_utils/get_network_from_plans.py
@@ -18,9 +18,8 @@ def get_network_from_plans(
     num_input_channels: int,
     num_output_channels: int | None = None,
     deep_supervision: bool = True,
-):
-    """
-    we may have to change this in the future to accommodate other plans -> network mappings
+) -> nn.Module:
+    """We may have to change this in the future to accommodate other plans -> network mappings.
 
     num_input_channels can differ depending on whether we do cascade. Its best to make this info available in the
     trainer rather than inferring it again from the plans here.
diff --git a/TPTBox/segmentation/nnUnet_utils/inference_api.py b/TPTBox/segmentation/nnUnet_utils/inference_api.py
index 4f2c774..4913952 100755
--- a/TPTBox/segmentation/nnUnet_utils/inference_api.py
+++ b/TPTBox/segmentation/nnUnet_utils/inference_api.py
@@ -29,28 +29,43 @@ def load_inf_model(
     init_threads: bool = True,
     allow_non_final: bool = True,
     inference_augmentation: bool = False,
-    use_gaussian=True,
+    use_gaussian: bool = True,
     verbose: bool = False,
-    gpu=None,
-    memory_base=5000,  # Base memory in MB, default is 5GB
-    memory_factor=160,  # prod(shape)*memory_factor / 1000, 160 ~> 30 GB
-    memory_max=160000,  # in MB, default is 160GB
-    wait_till_gpu_percent_is_free=0.3,
+    gpu: int | None = None,
+    memory_base: int = 5000,
+    memory_factor: int = 160,
+    memory_max: int = 160000,
+    wait_till_gpu_percent_is_free: float = 0.3,
 ) -> nnUNetPredictor:
-    """Loads the Nako-Segmentor Model Predictor
+    """Load and initialise an nnU-Net model predictor from a trained model folder.
 
     Args:
-        model_folder (str, optional): nnUNet Result Model Folder containing the "fold_x" directories. Default to the basic folder
-        step_size (float, optional): Step size for sliding window prediction. The larger it is the faster but less accurate "
-        "the prediction. Default: 0.5. Cannot be larger than 1.
-        ddevice (str, optional): The device the inference should run with. Available options are 'cuda' "
-        "(GPU), 'cpu' (CPU) and 'mps' (Apple M1/M2). Do NOT use this to set which GPU ID!. Defaults to "cuda".
-        memory_base (int, optional): Base memory in MB for the model. Default is 5000 MB (5GB).
-        memory_factor (int, optional): Memory factor for the model. Default is 160, which is ~30GB for a 512x512x512 image.
-        memory_max (int, optional): Maximum memory in MB for the model. Default is 160000 MB (160GB).
+        model_folder: Path to the nnU-Net result folder containing ``fold_*``
+            sub-directories.
+        step_size: Sliding-window step size as a fraction of the patch size.
+            Larger values are faster but may reduce accuracy.  Must be in (0, 1].
+        ddevice: Inference device: ``"cuda"`` (GPU), ``"cpu"``, or ``"mps"``
+            (Apple Silicon).  Do NOT use this to select a GPU index.
+        use_folds: Tuple of fold indices or fold names to load.  Loads all
+            available folds when ``None``.
+        init_threads: If True, configure PyTorch thread counts optimally for the
+            selected device.
+        allow_non_final: If True, fall back to ``checkpoint_best.pth`` when
+            ``checkpoint_final.pth`` is not found.
+        inference_augmentation: If True, enable test-time mirroring augmentation.
+        use_gaussian: If True, apply Gaussian weighting in the sliding window.
+        verbose: If True, print progress information during model initialisation.
+        gpu: GPU device index forwarded to the predictor.  ``None`` defaults to 0.
+        memory_base: Base GPU memory reservation in MB (default 5 000 MB = 5 GB).
+        memory_factor: Per-voxel memory scaling factor.  The formula is
+            ``prod(shape) * memory_factor / 1000`` MB; 160 corresponds to ~30 GB
+            for a 512³ volume.
+        memory_max: Maximum GPU memory cap in MB (default 160 000 MB = 160 GB).
+        wait_till_gpu_percent_is_free: Fraction of GPU memory that must be free
+            before inference is started.
 
     Returns:
-        predictor: Loaded model predictor object
+        Initialised ``nnUNetPredictor`` ready for inference.
     """
     if isinstance(model_folder, str):
         model_folder = Path(model_folder)
@@ -113,20 +128,28 @@ def run_inference(
     input_nii: str | NII | list[NII],
     predictor: nnUNetPredictor,
     reorient_PIR: bool = False,  # noqa: N803
-    logits=False,
-    verbose=False,  # noqa: ARG001
+    logits: bool = False,
+    verbose: bool = False,  # noqa: ARG001
 ) -> tuple[NII, NII | None, np.ndarray | None]:
-    """Runs nnUnet model inference on one input.
+    """Run nnU-Net inference on a single image or list of images (multi-channel).
 
     Args:
-        input (str | NII): Path to a nifty file or a NII object.
-        predictor (_type_, optional): Loaded model predictor. If none, will load the default one. Defaults to None.
+        input_nii: Input as a path to a ``.nii.gz`` file, a ``NII`` object, or a
+            list of ``NII`` objects for multi-channel models.
+        predictor: Loaded ``nnUNetPredictor`` as returned by :func:`load_inf_model`.
+        reorient_PIR: If True, reorient each input image to PIR orientation before
+            passing it to the model.
+        logits: If True, return raw softmax logits.  Currently not implemented and
+            will raise ``NotImplementedError``.
+        verbose: Unused; reserved for future logging support.
 
     Raises:
-        AssertionError: If the input is not of expected type
+        NotImplementedError: If *logits* is True.
+        AssertionError: If *input_nii* is not a supported type, or if the output
+            shape does not match the input shape.
 
     Returns:
-        Segmentation (NII), Uncertainty Map (NII), Softmax Logits (numpy arr)
+        A tuple of (segmentation_NII, uncertainty_map_or_None, softmax_logits_or_None).
     """
     if logits:
         raise NotImplementedError("logits=True")
@@ -177,7 +200,20 @@ def run_inference(
 #    return sliding_nd_slices(img, patch_size=patch_size, overlap=overlap, fun=fun)[0], None
 
 
-def sliding_nd_slices(arr: np.ndarray, patch_size, overlap, fun):
+def sliding_nd_slices(arr: np.ndarray, patch_size: tuple, overlap: int, fun) -> np.ndarray:
+    """Apply *fun* to an N-D array using a sliding-window strategy with overlap.
+
+    Args:
+        arr: Input array to process.
+        patch_size: Size of each patch along every dimension.
+        overlap: Number of voxels to overlap between adjacent patches (symmetric).
+        fun: Callable applied to each patch; must return an array with the same
+            shape as its input.
+
+    Returns:
+        Reconstructed array of the same shape as *arr* with patch outputs stitched
+        together (overlap regions are overwritten by the most recent patch).
+    """
     print("sliding window")
     step = tuple(p - overlap for p in patch_size)
     half_overlap = overlap // 2
diff --git a/TPTBox/segmentation/nnUnet_utils/plans_handler.py b/TPTBox/segmentation/nnUnet_utils/plans_handler.py
index d9f88d2..8a94351 100755
--- a/TPTBox/segmentation/nnUnet_utils/plans_handler.py
+++ b/TPTBox/segmentation/nnUnet_utils/plans_handler.py
@@ -29,6 +29,13 @@
 
 
 class ConfigurationManager:
+    """Manages a single nnU-Net configuration dictionary, exposing its fields as typed properties.
+
+    Wraps a configuration dict (one entry from the ``configurations`` block of a
+    ``plans.json`` file) and resolves all keys through typed properties so that
+    callers receive properly typed values instead of raw dict lookups.
+    """
+
     def __init__(self, configuration_dict: dict):
         self.configuration = configuration_dict
 
@@ -37,15 +44,18 @@ def __repr__(self):
 
     @property
     def data_identifier(self) -> str:
+        """Unique string identifier for the preprocessed data folder."""
         return self.configuration["data_identifier"]
 
     @property
     def preprocessor_name(self) -> str:
+        """Class name of the preprocessor used for this configuration."""
         return self.configuration["preprocessor_name"]
 
     @property
     @lru_cache(maxsize=1)  # noqa: B019
     def preprocessor_class(self) -> type[DefaultPreprocessor]:
+        """Resolved preprocessor class object, looked up by name inside nnunetv2."""
         preprocessor_class = recursive_find_python_class(
             join(nnunetv2.__path__[0], "preprocessing"),  # type: ignore
             self.preprocessor_name,
@@ -55,35 +65,47 @@ def preprocessor_class(self) -> type[DefaultPreprocessor]:
 
     @property
     def batch_size(self) -> int:
+        """Training batch size for this configuration."""
         return self.configuration["batch_size"]
 
     @property
     def patch_size(self) -> list[int]:
+        """Patch size (in voxels) used during training and inference sliding-window."""
         return self.configuration["patch_size"]
 
     @property
     def median_image_size_in_voxels(self) -> list[int]:
+        """Median image size (in voxels) of the training dataset after resampling."""
         return self.configuration["median_image_size_in_voxels"]
 
     @property
     def spacing(self) -> list[float]:
+        """Target voxel spacing (mm) for this configuration."""
         return self.configuration["spacing"]
 
     @property
     def normalization_schemes(self) -> list[str]:
+        """Per-channel normalization scheme names (e.g. ``CTNormalization``)."""
         return self.configuration["normalization_schemes"]
 
     @property
     def use_mask_for_norm(self) -> list[bool]:
+        """Per-channel flags indicating whether the nonzero mask is used during normalization."""
         return self.configuration["use_mask_for_norm"]
 
     @property
     def UNet_class_name(self) -> str:
+        """Class name of the U-Net architecture used for this configuration."""
         return self.configuration["UNet_class_name"]
 
     @property
     @lru_cache(maxsize=1)  # noqa: B019
     def UNet_class(self) -> type[nn.Module]:
+        """Resolved U-Net class object, looked up inside dynamic_network_architectures.
+
+        Raises:
+            RuntimeError: If the class name cannot be found in the architectures package.
+        """
         unet_class = recursive_find_python_class(
             join(dynamic_network_architectures.__path__[0], "architectures"),  # type: ignore
             self.UNet_class_name,
@@ -100,30 +122,37 @@ def UNet_class(self) -> type[nn.Module]:
 
     @property
     def UNet_base_num_features(self) -> int:
+        """Base number of feature maps for the U-Net encoder/decoder."""
         return self.configuration["UNet_base_num_features"]
 
     @property
     def n_conv_per_stage_encoder(self) -> list[int]:
+        """Number of convolutions per encoder stage."""
         return self.configuration["n_conv_per_stage_encoder"]
 
     @property
     def n_conv_per_stage_decoder(self) -> list[int]:
+        """Number of convolutions per decoder stage."""
         return self.configuration["n_conv_per_stage_decoder"]
 
     @property
     def num_pool_per_axis(self) -> list[int]:
+        """Number of pooling operations applied along each spatial axis."""
         return self.configuration["num_pool_per_axis"]
 
     @property
     def pool_op_kernel_sizes(self) -> list[list[int]]:
+        """Kernel sizes for each pooling operation across all stages."""
         return self.configuration["pool_op_kernel_sizes"]
 
     @property
     def conv_kernel_sizes(self) -> list[list[int]]:
+        """Convolution kernel sizes for each stage."""
         return self.configuration["conv_kernel_sizes"]
 
     @property
     def unet_max_num_features(self) -> int:
+        """Maximum number of feature maps at any U-Net stage."""
         return self.configuration["unet_max_num_features"]
 
     @property
@@ -139,6 +168,7 @@ def resampling_fn_data(
         ],
         torch.Tensor | np.ndarray,
     ]:
+        """Resampling callable for image data, pre-bound with configuration kwargs."""
         fn = recursive_find_resampling_fn_by_name(self.configuration["resampling_fn_data"])
         fn = partial(fn, **self.configuration["resampling_fn_data_kwargs"])
         return fn
@@ -156,6 +186,7 @@ def resampling_fn_probabilities(
         ],
         torch.Tensor | np.ndarray,
     ]:
+        """Resampling callable for predicted probability maps, pre-bound with configuration kwargs."""
         fn = recursive_find_resampling_fn_by_name(self.configuration["resampling_fn_probabilities"])
         fn = partial(fn, **self.configuration["resampling_fn_probabilities_kwargs"])
         return fn
@@ -173,16 +204,19 @@ def resampling_fn_seg(
         ],
         torch.Tensor | np.ndarray,
     ]:
+        """Resampling callable for segmentation masks, pre-bound with configuration kwargs."""
         fn = recursive_find_resampling_fn_by_name(self.configuration["resampling_fn_seg"])
         fn = partial(fn, **self.configuration["resampling_fn_seg_kwargs"])
         return fn
 
     @property
     def batch_dice(self) -> bool:
+        """Whether batch dice loss is used during training."""
         return self.configuration["batch_dice"]
 
     @property
     def next_stage_names(self) -> list[str] | None:
+        """Names of the next cascade stage configurations, if any."""
         ret = self.configuration.get("next_stage")
         if ret is not None and isinstance(ret, str):
             ret = [ret]
@@ -190,20 +224,28 @@ def next_stage_names(self) -> list[str] | None:
 
     @property
     def previous_stage_name(self) -> str | None:
+        """Name of the previous cascade stage configuration, if any."""
         return self.configuration.get("previous_stage")
 
 
 class PlansManager:
+    """High-level interface to the nnU-Net ``plans.json`` file.
+
+    Responsibilities:
+        1. Resolve inheritance chains among configurations.
+        2. Expose label manager and image I/O classes by name.
+        3. Provide clearly typed access to plan fields rather than raw dict lookups.
+        4. Cache expensive lookups (class resolution, label managers, etc.).
+
+    Direct dict access is still possible via ``PlansManager.plans['key']``.
+    """
+
     def __init__(self, plans_file_or_dict: str | dict):
-        """
-        Why do we need this?
-        1) resolve inheritance in configurations
-        2) expose otherwise annoying stuff like getting the label manager or IO class from a string
-        3) clearly expose the things that are in the plans instead of hiding them in a dict
-        4) cache shit
-
-        This class does not prevent you from going wild. You can still use the plans directly if you prefer
-        (PlansHandler.plans['key'])
+        """Initialize the PlansManager from a JSON file path or a pre-loaded dict.
+
+        Args:
+            plans_file_or_dict: Either a path to a ``plans.json`` file or an
+                already-loaded dictionary representing that file.
         """
         self.plans = plans_file_or_dict if isinstance(plans_file_or_dict, dict) else load_json(plans_file_or_dict)
 
@@ -211,10 +253,11 @@ def __repr__(self):
         return self.plans.__repr__()
 
     def _internal_resolve_configuration_inheritance(self, configuration_name: str, visited: tuple[str, ...] | None = None) -> dict:
+        """Recursively resolve inherited configuration keys and merge them bottom-up."""
         if configuration_name not in self.plans["configurations"].keys():
             raise ValueError(
                 f"The configuration {configuration_name} does not exist in the plans I have. Valid "
-                f'configuration names are {list(self.plans["configurations"].keys())}.'
+                f"configuration names are {list(self.plans['configurations'].keys())}."
             )
         configuration = deepcopy(self.plans["configurations"][configuration_name])
         if "inherits_from" in configuration:
@@ -238,7 +281,19 @@ def _internal_resolve_configuration_inheritance(self, configuration_name: str, v
         return configuration
 
     @lru_cache(maxsize=10)  # noqa: B019
-    def get_configuration(self, configuration_name: str):
+    def get_configuration(self, configuration_name: str) -> ConfigurationManager:
+        """Return a :class:`ConfigurationManager` for the requested configuration.
+
+        Args:
+            configuration_name: Key into the ``configurations`` block of the plans.
+
+        Returns:
+            A :class:`ConfigurationManager` wrapping the fully-resolved configuration
+            dict (inheritance already applied).
+
+        Raises:
+            RuntimeError: If ``configuration_name`` is not present in the plans.
+        """
         if configuration_name not in self.plans["configurations"].keys():
             raise RuntimeError(
                 f"Requested configuration {configuration_name} not found in plans. "
@@ -250,40 +305,49 @@ def get_configuration(self, configuration_name: str):
 
     @property
     def dataset_name(self) -> str:
+        """Name of the dataset as stored in the plans file."""
         return self.plans["dataset_name"]
 
     @property
     def plans_name(self) -> str:
+        """Identifier string for this set of plans."""
         return self.plans["plans_name"]
 
     @property
     def original_median_spacing_after_transp(self) -> list[float]:
+        """Median voxel spacing (mm) of the training data after applying transpose_forward."""
         return self.plans["original_median_spacing_after_transp"]
 
     @property
     def original_median_shape_after_transp(self) -> list[float]:
+        """Median image shape (voxels) of the training data after applying transpose_forward."""
         return self.plans["original_median_shape_after_transp"]
 
     @property
     @lru_cache(maxsize=1)  # noqa: B019
     def image_reader_writer_class(self) -> type[BaseReaderWriter]:
+        """Resolved image reader/writer class used for I/O during inference."""
         return recursive_find_reader_writer_by_name(self.plans["image_reader_writer"])
 
     @property
     def transpose_forward(self) -> list[int]:
+        """Axis permutation applied to images before preprocessing (data -> network)."""
         return self.plans["transpose_forward"]
 
     @property
     def transpose_backward(self) -> list[int]:
+        """Axis permutation applied to predictions to restore original orientation."""
         return self.plans["transpose_backward"]
 
     @property
     def available_configurations(self) -> list[str]:
+        """Names of all configurations defined in this plans file."""
         return list(self.plans["configurations"].keys())
 
     @property
     @lru_cache(maxsize=1)  # noqa: B019
     def experiment_planner_class(self) -> type[ExperimentPlanner]:
+        """Resolved experiment planner class that generated these plans."""
         planner_name = self.experiment_planner_name
         experiment_planner = recursive_find_python_class(
             join(nnunetv2.__path__[0], "experiment_planning"),  # type: ignore
@@ -294,20 +358,34 @@ def experiment_planner_class(self) -> type[ExperimentPlanner]:
 
     @property
     def experiment_planner_name(self) -> str:
+        """Class name of the experiment planner that produced these plans."""
         return self.plans["experiment_planner_used"]
 
     @property
     @lru_cache(maxsize=1)  # noqa: B019
     def label_manager_class(self) -> type[LabelManager]:
+        """Resolved LabelManager class appropriate for this plans file."""
         return get_labelmanager_class_from_plans(self.plans)
 
     def get_label_manager(self, dataset_json: dict, **kwargs) -> LabelManager:
+        """Instantiate and return a LabelManager for the given dataset JSON.
+
+        Args:
+            dataset_json: Parsed ``dataset.json`` dictionary containing ``labels``
+                and optionally ``regions_class_order``.
+            **kwargs: Additional keyword arguments forwarded to the LabelManager
+                constructor.
+
+        Returns:
+            A configured :class:`LabelManager` instance.
+        """
         return self.label_manager_class(
             label_dict=dataset_json["labels"], regions_class_order=dataset_json.get("regions_class_order"), **kwargs
         )
 
     @property
     def foreground_intensity_properties_per_channel(self) -> dict:
+        """Per-channel foreground intensity statistics (min, max, mean, std, etc.)."""
         if "foreground_intensity_properties_per_channel" not in self.plans.keys():  # noqa: SIM102
             if "foreground_intensity_properties_by_modality" in self.plans.keys():
                 return self.plans["foreground_intensity_properties_by_modality"]
diff --git a/TPTBox/segmentation/nnUnet_utils/predictor.py b/TPTBox/segmentation/nnUnet_utils/predictor.py
index 6d36d2b..eb654e9 100755
--- a/TPTBox/segmentation/nnUnet_utils/predictor.py
+++ b/TPTBox/segmentation/nnUnet_utils/predictor.py
@@ -6,6 +6,7 @@
 import os
 import time
 import traceback
+from collections.abc import Generator
 from dataclasses import dataclass, field
 from math import ceil, floor
 
@@ -26,19 +27,51 @@
 from TPTBox.segmentation.nnUnet_utils.sliding_window_prediction import compute_gaussian, compute_steps_for_sliding_window
 
 
-def get_gpu_memory_MB(device):
+def get_gpu_memory_MB(device) -> float:
+    """Return the amount of free GPU memory in megabytes for the given device."""
     free, total = torch.cuda.mem_get_info(device)
     # print(f"{free=}", f"{total=}")
     return free / 1024**2
 
 
-def get_gpu_util(device):
+def get_gpu_util(device) -> float:
+    """Return the fraction of GPU memory currently in use (0.0 = idle, 1.0 = full)."""
     free, total = torch.cuda.mem_get_info(device)
     # print(f"{free=}", f"{total=}")
     return 1 - free / total
 
 
 class nnUNetPredictor:
+    """Sliding-window inference engine for nnU-Net v2 (and legacy v1) models.
+
+    Handles model loading, fold averaging, GPU memory management (automatic
+    fall-back to CPU), optional test-time mirroring, and conversion of raw
+    logits back to label maps in the original image space.
+
+    Args:
+        tile_step_size: Fractional step between consecutive sliding-window tiles
+            (0 < value <= 1). Smaller values yield more overlap and smoother
+            predictions at the cost of speed.
+        use_gaussian: If ``True``, weight predictions by a Gaussian kernel to
+            up-weight the tile center and down-weight borders.
+        use_mirroring: If ``True``, apply test-time augmentation by averaging
+            predictions over all axis flips defined in
+            ``allowed_mirroring_axes``.
+        perform_everything_on_gpu: If ``True``, keep aggregation tensors on the
+            GPU. Falls back to CPU on ``RuntimeError`` (OOM).
+        device: PyTorch device to run inference on.
+        cuda_id: CUDA device index (used when ``device`` is ``"cuda"``).
+        verbose: Print progress messages during inference.
+        verbose_preprocessing: Print preprocessing details.
+        allow_tqdm: Show a tqdm progress bar during sliding-window inference.
+        memory_base: Minimum GPU memory (MB) required before scheduling a tile.
+        memory_factor: Scales the estimated memory footprint with
+            ``np.prod(shape) / 1e6 * memory_factor``.
+        memory_max: Clamp on maximum GPU memory (MB) to assume available.
+        wait_till_gpu_percent_is_free: Fraction of GPU memory that must be free
+            before inference starts. Waits up to 40 minutes.
+    """
+
     def __init__(
         self,
         tile_step_size: float = 0.5,
@@ -92,9 +125,23 @@ def initialize_from_trained_model_folder(
         use_folds: tuple[int | str, ...] | None,
         checkpoint_name: str = "checkpoint_final.pth",
         cache_state_dicts: bool = True,
-    ):
-        """
-        This is used when making predictions with a trained model
+    ) -> None:
+        """Load model weights and plans from a trained nnU-Net output directory.
+
+        Supports both nnU-Net v1 (``plans.pkl``) and v2 (``plans.json``) models.
+        After calling this method the predictor is ready for inference.
+
+        Args:
+            model_training_output_dir: Root directory of the trained model
+                (contains ``plans.json``/``plans.pkl`` and per-fold sub-directories).
+            use_folds: Tuple of fold identifiers (int or ``"all"``) whose
+                checkpoints are averaged during inference. If ``None``, folds
+                0-4 are used.
+            checkpoint_name: Filename of the checkpoint inside each fold
+                directory.
+            cache_state_dicts: If ``True``, load all fold weights onto the
+                device up-front and cache the network instances. Reduces
+                per-sample latency at the cost of GPU memory.
         """
         if isinstance(use_folds, str):
             use_folds = [use_folds]  # type: ignore
@@ -252,9 +299,23 @@ def mapp(d: dict):
                 self.loaded_networks.append(self.network)
         # print(type(self.loaded_networks[0]))
 
-    def predict_single_npy_array(self, input_image: np.ndarray, image_properties: dict, save_or_return_probabilities: bool = False):
-        """
-        image_properties must only have a 'spacing' key!
+    def predict_single_npy_array(
+        self, input_image: np.ndarray, image_properties: dict, save_or_return_probabilities: bool = False
+    ) -> np.ndarray:
+        """Run full inference on a single numpy image array.
+
+        Args:
+            input_image: Image array with shape ``(C, X, Y, Z)`` where ``C`` is
+                the number of input channels.
+            image_properties: Dictionary that must contain a ``'spacing'`` key
+                with the voxel spacing in mm (list/tuple of floats).
+            save_or_return_probabilities: If ``True``, also return softmax
+                probabilities in addition to the label map. Currently raises
+                :class:`NotImplementedError` inside the conversion step.
+
+        Returns:
+            The predicted segmentation array (or a tuple with probabilities if
+            ``save_or_return_probabilities`` is ``True``).
         """
         segmentation_previous_stage: np.ndarray = None  # type: ignore # Was previously a parameter
 
@@ -292,13 +353,27 @@ def predict_single_npy_array(self, input_image: np.ndarray, image_properties: di
 
         return ret
 
-    def predict_logits_from_preprocessed_data(self, data: torch.Tensor, attempts=10) -> torch.Tensor:
-        """
-        IMPORTANT! IF YOU ARE RUNNING THE CASCADE, THE SEGMENTATION FROM THE PREVIOUS STAGE MUST ALREADY BE STACKED ON
-        TOP OF THE IMAGE AS ONE-HOT REPRESENTATION! SEE PreprocessAdapter ON HOW THIS SHOULD BE DONE!
+    def predict_logits_from_preprocessed_data(self, data: torch.Tensor, attempts: int = 10) -> torch.Tensor:
+        """Run sliding-window inference on already-preprocessed data and average across folds.
+
+        If running the cascade, the previous-stage segmentation must already be
+        stacked on top of the image as a one-hot representation (see
+        :class:`PreprocessAdapterFromNpy`).
+
+        The returned logits have the shape of the (preprocessed) input and must
+        be converted back to the original image size via
+        :func:`convert_predicted_logits_to_segmentation_with_correct_shape`.
+
+        Args:
+            data: Preprocessed image tensor with shape ``(C, X, Y, Z)``.
+            attempts: Number of retry attempts on GPU OOM before raising.
+
+        Returns:
+            Averaged raw logits tensor with shape
+            ``(num_classes, X, Y, Z)`` on CPU.
 
-        RETURNED LOGITS HAVE THE SHAPE OF THE INPUT. THEY MUST BE CONVERTED BACK TO THE ORIGINAL IMAGE SIZE.
-        SEE convert_predicted_logits_to_segmentation_with_correct_shape
+        Raises:
+            RuntimeError: If inference fails even after all retry attempts.
         """
         # USED
 
@@ -386,6 +461,7 @@ def predict_logits_from_preprocessed_data(self, data: torch.Tensor, attempts=10)
         return prediction  # type: ignore
 
     def _internal_get_sliding_window_slicers(self, image_size: tuple[int, ...]) -> list[tuple[slice, ...]]:
+        """Compute all tile slicers needed to cover the image with the configured patch size and step."""
         # USED
         slicers = []
         assert self.configuration_manager is not None
@@ -428,6 +504,7 @@ def _internal_get_sliding_window_slicers(self, image_size: tuple[int, ...]) -> l
         return slicers
 
     def _internal_maybe_mirror_and_predict(self, x: torch.Tensor, network) -> torch.Tensor:
+        """Run network forward pass and optionally accumulate flipped predictions for TTA."""
         if self.do_not_use_half_precision:
             x = x.float()
         # USED
@@ -458,6 +535,17 @@ def _internal_maybe_mirror_and_predict(self, x: torch.Tensor, network) -> torch.
         return prediction
 
     def predict_sliding_window_return_logits(self, input_image: torch.Tensor, network=None) -> np.ndarray | torch.Tensor:
+        """Tile the input image and aggregate per-tile logits into a full-volume prediction.
+
+        Args:
+            input_image: Image tensor with shape ``(C, X, Y, Z)``.
+            network: Optional network instance to use. Defaults to
+                ``self.network``.
+
+        Returns:
+            Aggregated logit array with shape ``(num_classes, X, Y, Z)``
+            cropped back to the original (un-padded) image size.
+        """
         # USED
         assert isinstance(input_image, torch.Tensor)
         if network is None:
@@ -572,6 +660,7 @@ def _run_prediction_splits(
         slicers: list[tuple[slice, ...]],
         pbar: tqdm,
     ):
+        """Run tiled inference by splitting the volume into spatial chunks to fit GPU memory."""
         widths = [ceil(s / sp) for s, sp in zip(global_shape, splits)]
         inter_mediate_slice: list[intermediate_slice] = []
         pbar.desc = "split in to GPU chunks"
@@ -614,7 +703,8 @@ def _run_prediction_splits(
         empty_cache(self.device)
         return predicted_logits
 
-    def _allocate(self, data: torch.Tensor, results_device, pbar: tqdm, gauss=True):
+    def _allocate(self, data: torch.Tensor, results_device, pbar: tqdm, gauss: bool = True):
+        """Pre-allocate output logit and count tensors; falls back to CPU on OOM."""
         pbar.desc = "preallocating arrays"
         pbar.update(0)
         try:
@@ -658,7 +748,8 @@ def _allocate(self, data: torch.Tensor, results_device, pbar: tqdm, gauss=True):
         #    empty_cache(self.device)
         return predicted_logits, n_predictions, gaussian, results_device
 
-    def _run_sub(self, data: torch.Tensor, network, results_device, slicers, pbar: tqdm, addendum=""):
+    def _run_sub(self, data: torch.Tensor, network, results_device, slicers, pbar: tqdm, addendum: str = ""):
+        """Iterate over slicers, run inference per tile, and accumulate results."""
         try:
             data = data.to(self.device)  # type: ignore
             predicted_logits, n_predictions, gaussian, results_device = self._allocate(data, results_device, pbar)
@@ -690,12 +781,26 @@ def _run_sub(self, data: torch.Tensor, network, results_device, slicers, pbar: t
 
 @dataclass
 class intermediate_slice:
+    """Accumulator for sliding-window slicers that fall within a spatial chunk.
+
+    Used by :meth:`nnUNetPredictor._run_prediction_splits` to group tile slicers
+    into GPU-sized spatial blocks. Tracks the bounding box of all accumulated
+    slicers so the minimal sub-volume of data can be transferred to the GPU.
+
+    Attributes:
+        meta_slice: Spatial extent of this chunk (one slice per spatial axis).
+        slicers: All tile slicers whose starting coordinates lie within this chunk.
+        min_s: Minimum start index per axis across all added slicers.
+        max_s: Maximum stop index per axis across all added slicers.
+    """
+
     meta_slice: list[slice]
     slicers: list[tuple[slice, ...]] = field(default_factory=list)
     min_s: list[int] | None = None
     max_s: list[int] | None = None
 
-    def is_in(self, s: tuple[slice, ...]):
+    def is_in(self, s: tuple[slice, ...]) -> bool:
+        """Return ``True`` if slicer ``s`` belongs to this chunk's spatial extent."""
         assert len(s) - 1 == len(self.meta_slice), (s, self.meta_slice)
         for ref, given in zip(s[1:], self.meta_slice):
             if ref.start < given.start:
@@ -704,7 +809,8 @@ def is_in(self, s: tuple[slice, ...]):
                 return False
         return True
 
-    def add_slicer(self, s: tuple[slice, ...]):
+    def add_slicer(self, s: tuple[slice, ...]) -> None:
+        """Register slicer ``s`` and expand the tracked bounding box accordingly."""
         if self.min_s is None:
             self.min_s = [s.start for s in s[1:]]
         else:
@@ -717,7 +823,8 @@ def add_slicer(self, s: tuple[slice, ...]):
         assert len(s) - 1 == len(self.meta_slice)
         self.slicers.append(s)
 
-    def get_intermediate(self):
+    def get_intermediate(self) -> tuple[slice, ...] | None:
+        """Return a slicer covering the bounding box of all registered slicers, or ``None``."""
         if self.min_s is None or self.max_s is None:
             return None
         return (
@@ -725,7 +832,8 @@ def get_intermediate(self):
             *tuple(slice(mi, ma) for mi, ma in zip(self.min_s, self.max_s)),
         )  # type: ignore
 
-    def get_slices(self):
+    def get_slices(self) -> Generator[tuple[slice, ...], None, None]:
+        """Yield each registered slicer adjusted to be relative to this chunk's origin."""
         assert self.min_s is not None
         for s in self.slicers:
             yield (
@@ -734,7 +842,14 @@ def get_slices(self):
             )
 
 
-def empty_cache(device: torch.device):
+def empty_cache(device: torch.device) -> None:
+    """Free the memory cache of the given device (CUDA or MPS).
+
+    Args:
+        device: The device whose cache should be cleared. Accepts a
+            :class:`torch.device` object or a string device identifier.
+            CPU devices are silently ignored.
+    """
     if isinstance(device, str):
         device = torch.device(device)
     if device.type == "cuda":
@@ -748,6 +863,8 @@ def empty_cache(device: torch.device):
 
 
 class dummy_context:
+    """No-op context manager used as a drop-in for :func:`torch.autocast` on non-CUDA devices."""
+
     def __enter__(self):
         pass
 
diff --git a/TPTBox/segmentation/nnUnet_utils/sliding_window_prediction.py b/TPTBox/segmentation/nnUnet_utils/sliding_window_prediction.py
index 363d0a7..88708e5 100755
--- a/TPTBox/segmentation/nnUnet_utils/sliding_window_prediction.py
+++ b/TPTBox/segmentation/nnUnet_utils/sliding_window_prediction.py
@@ -19,6 +19,7 @@ def compute_gaussian(
     dtype=torch.float16,
     device=torch.device("cuda", 0),  # noqa: B008
 ) -> torch.Tensor:
+    """Compute a normalised Gaussian importance map for a sliding-window tile of the given size."""
     tmp = np.zeros(tile_size)
     center_coords = [i // 2 for i in tile_size]
     sigmas = [i * sigma_scale for i in tile_size]
@@ -37,6 +38,7 @@ def compute_gaussian(
 
 
 def compute_steps_for_sliding_window(image_size: tuple[int, ...], tile_size: tuple[int, ...], tile_step_size: float) -> list[list[int]]:
+    """Compute per-dimension step start indices for a sliding-window inference pass over an image."""
     assert [i >= j for i, j in zip(image_size, tile_size)], "image size must be as large or larger than patch_size"
     assert 0 < tile_step_size <= 1, "step_size must be larger than 0 and smaller or equal to 1"
 
diff --git a/TPTBox/segmentation/spineps.py b/TPTBox/segmentation/spineps.py
index 6ea3657..026b763 100644
--- a/TPTBox/segmentation/spineps.py
+++ b/TPTBox/segmentation/spineps.py
@@ -11,9 +11,9 @@
 
 def get_outpaths_spineps(
     file_path: str | Path | BIDS_FILE,
-    dataset=None,
-    derivative_name="derivative",
-    ignore_bids_filter=True,
+    dataset: str | Path | None = None,
+    derivative_name: str = "derivative",
+    ignore_bids_filter: bool = True,
 ) -> dict[
     Literal[
         "out_spine",
@@ -30,6 +30,19 @@ def get_outpaths_spineps(
     ],
     Path,
 ]:
+    """Return the expected output paths for a SPINEPS segmentation run.
+
+    Args:
+        file_path: Path to the input NIfTI image, or a ``BIDS_FILE`` object.
+        dataset: Optional dataset root directory.  Required when *file_path* is a
+            plain ``str`` or ``Path`` and a BIDS dataset root is needed.
+        derivative_name: Name of the derivatives sub-folder used by SPINEPS.
+        ignore_bids_filter: If True, disable strict BIDS filename filtering.
+
+    Returns:
+        Dictionary mapping output keys (e.g. ``"out_spine"``, ``"out_vert"``) to
+        the corresponding ``Path`` objects.
+    """
     from spineps.seg_run import output_paths_from_input
 
     if not isinstance(file_path, BIDS_FILE):
@@ -47,21 +60,51 @@ def get_outpaths_spineps(
 
 def run_spineps(
     file_path: str | Path | BIDS_FILE,
-    dataset=None,
+    dataset: str | Path | None = None,
     model_semantic: str | Path = "t2w",
     model_instance: str | Path = "instance",
     model_labeling: str | None = "t2w_labeling",
-    derivative_name="derivative",
-    override_semantic=False,
-    override_instance=False,
+    derivative_name: str = "derivative",
+    override_semantic: bool = False,
+    override_instance: bool = False,
     lambda_semantic=None,
-    save_debug_data=False,
-    verbose=False,
-    save_raw=False,
-    ignore_compatibility_issues=False,
-    use_cpu=False,
+    save_debug_data: bool = False,
+    verbose: bool = False,
+    save_raw: bool = False,
+    ignore_compatibility_issues: bool = False,
+    use_cpu: bool = False,
     **args,
-):
+) -> dict:
+    """Run the SPINEPS spine segmentation pipeline on a single image.
+
+    Handles model loading, BIDS path resolution, and delegates to SPINEPS'
+    ``process_img_nii`` function.
+
+    Args:
+        file_path: Path to the input NIfTI image, or a ``BIDS_FILE`` object.
+        dataset: Optional dataset root directory (used when *file_path* is a plain
+            path and a BIDS root is required).
+        model_semantic: Semantic segmentation model name (e.g. ``"t2w"``) or
+            explicit path to a model folder.
+        model_instance: Instance segmentation model name or explicit path.
+        model_labeling: Labeling model name, or ``None`` to skip labeling.
+        derivative_name: Name of the derivatives sub-folder for outputs.
+        override_semantic: If True, recompute the semantic segmentation even when
+            a cached result exists.
+        override_instance: If True, recompute the instance segmentation even when
+            a cached result exists.
+        lambda_semantic: Optional callable to post-process the semantic output.
+        save_debug_data: If True, save intermediate debug files.
+        verbose: If True, enable verbose logging.
+        save_raw: If True, also save unprocessed (raw) model outputs.
+        ignore_compatibility_issues: If True, suppress BIDS compatibility checks
+            and model/image compatibility warnings.
+        use_cpu: If True, force CPU inference even if a GPU is available.
+        **args: Additional keyword arguments forwarded to ``process_img_nii``.
+
+    Returns:
+        The output paths dictionary returned by SPINEPS' ``process_img_nii``.
+    """
     from spineps import get_instance_model, get_semantic_model, process_img_nii
     from spineps.get_models import get_actual_model
 
@@ -106,7 +149,8 @@ def run_spineps(
     return output_paths
 
 
-def _run_spineps_all(nii_dataset: Path | str):
+def _run_spineps_all(nii_dataset: Path | str) -> None:
+    """Run SPINEPS with all supported semantic models over an entire dataset."""
     for model_semantic in ["t2w", "t1w", "vibe"]:
         command = [
             "spineps",
@@ -139,9 +183,10 @@ def _run_spineps_internal(
     proc_fillholes: bool = True,
     verbose: bool = False,
     outpath: str | Path | None = None,
-    override=False,
+    override: bool = False,
     # gpu=0,
-):
+) -> NII | None:
+    """Run a single SPINEPS semantic segmentation model on one image internally."""
     # TODO select GPU
     from spineps.get_models import get_actual_model
     from spineps.seg_model import OutputType, Segmentation_Model
@@ -199,20 +244,42 @@ def _run_spineps_internal(
 def _run_spineps_vert(
     input_nii: NII,
     subreg_nii: NII,
-    model_instance="instance",  # _sagittal_v1.2.0
+    model_instance: str | Path = "instance",  # _sagittal_v1.2.0
     model_labeling=None,
-    vertebra_instance_labeling_offset=2,
-    proc_fill_3d_holes=False,
-    proc_inst_detect_and_solve_merged_corpi=True,
-    proc_inst_corpus_clean=True,
-    proc_inst_clean_small_cc_artifacts=True,
-    proc_inst_largest_k_cc=0,
-    proc_clean_inst_by_sem=True,
-    proc_assign_missing_cc=False,
-    proc_vertebra_inconsistency=True,
-    verbose=True,
-    use_cpu=False,
-):
+    vertebra_instance_labeling_offset: int = 2,
+    proc_fill_3d_holes: bool = False,
+    proc_inst_detect_and_solve_merged_corpi: bool = True,
+    proc_inst_corpus_clean: bool = True,
+    proc_inst_clean_small_cc_artifacts: bool = True,
+    proc_inst_largest_k_cc: int = 0,
+    proc_clean_inst_by_sem: bool = True,
+    proc_assign_missing_cc: bool = False,
+    proc_vertebra_inconsistency: bool = True,
+    verbose: bool = True,
+    use_cpu: bool = False,
+) -> tuple[NII, NII, NII]:
+    """Run SPINEPS instance segmentation and post-processing to produce vertebra labels.
+
+    Args:
+        input_nii: Input image used for post-processing.
+        subreg_nii: Semantic sub-region segmentation used as input to the instance model.
+        model_instance: Instance model name or path.
+        model_labeling: Optional labeling model for vertebra numbering.
+        vertebra_instance_labeling_offset: Label offset applied during labeling.
+        proc_fill_3d_holes: If True, fill 3-D holes in the instance mask.
+        proc_inst_detect_and_solve_merged_corpi: Detect and split merged vertebra bodies.
+        proc_inst_corpus_clean: Apply corpus-cleaning post-processing.
+        proc_inst_clean_small_cc_artifacts: Remove small connected-component artefacts.
+        proc_inst_largest_k_cc: Keep only the *k* largest connected components (0 = keep all).
+        proc_clean_inst_by_sem: Clean instance mask using the semantic segmentation.
+        proc_assign_missing_cc: Assign unlabelled connected components to nearest vertebra.
+        proc_vertebra_inconsistency: Resolve vertebra label inconsistencies.
+        verbose: If True, enable verbose logging.
+        use_cpu: If True, force CPU inference.
+
+    Returns:
+        A tuple of (cleaned_semantic_NII, cleaned_vertebra_NII, raw_vertebra_NII).
+    """
     from spineps import (
         get_instance_model,
         phase_postprocess_combined,
diff --git a/TPTBox/spine/README.md b/TPTBox/spine/README.md
new file mode 100644
index 0000000..1ddca3a
--- /dev/null
+++ b/TPTBox/spine/README.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/README.md) | Modular 2D image snapshot generation (slices, MIPs, overlays) |
+| [`spinestats/`](spinestats/README.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/TPTBox/spine/snapshot2D/README.md b/TPTBox/spine/snapshot2D/README.md
new file mode 100644
index 0000000..f8bf792
--- /dev/null
+++ b/TPTBox/spine/snapshot2D/README.md
@@ -0,0 +1,26 @@
+# 2D Snapshots (`spine/snapshot2D`)
+
+Modular 2D image generation for NIfTI data.  Supports axial/sagittal/coronal slices,
+maximum intensity projections (MIPs), and segmentation overlays.
+
+## Key symbols
+
+| Symbol | Module | Description |
+|---|---|---|
+| `create_snapshot` | `snapshot_modular.py` | Main entry point — renders a list of `Snapshot_Frame` objects to a PNG |
+| `Snapshot_Frame` | `snapshot_modular.py` | Configuration for one image panel (image, overlay, view direction, …) |
+| `Plane` | `snapshot_modular.py` | Enum: `Plane.axial`, `Plane.sagittal`, `Plane.coronal` |
+| `to_image_nii` | `snapshot_modular.py` | Convert a NIfTI slice to a matplotlib-ready RGB array |
+| Pre-built templates | `snapshot_templates.py` | Ready-to-use snapshot configurations for common spine workflows |
+
+## Example
+
+```python
+from TPTBox.spine.snapshot2D.snapshot_modular import Snapshot_Frame, create_snapshot, Plane
+
+frames = [
+    Snapshot_Frame(image=ct, segmentation=seg, mode="CT", plane=Plane.sagittal),
+    Snapshot_Frame(image=ct, mode="CT", plane=Plane.axial),
+]
+create_snapshot(frames, to="output.png")
+```
diff --git a/TPTBox/spine/snapshot2D/snapshot_modular.py b/TPTBox/spine/snapshot2D/snapshot_modular.py
index ff86d95..7c31f06 100755
--- a/TPTBox/spine/snapshot2D/snapshot_modular.py
+++ b/TPTBox/spine/snapshot2D/snapshot_modular.py
@@ -44,6 +44,8 @@
 
 
 class Visualization_Type(Enum):
+    """Enum selecting how voxels along a projection axis are reduced to a 2D pixel value."""
+
     Slice = auto()
     Maximum_Intensity = auto()
     Maximum_Intensity_Colored_Depth = auto()
@@ -138,7 +140,7 @@ def sag_cor_curve_projection(
     cor_savgol_filter: bool = False,
     curve_location: Location = Location.Vertebra_Corpus,
 ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
-    """Makes a curve projection (spline interpolation) over the spline through the given centroids
+    """Makes a curve projection (spline interpolation) over the spline through the given centroids.
 
     Args:
         ctd_list: given Centroids
@@ -220,7 +222,34 @@ def sag_cor_curve_projection(
     return x_ctd, y_cord, z_cord
 
 
-def curve_projected_slice(x_ctd, img_data, y_cord, z_cord, axial_heights):
+def curve_projected_slice(
+    x_ctd: np.ndarray,
+    img_data: np.ndarray,
+    y_cord: np.ndarray,
+    z_cord: np.ndarray,
+    axial_heights: list[float] | None,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Extract sagittal, coronal, and axial slice planes along a curved spinal path.
+
+    For each axial position the sagittal slice is taken at the interpolated
+    coronal coordinate and vice versa.  Outside the range of the centroids the
+    boundary values are extrapolated.
+
+    Args:
+        x_ctd: Sorted x-indices of the vertebral centroids (integer array).
+        img_data: 3-D image volume in IPL orientation with shape (X, Y, Z).
+        y_cord: Interpolated y (anterior-posterior) coordinates for each x
+            position between the first and last centroid.
+        z_cord: Interpolated z (left-right) coordinates for each x position
+            between the first and last centroid.
+        axial_heights: Heights for the axial fallback planes passed through to
+            ``curve_projection_axial_fallback``.
+
+    Returns:
+        A tuple ``(sag_plane, cor_plane, axl_plane)`` where each element is a
+        2-D numpy array representing the sagittal, coronal, and axial
+        projections respectively.
+    """
     shp = img_data.shape
     cor_plane = np.zeros((shp[0], shp[2]))
     sag_plane = np.zeros((shp[0], shp[1]))
@@ -244,12 +273,33 @@ def curve_projected_slice(x_ctd, img_data, y_cord, z_cord, axial_heights):
 def curve_projected_mean(
     img_data: np.ndarray,
     zms: tuple[float, float, float],
-    x_ctd,
-    y_cord,
-    ctd_list,
+    x_ctd: np.ndarray,
+    y_cord: np.ndarray,
+    ctd_list: POI,
     thick_t: tuple[int, int] = (100, 300),
-    axial_heights=None,
-):
+    axial_heights: list[float] | None = None,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Compute mean-intensity curved-planar projections along the spinal curve.
+
+    For each axial position the sagittal mean is computed over all non-zero
+    voxels in that row, while the coronal mean is computed over a slab of
+    width ``thick_t`` centred on the interpolated y coordinate.
+
+    Args:
+        img_data: 3-D image volume in IPL orientation with shape (X, Y, Z).
+        zms: Voxel spacing (zoom) in mm for each axis ``(x, y, z)``.
+        x_ctd: Sorted x-indices of the vertebral centroids (integer array).
+        y_cord: Interpolated y (anterior-posterior) coordinates for each x
+            position between the first and last centroid.
+        ctd_list: POI object whose region keys are used to adjust slab
+            thickness near the sacrum.
+        thick_t: Anterior and posterior slab half-widths in mm used for the
+            coronal projection ``(anterior_mm, posterior_mm)``.
+        axial_heights: Heights for the axial fallback planes.
+
+    Returns:
+        A tuple ``(sag_plane, cor_plane, axl_plane)`` of 2-D float arrays.
+    """
     shp = img_data.shape
     cor_plane = np.zeros((shp[0], shp[2]))
     sag_plane = np.zeros((shp[0], shp[1]))
@@ -289,13 +339,39 @@ def curve_projected_mean(
 def curve_projected_mip(
     img_data: np.ndarray,
     zms: tuple[float, float, float],
-    x_ctd,
-    y_cord,
-    ctd_list,  # noqa: ARG001
+    x_ctd: np.ndarray,
+    y_cord: np.ndarray,
+    ctd_list: POI,  # noqa: ARG001
     thick_t: tuple[int, int] = (100, 300),
     make_colored_depth: bool = False,
-    axial_heights=None,
-):
+    axial_heights: list[float] | None = None,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Compute maximum-intensity curved-planar projections along the spinal curve.
+
+    A slab of configurable thickness is extracted around the interpolated
+    spinal curve for each axial position, and the maximum intensity is
+    projected onto the output plane.  Optionally the depth of the maximum is
+    colour-encoded using the ``inferno`` colourmap.
+
+    Args:
+        img_data: 3-D image volume in IPL orientation with shape (X, Y, Z).
+        zms: Voxel spacing (zoom) in mm for each axis ``(x, y, z)``.
+        x_ctd: Sorted x-indices of the vertebral centroids (integer array).
+        y_cord: Interpolated y (anterior-posterior) coordinates for each x
+            position between the first and last centroid.
+        ctd_list: POI object (currently unused, reserved for future thickness
+            adaptation near the sacrum).
+        thick_t: Anterior and posterior slab half-widths in mm
+            ``(anterior_mm, posterior_mm)``.
+        make_colored_depth: If ``True`` the returned planes are RGB arrays
+            colour-coded by depth; otherwise they are scalar intensity arrays.
+        axial_heights: Heights for the axial fallback planes.
+
+    Returns:
+        A tuple ``(sag_plane, cor_plane, axl_plane)``.  When
+        ``make_colored_depth`` is ``True`` the sagittal and coronal arrays
+        have shape ``(X, Y, 3)`` and ``(X, Z, 3)`` respectively.
+    """
     shp = img_data.shape
     cor_plane = np.zeros((shp[0], shp[2]))
     cor_depth_plane = np.zeros((shp[0], shp[2]))
@@ -357,7 +433,17 @@ def curve_projected_mip(
     )
 
 
-def normalize_image(img, v_range: tuple[float, float] | None = None):
+def normalize_image(img: np.ndarray, v_range: tuple[float, float] | None = None) -> np.ndarray:
+    """Linearly rescale an array to the range [0, 1].
+
+    Args:
+        img: Input array to normalise.
+        v_range: Optional ``(min, max)`` clip range.  When ``None`` the
+            actual minimum and maximum of ``img`` are used.
+
+    Returns:
+        A float array with values in ``[0, 1]``.
+    """
     if v_range is None:
         min_v = np.min(img)
         max_v = np.max(img)
@@ -367,7 +453,27 @@ def normalize_image(img, v_range: tuple[float, float] | None = None):
     return (img - min_v) / (max_v - min_v)
 
 
-def curve_projection_axial_fallback(img_data, x_ctd, heights: list[float] | None):
+def curve_projection_axial_fallback(
+    img_data: np.ndarray,
+    x_ctd: np.ndarray,
+    heights: list[float] | None,
+) -> np.ndarray:
+    """Build an axial composite plane for display as a fallback or from explicit heights.
+
+    When ``heights`` is given each value is interpreted as an absolute slice
+    index (if ``|h| >= 1``) or as a fraction of the volume depth (if
+    ``|h| < 1``).  The slices are concatenated vertically.  When ``heights``
+    is ``None`` three slices centred on the median centroid are concatenated.
+
+    Args:
+        img_data: 3-D image volume in IPL orientation with shape (X, Y, Z).
+        x_ctd: Sorted x-indices of the vertebral centroids (integer array).
+        heights: Explicit axial heights to extract, or ``None`` to use the
+            three slices surrounding the central centroid.
+
+    Returns:
+        A 2-D numpy array representing the composed axial view.
+    """
     if heights is not None:
         heights = [int(abs(h if abs(h) >= 1 else img_data.shape[0] * h)) for h in (heights) if abs(h) <= img_data.shape[0]]
         axl_plane = np.concatenate([img_data[h, :, :] for h in heights], axis=0)
@@ -392,7 +498,19 @@ def curve_projection_axial_fallback(img_data, x_ctd, heights: list[float] | None
         return axl_plane
 
 
-def make_isotropic2d(arr2d: np.ndarray, zms2d, msk=False) -> np.ndarray:
+def make_isotropic2d(arr2d: np.ndarray, zms2d: tuple[float, float], msk: bool = False) -> np.ndarray:
+    """Resample a 2-D array to isotropic pixel spacing.
+
+    Args:
+        arr2d: Input 2-D array.
+        zms2d: Voxel spacing ``(dy, dz)`` of the input array in mm.  The
+            output will have 1 mm × 1 mm pixels.
+        msk: If ``True`` nearest-neighbour interpolation is used (suitable
+            for label maps); otherwise linear interpolation is applied.
+
+    Returns:
+        Resampled 2-D array with isotropic pixel spacing.
+    """
     if np.issubdtype(arr2d.dtype, np.floating):
         arr2d = arr2d.astype(int)
     xs = list(range(arr2d.shape[0]))
@@ -414,7 +532,26 @@ def make_isotropic2d(arr2d: np.ndarray, zms2d, msk=False) -> np.ndarray:
     return img
 
 
-def make_isotropic2dpluscolor(arr3d, zms2d, msk=False):
+def make_isotropic2dpluscolor(
+    arr3d: np.ndarray,
+    zms2d: tuple[float, float],
+    msk: bool = False,
+) -> np.ndarray:
+    """Resample a 2-D or 2-D+RGB array to isotropic pixel spacing.
+
+    Delegates to :func:`make_isotropic2d` for scalar images.  For colour
+    images (3rd dimension of size 3) each channel is resampled independently
+    and the results are stacked.
+
+    Args:
+        arr3d: Input array with shape ``(H, W)`` or ``(H, W, 3)``.
+        zms2d: Voxel spacing ``(dy, dz)`` of the input array in mm.
+        msk: Passed through to :func:`make_isotropic2d`; use ``True`` for
+            label maps to enable nearest-neighbour interpolation.
+
+    Returns:
+        Resampled array with the same number of channels as the input.
+    """
     # print(arr3d.shape)
     if arr3d.ndim == 2:
         return make_isotropic2d(arr3d, zms2d, msk=msk)
@@ -428,7 +565,20 @@ def make_isotropic2dpluscolor(arr3d, zms2d, msk=False):
     return img
 
 
-def get_contrasting_stroke_color(rgb):
+def get_contrasting_stroke_color(rgb: int | list[float] | tuple[float, ...]) -> str:
+    """Return ``"gray"`` or ``"black"`` depending on the perceived luminance of ``rgb``.
+
+    A dark foreground colour (luminance < 0.3) gets a ``"gray"`` stroke so
+    that text remains readable on dark backgrounds; all other colours receive
+    a ``"black"`` stroke.
+
+    Args:
+        rgb: Either an integer label index (looked up in the colour map) or an
+            RGB / RGBA tuple / list of floats in ``[0, 1]``.
+
+    Returns:
+        ``"gray"`` for dark colours, ``"black"`` for bright colours.
+    """
     # Convert RGBA to RGB if necessary
     if isinstance(rgb, int):
         rgb = list(get_color_by_label(rgb).rgb / 255.0)
@@ -438,7 +588,25 @@ def get_contrasting_stroke_color(rgb):
     return "gray" if luminance < 0.3 else "black"
 
 
-def create_figure(dpi, planes: list, has_title=True):
+def create_figure(
+    dpi: int,
+    planes: list[np.ndarray],
+    has_title: bool = True,
+) -> tuple:
+    """Create a matplotlib figure sized to contain all projection planes side by side.
+
+    Args:
+        dpi: Output resolution in dots per inch.
+        planes: List of 2-D (or 3-D colour) arrays whose widths determine the
+            column layout of the figure.
+        has_title: When ``True`` extra vertical space is reserved for a title
+            row above the images.
+
+    Returns:
+        A ``(fig, axs)`` tuple where ``fig`` is the
+        :class:`~matplotlib.figure.Figure` and ``axs`` is a list of
+        :class:`~matplotlib.axes.Axes`, one per plane.
+    """
     fig_h = round(2 * planes[0].shape[0] / dpi, 2) + (0.5 if has_title else 0)
     plane_w = [p.shape[1] for p in planes]
     w = sum(plane_w)
@@ -460,13 +628,35 @@ def create_figure(dpi, planes: list, has_title=True):
 def plot_sag_centroids(
     axs: Axes,
     ctd: POI,
-    zms,
+    zms: tuple[float, float, float],
     poi_labelmap: dict[int, str],
     hide_centroid_labels: bool,
     cmap: ListedColormap = cm_itk,
     curve_location: Location = Location.Vertebra_Corpus,
-    show_these_subreg_poi=None,
-):
+    show_these_subreg_poi: list[int | Location] | None = None,
+) -> None:
+    """Overlay centroid circles and vertebra labels on a sagittal axis.
+
+    Points are drawn as filled circles coloured by vertebra label.  Vertebra
+    names from ``poi_labelmap`` are added as bold text next to the circle when
+    ``hide_centroid_labels`` is ``False``.  Additional arrows and text
+    annotations stored in ``ctd.info["line_segments_sag"]`` and
+    ``ctd.info["text_sag"]`` are also rendered.
+
+    Args:
+        axs: Matplotlib axes on which to draw.
+        ctd: POI object containing centroid coordinates and optional rendering
+            hints in its ``info`` dictionary.
+        zms: Voxel spacing ``(dx, dy, dz)`` in mm used to convert voxel
+            coordinates to pixel coordinates.
+        poi_labelmap: Mapping from vertebra region ID to display name.
+        hide_centroid_labels: When ``True`` vertebra name labels are omitted.
+        cmap: Colour map used to assign per-vertebra colours.
+        curve_location: Sub-region location whose centroid receives the text
+            label.
+        show_these_subreg_poi: If provided, only POIs with these sub-region
+            IDs are plotted.
+    """
     # requires v_dict = dictionary of mask labels
     ctd2 = ctd
     if show_these_subreg_poi is not None:
@@ -546,15 +736,35 @@ def plot_sag_centroids(
 
 
 def plot_cor_centroids(
-    axs,
+    axs: Axes,
     ctd: POI,
-    zms,
+    zms: tuple[float, float, float],
     poi_labelmap: dict[int, str],
     hide_centroid_labels: bool,
     cmap: ListedColormap = cm_itk,
     curve_location: Location = Location.Vertebra_Corpus,
-    show_these_subreg_poi=None,
-):
+    show_these_subreg_poi: list[int | Location] | None = None,
+) -> None:
+    """Overlay centroid circles and vertebra labels on a coronal axis.
+
+    Analogous to :func:`plot_sag_centroids` but uses the z-coordinate for the
+    horizontal axis instead of the y-coordinate.  Additional arrows and text
+    stored in ``ctd.info["line_segments_cor"]`` and ``ctd.info["text_cor"]``
+    are also rendered.
+
+    Args:
+        axs: Matplotlib axes on which to draw.
+        ctd: POI object containing centroid coordinates and optional rendering
+            hints in its ``info`` dictionary.
+        zms: Voxel spacing ``(dx, dy, dz)`` in mm.
+        poi_labelmap: Mapping from vertebra region ID to display name.
+        hide_centroid_labels: When ``True`` vertebra name labels are omitted.
+        cmap: Colour map used to assign per-vertebra colours.
+        curve_location: Sub-region location whose centroid receives the text
+            label.
+        show_these_subreg_poi: If provided, only POIs with these sub-region
+            IDs are plotted.
+    """
     ctd2 = ctd
     if show_these_subreg_poi is not None:
         ctd2 = ctd.extract_subregion(*show_these_subreg_poi)
@@ -646,11 +856,44 @@ def make_2d_slice(
     visualization_type: Visualization_Type,
     ctd_fallback: POI,
     cor_savgol_filter: bool = False,
-    to_ax=("I", "P", "L"),
+    to_ax: tuple[str, str, str] = ("I", "P", "L"),
     curve_location: Location = Location.Vertebra_Corpus,
     rescale_to_iso: bool = True,
-    axial_heights=None,
-):
+    axial_heights: list[float] | None = None,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Generate 2-D sagittal, coronal, and axial projection images from a volume.
+
+    The image is reoriented to ``to_ax`` and a spline through the vertebral
+    centroids is computed.  Depending on ``visualization_type`` slices,
+    maximum-intensity projections, depth-coloured MIPs, or mean-intensity
+    projections are extracted.  The result is optionally resampled to
+    isotropic pixel spacing.
+
+    Args:
+        img: Source image volume.
+        ctd: POI object used to compute the spinal curve.
+        zms: Voxel spacing ``(dx, dy, dz)`` in mm of the reoriented image.
+        msk: When ``True`` the volume is treated as a label map: zero voxels
+            are set to ``NaN`` and nearest-neighbour resampling is applied.
+        visualization_type: One of the :class:`Visualization_Type` enum values
+            controlling which projection method is used.
+        ctd_fallback: Fallback POI used when ``ctd`` has too few points for
+            spline interpolation.
+        cor_savgol_filter: Whether to apply a Savitzky-Golay filter to the
+            coronal spline in :func:`sag_cor_curve_projection`.
+        to_ax: Target orientation axes as a 3-tuple of direction codes.
+        curve_location: Anatomical sub-region used for spline fitting.
+        rescale_to_iso: When ``True`` all returned planes are resampled to
+            isotropic pixel spacing using the zoom factors from ``zms``.
+        axial_heights: Optional explicit axial slice heights; passed to
+            :func:`curve_projection_axial_fallback`.
+
+    Returns:
+        A tuple ``(sag, cor, axl)`` of 2-D float arrays.  For
+        :attr:`Visualization_Type.Maximum_Intensity_Colored_Depth` without
+        ``msk`` the sagittal and coronal arrays are ``(H, W, 3)`` colour
+        images.
+    """
     img_nii = to_nii(img)
     img_reo = img_nii.reorient_(to_ax)
     ctd_reo = ctd.reorient(img_reo.orientation)
@@ -734,8 +977,8 @@ def make_2d_slice(
     return sag, cor, axl
 
 
-def div0(a, b, fill=0):
-    """a / b, divide by 0 -> `fill`"""
+def div0(a, b, fill=0) -> np.ndarray | float:
+    """Divide ``a`` by ``b``, replacing divisions by zero with ``fill``."""
     with np.errstate(divide="ignore", invalid="ignore"):
         c = np.true_divide(a, b)
     if np.isscalar(c):
@@ -750,6 +993,8 @@ def div0(a, b, fill=0):
 
 @dataclass(init=True)
 class Snapshot_Frame:
+    """Dataclass bundling an image, optional segmentation/centroids, and per-frame rendering settings."""
+
     # Content
     image: Image_Reference
     segmentation: Image_Reference | None = None
@@ -790,6 +1035,16 @@ class Snapshot_Frame:
 
 
 def to_cdt(ctd_bids: POI_Reference | None) -> POI | None:
+    """Load a POI from a reference and return it, or ``None`` if it is empty.
+
+    Args:
+        ctd_bids: A path, BIDS file, or POI object to load.  ``None`` is
+            returned as-is.
+
+    Returns:
+        The loaded :class:`~TPTBox.POI` if it contains at least one centroid,
+        otherwise ``None``.
+    """
     if ctd_bids is None:
         return None
     ctd = POI.load(ctd_bids, allow_global=True)
@@ -807,8 +1062,8 @@ def create_snapshot(  # noqa: C901
     to_ax=("I", "P", "L"),
     dpi=96,
     verbose: bool = False,
-):
-    """Create virtual dx, sagittal, and coronal curved-planar CT snapshots with mask overlay
+) -> None:
+    """Create virtual dx, sagittal, and coronal curved-planar CT snapshots with mask overlay.
 
     Args:
         snp_path (str): Path to the new jpg
@@ -818,7 +1073,6 @@ def create_snapshot(  # noqa: C901
         to_ax (Orientation): Sets the Orientation. Can be used for flipping the image or fixing false rotations of the original inputs.
         dpi (int): Set the resolution.
     """
-
     # Checks if snaps already exists, does nothing if true and check is true
     exist = all(Path(i).is_file() for i in snp_path) if isinstance(snp_path, list) else Path(snp_path).is_file()
     if check and exist:
diff --git a/TPTBox/spine/snapshot2D/snapshot_templates.py b/TPTBox/spine/snapshot2D/snapshot_templates.py
index 5fdd0ed..ee92ba5 100755
--- a/TPTBox/spine/snapshot2D/snapshot_templates.py
+++ b/TPTBox/spine/snapshot2D/snapshot_templates.py
@@ -13,9 +13,31 @@ def mip_shot(
     ct_ref: BIDS_FILE,
     vert_msk: Image_Reference,
     subreg_ctd: POI_Reference,
-    subreg_msk: Image_Reference = None,
-    out_path=None,
-):
+    subreg_msk: Image_Reference | None = None,
+    out_path: str | Path | None = None,
+) -> None:
+    """Save a multi-panel CT snapshot combining slice, mean-intensity, and coloured-depth MIP views.
+
+    Three frames are always included:
+
+    1. Standard CT slice view with vertebra segmentation and centroids
+       (sagittal + coronal).
+    2. Mean-intensity projection of the masked vertebra region only
+       (sagittal + coronal, no segmentation overlay).
+    3. Coloured-depth maximum-intensity projection of the bone above a 100 HU
+       threshold (coronal only).
+
+    An optional fourth frame with the subregion mask is appended when
+    ``subreg_msk`` is provided.
+
+    Args:
+        ct_ref: BIDS file pointing to the CT image.
+        vert_msk: Vertebra segmentation mask.
+        subreg_ctd: Subregion centroids (POI reference).
+        subreg_msk: Optional subregion segmentation mask for an extra frame.
+        out_path: Output file path.  When ``None`` the path is derived
+            automatically from ``ct_ref`` with ``desc=mip``.
+    """
     frames = [
         Snapshot_Frame(
             image=ct_ref,
@@ -87,8 +109,27 @@ def sacrum_shot(
     subreg_ctd: POI_Reference,
     add_ctd: list[POI_Reference] | None = None,
     mip_c: bool = False,
-    out_path=None,
-):
+    out_path: str | Path | None = None,
+) -> None:
+    """Save a CT snapshot focused on the sacrum region.
+
+    A primary sagittal + coronal frame is always created.  Additional coronal
+    frames are appended for each extra centroid file in ``add_ctd``.  When
+    ``mip_c`` is ``True`` a coloured-depth MIP coronal frame is added.
+
+    Args:
+        ct_ref: BIDS file pointing to the CT image.  If an instance of
+            :class:`~TPTBox.BIDS_FILE`, the image is pre-loaded and
+            reoriented.
+        vert_msk: Vertebra segmentation mask.
+        subreg_ctd: Primary subregion centroids (POI reference).
+        add_ctd: Optional list of additional centroid references, each
+            rendered as an extra coronal frame.
+        mip_c: When ``True`` a coloured-depth maximum-intensity projection
+            frame is appended.
+        out_path: Output file path.  When ``None`` the path is derived
+            automatically from ``ct_ref`` with ``desc=sacrum``.
+    """
     if isinstance(ct_ref, BIDS_FILE):
         ct_ref = ct_ref.open_nii().reorient_()
     frames = [
@@ -152,8 +193,24 @@ def spline_shot(
     subreg_ctd: POI_Reference,
     spline_nii: NII,
     add_info: str = "",
-    out_path=None,
-):
+    out_path: str | Path | None = None,
+) -> None:
+    """Save a two-frame CT snapshot showing the spinal spline interpolation result.
+
+    Frame 1 shows the original vertebra mask overlaid on the CT (sagittal
+    only).  Frame 2 shows the spline NIfTI segmentation overlaid on the CT
+    (sagittal + coronal) so that the spline quality can be assessed visually.
+
+    Args:
+        ct_ref: BIDS file pointing to the CT image.
+        vert_msk: Vertebra segmentation mask.
+        subreg_ctd: Subregion centroids (POI reference).
+        spline_nii: NIfTI image containing the fitted spline segmentation.
+        add_info: Optional string appended to the ``desc`` field of the
+            auto-generated output path.
+        out_path: Output file path.  When ``None`` the path is derived
+            automatically from ``ct_ref``.
+    """
     frames = [
         Snapshot_Frame(
             image=ct_ref,
@@ -189,11 +246,31 @@ def snapshot(
     ref: Image_Reference,
     vert_msk: Image_Reference,
     subreg_ctd: POI_Reference,
-    subreg_msk: Image_Reference = None,
+    subreg_msk: Image_Reference | None = None,
     out_path: str | Path | list[str | Path] | list[Path] | None = None,
-    mode="MINMAX",
-    crop=False,
-):
+    mode: str = "MINMAX",
+    crop: bool = False,
+) -> list[str | Path]:
+    """Save a standard vertebra snapshot, auto-detecting CT vs. MRI mode.
+
+    Delegates to :func:`mri_snapshot` after setting ``mode`` to ``"CT"`` for
+    BIDS CT files or ``"MRI"`` for all other BIDS files.
+
+    Args:
+        ref: Source image reference.  A :class:`~TPTBox.BIDS_FILE` whose
+            ``bids_format`` is ``"ct"`` is treated as CT; everything else
+            is treated as MRI.
+        vert_msk: Vertebra segmentation mask.
+        subreg_ctd: Subregion centroids (POI reference).
+        subreg_msk: Optional subregion segmentation mask for an extra frame.
+        out_path: Output path(s).  ``None`` triggers automatic path derivation.
+        mode: Intensity window mode passed to :class:`~.Snapshot_Frame` when
+            ``ref`` is not a :class:`~TPTBox.BIDS_FILE`.
+        crop: Whether to crop the output to the segmentation bounding box.
+
+    Returns:
+        List of saved output paths.
+    """
     if isinstance(ref, BIDS_FILE):
         mode = "CT" if ref.bids_format == "ct" else "MRI"
 
@@ -204,11 +281,32 @@ def mri_snapshot(
     mrt_ref: BIDS_FILE,
     vert_msk: Image_Reference,
     subreg_ctd: POI_Reference,
-    subreg_msk: Image_Reference = None,
+    subreg_msk: Image_Reference | None = None,
     out_path: str | Path | list[str | Path] | list[Path] | None = None,
-    mode="MRI",
-    crop=False,
-):
+    mode: str = "MRI",
+    crop: bool = False,
+) -> list[str | Path]:
+    """Save a two-frame (or three-frame) MRI vertebra snapshot.
+
+    Frame 1: image with centroids but without segmentation overlay (to
+    check centroid placement without clutter).
+    Frame 2: image with both centroids and segmentation overlay.
+    Frame 3 (optional): image with the subregion mask overlay, added when
+    ``subreg_msk`` is provided.
+
+    Args:
+        mrt_ref: BIDS file pointing to the MRI image.
+        vert_msk: Vertebra segmentation mask.
+        subreg_ctd: Subregion centroids (POI reference).
+        subreg_msk: Optional subregion segmentation mask for an extra frame.
+        out_path: Output path(s).  When ``None`` the path is derived
+            automatically from ``mrt_ref`` with ``desc=vert``.
+        mode: Intensity window mode; defaults to ``"MRI"``.
+        crop: Whether to crop output frames to the segmentation bounding box.
+
+    Returns:
+        List of saved output paths.
+    """
     frames = [
         Snapshot_Frame(
             image=mrt_ref,
@@ -260,9 +358,30 @@ def vibe_snapshot(
     subreg_ctd: POI_Reference,
     subreg_msk: Image_Reference,
     hide_centroids: bool = False,
-    out_path=None,
+    out_path: str | Path | None = None,
     verbose: bool = False,
-):
+) -> str | Path:
+    """Save a VIBE multi-contrast MRI snapshot with four Dixon phases.
+
+    Creates one sagittal frame for each of the four VIBE contrast phases in
+    ``mrt_ref``, all with the subregion mask overlay.  An optional fifth
+    frame shows the first phase in sagittal + coronal with the vertebra mask.
+
+    Args:
+        mrt_ref: Four-tuple of BIDS files corresponding to the VIBE Dixon
+            phases (e.g. in-phase, opposed-phase, water, fat).
+        vert_msk: Optional vertebra segmentation mask used for an extra
+            sagittal + coronal frame.  Skipped when ``None``.
+        subreg_ctd: Subregion centroids (POI reference).
+        subreg_msk: Subregion segmentation mask overlaid on all four phases.
+        hide_centroids: When ``True`` centroid markers are hidden.
+        out_path: Output file path.  When ``None`` the path is derived
+            automatically from ``mrt_ref[0]`` with ``desc=vibe``.
+        verbose: When ``True`` the saved path is printed to stdout.
+
+    Returns:
+        Path to the saved snapshot image.
+    """
     # print(type(mrt_ref[0]))
     frames = [
         Snapshot_Frame(
@@ -337,9 +456,30 @@ def ct_mri_snapshot(
     subreg_ctd_mrt: POI_Reference | None = None,
     vert_msk_ct: Image_Reference | None = None,
     subreg_ctd_ct: POI_Reference | None = None,
-    out_path=None,
-    return_frames=False,
-):
+    out_path: str | Path | None = None,
+    return_frames: bool = False,
+) -> list | str | Path:
+    """Save a two-frame snapshot comparing an MRI and a CT side by side.
+
+    Frame 1: MRI in ``"MRI"`` mode with optional vertebra mask and centroids.
+    Frame 2: CT in ``"CT"`` mode with optional vertebra mask and centroids.
+
+    Args:
+        mrt_ref: MRI image reference.
+        ct_ref: CT image reference.
+        vert_msk_mrt: Optional vertebra segmentation for the MRI frame.
+        subreg_ctd_mrt: Optional subregion centroids for the MRI frame.
+        vert_msk_ct: Optional vertebra segmentation for the CT frame.
+        subreg_ctd_ct: Optional subregion centroids for the CT frame.
+        out_path: Output file path.  When ``None`` the path is derived
+            automatically from ``mrt_ref`` (must be a :class:`~TPTBox.BIDS_FILE`).
+        return_frames: When ``True`` the list of
+            :class:`~.Snapshot_Frame` objects is returned without saving.
+
+    Returns:
+        The list of :class:`~.Snapshot_Frame` objects when ``return_frames``
+        is ``True``, otherwise the path to the saved snapshot image.
+    """
     frames = [
         Snapshot_Frame(
             image=mrt_ref,
@@ -375,8 +515,21 @@ def poi_snapshot(
     ct_nii: BIDS_FILE,
     vert_msk: Image_Reference | None,
     subreg_ctd: POI_Reference,
-    out_path=None,
-):
+    out_path: str | Path | None = None,
+) -> None:
+    """Save a multi-frame CT snapshot visualising ligament attachment-point POIs.
+
+    The POIs are partitioned into lateral groups (dorsal ``_D``, sinister
+    ``_S``, median) and ligament groups (ALL, PLL, FL).  Seven frames are
+    produced covering different sagittal and coronal views of these groups.
+
+    Args:
+        ct_nii: BIDS file pointing to the CT image.
+        vert_msk: Optional vertebra segmentation mask.
+        subreg_ctd: POI reference containing the ligament attachment points.
+        out_path: Output file path.  When ``None`` the path is derived
+            automatically from ``ct_nii`` with ``desc=poi``.
+    """
     # conversion_poi = {
     #    "SSL": 81,  # this POI is not included in our POI list
     #    "ALL_CR_S": 109,
@@ -505,7 +658,8 @@ def poi_snapshot(
     # poi_snapshot(ct_file, f, g)
     from pathlib import Path
 
-    def make_snap(file):
+    def make_snap(file) -> None:
+        """Generate a POI snapshot for the given file if it matches the expected subject index."""
         idx = file.stem
         if idx != "63":
             return
diff --git a/TPTBox/spine/spinestats/README.md b/TPTBox/spine/spinestats/README.md
new file mode 100644
index 0000000..fce970e
--- /dev/null
+++ b/TPTBox/spine/spinestats/README.md
@@ -0,0 +1,27 @@
+# Spine Statistics (`spine/spinestats`)
+
+Clinical spine measurements computed from `POI` objects and `NII` segmentations.
+
+## Modules
+
+| Module | Description |
+|---|---|
+| `distances.py` | Distances between anatomical landmarks (IVD height, canal diameter, …) |
+| `angles.py` | Cobb angle and other spine curvature measurements |
+| `ivd_pois.py` | Intervertebral disc (IVD) Point of Interest computation |
+| `body_quadrants.py` | Subdivides vertebra bodies into anatomical quadrants |
+| `make_endplate.py` | Generates superior/inferior endplate surfaces from segmentations |
+
+## Key functions
+
+| Function | Module | Description |
+|---|---|---|
+| `compute_cobb_angle(poi)` | `angles.py` | Cobb angle between vertebra pairs from POI coordinates |
+| `compute_ivd_height(poi)` | `distances.py` | Inter-vertebral disc height at a given level |
+| `calc_ivd_pois(vert_nii, subreg_nii)` | `ivd_pois.py` | Compute IVD POIs from vertebra + subregion segmentations |
+| `make_endplate(nii, poi, ...)` | `make_endplate.py` | Fit an endplate surface to a vertebra body |
+
+## Coordinate convention
+
+All measurement functions consume `POI` objects (voxel or world space) produced by
+`calc_centroids` or `calc_poi_from_subreg_vert` from the `core` module.
diff --git a/TPTBox/spine/spinestats/angles.py b/TPTBox/spine/spinestats/angles.py
index 7d6d7b8..7c7f832 100644
--- a/TPTBox/spine/spinestats/angles.py
+++ b/TPTBox/spine/spinestats/angles.py
@@ -16,14 +16,14 @@
 
 
 class MoveTo(Enum):
+    """Enum selecting which endplate or centre point of a vertebra is used as the measurement anchor."""
+
     TOP = auto()
     BOTTOM = auto()
     CENTER = auto()
 
-    def has_point(self, v: Vertebra_Instance | int, poi: POI):
-        """
-        Checks if the given vertebra instance or ID has a specific point
-        of interest (POI) based on the current MoveTo position.
+    def has_point(self, v: Vertebra_Instance | int, poi: POI) -> bool:
+        """Check if the given vertebra has a specific POI at the current MoveTo position.
 
         Args:
             v (Vertebra_Instance | int): The vertebra instance or its ID.
@@ -40,10 +40,8 @@ def has_point(self, v: Vertebra_Instance | int, poi: POI):
             return False
         return True
 
-    def get_location(self, v: Vertebra_Instance | int, poi: POI):
-        """
-        Determines the anatomical location of a point of interest (POI)
-        in a vertebra based on the MoveTo position.
+    def get_location(self, v: Vertebra_Instance | int, poi: POI) -> tuple:
+        """Determine the anatomical POI coordinates for the current MoveTo position in a vertebra.
 
         Args:
             v (Vertebra_Instance | int): The vertebra instance or its ID.
@@ -88,10 +86,8 @@ def get_location(self, v: Vertebra_Instance | int, poi: POI):
                 return (v, subreg, prev_vert, subreg)
         return (v, 50)
 
-    def get_point(self, v: Vertebra_Instance | int, poi: POI):
-        """
-        Retrieves the 3D coordinates of a specific point of interest (POI)
-        in a vertebra based on the MoveTo position.
+    def get_point(self, v: Vertebra_Instance | int, poi: POI) -> np.ndarray:
+        """Retrieve the 3D coordinates of a POI in a vertebra at the current MoveTo position.
 
         Args:
             v (Vertebra_Instance | int): The vertebra instance or its ID.
@@ -111,14 +107,20 @@ def get_point(self, v: Vertebra_Instance | int, poi: POI):
         raise NotImplementedError(v, poi)
 
 
-def unit_vector(vector):
-    """Returns the unit vector of the vector."""
-    return vector / np.linalg.norm(vector)
+def unit_vector(vector: np.ndarray) -> np.ndarray:
+    """Return the unit vector of the input vector.
 
+    Args:
+        vector: Any non-zero numeric array.
 
-def angle_between(v1, v2):
+    Returns:
+        Array with the same direction as ``vector`` but unit length.
     """
-    Calculates the angle in radians between two vectors.
+    return vector / np.linalg.norm(vector)
+
+
+def angle_between(v1, v2) -> float:
+    """Calculates the angle in radians between two vectors.
 
     Args:
         v1 (tuple): The first vector.
@@ -140,10 +142,8 @@ def angle_between(v1, v2):
     return np.arccos(np.clip(np.dot(v1_u, v2_u), -1.0, 1.0))
 
 
-def get_to_space(a, b, c):
-    """
-    Computes the transformation matrices from the input coordinate space to the canonical space
-    defined by orthogonal vectors a, b, and c, and vice versa.
+def get_to_space(a, b, c) -> tuple[np.ndarray, np.ndarray]:
+    """Compute forward and inverse transformation matrices for the space defined by three orthogonal vectors.
 
     Args:
         a (np.ndarray): First orthogonal vector.
@@ -160,9 +160,8 @@ def get_to_space(a, b, c):
     return to_space, from_space
 
 
-def cosine_distance(a, b):
-    """
-    Computes the cosine distance between two vectors.
+def cosine_distance(a, b) -> float:
+    """Computes the cosine distance between two vectors.
 
     Args:
         a (np.ndarray): The first vector.
@@ -184,10 +183,10 @@ def compute_angel_between_two_points_(
     project_2D=False,
     use_ivd_direction=False,
 ) -> float | None:
-    """
-    Computes the 2D and 3D angles between two points in a given anatomical structure,
-    such as vertebrae, based on specified directions. This function is particularly
-    useful for calculating coplanar angles, lordosis, and kyphosis, depending on the direction specified.
+    """Compute the 2D or 3D angle between two anatomical landmarks.
+
+    Useful for calculating coplanar angles, lordosis, and kyphosis depending on
+    the direction specified.
 
     Args:
         poi (POI): An object representing a point of interest that supports indexing
@@ -325,9 +324,8 @@ def compute_angel_between_two_points_(
     return angle_2D / np.pi * 180
 
 
-def compute_lordosis_and_kyphosis(poi: POI, project_2D=True):
-    """
-    Calculates the angles of cervical lordosis, thoracic kyphosis, and lumbar lordosis based on the given points of interest (POI).
+def compute_lordosis_and_kyphosis(poi: POI, project_2D=True) -> dict[str, float | None]:
+    """Calculates the angles of cervical lordosis, thoracic kyphosis, and lumbar lordosis based on the given points of interest (POI).
 
     This function determines the angles formed by specific vertebrae along the spine, which are indicative of spinal curvatures.
     The angles are calculated for three key regions: cervical, thoracic, and lumbar, representing lordosis and kyphosis.
@@ -350,6 +348,7 @@ def compute_lordosis_and_kyphosis(poi: POI, project_2D=True):
         - It is essential that the `poi` contains the posterior vertebra direction for accurate angle calculations.
         - Thoracic kyphosis is calculated from T1 to the last thoracic vertebra identified in the POI.
         - Lumbar lordosis is calculated from L1 to the last lumbar vertebra identified in the POI.
+
     Example:
         To compute the spinal angles for a given POI object:
 
@@ -381,7 +380,8 @@ def compute_lordosis_and_kyphosis(poi: POI, project_2D=True):
     }
 
 
-def _get_norm(poi: POI, id1, mv: MoveTo, location: Location, inv=1):  # noqa: ARG001
+def _get_norm(poi: POI, id1: int | Vertebra_Instance, mv: MoveTo, location: Location, inv: int = 1) -> np.ndarray | None:  # noqa: ARG001
+    """Return the normalised direction vector from a location POI to the vertebra centroid."""
     if isinstance(id1, int):
         id1 = Vertebra_Instance(id1)
     subreg = 50
@@ -410,16 +410,16 @@ def _get_norm(poi: POI, id1, mv: MoveTo, location: Location, inv=1):  # noqa: AR
     return norm1_vert
 
 
-def _get_last_lumbar(poi: POI):
-    # if Vertebra_Instance.S1.value not in poi.keys_region():
-    #    return None
+def _get_last_lumbar(poi: POI) -> Vertebra_Instance | None:
+    """Return the most inferior lumbar vertebra that has a centroid in ``poi``."""
     for i in list(reversed(Vertebra_Instance.lumbar()))[:5]:
         if (i.value, 50) in poi:
             return i
     return None
 
 
-def _get_last_thoracic(poi: POI):
+def _get_last_thoracic(poi: POI) -> Vertebra_Instance | None:
+    """Return the most inferior thoracic vertebra that has a centroid in ``poi``."""
     for i in list(reversed(Vertebra_Instance.thoracic()))[:3]:
         if (i.value, 50) in poi:
             return i
@@ -433,9 +433,8 @@ def compute_max_cobb_angle(
     vert_id2_mv: MoveTo = MoveTo.BOTTOM,
     project_2D=True,
     use_ivd_direction=False,
-):
-    """
-    Calculates the maximum Cobb angle from a list of vertebrae using the points of interest (POI).
+) -> tuple[float, int | None, int | None, int | None]:
+    """Calculates the maximum Cobb angle from a list of vertebrae using the points of interest (POI).
 
     The Cobb angle is a measure commonly used to quantify the degree of spinal curvature, particularly for scoliosis.
     This function identifies the maximum Cobb angle by comparing angles between pairs of vertebrae in the specified list.
@@ -450,6 +449,7 @@ def compute_max_cobb_angle(
         poi = calc_poi_from_subreg_vert(nii, nii_subreg, subreg_id=[Location.Vertebra_Corpus,Location.Vertebra_Direction_Right,Location.Vertebra_Disc,Location.Vertebra_Disc_Superior])
         ivd (Vertebra_Disc) will be computed by the segmentation
         + use_ivd_direction = True will use the disc direction and will note if there is a large shift between vertebra without rotation.
+
     Args:
         poi (POI): The points of interest object containing 3D coordinates for various vertebrae.
         vertebrae_list (list, optional): A list of vertebra instances to consider for Cobb angle calculation.
@@ -542,9 +542,8 @@ def compute_max_cobb_angle_multi(
     vert_id2_mv: MoveTo = MoveTo.BOTTOM,
     use_ivd_direction=False,
     project_2D=True,
-):
-    """
-    Identifies multiple Cobb angles along the spine that exceed a given threshold.
+) -> list[tuple[float, int, int, int | None]]:
+    """Identifies multiple Cobb angles along the spine that exceed a given threshold.
 
     This function calculates Cobb angles for a list of vertebrae and recursively finds multiple
     spinal curvatures that are large enough, as determined by a threshold angle. It is useful for
@@ -560,6 +559,7 @@ def compute_max_cobb_angle_multi(
         poi = calc_poi_from_subreg_vert(nii, nii_subreg, subreg_id=[Location.Vertebra_Corpus,Location.Vertebra_Direction_Right,Location.Vertebra_Disc,Location.Vertebra_Disc_Inferior])
         ivd (Vertebra_Disc) will be computed by the segmentation
         + use_ivd_direction = True will use the disc direction and will note if there is a large shift between vertebra without rotation.
+
     Args:
         poi (POI): The points of interest object containing 3D coordinates for various vertebrae.
         vertebrae_list (list, optional): A list of vertebra instances to consider for Cobb angle calculation.
@@ -593,7 +593,6 @@ def compute_max_cobb_angle_multi(
         Angle: 18.2, From: 2, To: 6, Apex: 4
         Angle: 12.4, From: 7, To: 10, Apex: 8
     """
-
     if out_list is None:
         out_list = []
     if vertebrae_list is None:
@@ -641,7 +640,8 @@ def compute_max_cobb_angle_multi(
     return out_list
 
 
-def _add_artificial_ivd(poi: POI):
+def _add_artificial_ivd(poi: POI) -> POI:
+    """Insert synthetic IVD centroids midway between adjacent vertebra centroids if missing."""
     ## ADD IVD if nessasary
     if 100 not in poi.keys_subregion():
         last = None
@@ -664,9 +664,8 @@ def plot_compute_lordosis_and_kyphosis(
     seg: Image_Reference | None = None,
     line_len=100,
     project_2D=True,
-):
-    """
-    Plots and computes the angles of lordosis and kyphosis on a spinal image.
+) -> tuple[dict[str, float | None], Snapshot_Frame]:
+    """Plots and computes the angles of lordosis and kyphosis on a spinal image.
 
     This function calculates cervical lordosis, thoracic kyphosis, and lumbar lordosis angles
     based on the provided Points of Interest (POI) object. It visualizes these angles on the
@@ -724,9 +723,7 @@ def plot_compute_lordosis_and_kyphosis(
         out.append((id1.value, s, (-a[0] * line_len * 3, -a[1] * line_len * 3)))
     out2 = compute_lordosis_and_kyphosis(poi, project_2D=project_2D)
     for (name, v), id1, id2 in zip_strict(
-        out2.items(),
-        [Vertebra_Instance.C7, last_t, last_l],
-        [Vertebra_Instance.C2, Vertebra_Instance.C7, last_t]
+        out2.items(), [Vertebra_Instance.C7, last_t, last_l], [Vertebra_Instance.C2, Vertebra_Instance.C7, last_t]
     ):
         if v is None:
             continue
@@ -758,10 +755,8 @@ def plot_cobb_angle(
     vert_id2_mv: MoveTo = MoveTo.BOTTOM,
     use_ivd_direction=False,
     project_2D=True,
-):
-    """
-    Visualizes the cobb angles for a given spinal image by plotting the angle measurements on the image.
-    The function calculates the maximum cobb angles across the spine and displays the results on the image.
+) -> tuple[list[tuple[float, int, int, int | None]], Snapshot_Frame]:
+    """Visualize Cobb angles on a spinal image by plotting the maximum angles across the spine.
 
     Args:
         img_path (str | Path | None): The file path where the output image with plotted angles should be saved.
@@ -849,9 +844,8 @@ def plot_cobb_and_lordosis_and_kyphosis(
     line_len=100,
     threshold_deg=10,
     project_2D=True,
-):
-    """
-    Plots Cobb angles and lordosis/kyphosis angles on a spinal image.
+) -> tuple[list, dict[str, float | None], list[Snapshot_Frame]]:
+    """Plots Cobb angles and lordosis/kyphosis angles on a spinal image.
 
     This function calculates and visualizes both the Cobb angles for spinal curvature and the angles
     of cervical lordosis, thoracic kyphosis, and lumbar lordosis. It overlays these visualizations
diff --git a/TPTBox/spine/spinestats/body_quadrants.py b/TPTBox/spine/spinestats/body_quadrants.py
index 2ae8e4e..8cf287b 100644
--- a/TPTBox/spine/spinestats/body_quadrants.py
+++ b/TPTBox/spine/spinestats/body_quadrants.py
@@ -4,7 +4,7 @@
 
 import numpy as np
 
-from TPTBox import Image_Reference, Location, calc_poi_from_subreg_vert, to_nii
+from TPTBox import NII, Image_Reference, Location, calc_poi_from_subreg_vert, to_nii
 
 
 def make_quadrants(
@@ -14,9 +14,8 @@ def make_quadrants(
     vert_ids: list[int] | None = None,
     mask_ids=(49, 50, 52),
     erode=0,
-):
-    """
-    Subdivide vertebral body masks into anatomically oriented 3×3×3 regions.
+) -> NII:
+    """Subdivide vertebral body masks into anatomically oriented 3×3×3 regions.
 
     This function computes point-of-interest (POI) landmarks for each vertebra,
     constructs a local vertebra-centric coordinate system, and partitions the
@@ -26,7 +25,7 @@ def make_quadrants(
     image coordinates, making it robust to subject pose, spinal curvature,
     and acquisition orientation.
 
-    Notes
+    Notes:
     -----
     - Only vertebral body voxels are considered (intersection of vertebra and
       spine body labels).
@@ -68,18 +67,18 @@ def make_quadrants(
         List of vertebra IDs to process. If None, all vertebrae found
         in the segmentation are processed.
 
-    Returns
+    Returns:
     -------
     Image_Reference
         An image where each vertebral body voxel is labeled with a value
         from 1 to 27, representing its anatomical subregion.
 
-    Raises
+    Raises:
     ------
     None
         Vertebrae missing required POIs are silently skipped.
 
-    Examples
+    Examples:
     --------
     >>> out = make_quadrants(vert_seg, spine_seg)
     >>> out.save("vertebra_quadrants.nii.gz")
diff --git a/TPTBox/spine/spinestats/distances.py b/TPTBox/spine/spinestats/distances.py
index 2c1a56a..5a9e6b1 100644
--- a/TPTBox/spine/spinestats/distances.py
+++ b/TPTBox/spine/spinestats/distances.py
@@ -10,17 +10,35 @@ def _compute_distance(
     key: str,
     vert: Image_Reference | None = None,
     subreg: Image_Reference | None = None,
-    all_pois_computed=False,
-    recompute=False,
-):
-    """Compute the IVD height with a single point. Returns poi-object with computed points poi heights in
-    poi.info["ivd_heights_center_mm"]
-    all_pois_computed requires [Location.Vertebra_Direction_Inferior,  Location.Vertebra_Disc_Superior] to be computed
-    recompute skips if poi.info["ivd_heights_center_mm"] exist
+    all_pois_computed: bool = False,
+    recompute: bool = False,
+) -> POI:
+    """Compute pairwise distances between two anatomical locations across vertebral regions.
+
+    The distances are stored in ``poi.info[key]`` as a dictionary mapping
+    vertebra region IDs to distances in mm.  If the key already exists and
+    ``recompute`` is ``False`` the function returns ``poi`` unchanged.
+
     Args:
-        vert (Image_Reference): _description_
-        subreg (Image_Reference): _description_
-        poi (POI): _description_
+        poi: POI object containing (or to be extended with) anatomical
+            landmark coordinates.
+        l1: First anatomical location (e.g. superior disc face).
+        l2: Second anatomical location (e.g. inferior disc face).
+        key: Name under which the computed distances are stored in
+            ``poi.info``.
+        vert: Vertebra segmentation image used to compute missing POIs.
+            Required when ``all_pois_computed=False`` and the locations are
+            absent from ``poi``.
+        subreg: Subregion segmentation image used together with ``vert`` for
+            POI computation.
+        all_pois_computed: Skip POI computation and use existing centroids
+            directly.  Requires ``l1`` and ``l2`` to already be present in
+            ``poi``.
+        recompute: When ``True`` overwrite an existing entry in ``poi.info``.
+
+    Returns:
+        The updated :class:`~TPTBox.POI` object with distances stored under
+        ``poi.info[key]``.
     """
     if key in poi.info and not recompute:
         return poi
@@ -59,9 +77,30 @@ def compute_all_distances(
     poi: POI,
     vert: Image_Reference | None = None,
     subreg: Image_Reference | None = None,
-    all_pois_computed=False,
-    recompute=False,
-):
+    all_pois_computed: bool = False,
+    recompute: bool = False,
+) -> POI:
+    """Compute all registered anatomical distances and store them in ``poi.info``.
+
+    Iterates over :data:`distances_funs` and calls :func:`_compute_distance`
+    for each entry.  Results are accumulated in the returned POI object under
+    the corresponding key in ``poi.info``.
+
+    Args:
+        poi: POI object to compute distances for and to store results in.
+        vert: Vertebra segmentation image required when POIs have not been
+            pre-computed.  May be ``None`` when ``all_pois_computed=True``.
+        subreg: Subregion segmentation image required when POIs have not been
+            pre-computed.  May be ``None`` when ``all_pois_computed=True``.
+        all_pois_computed: When ``True`` the function skips POI computation
+            and uses the existing centroids in ``poi`` directly.
+        recompute: When ``True`` existing entries in ``poi.info`` are
+            overwritten; otherwise already-computed keys are skipped.
+
+    Returns:
+        The updated :class:`~TPTBox.POI` object with distance dictionaries
+        stored under the keys defined in :data:`distances_funs`.
+    """
     for key, (l1, l2) in distances_funs.items():
         poi = _compute_distance(poi, l1, l2, key, vert, subreg, all_pois_computed, recompute)
     return poi
diff --git a/TPTBox/spine/spinestats/ivd_pois.py b/TPTBox/spine/spinestats/ivd_pois.py
index 260d943..8f96571 100644
--- a/TPTBox/spine/spinestats/ivd_pois.py
+++ b/TPTBox/spine/spinestats/ivd_pois.py
@@ -15,7 +15,34 @@
 _log = Print_Logger()
 
 
-def strategy_calculate_up_vector(poi: POI, current_vert: NII, vert_id: int, bb, log=_log):
+def strategy_calculate_up_vector(
+    poi: POI,
+    current_vert: NII,
+    vert_id: int,
+    bb: tuple,
+    log: object = _log,
+) -> POI:
+    """Compute IVD superior and inferior extreme points via PCA-based normal estimation.
+
+    Fits a principal component axis through the IVD label (``vert_id + 100``)
+    to determine the superior–inferior direction of the disc, then ray-casts to
+    the extreme points along that axis.  The results are stored as
+    :attr:`~TPTBox.Location.Vertebra_Disc_Inferior` and
+    :attr:`~TPTBox.Location.Vertebra_Disc_Superior` in ``poi``.
+
+    Args:
+        poi: POI object that already contains the IVD centroid for ``vert_id``.
+            Updated in place and returned.
+        current_vert: Cropped vertebra NIfTI used for PCA and ray casting.
+        vert_id: Integer vertebra region ID whose IVD label is ``vert_id + 100``.
+        bb: Bounding-box slices (as returned by
+            :meth:`~TPTBox.NII.compute_crop`) used to convert local
+            coordinates back to the full image space.
+        log: Logger instance used for progress / warning messages.
+
+    Returns:
+        The updated :class:`~TPTBox.POI` object.
+    """
     center = to_local_np(Location.Vertebra_Disc, bb, poi, vert_id, log)
     if center is None:
         return poi
@@ -45,7 +72,14 @@ def strategy_calculate_up_vector(poi: POI, current_vert: NII, vert_id: int, bb,
     return poi
 
 
-def _crop(i: int, verts_ids: list[int], vert_full: NII, spine_full: NII, poi: POI):
+def _crop(
+    i: int,
+    verts_ids: list[int],
+    vert_full: NII,
+    spine_full: NII,
+    poi: POI,
+) -> tuple | None:
+    """Crop the vertebra and spine volumes around vertebra ``i`` and its neighbour."""
     if i >= 100 or (i + 100 in verts_ids):
         return None
     next_id = Vertebra_Instance(i).get_next_poi(verts_ids)
@@ -58,7 +92,8 @@ def _crop(i: int, verts_ids: list[int], vert_full: NII, spine_full: NII, poi: PO
     return i, verts_ids, vert, spine, poi, crop, next_id
 
 
-def _process_vertebra_A(idx, vert: NII, spine: NII, next_id, poi) -> NII | None:
+def _process_vertebra_A(idx: int, vert: NII, spine: NII, next_id: int, poi: POI) -> NII | None:
+    """Generate the IVD mask between vertebra ``idx`` and ``next_id`` using endplate extraction."""
     from TPTBox.spine.spinestats import endplate_extraction
 
     try:
@@ -83,7 +118,8 @@ def _process_vertebra_A(idx, vert: NII, spine: NII, next_id, poi) -> NII | None:
     return ivd
 
 
-def _process_vertebra_B(idx: int, vert: NII, spine: NII, next_id, dilate=1):
+def _process_vertebra_B(idx: int, vert: NII, spine: NII, next_id: Vertebra_Instance, dilate: int = 1) -> NII:
+    """Generate the IVD mask between vertebra ``idx`` and ``next_id`` using convex-hull morphology."""
     spine = spine.extract_label([49, 50, 26])
     spine_full = spine.extract_label([49, 50, 26, 41, 43, 44])
     spine_full = spine_full.calc_convex_hull("S")
@@ -121,9 +157,14 @@ def _process_vertebra_B(idx: int, vert: NII, spine: NII, next_id, dilate=1):
 
 
 def _process_vertebra(
-    idx: int, verts_ids: list[int], vert: NII, spine: NII, poi: POI, dilate=1
+    idx: int,
+    verts_ids: list[int],
+    vert: NII,
+    spine: NII,
+    poi: POI,
+    dilate: int = 1,
 ) -> tuple[NII, tuple[slice, slice, slice]] | None:
-    """Process a single vertebra index."""
+    """Compute the synthetic IVD mask for a single vertebra and return it with its crop slices."""
     # POI is not cropped, as we only need the vertebra direction
     result = _crop(idx, verts_ids, vert, spine, poi)
     if result is None:
@@ -198,7 +239,27 @@ def _process_vertebra(
     return ivd_2, crop
 
 
-def compute_fake_ivd(vert_full: NII, subreg_full: NII, poi: POI, dilate=1):
+def compute_fake_ivd(vert_full: NII, subreg_full: NII, poi: POI, dilate: int = 1) -> NII:
+    """Add synthetic intervertebral disc (IVD) labels to the vertebra segmentation.
+
+    For every adjacent vertebra pair a synthetic IVD mask is computed using
+    morphological operations on the subregion labels.  The disc for vertebra
+    ``i`` is assigned label ``100 + i`` in the output.  The computation is
+    parallelised over vertebrae using a :class:`~concurrent.futures.ProcessPoolExecutor`.
+
+    Args:
+        vert_full: Vertebra segmentation NIfTI; each vertebra has a unique
+            integer label.  Modified in place and returned.
+        subreg_full: Subregion segmentation NIfTI containing spine body labels
+            (e.g. 49, 50).
+        poi: POI object used to ensure that
+            :attr:`~TPTBox.Location.Vertebra_Corpus` centroids are available.
+        dilate: Morphological dilation radius applied when building the IVD
+            hull mask.
+
+    Returns:
+        The updated ``vert_full`` NIfTI with synthetic IVD labels added.
+    """
     subreg_ids_required_for_ivd_generation = [
         # Location.Inferior_Articular_Left,
         # Location.Inferior_Articular_Right,
@@ -245,7 +306,34 @@ def compute_fake_ivd(vert_full: NII, subreg_full: NII, poi: POI, dilate=1):
     return vert_full
 
 
-def calculate_IVD_POI(vert: NII, subreg: NII, poi: POI, ivd_location: set[Location] | None = None):
+def calculate_IVD_POI(
+    vert: NII,
+    subreg: NII,
+    poi: POI,
+    ivd_location: set[Location] | None = None,
+) -> POI:
+    """Compute IVD-related Points of Interest and add them to ``poi``.
+
+    If the subregion image does not yet contain IVD labels (label 100),
+    :func:`compute_fake_ivd` is called first to synthesise them.  Centroid
+    POIs at label 100 are then computed for all vertebrae and optionally
+    extended with superior / inferior extreme disc points via
+    :func:`strategy_calculate_up_vector`.
+
+    Args:
+        vert: Vertebra segmentation NIfTI.
+        subreg: Subregion segmentation NIfTI; updated in place when IVD labels
+            are synthesised.
+        poi: POI object to extend.  Updated in place and returned.
+        ivd_location: Set of :class:`~TPTBox.Location` values to compute.
+            Defaults to
+            ``{Location.Vertebra_Disc_Superior, Location.Vertebra_Disc}``.
+            Pass an empty set to skip computation entirely.
+
+    Returns:
+        The updated :class:`~TPTBox.POI` object with IVD-related locations
+        added.
+    """
     if ivd_location is None:
         ivd_location = {Location.Vertebra_Disc_Superior, Location.Vertebra_Disc}
     # Note: currently we always need point 100, so it is computed if any Location is in ivd_location
diff --git a/TPTBox/spine/spinestats/make_endplate.py b/TPTBox/spine/spinestats/make_endplate.py
index cd8f8fa..7799636 100644
--- a/TPTBox/spine/spinestats/make_endplate.py
+++ b/TPTBox/spine/spinestats/make_endplate.py
@@ -25,7 +25,8 @@
 )
 
 
-def _dilate_erode_special(np_array: np.ndarray, ball_size=3, normal: None | np.ndarray = None) -> np.ndarray:
+def _dilate_erode_special(np_array: np.ndarray, ball_size: int = 3, normal: np.ndarray | None = None) -> np.ndarray:
+    """Apply a morphological open (dilate then erode) with an axis-aligned or isotropic structuring element."""
     if normal is None:
         struct = ball(ball_size)
     else:
@@ -38,14 +39,14 @@ def _dilate_erode_special(np_array: np.ndarray, ball_size=3, normal: None | np.n
 
 
 def _get_largest_CC(segmentation: np.ndarray) -> np.ndarray:
-    """
-    Extracts the largest connected component from a binary segmentation.
+    """Extract the largest connected component from a binary segmentation.
 
-    Parameters:
-    - segmentation (np.ndarray): Input binary segmentation array.
+    Args:
+        segmentation: Input binary segmentation array of any dimensionality.
 
     Returns:
-    - np.ndarray: Binary array of the largest connected component.
+        Binary integer array of the same shape containing only the largest
+        connected component (background label 0 is excluded).
     """
     labels = label(segmentation)
     unique, counts = np.unique(labels, return_counts=True)  # type: ignore
@@ -53,12 +54,21 @@ def _get_largest_CC(segmentation: np.ndarray) -> np.ndarray:
     return (labels == largest_label).astype(int)
 
 
-def _get_endplate(body, mult, axis=1):
-    """
-    calculating the endplates using projection method
-    mult variable is a 3D numpy array of indices with the same size as body,
-    descending and ascending indices determents wether we are extracting the
-    upper or lower endplate.
+def _get_endplate(body: np.ndarray, mult: np.ndarray, axis: int = 1) -> np.ndarray:
+    """Extract a single endplate surface from a vertebra body via projection and K-means clustering.
+
+    The ``mult`` array encodes depth along the normal direction.  K-means
+    with three clusters is applied to the per-pixel argmax values to separate
+    the true endplate layer from noise and the opposite surface.
+
+    Args:
+        body: 3-D binary array of the vertebral body voxels.
+        mult: 3-D integer array of the same shape as ``body`` containing
+            depth indices along the projection axis.
+        axis: Image axis along which the projection (argmax) is taken.
+
+    Returns:
+        3-D binary array marking the extracted endplate voxels.
     """
     body = body * mult
 
@@ -98,15 +108,19 @@ def _get_endplate(body, mult, axis=1):
 
 
 def _extract_endplate_np(body: np.ndarray, projected: np.ndarray, normal: np.ndarray, lower: bool = False) -> np.ndarray:
-    """
-    Extracts the upper or lower endplate of the given body.
+    """Extract the superior or inferior endplate from a body array.
 
-    Parameters:
-    - body (np.ndarray): 3D binary array representing the segmented body.
-    - lower (bool): If True, extracts the lower endplate. Otherwise, extracts the upper endplate.
+    Args:
+        body: 3-D binary array of the segmented vertebral body.
+        projected: 3-D integer depth-index array aligned with the vertebra
+            normal direction.
+        normal: Normal vector of the endplate plane, used to choose the
+            structuring element orientation for morphological smoothing.
+        lower: When ``True`` the inferior (lower) endplate is extracted;
+            otherwise the superior (upper) endplate is returned.
 
     Returns:
-    - np.ndarray: Binary mask representing the extracted endplate.
+        3-D binary array marking the extracted endplate voxels.
     """
     # Adjust projection for lower endplate if needed
     if lower:
@@ -117,15 +131,24 @@ def _extract_endplate_np(body: np.ndarray, projected: np.ndarray, normal: np.nda
     return endplate_mask
 
 
-def _endplate_extraction_msk(subreg_tmp: NII, normal: np.ndarray, _extract=True) -> NII:
-    """
-    Extracts upper and lower endplates from the given NII object and labels them.
+def _endplate_extraction_msk(subreg_tmp: NII, normal: np.ndarray, _extract: bool = True) -> NII:
+    """Extract superior and inferior endplates from a NIfTI segmentation and label them.
+
+    Projects the body along the vertebra normal vector, then calls
+    :func:`_extract_endplate_np` twice (for superior and inferior surfaces).
+    Labels are set to
+    :attr:`~TPTBox.Location.Vertebral_Body_Endplate_Superior` and
+    :attr:`~TPTBox.Location.Vertebral_Body_Endplate_Inferior`.
 
-    Parameters:
-    - subreg_tmp (NII): Input NII object containing the body segmentation.
+    Args:
+        subreg_tmp: NIfTI segmentation containing vertebra body labels.
+        normal: Normal vector of the endplate plane used to orient the
+            projection and structuring element.
+        _extract: When ``True`` only voxels belonging to ``vertebra_body``
+            labels are considered; when ``False`` all non-zero voxels are used.
 
     Returns:
-    - NII: Updated NII object with labeled endplates.
+        Updated :class:`~TPTBox.NII` with endplate labels set.
     """
     out_arr = np.zeros_like(subreg_tmp.get_array())
     if _extract:
@@ -146,12 +169,32 @@ def _endplate_extraction_msk(subreg_tmp: NII, normal: np.ndarray, _extract=True)
     return subreg_tmp.set_array(out_arr)
 
 
-def endplate_extraction(idx, vert: NII, subreg: NII, poi: POI) -> NII | None:
-    """
-    Retrospectively computes an endplate to a vertebra (Two-Sided).
+def endplate_extraction(
+    idx: int | Enum,
+    vert: NII,
+    subreg: NII,
+    poi: POI,
+) -> NII | None:
+    """Compute the superior and inferior endplates for a single vertebra.
+
+    The vertebra is reoriented to a canonical orientation, cropped, and
+    the endplate surfaces are extracted using projection and K-means
+    clustering along the superior–inferior normal direction.  Sacral
+    vertebrae (except S1) are skipped.
+
+    Args:
+        idx: Vertebra region label (integer or :class:`~enum.Enum` subtype).
+        vert: Full vertebra segmentation NIfTI.
+        subreg: Subregion segmentation NIfTI containing vertebra body labels.
+        poi: POI object used to retrieve the superior–inferior direction for
+            the vertebra.
 
     Returns:
-    - NII: endplates labeled 52, 53.
+        A :class:`~TPTBox.NII` with endplate labels set to
+        :attr:`~TPTBox.Location.Vertebral_Body_Endplate_Superior` and
+        :attr:`~TPTBox.Location.Vertebral_Body_Endplate_Inferior`, or
+        ``None`` when the vertebra is a sacral level or no direction POI is
+        available.
     """
     if isinstance(idx, Enum):
         idx = idx.value
diff --git a/TPTBox/stitching/README.md b/TPTBox/stitching/README.md
index 7f332a4..bc80162 100644
--- a/TPTBox/stitching/README.md
+++ b/TPTBox/stitching/README.md
@@ -1,6 +1,16 @@
-# Torso Processing ToolBox (TPTBox) - Stitching
+# Stitching (`TPTBox.stitching`)
 
-This tool can merge multiple Nifti images if they are already aligned in global space. You can check this by opening them in ITKSnap with "open additional image."
+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](stitching.jpg?raw=true "Example of a stitching")
 
@@ -77,4 +87,4 @@ Graf, R., Platzek, PS., Riedel, E.O. et al. Generating synthetic high-resolution
   publisher={Springer}
 }
 
-```
\ No newline at end of file
+```
diff --git a/TPTBox/stitching/stitching.py b/TPTBox/stitching/stitching.py
index 02b8e2e..affb85d 100755
--- a/TPTBox/stitching/stitching.py
+++ b/TPTBox/stitching/stitching.py
@@ -13,7 +13,18 @@
 from skimage.exposure import match_histograms
 
 
-def get_rotation_and_spacing_from_affine(affine: np.ndarray):
+def get_rotation_and_spacing_from_affine(affine: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Decompose a NIfTI affine into its rotation matrix and voxel spacing.
+
+    Adapted from nibabel.orientations.
+
+    Args:
+        affine: 4x4 affine transformation matrix.
+
+    Returns:
+        A 2-tuple of ``(rotation, spacing)`` where ``rotation`` is a 3x3
+        orthonormal matrix and ``spacing`` is a 1-D array of three voxel sizes.
+    """
     # From https://github.com/nipy/nibabel/blob/master/nibabel/orientations.py
     rotation_zoom = affine[:3, :3]
     spacing = np.sqrt(np.sum(rotation_zoom * rotation_zoom, axis=0))
@@ -21,7 +32,19 @@ def get_rotation_and_spacing_from_affine(affine: np.ndarray):
     return rotation, spacing
 
 
-def get_ras_affine(rotation, spacing, origin) -> np.ndarray:
+def get_ras_affine(rotation: np.ndarray, spacing: np.ndarray, origin: np.ndarray) -> np.ndarray:
+    """Build a RAS affine matrix from rotation, voxel spacing, and image origin.
+
+    Adapted from TorchIO's IO utilities.
+
+    Args:
+        rotation: 3x3 orthonormal rotation matrix.
+        spacing: 1-D array of three voxel spacings (mm).
+        origin: 1-D array giving the index-space origin coordinates.
+
+    Returns:
+        A 4x4 RAS affine matrix.
+    """
     # https://github.com/fepegar/torchio/blob/5983f83f0e7f13f9c5056e25f8753b03426ae18a/src/torchio/data/io.py#L357
     rotation_zoom = rotation * spacing
     translation_ras = rotation.dot(origin)
@@ -31,7 +54,17 @@ def get_ras_affine(rotation, spacing, origin) -> np.ndarray:
     return affine
 
 
-def get_all_corner_points(affine, shape):
+def get_all_corner_points(affine: np.ndarray, shape: tuple[int, ...]) -> np.ndarray:
+    """Compute the eight world-space corner points of a voxel volume.
+
+    Args:
+        affine: 4x4 affine mapping voxel indices to world coordinates.
+        shape: Volume shape (X, Y, Z).
+
+    Returns:
+        Array of shape (8, 3) with the world-space coordinates of all eight
+        corners of the bounding box.
+    """
     lst = list(itertools.product([0, 1], repeat=3))
     lst = np.array(lst) * np.array(shape)
     lst += 1
@@ -40,10 +73,30 @@ def get_all_corner_points(affine, shape):
 
 
 def get_array(nii: Nifti1Image) -> np.ndarray:
+    """Extract the voxel data from a NIfTI image as a writable NumPy array.
+
+    Args:
+        nii: Source NIfTI image.
+
+    Returns:
+        A copy of the image data array with the original dtype preserved.
+    """
     return np.asanyarray(nii.dataobj, dtype=nii.dataobj.dtype).copy()  # type: ignore
 
 
 def set_array(nii: Nifti1Image, arr: np.ndarray) -> Nifti1Image:
+    """Return a new NIfTI image with the given array, preserving header and affine.
+
+    If the dtype of ``arr`` differs from the existing image, the header dtype is
+    updated accordingly.
+
+    Args:
+        nii: Source NIfTI image whose header and affine are reused.
+        arr: Replacement voxel data array.
+
+    Returns:
+        A new :class:`Nifti1Image` backed by ``arr``.
+    """
     if nii.dataobj.dtype == arr.dtype:  # type: ignore
         nii = Nifti1Image(arr, nii.affine, nii.header)
     else:
@@ -53,11 +106,47 @@ def set_array(nii: Nifti1Image, arr: np.ndarray) -> Nifti1Image:
     return nii
 
 
-def argmin(lst: list):
+def argmin(lst: list) -> int:
+    """Return the index of the minimum element in a list.
+
+    Args:
+        lst: Input list of comparable elements.
+
+    Returns:
+        Zero-based index of the smallest element.
+    """
     return lst.index(min(lst))
 
 
-def get_max_affine_and_shape(points: np.ndarray, affines, min_spacing=None, dtype: type = float, verbose=False):
+def get_max_affine_and_shape(
+    points: np.ndarray,
+    affines: list[np.ndarray],
+    min_spacing: float | None = None,
+    dtype: type = float,
+    verbose: bool = False,
+) -> Nifti1Image:
+    """Determine the optimal output affine and shape that encloses all input volumes.
+
+    Iterates over all input affines and selects the rotation that minimises the
+    bounding-box volume of the convex hull of ``points``.  The finest (minimum)
+    voxel spacing across all inputs is used, optionally clipped from below by
+    ``min_spacing``.
+
+    Args:
+        points: World-space corner coordinates of all input volumes, shape (N, 3).
+        affines: List of 4x4 affine matrices, one per input volume.
+        min_spacing: Optional lower-bound on the output voxel spacing (mm).
+        dtype: NumPy dtype for the output image data.
+        verbose: If True, prints chosen spacing, shape, origin, and optimal
+            rotation to stdout.
+
+    Returns:
+        A zeroed :class:`Nifti1Image` with the computed affine and shape, ready
+        to be used as a resampling target.
+
+    Raises:
+        ValueError: If no valid rotation could be determined from ``affines``.
+    """
     hull = ConvexHull(points)
 
     min_possible_volume = hull.volume
@@ -109,9 +198,8 @@ def get_max_affine_and_shape(points: np.ndarray, affines, min_spacing=None, dtyp
     return nib.Nifti1Image(np.zeros(shape.astype(int), dtype=dtype), affine)  # type: ignore
 
 
-def compute_crop_slice(nii: Nifti1Image, minimum=0, dist=0):
-    """
-    Computes the minimum slice that removes unused space from the image and returns the corresponding slice tuple along with the origin shift required for centroids.
+def compute_crop_slice(nii: Nifti1Image, minimum=0, dist=0) -> tuple[slice, slice, slice]:
+    """Computes the minimum slice that removes unused space from the image and returns the corresponding slice tuple along with the origin shift required for centroids.
 
     Args:
         minimum (int): The minimum value of the array (0 for MRI, -1024 for CT). Default value is 0.
@@ -153,25 +241,20 @@ def compute_crop_slice(nii: Nifti1Image, minimum=0, dist=0):
     return ex_slice
 
 
-def dilate_msk(msk_i_data: np.ndarray, mm: int = 5, connectivity: int = 3):
-    from scipy.ndimage import binary_dilation, generate_binary_structure
-
-    """
-    Dilates the binary segmentation mask by the specified number of voxels.
+def dilate_msk(msk_i_data: np.ndarray, mm: int = 5, connectivity: int = 3) -> np.ndarray:
+    """Dilate each label in a segmentation mask by a fixed number of voxels.
 
     Args:
-        mm (int, optional): The number of voxels to dilate the mask by. Defaults to 5.
-        connectivity (int, optional): Elements up to a squared distance of connectivity from the center are considered neighbors. connectivity may range from 1 (no diagonal elements are neighbors) to rank (all elements are neighbors).
-        inplace (bool, optional): Whether to modify the mask in place or return a new object. Defaults to False.
-        verbose (bool, optional): Whether to print a message indicating that the mask was dilated. Defaults to True.
+        msk_i_data: Integer-valued 3-D segmentation array. Label 0 is background.
+        mm: Number of dilation iterations to apply per label.
+        connectivity: Structuring-element connectivity (1 = face-connected,
+            3 = fully-connected including diagonals).
 
     Returns:
-        NII: The dilated mask.
-
-    Notes:
-        The method uses binary dilation with a 3D structuring element to dilate the mask by the specified number of voxels.
-
+        A dilated ``uint8`` array of the same shape as ``msk_i_data``.
     """
+    from scipy.ndimage import binary_dilation, generate_binary_structure
+
     struct = generate_binary_structure(3, connectivity)
     out = msk_i_data.copy() * 0
     for i in np.unique(msk_i_data):
@@ -186,15 +269,42 @@ def dilate_msk(msk_i_data: np.ndarray, mm: int = 5, connectivity: int = 3):
 
 def n4_bias_field_correction(
     nib: Nifti1Image,
-    mask=None,
-    threshold=60,
-    shrink_factor=4,
-    convergence=None,
-    spline_param=150,
-    verbose=False,
-    weight_mask=None,
-    crop=False,
-):
+    mask: np.ndarray | None = None,
+    threshold: int = 60,
+    shrink_factor: int = 4,
+    convergence: dict | None = None,
+    spline_param: int = 150,
+    verbose: bool = False,
+    weight_mask: np.ndarray | None = None,
+    crop: bool = False,
+) -> Nifti1Image:
+    """Apply N4 bias-field correction to a NIfTI image using ANTsPy.
+
+    A binary mask is derived automatically from voxels above ``threshold``
+    and dilated by 3 voxels before correction is applied.
+
+    Args:
+        nib: Input NIfTI image to correct.
+        mask: Optional pre-computed binary mask passed to ANTsPy. Overridden
+            when ``threshold != 0``.
+        threshold: Voxel intensity threshold for automatic mask generation.
+            Set to 0 to disable automatic masking.
+        shrink_factor: Image downsampling factor used inside ANTsPy to
+            speed up computation.
+        convergence: ANTsPy convergence dict with keys ``"iters"`` and
+            ``"tol"``. Defaults to ``{"iters": [50, 50, 50, 50], "tol": 1e-7}``.
+        spline_param: B-spline control point spacing for the bias field model.
+        verbose: If True, ANTsPy prints progress information.
+        weight_mask: Optional spatial weight mask passed to ANTsPy.
+        crop: If True, crops the corrected image to the region where the bias
+            field differed from the input.
+
+    Returns:
+        The bias-field-corrected NIfTI image.
+
+    Raises:
+        ModuleNotFoundError: If ``antspyx`` is not installed.
+    """
     try:
         import ants
         import ants.utils.bias_correction as bc  # pip install antspyx==0.4.2
@@ -209,14 +319,13 @@ def n4_bias_field_correction(
         # TODO add conversion and remove this
 
         def from_nibabel(nib_image):
-            """
-            Converts a given Nifti image into an ANTsPy image
+            """Converts a given Nifti image into an ANTsPy image.
 
             Parameters
             ----------
                 img: NiftiImage
 
-            Returns
+            Returns:
             -------
                 ants_image: ANTsImage
             """
@@ -286,7 +395,21 @@ def to_nibabel(img: ants.core.ants_image.ANTsImage):
 buffer_references = {}
 
 
-def buffer_reference(path, bias_field: bool, crop=False):
+def buffer_reference(path: str | Path, bias_field: bool, crop: bool = False) -> np.ndarray | Nifti1Image:
+    """Load (and optionally bias-correct) a NIfTI file, caching the result.
+
+    Subsequent calls with the same ``path`` return the cached result without
+    re-reading or re-correcting the file.
+
+    Args:
+        path: File path of the NIfTI image.
+        bias_field: If True, applies N4 bias-field correction before caching.
+        crop: Passed to :func:`n4_bias_field_correction` when ``bias_field`` is True.
+
+    Returns:
+        The image data array (if ``bias_field`` is False) or the corrected
+        :class:`Nifti1Image` (if ``bias_field`` is True).
+    """
     if path in buffer_references:
         return buffer_references[path]
     reference = n4_bias_field_correction(nib.load(path), crop) if bias_field else get_array(nib.load(path))  # type: ignore
@@ -318,14 +441,64 @@ def main(  # noqa: C901
     crop_to_bias_field: bool = False,
     crop_empty: bool = False,
     histogram: str | None = None,
-    ramp_edge_min_value=5,
-    min_spacing: None | int = None,
-    kick_out_fully_integrated_images=False,
+    ramp_edge_min_value: int = 5,
+    min_spacing: int | None = None,
+    kick_out_fully_integrated_images: bool = False,
     is_segmentation: bool = False,
     dtype: type | str = float,
-    save=True,
+    save: bool = True,
     ramp_path=None,
-):
+) -> tuple[Nifti1Image | None, Nifti1Image | None]:
+    """Stitch multiple overlapping NIfTI volumes into a single output volume.
+
+    The algorithm:
+
+    1. Optionally applies N4 bias-field correction and histogram matching to
+       each input volume.
+    2. Finds the minimum bounding-box affine that encloses all inputs.
+    3. Resamples every volume into that common space.
+    4. Computes per-voxel blending weights using distance-transform-based
+       ramps in overlap regions.
+    5. Combines all resampled volumes with those weights and saves the result.
+
+    Args:
+        images: Input volumes as file paths or pre-loaded :class:`Nifti1Image`
+            objects. At least two are required.
+        output: Output file path (``".nii.gz"`` extension is appended if
+            absent). If None the result is returned without writing to disk
+            (``save`` must also be False).
+        match_histogram: If True, matches the histogram of each volume to the
+            previous one before stitching.
+        store_ramp: If True, also saves the per-volume blend weights as a 4-D
+            NIfTI alongside the stitched output.
+        verbose: If True, prints progress messages to stdout.
+        min_value: Background value (0 for MRI, -1024 for CT). Voxels at or
+            below this value are replaced by it in the output.
+        bias_field: If True, applies N4 bias-field correction to each input
+            before stitching. Forced to False for segmentations.
+        crop_to_bias_field: If True, crops each bias-corrected volume to the
+            region affected by the correction.
+        crop_empty: If True, crops the final output to its non-background
+            bounding box.
+        histogram: Path or index string used as the histogram reference for
+            ``match_histogram``.
+        ramp_edge_min_value: Minimum thickness (voxels) of non-overlapping
+            regions used when computing distance-transform ramps.
+        min_spacing: Minimum allowed output voxel spacing (mm). Overrides the
+            finest input spacing when specified.
+        kick_out_fully_integrated_images: If True, recursively removes volumes
+            that are fully enclosed within another volume.
+        is_segmentation: If True, disables bias field, histogram matching, and
+            uses nearest-neighbour resampling with integer dtype selection.
+        dtype: Output data type. Accepts a Python type (e.g. ``float``,
+            ``np.uint16``) or a string key from the internal type mapping.
+        save: If True, writes the stitched image to ``output``.
+
+    Returns:
+        A 2-tuple ``(stitched_nii, ramp_nii)`` where ``ramp_nii`` is None
+        unless ``store_ramp`` is True. Returns ``(None, None)`` when fewer
+        than two images are supplied.
+    """
     np.set_printoptions(precision=2, floatmode="fixed")
     if is_segmentation:
         bias_field = False
diff --git a/TPTBox/stitching/stitching_tools.py b/TPTBox/stitching/stitching_tools.py
index bbcb4be..2e44fc4 100755
--- a/TPTBox/stitching/stitching_tools.py
+++ b/TPTBox/stitching/stitching_tools.py
@@ -13,17 +13,46 @@
 def stitching(
     bids_files: list[BIDS_FILE | NII | str | Path] | list,
     out: BIDS_FILE | str | Path,
-    is_seg=False,
+    is_seg: bool = False,
     is_ct: bool = False,
-    verbose_stitching=False,
-    bias_field=False,
-    kick_out_fully_integrated_images=True,
-    verbose=True,
+    verbose_stitching: bool = False,
+    bias_field: bool = False,
+    kick_out_fully_integrated_images: bool = True,
+    verbose: bool = True,
     dtype: type = float,
-    match_histogram=False,
-    store_ramp=False,
+    match_histogram: bool = False,
+    store_ramp: bool = False,
     ramp_path=None,
-):
+) -> tuple:
+    """Stitch a list of BIDS/NII volumes into a single output NIfTI file.
+
+    Convenience wrapper around :func:`stitching_raw` that accepts BIDS_FILE
+    objects, NII instances, or raw file paths and resolves the output path from
+    a BIDS_FILE if necessary.
+
+    Args:
+        bids_files: Input volumes to stitch.  Accepts any mix of
+            :class:`BIDS_FILE`, :class:`NII`, ``str``, or :class:`Path`.
+        out: Destination path for the stitched volume. When a
+            :class:`BIDS_FILE` is provided, the ``"nii.gz"`` file path is used.
+        is_seg: If True, treats the inputs as segmentation images (disables
+            bias field and histogram matching, uses integer dtypes).
+        is_ct: If True, sets the background ``min_value`` to ``-1024`` (CT
+            air) instead of ``0`` (MRI).
+        verbose_stitching: If True, forwards verbose output from the low-level
+            stitching routine.
+        bias_field: If True, applies N4 bias-field correction to each input.
+        kick_out_fully_integrated_images: If True, removes volumes that are
+            fully contained within another volume before stitching.
+        verbose: If True, logs the output path before stitching.
+        dtype: NumPy dtype for the output array.
+        match_histogram: If True, matches histograms between consecutive inputs.
+        store_ramp: If True, also returns the per-volume blending weight array.
+
+    Returns:
+        A 2-tuple ``(stitched_nii, ramp_nii)`` as returned by
+        :func:`stitching_raw`.
+    """
     out = str(out.file["nii.gz"]) if isinstance(out, BIDS_FILE) else str(out)
     files = [to_nii(bf).nii for bf in bids_files]
     logger.print("stitching", out, verbose=verbose)
@@ -43,6 +72,7 @@ def stitching(
 
 
 def _crop_borders(nii: NII, chunk_info: str, cut: dict[str, tuple[slice, slice, slice]]) -> NII:
+    """Crop a NII volume to predefined borders for a given spine-chunk key."""
     if chunk_info not in cut:
         logger.print("chunk_info must be in [HWS, BWS, LWS]")
     ori = nii.orientation
@@ -59,8 +89,9 @@ def GNC_stitch_T2w(
     #    "BWS": (slice(None), slice(80, 400), slice(None)),
     #    "LWS": (slice(None), slice(48, 448), slice(None)),
     # },
-):
-    """Preprocessing steps where n4 each chunk, then stitch, then n4
+) -> NII:
+    """Apply N4 bias correction to each chunk, stitch them, then apply N4 again.
+
     Args:
         HWS (NII | str | Path): Cervical region
         BWS (NII | str | Path): Thoracic region
@@ -107,7 +138,26 @@ def n4_bias(
     spline_param: int = 200,
     dtype2nii: bool = False,
     norm: int = -1,
-):
+) -> tuple[NII, NII]:
+    """Apply N4 bias-field correction to a NII image with automatic mask generation.
+
+    Voxels below ``threshold`` are excluded from the bias estimation via a
+    dilated binary mask.
+
+    Args:
+        nii: Input image to correct.
+        threshold: Intensity threshold below which voxels are excluded from
+            the bias estimation mask.
+        spline_param: B-spline control point spacing for the bias field model.
+        dtype2nii: If True, casts the corrected image back to the original
+            dtype of ``nii``.
+        norm: If != -1, normalizes the corrected image so its maximum equals
+            ``norm``.
+
+    Returns:
+        A 2-tuple ``(n4_corrected_nii, mask_nii)`` where ``mask_nii`` is the
+        dilated binary mask used during correction.
+    """
     from ants.utils.convert_nibabel import from_nibabel
 
     # print("n4 bias", nii.dtype)
@@ -125,8 +175,8 @@ def n4_bias(
     return n4, mask_nii
 
 
-def _center_frontal(size):
-    """Calculating the location of the frontalplain +- 256"""
+def _center_frontal(size: int) -> slice:
+    """Compute a slice centred on the frontal plane of a spinal MRI volume."""
     # The multiplicator-factor was empirically evaluated in an excel sheet with 11 random MRIs
     lower_bound = size * 0.2
     upper_bound = size * 0.75
diff --git a/TPTBox/tests/speedtests/speedtest_panoptica.py b/TPTBox/tests/speedtests/speedtest_panoptica.py
new file mode 100644
index 0000000..84f4801
--- /dev/null
+++ b/TPTBox/tests/speedtests/speedtest_panoptica.py
@@ -0,0 +1,37 @@
+if __name__ == "__main__":
+    # speed test dilation
+    import random
+
+    import numpy as np
+    from panoptica.utils.input_check_and_conversion.sanity_checker import sanity_check_and_convert_to_array
+    from scipy.ndimage import center_of_mass
+
+    from TPTBox.core.nii_wrapper import NII
+    from TPTBox.core.np_utils import (
+        _to_labels,
+        np_extract_label,
+    )
+    from TPTBox.tests.speedtests.speedtest import speed_test
+    from TPTBox.tests.test_utils import get_nii
+
+    def get_nii_array():
+        num_points = random.randint(5, 10)
+        nii, points, orientation, sizes = get_nii(x=(10, 10, 10), num_point=num_points)
+        # nii.map_labels_({1: -1}, verbose=False)
+        arr = nii.get_seg_array().astype(np.uint8)
+        # arr[arr == 1] = -1
+        # arr_r = arr.copy()
+        return arr
+
+    def check_sanity(arr: np.ndarray):
+        _, c = sanity_check_and_convert_to_array(arr, arr)
+        return c.name
+
+    speed_test(
+        repeats=5,
+        get_input_func=get_nii_array,
+        functions=[check_sanity],
+        assert_equal_function=lambda x, y: np.array_equal(x, y),  # noqa: ARG005
+        # np.all([x[i] == y[i] for i in range(len(x))])
+    )
+    # print(time_measures)
diff --git a/docs/api/bids.md b/docs/api/bids.md
new file mode 100644
index 0000000..2e32d86
--- /dev/null
+++ b/docs/api/bids.md
@@ -0,0 +1,35 @@
+# BIDS Files
+
+Classes for navigating BIDS-compliant datasets, parsing filenames into structured entities,
+and filtering/querying files across subjects and sessions.
+
+## BIDS_Global_info
+
+::: TPTBox.core.bids_files.BIDS_Global_info
+    options:
+      show_source: true
+      members_order: source
+
+## Subject_Container
+
+::: TPTBox.core.bids_files.Subject_Container
+    options:
+      show_source: true
+
+## BIDS_FILE
+
+::: TPTBox.core.bids_files.BIDS_FILE
+    options:
+      show_source: true
+
+## Searchquery
+
+::: TPTBox.core.bids_files.Searchquery
+    options:
+      show_source: true
+
+## BIDS_Family
+
+::: TPTBox.core.bids_files.BIDS_Family
+    options:
+      show_source: true
diff --git a/docs/api/logger.md b/docs/api/logger.md
new file mode 100644
index 0000000..dad8b6e
--- /dev/null
+++ b/docs/api/logger.md
@@ -0,0 +1,33 @@
+# Logger
+
+Structured, consistent logging for long-running medical image processing pipelines.
+
+## Logger
+
+::: TPTBox.logger.log_file.Logger
+    options:
+      show_source: true
+
+## Logger_Interface
+
+::: TPTBox.logger.log_file.Logger_Interface
+    options:
+      show_source: true
+
+## No_Logger
+
+::: TPTBox.logger.log_file.No_Logger
+    options:
+      show_source: true
+
+## String_Logger
+
+::: TPTBox.logger.log_file.String_Logger
+    options:
+      show_source: true
+
+## Log_Type
+
+::: TPTBox.logger.log_constants.Log_Type
+    options:
+      show_source: true
diff --git a/docs/api/mesh3d.md b/docs/api/mesh3d.md
new file mode 100644
index 0000000..baf7275
--- /dev/null
+++ b/docs/api/mesh3d.md
@@ -0,0 +1,31 @@
+# Mesh 3D
+
+3D surface mesh generation from segmentation volumes and snapshot rendering.
+
+## Snapshot 3D
+
+::: TPTBox.mesh3D.snapshot3D
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## Mesh
+
+::: TPTBox.mesh3D.mesh
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## Mesh Colors
+
+::: TPTBox.mesh3D.mesh_colors
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## HTML Preview
+
+::: TPTBox.mesh3D.html_preview
+    options:
+      show_source: true
+      filters: ["!^_"]
diff --git a/docs/api/nii.md b/docs/api/nii.md
new file mode 100644
index 0000000..1123137
--- /dev/null
+++ b/docs/api/nii.md
@@ -0,0 +1,12 @@
+# NII — NIfTI Image Wrapper
+
+The [`NII`][TPTBox.core.nii_wrapper.NII] class is the central image abstraction in TPTBox.
+It wraps a nibabel `Nifti1Image` and exposes reorientation, resampling, masking, arithmetic,
+and I/O operations through a consistent interface.
+
+## NII
+
+::: TPTBox.core.nii_wrapper.NII
+    options:
+      show_source: true
+      members_order: source
diff --git a/docs/api/np_utils.md b/docs/api/np_utils.md
new file mode 100644
index 0000000..ce34758
--- /dev/null
+++ b/docs/api/np_utils.md
@@ -0,0 +1,11 @@
+# NumPy Utilities
+
+Low-level array helpers used throughout TPTBox for label extraction, morphological operations,
+connected components, centre-of-mass computation, and more.
+
+::: TPTBox.core.np_utils
+    options:
+      show_source: true
+      members_order: source
+      filters:
+        - "!^_"
diff --git a/docs/api/poi.md b/docs/api/poi.md
new file mode 100644
index 0000000..5e60d3a
--- /dev/null
+++ b/docs/api/poi.md
@@ -0,0 +1,27 @@
+# POI — Points of Interest
+
+[`POI`][TPTBox.core.poi.POI] maps `(vertebra_id, subregion_id)` tuples to 3D coordinates and
+provides save/load, coordinate-space conversion, and iteration helpers.
+
+## POI
+
+::: TPTBox.core.poi.POI
+    options:
+      show_source: true
+      members_order: source
+
+## POI_Global
+
+::: TPTBox.core.poi_fun.poi_global.POI_Global
+    options:
+      show_source: true
+
+## Helper functions
+
+::: TPTBox.core.poi
+    options:
+      show_source: true
+      members:
+        - calc_centroids
+        - calc_poi_from_subreg_vert
+        - calc_poi_from_two_segs
diff --git a/docs/api/poi_fun.md b/docs/api/poi_fun.md
new file mode 100644
index 0000000..d1050ca
--- /dev/null
+++ b/docs/api/poi_fun.md
@@ -0,0 +1,46 @@
+# POI Strategies
+
+Internal modules that implement the various strategies for computing Points of Interest
+from segmentation volumes.
+
+## Ray Casting
+
+::: TPTBox.core.poi_fun.ray_casting
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## Vertebra Direction
+
+::: TPTBox.core.poi_fun.vertebra_direction
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## Vertebra Non-Centroid POIs
+
+::: TPTBox.core.poi_fun.vertebra_pois_non_centroids
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## Pixel-Based Point Finder
+
+::: TPTBox.core.poi_fun.pixel_based_point_finder
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## Strategies
+
+::: TPTBox.core.poi_fun.strategies
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## Save / Load
+
+::: TPTBox.core.poi_fun.save_load
+    options:
+      show_source: true
+      filters: ["!^_"]
diff --git a/docs/api/registration.md b/docs/api/registration.md
new file mode 100644
index 0000000..2a0a790
--- /dev/null
+++ b/docs/api/registration.md
@@ -0,0 +1,33 @@
+# Registration
+
+Image registration via ANTs (rigid and deformable) and DeepALI (deep learning–based).
+
+## Point-Based Rigid Registration
+
+::: TPTBox.registration.Point_Registration
+    options:
+      show_source: true
+
+::: TPTBox.registration.ridged_points_from_poi
+    options:
+      show_source: true
+
+::: TPTBox.registration.ridged_points_from_subreg_vert
+    options:
+      show_source: true
+
+## Deformable Registration
+
+::: TPTBox.registration.Deformable_Registration
+    options:
+      show_source: true
+
+::: TPTBox.registration.Template_Registration
+    options:
+      show_source: true
+
+## Deep Learning Registration (DeepALI)
+
+::: TPTBox.registration.General_Registration
+    options:
+      show_source: true
diff --git a/docs/api/segmentation.md b/docs/api/segmentation.md
new file mode 100644
index 0000000..de6e081
--- /dev/null
+++ b/docs/api/segmentation.md
@@ -0,0 +1,25 @@
+# Segmentation
+
+Integration with external segmentation pipelines: SPINEPS (spine segmentation) and
+VibeSeg / nnU-Net (general deep learning inference).
+
+## SPINEPS
+
+::: TPTBox.segmentation.spineps
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## VibeSeg
+
+::: TPTBox.segmentation.VibeSeg.vibeseg
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## nnU-Net Utilities
+
+::: TPTBox.segmentation.nnUnet_utils.inference_api
+    options:
+      show_source: true
+      filters: ["!^_"]
diff --git a/docs/api/spine.md b/docs/api/spine.md
new file mode 100644
index 0000000..89feb55
--- /dev/null
+++ b/docs/api/spine.md
@@ -0,0 +1,39 @@
+# Spine
+
+Spine-specific utilities: modular 2D snapshot generation and statistical measurements
+(distances, angles, intervertebral disc POIs).
+
+## 2D Snapshots
+
+::: TPTBox.spine.snapshot2D.snapshot_modular
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## Snapshot Templates
+
+::: TPTBox.spine.snapshot2D.snapshot_templates
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## Distances
+
+::: TPTBox.spine.spinestats.distances
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## Angles
+
+::: TPTBox.spine.spinestats.angles
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## IVD POIs
+
+::: TPTBox.spine.spinestats.ivd_pois
+    options:
+      show_source: true
+      filters: ["!^_"]
diff --git a/docs/api/stitching.md b/docs/api/stitching.md
new file mode 100644
index 0000000..0f06708
--- /dev/null
+++ b/docs/api/stitching.md
@@ -0,0 +1,18 @@
+# Stitching
+
+Multi-station image stitching for combining overlapping field-of-view acquisitions into
+a single volume.
+
+## Stitching
+
+::: TPTBox.stitching.stitching
+    options:
+      show_source: true
+      filters: ["!^_"]
+
+## Stitching Tools
+
+::: TPTBox.stitching.stitching_tools
+    options:
+      show_source: true
+      filters: ["!^_"]
diff --git a/docs/api/vert_constants.md b/docs/api/vert_constants.md
new file mode 100644
index 0000000..07dbc58
--- /dev/null
+++ b/docs/api/vert_constants.md
@@ -0,0 +1,28 @@
+# Vertebra Constants
+
+Defines the shared label space used throughout TPTBox: vertebra IDs, subregion labels,
+sort orders, and anatomical name mappings.
+
+## Location (subregion enum)
+
+::: TPTBox.core.vert_constants.Location
+    options:
+      show_source: true
+
+## Vertebra_Instance
+
+::: TPTBox.core.vert_constants.Vertebra_Instance
+    options:
+      show_source: true
+
+## Utility functions
+
+::: TPTBox.core.vert_constants
+    options:
+      show_source: true
+      members:
+        - v_name2idx
+        - v_idx2name
+        - v_idx_order
+        - ZOOMS
+        - AX_CODES
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..cd94166
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,105 @@
+# Getting Started
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install TPTBox
+```
+
+### From source (development)
+
+```bash
+git clone https://github.com/Hendrik-code/TPTBox.git
+cd TPTBox
+pip install poetry
+poetry install --with dev
+```
+
+### Optional dependencies
+
+```bash
+# Deep learning registration (DeepALI)
+pip install hf-deepali
+
+# 3D mesh visualisation
+pip install pyvista vtk
+```
+
+## Core Concepts
+
+### NII — NIfTI image wrapper
+
+[`NII`][TPTBox.core.nii_wrapper.NII] wraps a nibabel `Nifti1Image` and adds convenient reorientation,
+resampling, masking, and arithmetic operations. Set `seg=True` for integer-labelled segmentation
+images to keep the smallest integer dtype.
+
+```python
+from TPTBox import NII
+
+# Load from file
+ct = NII.load("ct.nii.gz", seg=False)
+seg = NII.load("seg.nii.gz", seg=True)
+
+# Reorient to RAS
+ct_ras = ct.reorient(("R", "A", "S"))
+
+# Resample to 1 mm isotropic
+ct_1mm = ct_ras.rescale((1.0, 1.0, 1.0))
+
+# Apply a segmentation mask
+masked = ct_1mm.apply_mask(seg)
+
+# Save
+ct_1mm.save("ct_1mm.nii.gz")
+```
+
+### POI — Points of Interest
+
+[`POI`][TPTBox.core.poi.POI] maps `(vertebra_id, subregion_id) → 3D coordinate`.  Coordinates can be in
+voxel or world (mm) space.  Use [`calc_centroids`][TPTBox.core.poi.calc_centroids] to compute centroids
+from a segmentation.
+
+```python
+from TPTBox import NII, calc_centroids
+
+seg = NII.load("seg.nii.gz", seg=True)
+poi = calc_centroids(seg)
+print(poi)
+```
+
+### BIDS dataset navigation
+
+[`BIDS_Global_info`][TPTBox.core.bids_files.BIDS_Global_info] scans a dataset root and lets you filter
+subjects, sessions, and modalities with a query interface.
+
+```python
+from TPTBox import BIDS_Global_info
+
+bids = BIDS_Global_info(
+    datasets=["path/to/dataset"],
+    parents=["rawdata", "derivatives/spineps"],
+)
+
+for subject, container in bids.enumerate_subjects(sort=True):
+    query = container.new_query(flatten=False)
+    query.filter("format", "T2w")
+    for family in query.loop_dict(key_addendum=["acq"]):
+        t2w = family["T2w"][0].open_nii()
+        ...
+```
+
+## Running Tests
+
+```bash
+pytest unit_tests/ -x -q
+```
+
+## Building the Documentation Locally
+
+```bash
+pip install mkdocs mkdocs-material "mkdocstrings[python]"
+mkdocs serve   # live-reload preview at http://127.0.0.1:8000
+mkdocs build   # static build into site/
+```
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..edf2ec5
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,42 @@
+# TPTBox
+
+**The Torso Processing Toolbox (TPTBox)** is a multi-functional Python package for processing BIDS-compliant medical imaging datasets (CT, MRI, and more).
+
+[![PyPI version](https://badge.fury.io/py/tptbox.svg)](https://pypi.python.org/pypi/tptbox/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/tptbox)](https://pypi.org/project/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)
+
+## Overview
+
+TPTBox provides a unified interface for the most common tasks in medical image processing research:
+
+- **BIDS dataset navigation** — load, filter, and iterate over BIDS-compliant datasets
+- **NIfTI I/O** — read and write NIfTI files with consistent reorientation and resampling
+- **Points of Interest (POI)** — compute and manipulate anatomical landmarks on vertebrae
+- **2D snapshots** — modular, multi-view MIP and overlay image generation
+- **3D mesh generation** — surface meshes from segmentations with configurable rendering
+- **Registration** — rigid (point- and intensity-based) and deformable registration via ANTs and DeepALI
+- **Segmentation** — integration with SPINEPS and nnU-Net inference pipelines
+- **Image stitching** — multi-station field-of-view stitching
+- **Logging** — structured, consistent logging across long-running pipelines
+
+## Quick Example
+
+```python
+from TPTBox import NII, BIDS_Global_info
+
+# Load a NIfTI and reorient + resample
+nii = NII.load("path/to/image.nii.gz", seg=False)
+nii_ras = nii.reorient(("R", "A", "S"))
+nii_1mm = nii_ras.rescale((1.0, 1.0, 1.0))
+
+# Iterate over a BIDS dataset
+bids = BIDS_Global_info(["path/to/dataset"], parents=["rawdata"])
+for subject, container in bids.enumerate_subjects():
+    t2w = container.new_query().filter("format", "T2w").first()
+    if t2w is not None:
+        nii = t2w.open_nii()
+```
+
+See [Getting Started](getting-started.md) for installation instructions and more examples.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..ce541f1
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,78 @@
+site_name: TPTBox
+site_description: Torso Processing Toolbox — BIDS-compliant medical image processing for CT and MRI.
+site_url: https://tptbox.readthedocs.io
+repo_url: https://github.com/Hendrik-code/TPTBox
+repo_name: Hendrik-code/TPTBox
+edit_uri: blob/main/
+
+theme:
+  name: material
+  logo: TPTBox/images/logo.svg
+  favicon: TPTBox/images/logo.svg
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - toc.integrate
+    - content.code.copy
+    - content.code.annotate
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: google
+            show_source: true
+            show_root_heading: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            members_order: source
+            separate_signature: true
+            show_signature_annotations: true
+            unwrap_annotated: true
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - attr_list
+  - md_in_html
+  - toc:
+      permalink: true
+
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - API Reference:
+      - Core:
+          - NII (NIfTI wrapper): api/nii.md
+          - POI (Points of Interest): api/poi.md
+          - BIDS Files: api/bids.md
+          - NumPy Utilities: api/np_utils.md
+          - Vertebra Constants: api/vert_constants.md
+          - POI Strategies: api/poi_fun.md
+      - Spine: api/spine.md
+      - Registration: api/registration.md
+      - Segmentation: api/segmentation.md
+      - Mesh 3D: api/mesh3d.md
+      - Stitching: api/stitching.md
+      - Logger: api/logger.md
diff --git a/pyproject.toml b/pyproject.toml
index 61fd111..d0072d0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -52,6 +52,13 @@ pytest-mock = "^3.6.0"
 exceptiongroup = { version = "^1.2", python = "<3.11" }
 tomli = {version = "*", python = "<3.11" }
 
+[tool.poetry.group.docs.dependencies]
+mkdocs = ">=1.6"
+mkdocs-material = ">=9.5"
+mkdocstrings = {extras = ["python"], version = ">=0.25"}
+mkdocs-gen-files = ">=0.5"
+mkdocs-literate-nav = ">=0.6"
+
 [build-system]
 requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
 build-backend = "poetry_dynamic_versioning.backend"
@@ -124,9 +131,9 @@ select = [
     "TD005",
     "FIX003",
     "FIX004",
-    #"ERA", For clean up
-    #"D", Dockstring For clean up
-    #"ANN", Annoation For clean up
+    #"ERA",
+    "D",
+    "ANN201",
     "PD",
     "PGH",
     "PL",
@@ -163,16 +170,27 @@ ignore = [
     "UP038",
     "N999",
     "E741",
-    "SIM118",  # dictionay keys
+    "SIM118",  # dictionary keys
     "N802",    # function name lowercase
     "F811",
     "N803",
     "N806",
-    "FURB171", 
+    "FURB171",
     "PLW0108",
-    "B905", # strict= in zip
-    "UP007", # Union and "|" python 3.9
+    "B905",    # strict= in zip
+    "UP007",   # Union and "|" python 3.9
     "PLC0415", # import-outside-top-level
+    # Docstring rules relaxed for internal / magic / dunder members
+    "D100",    # missing docstring in public module
+    "D104",    # missing docstring in public package
+    "D105",    # missing docstring in magic method
+    "D107",    # missing docstring in __init__ (covered by class docstring)
+    # Argument descriptions in existing docstrings — addressed progressively
+    "D417",
+    # Return-type annotation not required for private helpers
+    "ANN202",
+    # En-dashes (–) in docstrings are legitimate range notation (e.g. "C1–C7")
+    "RUF002",
     ]
 
 # Allow fix for all enabled rules (when `--fix`) is provided.
@@ -185,6 +203,14 @@ extend-safe-fixes = ["RUF015", "C419", "C408", "B006"]
 # Allow unused variables when underscore-prefixed.
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+# Test files: don't require docstrings on test functions / helper utilities
+"unit_tests/**" = ["D101", "D102", "D103", "D205", "D415", "ANN201"]
+"TPTBox/tests/**" = ["D101", "D102", "D103", "D205", "D415", "ANN201"]
+
 [tool.ruff.lint.mccabe]
 # Flag errors (`C901`) whenever the complexity level exceeds 5.
 max-complexity = 20
diff --git a/unit_tests/test_nputils.py b/unit_tests/test_nputils.py
index aa134da..bc5cdb5 100755
--- a/unit_tests/test_nputils.py
+++ b/unit_tests/test_nputils.py
@@ -26,8 +26,7 @@ def make_test_array_repeating(shape=(4, 4), labels=(0, 1, 2, 3)) -> np.ndarray:
 
 
 def make_labeled_3d_array() -> np.ndarray:
-    """
-    Create a small 3D array with labeled connected components.
+    """Create a small 3D array with labeled connected components.
     Components:
     - One block of 1s
     - One isolated voxel of 2