This is graduation-research code that segments lumbar MRI into four classes: background, vertebrae, spinal canal, and intervertebral discs.
Homepage | Paper | Dataset | Detailed README
LumbarSeg is a research repository for reproducing and improving the lumbar spine MRI segmentation baseline from Ahmed et al. (2025). The project first targets the reported Dice score of about 0.97 on SPIDER T2 SPACE data, then explores improvements beyond the reproduced baseline.
- Paper-aligned baseline: Modified U-Net with Leaky ReLU, Glorot initialization, and combined Focal + Dice loss.
- Four-class segmentation: Background, vertebrae, spinal canal, and intervertebral discs.
- SPIDER-ready preprocessing: Converts 3D MHA volumes into sagittal 2D training slices.
- Colab-first execution: Designed for Google Colab GPU runs with data stored on Google Drive.
- Separated project page: Website source lives in a dedicated
lumbarseg.github.iorepository, following the FastGS-style code/page split.
Repository split completed: research code stays in Sol-momma/LumbarSeg, while the Astro project website has been moved to lumbarseg.github.io.
Baseline CLI added for preprocessing, training, and validation evaluation.
SPIDER mask label mapping confirmed:
| Raw label | Class |
|---|---|
0 |
Background |
1-99 |
Vertebrae |
100 |
Spinal Canal |
200+ |
IVDs |
- Baseline preprocessing:
preprocess.py - Modified U-Net training:
train.py - Validation metrics:
evaluate.py - Reusable package modules:
spine_baseline/
- Full T2 SPACE reproduction run
- Mask overlay visualization
- Architecture and augmentation improvements
- T1/T2/T2 SPACE comparison
The baseline uses TensorFlow/Keras and follows the implementation style of the target paper.
- GPU: Google Colab GPU is recommended.
- Memory: Batch size
8is the default target; reduce it for smaller GPUs. - Storage: SPIDER dataset and generated slices should be stored on Google Drive or local fast storage.
- Python 3.10+
- TensorFlow/Keras
- SimpleITK
- NumPy / pandas / scikit-learn
Install the baseline dependencies:
pip install -r requirements-baseline.txtgit clone https://github.com/Sol-momma/LumbarSeg.git
cd LumbarSegDownload SPIDER from Zenodo and organize it as:
SPIDER/DataSet/
├── images/
│ ├── *.mha
│ └── ...
├── masks/
│ ├── *.mha
│ └── ...
└── SPIDER Lumbar Spine Segmentation Overview.csv
See data/README.md for dataset notes.
python preprocess.py \
--data_root /path/to/SPIDER/DataSet \
--output_root outputs/t2_space_baseline \
--sequences T2_SPACERun one epoch before a full experiment:
python train.py \
--data_root /path/to/SPIDER/DataSet \
--output_root outputs/t2_space_baseline \
--sequences T2_SPACE \
--epochs 1 \
--batch_size 2To run on an NVIDIA GPU on a Windows PC, see docs/windows_gpu.md. Native Windows GPU support assumes the TensorFlow 2.10 line.
Shortest commands:
git clone https://github.com/Sol-momma/LumbarSeg.git
cd LumbarSeg
powershell -ExecutionPolicy Bypass -File scripts\setup_windows_native_gpu.ps1
powershell -ExecutionPolicy Bypass -File scripts\run_windows_smoke.ps1 -DataRoot "D:\SPIDER\DataSet"
powershell -ExecutionPolicy Bypass -File scripts\run_windows_train.ps1 -DataRoot "D:\SPIDER\DataSet"python train.py \
--data_root /path/to/SPIDER/DataSet \
--output_root outputs/t2_space_baseline \
--sequences T2_SPACE \
--batch_size 8 \
--epochs 100python evaluate.py \
--data_root /path/to/SPIDER/DataSet \
--output_root outputs/t2_space_baseline \
--model_path outputs/t2_space_baseline/checkpoints/best_model.kerasWrites PNGs of the input image, ground-truth mask, predicted mask, and overlay for validation slices.
python visualize_predictions.py \
--data_root /path/to/SPIDER/DataSet \
--output_root outputs/t2_relaxed \
--model_path outputs/t2_relaxed/checkpoints/best_model.keras \
--sequences T2 \
--min_classes 3 \
--imbalance_threshold 0.90 \
--max_slices_per_sequence 0 \
--num_samples 12Output goes to outputs/t2_relaxed/predictions/. Slice Dice for each PNG is saved in prediction_summary.csv.
To score the full validation set and inspect the 8 lowest-scoring images for the overall score, vertebrae, spinal canal, and intervertebral discs, run the following.
If the intermediate images have been deleted, regenerate only the validation images from the saved filtered_files.txt into another location. This only reads the original MHA files and the file list. It does not change the Google Drive originals or the saved list.
python regenerate_selected_slices.py \
--data_root /path/to/SPIDER/DataSet \
--output_root /path/to/temporary_validation_slices \
--file_list /path/to/experiment/filtered_files.txt \
--split validationpython visualize_predictions.py \
--data_root /path/to/SPIDER/DataSet \
--output_root /path/to/temporary_validation_slices \
--model_path outputs/all_sequences/checkpoints/best_model.keras \
--filtered_file_list outputs/all_sequences/filtered_files.txt \
--min_classes 4 \
--imbalance_threshold 0.90 \
--max_slices_per_sequence 1000 \
--batch_size 2 \
--worst_per_metric 8prediction_summary.csv stores Dice and the ground-truth and predicted region pixel counts for every validation sample. Low-scoring images are split into worst_dice_mean/, worst_dice_vertebrae/, worst_dice_spinal_canal/, and worst_dice_ivds/. Rankings are in worst_case_summary.csv.
MRI sequences to use. Supports T1, T2, and T2_SPACE.
2D slice size. Defaults to 512 x 640.
Maximum dominant foreground class ratio allowed during slice filtering. Default: 0.55.
Maximum number of slices retained per sequence. Default: 1000.
Combined loss settings. Defaults: 0.6 and 4.0.
| Feature | LumbarSeg |
|---|---|
| Task | Four-class lumbar MRI segmentation |
| Dataset | SPIDER |
| Input | 2D sagittal slices from 3D MHA |
| Model | Modified U-Net |
| Loss | 0.6 x Focal + 0.4 x Dice |
| Target metric | Dice around 0.97 on T2 SPACE |
| Main runtime | Google Colab GPU |
LumbarSeg/
├── preprocess.py
├── train.py
├── evaluate.py
├── spine_baseline/
├── arguments/
├── data/
├── requirements-baseline.txt
└── REPOSITORY_SPLIT.md
The earlier detailed README is archived at docs/archive/readme-snapshots/README.detailed.md.
Lightweight experiment notes from a local GPU or Colab are stored in docs/experiments/README.md. Model weights and preprocessed slices are not tracked by Git.
The audit and run plan for fully reproducing the paper's reported Dice is in PAPER_REPRODUCTION_PLAN.md. Use audit_reproduction.py to audit sample counts, filtering, and the split.
PR descriptions must be in English and include Why / What / How. See docs/workflow/pr_description.md.
This project is based on the SPIDER dataset and the lumbar MRI segmentation baseline reported by Ahmed et al. (2025). The repository structure is inspired by FastGS, especially the separation between research code and the public website.
If this repository helps your research, please cite the original dataset and baseline papers:
@article{ahmed2025lumbar,
title={Pioneering Precision in Lumbar Spine MRI Segmentation with Advanced Deep Learning and Data Enhancement},
author={Ahmed, I. and others},
journal={Machine Learning with Applications},
volume={20},
year={2025}
}
@article{vanderGraaf2024spider,
title={Lumbar spine segmentation in MR images: a dataset and a public benchmark},
author={van der Graaf, J. W. and others},
journal={Scientific Data},
volume={11},
pages={264},
year={2024}
}If LumbarSeg helps your research, please consider starring this repository.
See HARNESS.md: python -m lumbarseg_cli smoke --download --json runs data → tiny training → evaluation → metrics JSON in one line; doctor checks GPU/data/deps for the box, Colab and the lab PC (WSL2).
No license file yet, so all rights are reserved. The SPIDER dataset and the target paper are under their own terms; see the links at the top.