🧠 Neuro Segmentation Toolkit

Automated brain tumor segmentation pipeline using 3D Slicer + ITK-SNAP

An end-to-end pipeline for brain tumor segmentation from multi-sequence MRI studies (T1, T1c, T2, FLAIR). Built for researchers and clinicians working with glioma and meningioma cases, integrating 3D Slicer for visualization and ITK-SNAP for active contour refinement.

---

✨ Features

• Multi-sequence DICOM loading — Auto-classifies T1, T1c, T2, and FLAIR series from study metadata
• N4 bias field correction — Corrects intensity inhomogeneity common in MRI
• Automated skull stripping — Morphological approach with largest-component extraction
• Multi-sequence co-registration — Rigid registration to T1c reference using Mattes MI
• Threshold + morphology segmentation — Multi-label segmentation (necrotic core, edema, enhancing tumor)
• Volumetric analysis — Compartment volumes, enhancement ratio, surface area
• 3D Slicer module — Scripted extension with full GUI for interactive use
• ITK-SNAP integration — Label file generation, workspace management, active contour CLI
• Batch processing — Parallel execution with resume support and incremental JSON results
• BraTS-compatible labels — Standard color scheme matching the Brain Tumor Segmentation challenge

🏗️ Pipeline Architecture

DICOM Study
    │
    ├─ DicomLoader ─── Series discovery + sequence classification
    │
    ├─ Preprocessor
    │   ├── N4 Bias Field Correction
    │   ├── Skull Stripping (morphological)
    │   ├── Rigid Registration → T1c reference
    │   └── Intensity Normalization (z-score / min-max)
    │
    ├─ TumorSegmenter
    │   ├── Multi-sequence thresholding (T1c + FLAIR)
    │   └── Morphological refinement (component filtering)
    │
    ├─ VolumetricAnalyzer
    │   ├── Compartment volumes (cc)
    │   ├── Enhancement ratio
    │   └── JSON report generation
    │
    └─ Output
        ├── NIfTI segmentation (.nii.gz)
        ├── JSON analysis report
        └── ITK-SNAP workspace / 3D Slicer scene

🚀 Quick Start

Prerequisites

• Python 3.10+
• 3D Slicer 5.6+ (optional — for GUI module)
• ITK-SNAP 4.0+ (optional — for active contour refinement)

Installation

git clone https://github.com/bradleybeatz1313/neuro-segmentation-toolkit.git
cd neuro-segmentation-toolkit
pip install -r requirements.txt

Command-Line Usage

# Single study
python src/segmentation_pipeline.py /path/to/dicom/study ./output \
    --patient-id PAT001 \
    --study-date 2025-06-15 \
    --verbose

# Batch processing
python scripts/batch_process.py /path/to/dataset ./batch_output \
    --workers 4 \
    --resume

3D Slicer Module

1. Open 3D Slicer
2. Go to Edit → Application Settings → Modules
3. Add src/ to the module paths
4. Restart Slicer — find "Neuro Segmentation Toolkit" under Segmentation

ITK-SNAP Integration

from src.itksnap_utils import generate_label_file, create_workspace, GLIOMA_LABELS

# Generate BraTS-compatible label file
generate_label_file(GLIOMA_LABELS, "glioma.label")

# Create workspace with pre-loaded data
create_workspace(
    main_image_path="patient_T1c.nii.gz",
    overlay_paths={"FLAIR": "patient_FLAIR.nii.gz"},
    segmentation_path="patient_seg.nii.gz",
    label_file_path="glioma.label",
    output_path="patient.itksnap"
)

📁 Project Structure

neuro-segmentation-toolkit/
├── src/
│   ├── segmentation_pipeline.py  # Core pipeline (loader, preprocessor, segmenter, analyzer)
│   ├── itksnap_utils.py          # ITK-SNAP label files, workspaces, CLI automation
│   ├── slicer_module.py          # 3D Slicer scripted module with GUI
│   └── visualization.py          # Slice overlays, volume charts, multiplanar views
├── scripts/
│   └── batch_process.py          # Parallel batch processing with resume
├── configs/
│   ├── default_config.json       # Pipeline configuration
│   ├── glioma_labels.label       # BraTS glioma label descriptions
│   └── meningioma_labels.label   # Meningioma label descriptions
├── tests/
│   └── test_pipeline.py          # Unit tests with synthetic phantoms
├── assets/                       # Generated figures and screenshots
├── requirements.txt
└── README.md

🧪 Testing

Tests use synthetic brain phantoms — no real patient data required:

cd neuro-segmentation-toolkit
python -m pytest tests/ -v

📋 Configuration

Edit configs/default_config.json to customize:

Parameter	Default	Description
target_spacing	[1.0, 1.0, 1.0]	Isotropic resampling resolution (mm)
intensity_normalization	z-score	Normalization method (z-score or min-max)
skull_strip	true	Enable skull stripping
bias_field_correction	true	Enable N4 correction
registration_target	T1c	Reference sequence for co-registration
min_tumor_volume_cc	0.5	Minimum volume threshold for quality flag
enhancing_threshold_std	2.0	Std devs above mean for enhancing detection

🤝 Acknowledgments

• SimpleITK — Image processing backbone
• 3D Slicer — Visualization and interactive editing
• ITK-SNAP — Active contour segmentation and label management
• BraTS Challenge — Label convention and evaluation methodology

📄 License

MIT License — see LICENSE for details.

⚠️ Disclaimer: This tool is for research and educational purposes only. It is not a certified medical device and should not be used for clinical diagnosis.