Skip to content

Latest commit

 

History

History
315 lines (221 loc) · 9.76 KB

README.md

File metadata and controls

315 lines (221 loc) · 9.76 KB

LumbarSeg: Four-Class Lumbar MRI Segmentation

English | 日本語

This is graduation-research code that segments lumbar MRI into four classes: background, vertebrae, spinal canal, and intervertebral discs.

Graduation Research 2026

Homepage | Paper | Dataset | Detailed README

LumbarSeg overview TensorFlow Dataset

What Makes LumbarSeg Special?

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.io repository, following the FastGS-style code/page split.

Latest Updates

[2026.06]

Repository split completed: research code stays in Sol-momma/LumbarSeg, while the Astro project website has been moved to lumbarseg.github.io.

[2026.06]

Baseline CLI added for preprocessing, training, and validation evaluation.

[2026.06]

SPIDER mask label mapping confirmed:

Raw label Class
0 Background
1-99 Vertebrae
100 Spinal Canal
200+ IVDs

Coming Soon

Released

  • Baseline preprocessing: preprocess.py
  • Modified U-Net training: train.py
  • Validation metrics: evaluate.py
  • Reusable package modules: spine_baseline/

To Be Released

  • Full T2 SPACE reproduction run
  • Mask overlay visualization
  • Architecture and augmentation improvements
  • T1/T2/T2 SPACE comparison

Training Framework

The baseline uses TensorFlow/Keras and follows the implementation style of the target paper.

Hardware Requirements

  • GPU: Google Colab GPU is recommended.
  • Memory: Batch size 8 is the default target; reduce it for smaller GPUs.
  • Storage: SPIDER dataset and generated slices should be stored on Google Drive or local fast storage.

Software Requirements

  • Python 3.10+
  • TensorFlow/Keras
  • SimpleITK
  • NumPy / pandas / scikit-learn

Install the baseline dependencies:

pip install -r requirements-baseline.txt

Quick Start

Clone the Repository

git clone https://github.com/Sol-momma/LumbarSeg.git
cd LumbarSeg

Dataset Organization

Download 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.

Preprocess

python preprocess.py \
  --data_root /path/to/SPIDER/DataSet \
  --output_root outputs/t2_space_baseline \
  --sequences T2_SPACE

Smoke Test

Run 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 2

Windows GPU

To 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"

Training & Evaluation

Baseline Training

python train.py \
  --data_root /path/to/SPIDER/DataSet \
  --output_root outputs/t2_space_baseline \
  --sequences T2_SPACE \
  --batch_size 8 \
  --epochs 100

Evaluation

python evaluate.py \
  --data_root /path/to/SPIDER/DataSet \
  --output_root outputs/t2_space_baseline \
  --model_path outputs/t2_space_baseline/checkpoints/best_model.keras

Prediction Visualization

Writes 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 12

Output 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 validation
python 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 8

prediction_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.

Advanced: Key Command Line Arguments

--sequences

MRI sequences to use. Supports T1, T2, and T2_SPACE.

--target_height / --target_width

2D slice size. Defaults to 512 x 640.

--imbalance_threshold

Maximum dominant foreground class ratio allowed during slice filtering. Default: 0.55.

--max_slices_per_sequence

Maximum number of slices retained per sequence. Default: 1000.

--focal_weight / --focal_gamma

Combined loss settings. Defaults: 0.6 and 4.0.

Quick Facts

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

Repository Layout

LumbarSeg/
├── preprocess.py
├── train.py
├── evaluate.py
├── spine_baseline/
├── arguments/
├── data/
├── requirements-baseline.txt
└── REPOSITORY_SPLIT.md

Detailed Notes

The earlier detailed README is archived at docs/archive/readme-snapshots/README.detailed.md.

Experiment Records

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.

Paper Reproduction

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.

Pull Request Rule

PR descriptions must be in English and include Why / What / How. See docs/workflow/pr_description.md.

Acknowledgements

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.

Citation

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.

Experiment harness

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).

License

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.