mri_WMHsynthseg

⚠️ Important Notice: The wmh_synthseg model has just been trained and is ready for use. A Docker container is temporarily available.

WMH-SynthSeg

"Quantifying White Matter Hyperintensity and Brain Volumes in Heterogeneous Clinical and Low-field portable MRI". [View Project]

Developed as part of my Master's thesis at MGH, Harvard Medical School, and CSAIL, MIT, this project leverages WMH-SynthSeg, an extension of SynthSeg, designed for brain MRI scans. It uniquely adapts to low-field MRI scans, providing high-resolution segmentations of white matter hyperintensities (WMH) and anatomical structures, even in challenging imaging conditions.

Author: Pablo Laso
Email: plaso@kth.se
Citation: If you use WMH-SynthSeg in your analysis, please cite our paper under review.

Installation

The wmh_synthseg model has already been trained and is ready for use. Here are some options to run the model now:

1. A Docker container is temporarily avialable. (recommended)

2. Alternatively, you can clone this repository, download the model from the link, and add it to your path. Please note you need a big memory to run it locally.

3. You can also try to use it from FreeSurfer. However, please note that integration with FreeSurfer is currently in progress and not yet available. In other words, running the model will not be straight-forward. Stay tuned for updates on this implementation.

(1) Docker:

1. Downloading the Docker Container:

To download the container from Docker, use the following command:

    docker pull pablaso/wmh_synthseg:latest

2. Running the Docker Container:

To run the container and process your MRI images, use the following command:

    docker run --rm -v /path/to/your/data:/data pablaso/wmh_synthseg --i /data/your_input_image.nii.gz --o /data/your_output_image.nii.gz

(2) Cloning repo and changing the path:

1. Clone repository:

    git clone https://github.com/lasopablo/freesurfer-freesurfer-dev-mri_WMHsynthseg.git
    cd freesurfer-freesurfer-dev-mri_WMHsynthseg

2. Change path in the inference.py file:

      model_file = os.path.join('/app/models', 'WMH-SynthSeg_v10_231110.pth')

(3) Downloading the atlas (official):

This section documents how to download and install the atlas file required by the mri_WMHsynthseg utility. General usage and utility description can be found at:

https://surfer.nmr.mgh.harvard.edu/fswiki/WMH-SynthSeg

This utility requires an atlas file that does not ship with the standard install of FreeSurfer. This is done in an effort to keep the size of the installer reasonable. The utility expects the atlas file, WMH-SynthSeg_v10_231110.pth,
to be installed under $FREESURFER_HOME/models, and can be downloaded from an ftp server.

1. Download the atlas:

Linux:

    wget https://ftp.nmr.mgh.harvard.edu/pub/dist/lcnpublic/dist/WMH-SynthSeg/WMH-SynthSeg_v10_231110.pth 

MacOS:

    curl -o WMH-SynthSeg_v10_231110.pth https://ftp.nmr.mgh.harvard.edu/pub/dist/lcnpublic/dist/WMH-SynthSeg/WMH-SynthSeg_v10_231110.pth 
  ```

Installing the atlas (same for both Linux and MacOS):
```bash
    cp WMH-SynthSeg/WMH-SynthSeg_v10_231110.pth $FREESURFER_HOME/models

You should now see WMH-SynthSeg_v10_231110.pth under $FREESURFER_HOME/models This can be confirmed, by running:

    ls $FREESURFER_HOME/models | grep WMH-SynthSeg_v10_231110.pth | wc -l

The above command should print '1' to the terminal if the model is in the proper location.

2. Run the model

Run mri_WMHsynthseg on the command line, with the appropriate arguments.

usage: inference.py [-h] --i I --o O [--csv_vols CSV_VOLS] [--device DEVICE]
                    [--threads THREADS] [--save_lesion_probabilities] [--crop]