# TotalSpineSeg
[](https://doi.org/10.5281/zenodo.13894354)
TotalSpineSeg is a tool for automatic instance segmentation of all vertebrae, intervertebral discs (IVDs), spinal cord, and spinal canal in MRI images. It is robust to various MRI contrasts, acquisition orientations, and resolutions. The model used in TotalSpineSeg is based on [nnU-Net](https://github.com/MIC-DKFZ/nnUNet) as the backbone for training and inference.
If you use this model, please cite our work:
> Warszawer Y, Molinier N, Valošek J, Shirbint E, Benveniste PL, Achiron A, Eshaghi A and Cohen-Adad J. _Fully Automatic Vertebrae and Spinal Cord Segmentation Using a Hybrid Approach Combining nnU-Net and Iterative Algorithm_. Proceedings of the 32th Annual Meeting of ISMRM. 2024
Please also cite nnU-Net since our work is heavily based on it:
> Isensee, F., Jaeger, P. F., Kohl, S. A., Petersen, J., & Maier-Hein, K. H. (2021). nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nature methods, 18(2), 203-211.
## Table of Contents
- [Model Description](#model-description)
- [Datasets](#datasets)
- [Dependencies](#dependencies)
- [Installation](#installation)
- [Training](#training)
- [Inference](#inference)
- [Localizer based labeling](#localizer-based-labeling)
- [Results](#results)
- [List of Classes](#list-of-classes)
## Model Description
TotalSpineSeg uses a hybrid approach that integrates nnU-Net with an iterative algorithm for instance segmentation and labeling of vertebrae, intervertebral discs (IVDs), spinal cord, and spinal canal. The process involves two main steps:
**Step 1**: An nnU-Net model (`Dataset101`) was trained to identify nine classes in total. This includes four main classes: spinal cord, spinal canal, IVDs, and vertebrae. Additionally, it identifies four specific IVDs: C2-C3, C7-T1, T12-L1, and L5-S, which represent key anatomical landmarks along the spine, as well as the C1 vertebra to determine whether the MRI images include C1 (Figure 1B). The output segmentation was processed using an iterative algorithm to extract individual IVDs (Figure 1C), from which the odd IVDs segmentation was extracted (Figure 1D).
**Step 2:** A second nnU-Net model (`Dataset102`) was trained to identify ten classes in total. This includes five main classes: spinal cord, spinal canal, IVDs, odd vertebrae, and even vertebrae. Additionally, it identifies four specific IVDs: C2-C3, C7-T1, T12-L1, and L5-S, which represent key anatomical landmarks along the spine, as well as the sacrum (Figure 1E). This model uses two input channels: the MRI image (Figure 1A) and the odd IVDs extracted from the first step (Figure 1D). The output segmentation was processed using an algorithm that assigns individual labels to each vertebra and IVD in the final segmentation (Figure 1F).
For comparison, we also trained a single model (`Dataset103`) that outputs individual label values for each vertebra and IVD in a single step.
**Figure 1**: Illustration of the hybrid method for automatic segmentation of spinal structures. (A) MRI image used to train the Step 1 model. (B) The Step 1 model outputs nine classes. (C) Individual IVDs extracted from the output labels. (D) Odd IVDs extracted from the individual IVDs. (E) MRI image and odd IVDs used as inputs to train the Step 2 model, which outputs ten classes. (F) Final segmentation with individual labels for each vertebra and IVD.
## Datasets
The totalspineseg model was trained on these 3 main datasets:
- Private whole-spine dataset (Internal access: `git@data.neuro.polymtl.ca:datasets/whole-spine.git`).
- [SPIDER](https://doi.org/10.5281/zenodo.10159290) project dataset (Internal access: `git@data.neuro.polymtl.ca:datasets/spider-challenge-2023.git`)
- [Spine Generic Project](https://github.com/spine-generic), including single and multi subject datasets (Public access: `git@github.com:spine-generic/data-single-subject.git` and `git@github.com:spine-generic/data-multi-subject.git`).
We used manual labels from the SPIDER dataset. For other datasets, we generated initial labels by registering MRIs to the PAM50 template using [Spinal Cord Toolbox (SCT)](https://spinalcordtoolbox.com/). We trained an initial segmentation model with these labels, applied it to the datasets, and manually corrected the outputs using [3D Slicer](https://www.slicer.org/).
Additional public datasets were used during this project to generate sacrum segmentations:
- [GoldAtlas](https://zenodo.org/records/583096) (Internal access: `git@data.neuro.polymtl.ca:datasets/goldatlas.git`)
- [SynthRAD2023](https://synthrad2023.grand-challenge.org/) (Internal access: `git@data.neuro.polymtl.ca:datasets/synthrad-challenge-2023.git`)
- [MRSpineSeg](https://paperswithcode.com/dataset/mrspineseg-challenge) (Internal access: `git@data.neuro.polymtl.ca:datasets/mrspineseg-challenge-2021.git`)
When not available, sacrum segmentations were generated using the [totalsegmentator](https://github.com/wasserth/TotalSegmentator) model. For more information, please see [this issue](https://github.com/neuropoly/totalspineseg/issues/18).
## Dependencies
- `bash` terminal
- [Python](https://www.python.org/) >= 3.9, with pip >= 23 and setuptools >= 67
## Installation
1. Open a `bash` terminal in the directory where you want to work.
2. Create the installation directory:
```bash
mkdir TotalSpineSeg
cd TotalSpineSeg
```
3. Create and activate a virtual environment (highly recommended):
```bash
python3 -m venv venv
source venv/bin/activate
```
4. Install this repository using one of the following options:
- Git clone (for developpers)
```bash
git clone https://github.com/neuropoly/totalspineseg.git
python3 -m pip install -e totalspineseg
```
- PyPI installation (for inference only)
```
pip install totalspineseg
```
5. For CUDA GPU support, install **PyTorch** following the instructions on their [website](https://pytorch.org/). Be sure to add the `--upgrade` flag to your installation command to replace any existing PyTorch installation.
Example:
```bash
python3 -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 --upgrade
```
## Training
To train the TotalSpineSeg model, you will need the following hardware specifications:
- Approximately 3.5TB of available disk space (for training with data augmentation)
- RAM capacity of at least 32GB
- CUDA GPU with at least 8GB of VRAM
Please ensure that your system meets these requirements before proceeding with the training process.
1. Make sure that the `bash` terminal is opened with the virtual environment (if used) activated (using `source <path to installation directory>/venv/bin/activate`).
2. Ensure training dependencies are installed:
```bash
apt-get install git git-annex jq -y
```
3. Set the path to TotalSpineSeg and data folders in the virtual environment:
```bash
mkdir data
export TOTALSPINESEG="$(realpath totalspineseg)"
export TOTALSPINESEG_DATA="$(realpath data)"
echo "export TOTALSPINESEG=\"$TOTALSPINESEG\"" >> venv/bin/activate
echo "export TOTALSPINESEG_DATA=\"$TOTALSPINESEG_DATA\"" >> venv/bin/activate
```
4. Download the required datasets into `$TOTALSPINESEG_DATA/bids` (make sure you have access to the specified repositories):
```bash
bash "$TOTALSPINESEG"/scripts/download_datasets.sh
```
5. Temporary step (until all labels are pushed into the repositories) - Download labels into `$TOTALSPINESEG_DATA/bids`:
```bash
curl -L -O https://github.com/neuropoly/totalspineseg/releases/download/labels/labels_iso_bids_0924.zip
unzip -qo labels_iso_bids_0924.zip -d "$TOTALSPINESEG_DATA"
rm labels_iso_bids_0924.zip
```
6. Prepare datasets in nnUNetv2 structure into `$TOTALSPINESEG_DATA/nnUnet`:
```bash
bash "$TOTALSPINESEG"/scripts/prepare_datasets.sh [DATASET_ID] [-noaug]
```
The script optionally accepts `DATASET_ID` as the first positional argument to specify the dataset to prepare. It can be either 101, 102, 103, or all. If `all` is specified, it will prepare all datasets (101, 102, 103). By default, it will prepare datasets 101 and 102.
Additionally, you can use the `-noaug` parameter to prepare the datasets without data augmentations.
7. Train the model:
```bash
bash "$TOTALSPINESEG"/scripts/train.sh [DATASET_ID [FOLD]]
```
The script optionally accepts `DATASET_ID` as the first positional argument to specify the dataset to train. It can be either 101, 102, 103, or all. If `all` is specified, it will train all datasets (101, 102, 103). By default, it will train datasets 101 and 102.
Additionally, you can specify `FOLD` as the second positional argument to specify the fold. It can be either 0, 1, 2, 3, 4, 5 or all. By default, it will train with fold 0.
## Inference
1. Make sure that the `bash` terminal is opened with the virtual environment (if used) activated (using `source <path to installation directory>/venv/bin/activate`).
2. Install the inference weights using this command (If you did not train a new model)
```
totalspineseg_init
```
3. Run the model on a folder containing the images in .nii.gz format, or on a single .nii.gz file:
```bash
totalspineseg INPUT OUTPUT_FOLDER [--step1] [--iso]
```
This will process the images in INPUT or the single image and save the results in OUTPUT_FOLDER.
**Important Note:** By default, the output segmentations are resampled back to the input image space. If you prefer to obtain the outputs in the model's original 1mm isotropic resolution, especially useful for visualization purposes, we strongly recommend using the `--iso` argument.
Additionally, you can use the `--step1` parameter to run only the step 1 model, which outputs a single label for all vertebrae, including the sacrum.
For more options, you can use the `--help` parameter:
```bash
totalspineseg --help
```
**Output Data Structure:**
```
output_folder/
├── input/ # Preprocessed input images
├── preview/ # Preview images for all steps
├── step1_raw/ # Raw outputs from step 1 model
├── step1_output/ # Results of iterative labeling algorithm for step 1
├── step1_cord/ # Spinal cord soft segmentations
├── step1_canal/ # Spinal canal soft segmentations
├── step1_levels/ # Single voxel in canal centerline at each IVD level
├── step2_raw/ # Raw outputs from step 2 model
└── step2_output/ # Results of iterative labeling algorithm for step 2 (final output)
```
**Important Note:** While TotalSpineSeg provides spinal cord segmentation, it is not intended to replace validated methods for cross-sectional area (CSA) analysis. The spinal cord segmentation from TotalSpineSeg has not been validated for CSA measurements, nor has it been tested on cases involving spinal cord compressions, MS lesions, or other spinal cord abnormalities. For accurate CSA analysis, we strongly recommend using the validated algorithms available in the [Spinal Cord Toolbox](https://spinalcordtoolbox.com/user_section/tutorials/segmentation.html).
Key points:
- All segmentations in NIfTI (.nii.gz) format
- Preview images in JPEG format
- step1_levels: single voxel in canal centerline at each IVD level, numbered from C1 (1 above C1, 2 above C2, etc.)
- step2_output: final labeled vertebrae, discs, cord, and canal
## Localizer based labeling
TotalSpineSeg supports using localizer images to improve the labeling process, particularly useful for images with different fields of view (FOV) where landmarks like C1 and sacrum may not be visible. It uses localizer information to accurately label vertebrae and discs in the main image.
Example of directory structure:
```
.
├── images/
│ ├── sub-01_T2w.nii.gz
│ └── sub-02_T2w.nii.gz
└── localizers/
├── sub-01_T1w.nii.gz
└── sub-02_T1w.nii.gz
```
In this example, main images are placed in the `images` folder and corresponding localizer images in the `localizers` folder.
To use localizer-based labeling:
```bash
# Process localizer images. We recommend using the --iso flag for the localizer to ensure consistent resolution.
totalspineseg localizers localizers_output --iso
# Run model on main images using localizer output
totalspineseg images output --loc localizers_output/step2_output --suffix _T2w --loc-suffix _T1w
```
- `--loc`: Specifies the path to the localizer output
- `--suffix`: Suffix for the main images (e.g., "_T2w")
- `--loc-suffix`: Suffix for the localizer images (e.g., "_T1w")
Note: If the localizer and main image files have the same names, you can omit the `--suffix` and `--loc-suffix` arguments.
## Results
TotalSpineSeg demonstrates robust performance across a wide range of imaging parameters. Here are some examples of the model output:
The examples shown above include segmentation results on various contrasts (T1w, T2w, STIR, MTS, T2star, and even CT images), acquisition orientations (sagittal, axial), and resolutions.
## List of Classes
| Label | Name |
|:------|:-----|
| 1 | spinal_cord |
| 2 | spinal_canal |
| 11 | vertebrae_C1 |
| 12 | vertebrae_C2 |
| 13 | vertebrae_C3 |
| 14 | vertebrae_C4 |
| 15 | vertebrae_C5 |
| 16 | vertebrae_C6 |
| 17 | vertebrae_C7 |
| 21 | vertebrae_T1 |
| 22 | vertebrae_T2 |
| 23 | vertebrae_T3 |
| 24 | vertebrae_T4 |
| 25 | vertebrae_T5 |
| 26 | vertebrae_T6 |
| 27 | vertebrae_T7 |
| 28 | vertebrae_T8 |
| 29 | vertebrae_T9 |
| 30 | vertebrae_T10 |
| 31 | vertebrae_T11 |
| 32 | vertebrae_T12 |
| 41 | vertebrae_L1 |
| 42 | vertebrae_L2 |
| 43 | vertebrae_L3 |
| 44 | vertebrae_L4 |
| 45 | vertebrae_L5 |
| 50 | sacrum |
| 63 | disc_C2_C3 |
| 64 | disc_C3_C4 |
| 65 | disc_C4_C5 |
| 66 | disc_C5_C6 |
| 67 | disc_C6_C7 |
| 71 | disc_C7_T1 |
| 72 | disc_T1_T2 |
| 73 | disc_T2_T3 |
| 74 | disc_T3_T4 |
| 75 | disc_T4_T5 |
| 76 | disc_T5_T6 |
| 77 | disc_T6_T7 |
| 78 | disc_T7_T8 |
| 79 | disc_T8_T9 |
| 80 | disc_T9_T10 |
| 81 | disc_T10_T11 |
| 82 | disc_T11_T12 |
| 91 | disc_T12_L1 |
| 92 | disc_L1_L2 |
| 93 | disc_L2_L3 |
| 94 | disc_L3_L4 |
| 95 | disc_L4_L5 |
| 100 | disc_L5_S |
Raw data
{
"_id": null,
"home_page": null,
"name": "totalspineseg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "deep learning, image segmentation, semantic segmentation, medical image analysis, medical image segmentation, nnU-Net, nnunet, mri, spine, ivd, intervertebral disc, spinal cord",
"author": "Anat Achiron, Julien Cohen-Adad",
"author_email": "Yehuda Warszawer <yehuda.warszawer@sheba.health.gov.il>, Nathan Molinier <nathan.molinier@polymtl.ca>",
"download_url": "https://files.pythonhosted.org/packages/78/6f/94f6bc3382796fe783719e988f9e129100c6e13ac2052e1b56749efafa0d/totalspineseg-20241116.tar.gz",
"platform": null,
"description": "# TotalSpineSeg\n[](https://doi.org/10.5281/zenodo.13894354)\n\nTotalSpineSeg is a tool for automatic instance segmentation of all vertebrae, intervertebral discs (IVDs), spinal cord, and spinal canal in MRI images. It is robust to various MRI contrasts, acquisition orientations, and resolutions. The model used in TotalSpineSeg is based on [nnU-Net](https://github.com/MIC-DKFZ/nnUNet) as the backbone for training and inference.\n\nIf you use this model, please cite our work:\n> Warszawer Y, Molinier N, Valo\u0161ek J, Shirbint E, Benveniste PL, Achiron A, Eshaghi A and Cohen-Adad J. _Fully Automatic Vertebrae and Spinal Cord Segmentation Using a Hybrid Approach Combining nnU-Net and Iterative Algorithm_.\tProceedings of the 32th Annual Meeting of ISMRM. 2024\n\nPlease also cite nnU-Net since our work is heavily based on it:\n> Isensee, F., Jaeger, P. F., Kohl, S. A., Petersen, J., & Maier-Hein, K. H. (2021). nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nature methods, 18(2), 203-211.\n\n\n\n## Table of Contents\n\n- [Model Description](#model-description)\n- [Datasets](#datasets)\n- [Dependencies](#dependencies)\n- [Installation](#installation)\n- [Training](#training)\n- [Inference](#inference)\n- [Localizer based labeling](#localizer-based-labeling)\n- [Results](#results)\n- [List of Classes](#list-of-classes)\n\n## Model Description\n\nTotalSpineSeg uses a hybrid approach that integrates nnU-Net with an iterative algorithm for instance segmentation and labeling of vertebrae, intervertebral discs (IVDs), spinal cord, and spinal canal. The process involves two main steps:\n\n**Step 1**: An nnU-Net model (`Dataset101`) was trained to identify nine classes in total. This includes four main classes: spinal cord, spinal canal, IVDs, and vertebrae. Additionally, it identifies four specific IVDs: C2-C3, C7-T1, T12-L1, and L5-S, which represent key anatomical landmarks along the spine, as well as the C1 vertebra to determine whether the MRI images include C1 (Figure 1B). The output segmentation was processed using an iterative algorithm to extract individual IVDs (Figure 1C), from which the odd IVDs segmentation was extracted (Figure 1D).\n\n**Step 2:** A second nnU-Net model (`Dataset102`) was trained to identify ten classes in total. This includes five main classes: spinal cord, spinal canal, IVDs, odd vertebrae, and even vertebrae. Additionally, it identifies four specific IVDs: C2-C3, C7-T1, T12-L1, and L5-S, which represent key anatomical landmarks along the spine, as well as the sacrum (Figure 1E). This model uses two input channels: the MRI image (Figure 1A) and the odd IVDs extracted from the first step (Figure 1D). The output segmentation was processed using an algorithm that assigns individual labels to each vertebra and IVD in the final segmentation (Figure 1F).\n\nFor comparison, we also trained a single model (`Dataset103`) that outputs individual label values for each vertebra and IVD in a single step.\n\n\n\n**Figure 1**: Illustration of the hybrid method for automatic segmentation of spinal structures. (A) MRI image used to train the Step 1 model. (B) The Step 1 model outputs nine classes. (C) Individual IVDs extracted from the output labels. (D) Odd IVDs extracted from the individual IVDs. (E) MRI image and odd IVDs used as inputs to train the Step 2 model, which outputs ten classes. (F) Final segmentation with individual labels for each vertebra and IVD.\n\n## Datasets\n\nThe totalspineseg model was trained on these 3 main datasets:\n- Private whole-spine dataset (Internal access: `git@data.neuro.polymtl.ca:datasets/whole-spine.git`).\n- [SPIDER](https://doi.org/10.5281/zenodo.10159290) project dataset (Internal access: `git@data.neuro.polymtl.ca:datasets/spider-challenge-2023.git`)\n- [Spine Generic Project](https://github.com/spine-generic), including single and multi subject datasets (Public access: `git@github.com:spine-generic/data-single-subject.git` and `git@github.com:spine-generic/data-multi-subject.git`).\n\nWe used manual labels from the SPIDER dataset. For other datasets, we generated initial labels by registering MRIs to the PAM50 template using [Spinal Cord Toolbox (SCT)](https://spinalcordtoolbox.com/). We trained an initial segmentation model with these labels, applied it to the datasets, and manually corrected the outputs using [3D Slicer](https://www.slicer.org/).\n\nAdditional public datasets were used during this project to generate sacrum segmentations:\n- [GoldAtlas](https://zenodo.org/records/583096) (Internal access: `git@data.neuro.polymtl.ca:datasets/goldatlas.git`)\n- [SynthRAD2023](https://synthrad2023.grand-challenge.org/) (Internal access: `git@data.neuro.polymtl.ca:datasets/synthrad-challenge-2023.git`)\n- [MRSpineSeg](https://paperswithcode.com/dataset/mrspineseg-challenge) (Internal access: `git@data.neuro.polymtl.ca:datasets/mrspineseg-challenge-2021.git`)\n\nWhen not available, sacrum segmentations were generated using the [totalsegmentator](https://github.com/wasserth/TotalSegmentator) model. For more information, please see [this issue](https://github.com/neuropoly/totalspineseg/issues/18).\n\n## Dependencies\n\n- `bash` terminal\n- [Python](https://www.python.org/) >= 3.9, with pip >= 23 and setuptools >= 67\n\n## Installation\n\n1. Open a `bash` terminal in the directory where you want to work.\n\n2. Create the installation directory:\n```bash\nmkdir TotalSpineSeg\ncd TotalSpineSeg\n```\n\n3. Create and activate a virtual environment (highly recommended):\n```bash\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n4. Install this repository using one of the following options:\n - Git clone (for developpers)\n ```bash\n git clone https://github.com/neuropoly/totalspineseg.git\n python3 -m pip install -e totalspineseg\n ```\n - PyPI installation (for inference only)\n ```\n pip install totalspineseg\n ```\n\n5. For CUDA GPU support, install **PyTorch** following the instructions on their [website](https://pytorch.org/). Be sure to add the `--upgrade` flag to your installation command to replace any existing PyTorch installation.\n Example:\n```bash\npython3 -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 --upgrade\n```\n\n## Training\n\nTo train the TotalSpineSeg model, you will need the following hardware specifications:\n- Approximately 3.5TB of available disk space (for training with data augmentation)\n- RAM capacity of at least 32GB\n- CUDA GPU with at least 8GB of VRAM\n\nPlease ensure that your system meets these requirements before proceeding with the training process.\n\n1. Make sure that the `bash` terminal is opened with the virtual environment (if used) activated (using `source <path to installation directory>/venv/bin/activate`).\n\n2. Ensure training dependencies are installed:\n```bash\napt-get install git git-annex jq -y\n```\n\n3. Set the path to TotalSpineSeg and data folders in the virtual environment:\n```bash\nmkdir data\nexport TOTALSPINESEG=\"$(realpath totalspineseg)\"\nexport TOTALSPINESEG_DATA=\"$(realpath data)\"\necho \"export TOTALSPINESEG=\\\"$TOTALSPINESEG\\\"\" >> venv/bin/activate\necho \"export TOTALSPINESEG_DATA=\\\"$TOTALSPINESEG_DATA\\\"\" >> venv/bin/activate\n```\n\n4. Download the required datasets into `$TOTALSPINESEG_DATA/bids` (make sure you have access to the specified repositories):\n```bash\nbash \"$TOTALSPINESEG\"/scripts/download_datasets.sh\n```\n\n5. Temporary step (until all labels are pushed into the repositories) - Download labels into `$TOTALSPINESEG_DATA/bids`:\n```bash\ncurl -L -O https://github.com/neuropoly/totalspineseg/releases/download/labels/labels_iso_bids_0924.zip\nunzip -qo labels_iso_bids_0924.zip -d \"$TOTALSPINESEG_DATA\"\nrm labels_iso_bids_0924.zip\n```\n\n6. Prepare datasets in nnUNetv2 structure into `$TOTALSPINESEG_DATA/nnUnet`:\n```bash\nbash \"$TOTALSPINESEG\"/scripts/prepare_datasets.sh [DATASET_ID] [-noaug]\n```\n\n The script optionally accepts `DATASET_ID` as the first positional argument to specify the dataset to prepare. It can be either 101, 102, 103, or all. If `all` is specified, it will prepare all datasets (101, 102, 103). By default, it will prepare datasets 101 and 102.\n\n Additionally, you can use the `-noaug` parameter to prepare the datasets without data augmentations.\n\n7. Train the model:\n```bash\nbash \"$TOTALSPINESEG\"/scripts/train.sh [DATASET_ID [FOLD]]\n```\n\n The script optionally accepts `DATASET_ID` as the first positional argument to specify the dataset to train. It can be either 101, 102, 103, or all. If `all` is specified, it will train all datasets (101, 102, 103). By default, it will train datasets 101 and 102.\n\n Additionally, you can specify `FOLD` as the second positional argument to specify the fold. It can be either 0, 1, 2, 3, 4, 5 or all. By default, it will train with fold 0.\n\n## Inference\n\n1. Make sure that the `bash` terminal is opened with the virtual environment (if used) activated (using `source <path to installation directory>/venv/bin/activate`).\n\n2. Install the inference weights using this command (If you did not train a new model)\n```\ntotalspineseg_init\n```\n\n3. Run the model on a folder containing the images in .nii.gz format, or on a single .nii.gz file:\n```bash\ntotalspineseg INPUT OUTPUT_FOLDER [--step1] [--iso]\n```\n\n This will process the images in INPUT or the single image and save the results in OUTPUT_FOLDER.\n\n **Important Note:** By default, the output segmentations are resampled back to the input image space. If you prefer to obtain the outputs in the model's original 1mm isotropic resolution, especially useful for visualization purposes, we strongly recommend using the `--iso` argument.\n\n Additionally, you can use the `--step1` parameter to run only the step 1 model, which outputs a single label for all vertebrae, including the sacrum.\n\n For more options, you can use the `--help` parameter:\n```bash\ntotalspineseg --help\n```\n\n**Output Data Structure:**\n\n```\noutput_folder/\n\u251c\u2500\u2500 input/ # Preprocessed input images\n\u251c\u2500\u2500 preview/ # Preview images for all steps\n\u251c\u2500\u2500 step1_raw/ # Raw outputs from step 1 model\n\u251c\u2500\u2500 step1_output/ # Results of iterative labeling algorithm for step 1\n\u251c\u2500\u2500 step1_cord/ # Spinal cord soft segmentations\n\u251c\u2500\u2500 step1_canal/ # Spinal canal soft segmentations\n\u251c\u2500\u2500 step1_levels/ # Single voxel in canal centerline at each IVD level\n\u251c\u2500\u2500 step2_raw/ # Raw outputs from step 2 model\n\u2514\u2500\u2500 step2_output/ # Results of iterative labeling algorithm for step 2 (final output)\n```\n\n**Important Note:** While TotalSpineSeg provides spinal cord segmentation, it is not intended to replace validated methods for cross-sectional area (CSA) analysis. The spinal cord segmentation from TotalSpineSeg has not been validated for CSA measurements, nor has it been tested on cases involving spinal cord compressions, MS lesions, or other spinal cord abnormalities. For accurate CSA analysis, we strongly recommend using the validated algorithms available in the [Spinal Cord Toolbox](https://spinalcordtoolbox.com/user_section/tutorials/segmentation.html).\n\nKey points:\n- All segmentations in NIfTI (.nii.gz) format\n- Preview images in JPEG format\n- step1_levels: single voxel in canal centerline at each IVD level, numbered from C1 (1 above C1, 2 above C2, etc.)\n- step2_output: final labeled vertebrae, discs, cord, and canal\n\n## Localizer based labeling\n\nTotalSpineSeg supports using localizer images to improve the labeling process, particularly useful for images with different fields of view (FOV) where landmarks like C1 and sacrum may not be visible. It uses localizer information to accurately label vertebrae and discs in the main image.\n\n\n\nExample of directory structure:\n\n```\n.\n\u251c\u2500\u2500 images/\n\u2502 \u251c\u2500\u2500 sub-01_T2w.nii.gz\n\u2502 \u2514\u2500\u2500 sub-02_T2w.nii.gz\n\u2514\u2500\u2500 localizers/\n \u251c\u2500\u2500 sub-01_T1w.nii.gz\n \u2514\u2500\u2500 sub-02_T1w.nii.gz\n```\n\nIn this example, main images are placed in the `images` folder and corresponding localizer images in the `localizers` folder.\n\nTo use localizer-based labeling:\n\n```bash\n# Process localizer images. We recommend using the --iso flag for the localizer to ensure consistent resolution.\ntotalspineseg localizers localizers_output --iso\n\n# Run model on main images using localizer output\ntotalspineseg images output --loc localizers_output/step2_output --suffix _T2w --loc-suffix _T1w\n```\n\n- `--loc`: Specifies the path to the localizer output\n- `--suffix`: Suffix for the main images (e.g., \"_T2w\")\n- `--loc-suffix`: Suffix for the localizer images (e.g., \"_T1w\")\n\nNote: If the localizer and main image files have the same names, you can omit the `--suffix` and `--loc-suffix` arguments.\n\n## Results\n\nTotalSpineSeg demonstrates robust performance across a wide range of imaging parameters. Here are some examples of the model output:\n\n\n\nThe examples shown above include segmentation results on various contrasts (T1w, T2w, STIR, MTS, T2star, and even CT images), acquisition orientations (sagittal, axial), and resolutions.\n\n## List of Classes\n\n| Label | Name |\n|:------|:-----|\n| 1 | spinal_cord |\n| 2 | spinal_canal |\n| 11 | vertebrae_C1 |\n| 12 | vertebrae_C2 |\n| 13 | vertebrae_C3 |\n| 14 | vertebrae_C4 |\n| 15 | vertebrae_C5 |\n| 16 | vertebrae_C6 |\n| 17 | vertebrae_C7 |\n| 21 | vertebrae_T1 |\n| 22 | vertebrae_T2 |\n| 23 | vertebrae_T3 |\n| 24 | vertebrae_T4 |\n| 25 | vertebrae_T5 |\n| 26 | vertebrae_T6 |\n| 27 | vertebrae_T7 |\n| 28 | vertebrae_T8 |\n| 29 | vertebrae_T9 |\n| 30 | vertebrae_T10 |\n| 31 | vertebrae_T11 |\n| 32 | vertebrae_T12 |\n| 41 | vertebrae_L1 |\n| 42 | vertebrae_L2 |\n| 43 | vertebrae_L3 |\n| 44 | vertebrae_L4 |\n| 45 | vertebrae_L5 |\n| 50 | sacrum |\n| 63 | disc_C2_C3 |\n| 64 | disc_C3_C4 |\n| 65 | disc_C4_C5 |\n| 66 | disc_C5_C6 |\n| 67 | disc_C6_C7 |\n| 71 | disc_C7_T1 |\n| 72 | disc_T1_T2 |\n| 73 | disc_T2_T3 |\n| 74 | disc_T3_T4 |\n| 75 | disc_T4_T5 |\n| 76 | disc_T5_T6 |\n| 77 | disc_T6_T7 |\n| 78 | disc_T7_T8 |\n| 79 | disc_T8_T9 |\n| 80 | disc_T9_T10 |\n| 81 | disc_T10_T11 |\n| 82 | disc_T11_T12 |\n| 91 | disc_T12_L1 |\n| 92 | disc_L1_L2 |\n| 93 | disc_L2_L3 |\n| 94 | disc_L3_L4 |\n| 95 | disc_L4_L5 |\n| 100 | disc_L5_S |\n",
"bugtrack_url": null,
"license": null,
"summary": "TotalSpineSeg is a tool for automatic instance segmentation and labeling of all vertebrae, intervertebral discs (IVDs), spinal cord, and spinal canal in MRI images.",
"version": "20241116",
"project_urls": {
"Dataset101_TotalSpineSeg_step1": "https://github.com/neuropoly/totalspineseg/releases/download/r20241115/Dataset101_TotalSpineSeg_step1_r20241115.zip",
"Dataset102_TotalSpineSeg_step2": "https://github.com/neuropoly/totalspineseg/releases/download/r20241115/Dataset102_TotalSpineSeg_step2_r20241115.zip",
"homepage": "https://github.com/neuropoly/totalspineseg",
"repository": "https://github.com/neuropoly/totalspineseg"
},
"split_keywords": [
"deep learning",
" image segmentation",
" semantic segmentation",
" medical image analysis",
" medical image segmentation",
" nnu-net",
" nnunet",
" mri",
" spine",
" ivd",
" intervertebral disc",
" spinal cord"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "098c72d7ab895bb1ca07fe80ce26502cda0c6b36b3dada04c90df5381551c712",
"md5": "a3f4dff0d3078be0eb562eda4ad0ed5b",
"sha256": "6ed019e64999b8de33143e1d3329138dc9651ca8ee9337fd65160ffe1dfec1ba"
},
"downloads": -1,
"filename": "totalspineseg-20241116-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a3f4dff0d3078be0eb562eda4ad0ed5b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 73142,
"upload_time": "2024-11-18T21:20:20",
"upload_time_iso_8601": "2024-11-18T21:20:20.471813Z",
"url": "https://files.pythonhosted.org/packages/09/8c/72d7ab895bb1ca07fe80ce26502cda0c6b36b3dada04c90df5381551c712/totalspineseg-20241116-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "786f94f6bc3382796fe783719e988f9e129100c6e13ac2052e1b56749efafa0d",
"md5": "1651e5502afdc446fb88202a3e6717f4",
"sha256": "1244b63c0702db8587964f8fb8b22e39a746bf380be6888920e5cc411e41b9f2"
},
"downloads": -1,
"filename": "totalspineseg-20241116.tar.gz",
"has_sig": false,
"md5_digest": "1651e5502afdc446fb88202a3e6717f4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 55053,
"upload_time": "2024-11-18T21:20:21",
"upload_time_iso_8601": "2024-11-18T21:20:21.502616Z",
"url": "https://files.pythonhosted.org/packages/78/6f/94f6bc3382796fe783719e988f9e129100c6e13ac2052e1b56749efafa0d/totalspineseg-20241116.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-18 21:20:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "neuropoly",
"github_project": "totalspineseg",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "totalspineseg"
}
JSON
