Do I need to skull-strip / bias-correct / register first? — No. Feed the raw NIfTI.

"Warning: not using the GPU — … this PyTorch build cannot run on it" — the default pip PyTorch wheels no longer include kernels for older GPUs (e.g. Pascal cards: GTX 10xx, Quadro P series). MindGlide falls back to CPU automatically. To use such a GPU, install a compatible PyTorch first:

pip install "torch==2.6.0+cu118" --index-url https://download.pytorch.org/whl/cu118
pip install mindglide

GPU out of memory — try --sw-batch-size 1, or --device cpu.

Apple Silicon — auto uses MPS when available. If an operation is unsupported, run with --device cpu or set PYTORCH_ENABLE_MPS_FALLBACK=1.

Offline / air-gapped machines — download the checkpoint once and pass --model-path /path/to/model.pt (or set MODEL_PATH).

Model cache location — the auto-downloaded model lives in the Hugging Face cache (~/.cache/huggingface by default); set HF_HOME to move it.

Can I fine-tune it? — The original container-based training/fine-tuning pipeline is preserved at the legacy-container tag. Open a Discussion if you're interested.

Prebuilt images (model weights baked in — works offline; ~8 GB with the CUDA runtime) are published on every release:

docker pull ghcr.io/ms-pinpoint/mindglide:latest

# run on a folder ( --user keeps output files owned by you; drop --gpus all on CPU-only hosts )
docker run --gpus all --ipc=host --user $(id -u):$(id -g) -v /data:/data \
  ghcr.io/ms-pinpoint/mindglide:latest -i /data/scan.nii.gz -o /data/scan_seg.nii.gz

For Apptainer/Singularity on HPC:

apptainer pull mindglide.sif docker://ghcr.io/ms-pinpoint/mindglide:latest
apptainer run --nv -B /data:/data mindglide.sif -i /data/scan.nii.gz -o /data/scan_seg.nii.gz

To build the image yourself instead: git clone this repo and docker build -t mindglide .

The checkpoint (_20240404_conjurer_trained_dice_7733.pt) is downloaded automatically from Hugging Face: MS-PINPOINT/mindglide on first run, pinned to an exact revision for reproducibility. Additional and legacy checkpoints are archived in the same repository. Models were trained on the datasets described in the paper.

From a source checkout you can also fetch the weights as a git submodule (requires Git LFS):

git submodule update --init --recursive
git submodule foreach 'git lfs pull'

git clone https://github.com/MS-PINPOINT/mindGlide.git
cd mindGlide
pip install -e ".[test]"

pytest                          # fast unit tests (seconds, no model download)
MINDGLIDE_RUN_SLOW=1 pytest -v  # + end-to-end on a public MNI scan (CPU, and GPU if present)

See CONTRIBUTING.md. Changes to the numerical path must produce byte-identical segmentations (the e2e tests check real outputs on public data).

@article{Goebl2025,
    author = {Goebl, Philipp and Wingrove, Jed and Abdelmannan, Omar and {Brito Vega}, Barbara and Stutters, Jonathan and Ramos, {Silvia Da Graca} and Kenway, Owain and Rossor, Thomas and Wassmer, Evangeline and Arnold, Douglas L. and Collins, Louis and Hemingway, Cheryl and Narayanan, Sridar and Chataway, Jeremy and Chard, Declan and Iglesias, {Juan Eugenio} and Barkhof, Frederik and Parker, Geoffrey J. M. and Oxtoby, Neil P. and Hacohen, Yael and Thompson, Alan and Alexander, Daniel C. and Ciccarelli, Olga and Eshaghi, Arman},
    title = {Enabling new insights from old scans by repurposing clinical {MRI} archives for multiple sclerosis research},
    journal = {Nature Communications},
    volume = {16},
    number = {1},
    pages = {3149},
    year = {2025},
    month = apr,
    doi = {10.1038/s41467-025-58274-8},
    pmid = {40195318},
    pmcid = {PMC11976987}
}