Pipeline

SPINEPS processes a scan in a sequence of phases orchestrated by the functions in spineps.seg_run. There are two top-level entry points:

• process_img_nii — process a single image.
• process_dataset — discover and process every suitable scan in a BIDS dataset.

Two-phase approach

The core idea is to split spine segmentation into two complementary tasks:

1. Semantic phase — a multi-class network labels every voxel with its anatomical subregion (vertebra subregions, spinal cord, spinal canal, discs, endplate, sacrum).
2. Instance phase — using the vertebra subregions from the semantic mask, individual vertebrae are separated into a per-vertebra instance mask.

A combined post-processing step then cleans both masks against each other, assigns intervertebral discs and endplates to their parent vertebra, and (optionally) runs the VERIDAH labeling model to give each instance an anatomical vertebra label.

input scan
   │  pre-processing (normalize, optional N4 bias correction, crop, pad)
   ▼
semantic phase ──► subregion (semantic) mask
   │
   ▼
instance phase ──► per-vertebra instance mask
   │
   ▼
post-processing (clean, assign IVD/endplate, optional VERIDAH labeling)
   │
   ▼
seg-spine mask · seg-vert mask · centroids (.json) · snapshot (.png)

Outputs

For each processed scan SPINEPS writes a derivatives folder next to the input containing:

• a seg-spine mask (semantic / subregion segmentation),
• a seg-vert mask (vertebra instance segmentation),
• a centroid file (.json) with points of interest for each vertebra, endplate and disc,
• a snapshot .png visualizing the result,
• optionally: an uncertainty image, the model-resolution masks, softmax logits and debug data.

Calling from Python

from TPTBox import BIDS_FILE
from spineps import get_semantic_model, get_instance_model, process_img_nii

semantic = get_semantic_model("t2w")
instance = get_instance_model("instance")

process_img_nii(
    BIDS_FILE("sub-test_T2w.nii.gz", dataset="/path/to/dataset"),
    model_semantic=semantic,
    model_instance=instance,
)

process_img_nii exposes many proc_* flags to toggle individual processing steps (pre-processing, semantic/instance cleaning, hole filling, labeling, …). See the Pipeline & Run API reference for the full signature.

For batch processing, process_dataset accepts the same processing flags and applies them to every matching scan it finds.