PyTorch implementation of FastSurferCNN
This directory contains all information needed to run FastSurfer - a fast and accurate deep-learning based neuroimaging pipeline. This approach provides a full FreeSurfer alternative for volumetric analysis (within 1 minute) and surface-based thickness analysis (within only around 1h run time). It consists of two main parts:
(i) FastSurferCNN - an advanced deep learning architecture capable of whole brain segmentation into 95 classes in under 1 minute, mimicking FreeSurfer’s anatomical segmentation and cortical parcellation (DKTatlas)
(ii) recon-surf - full FreeSurfer alternative for cortical surface reconstruction, mapping of cortical labels and traditional point-wise and ROI thickness analysis in approximately 60 minutes.
Within this repository, we provide the code and Docker files for running FastSurferCNN (segmentation only) and recon-surf (surface pipeline only) independently from each other or as a whole pipeline (run_fastsurfer.sh, segmentation + surface pipeline). For each of these purposes, see the README.md's in the corresponding folders.
There are two ways to run FastSurfer - (a) as a native install or (b) using Docker.
(a) For a native install on a modern linux (e.g. Ubuntu 16.04 or Centos 7, or maybe higher), download this github repository (use git clone or download as zip and unpack) for the necessary source code and python scripts. You also need to have the necessary python 3 libraries installed (see requirements.txt) as well as bash-4.0 or higher. This is already enough to generate the whole-brain segmentation using FastSurferCNN (see the README.md in the FastSurferCNN directory for the exact commands). In order to run the whole FastSurfer pipeline locally on your machine, a working version of FreeSurfer (v6.0, https://surfer.nmr.mgh.harvard.edu/fswiki/rel6downloads) is needed (specifically to run recon-surf). See Example 1 and Example 2 for an illustration of the commands to run the entire FastSurfer pipeline (FastSurferCNN + recon-surf) natively.
(b) For a docker version, simply use the provided Dockerfiles in our Docker directory to build your image (see the README.md in the Docker directory). No other local installations are needed (FreeSurfer and everything else will be included, you only need to provide a FreeSurfer license file). We will also make a Docker image available on Dockerhub in the near future (probably with the official release of version 1.0, the current release is beta). See Example 3 for an example how to run FastSurfer inside a Docker container.
The main script called run_fastsurfer.sh can be used to run both FastSurferCNN and recon-surf sequentially on a given subject. There are a number of options which can be selected and set via the command line. List them by running the following command:
bash ./run_fastsurfer.sh --help
Given you want to analyze data for subject1 which is stored on your computer under /home/user/mymridata/subject1/orig.mgz, run the following command from the console (do not forget to source FreeSurfer!):
# Source FreeSurfer export FREESURFER_HOME=/path/to/freesurfer/fs60 source $FREESURFER_HOME/SetUpFreeSurfer.shDefine data directory
datadir=/home/user/my_mri_data fastsurferdir=/home/user/my_fastsurfer_analysis
Run FastSurfer
./run_fastsurfer.sh --t1 $datadir/subject1/orig.mgz
--sid subject1 --sd $fastsurferdir
--parallel --threads 4
The output will be stored in the $fastsurferdir (including the aparc.DKTatlas+aseg.deep.mgz segmentation under $fastsurferdir/subject1/mri (default location)). Processing of the hemispheres will be run in parallel (--parallel flag). Omit this flag to run the processing sequentially.
In order to run FastSurfer on a number of cases which are stored in the same directory, prepare a subjects_list.txt file listing the names line per line: subject1\n subject2\n subject3\n ... subject10\n
And invoke the following command (make sure you have enough ressources to run the given number of subjects in parallel!):
export FREESURFER_HOME=/path/to/freesurfer/fs60 source $FREESURFER_HOME/SetUpFreeSurfer.shcd /home/user/FastSurfer datadir=/home/user/my_mri_data fastsurferdir=/home/user/my_fastsurfer_analysis mkdir -p $fastsurferdir/logs # create log dir for storing nohup output log (optional)
while read p ; do echo $p nohup ./run_fastsurfer.sh --t1 $datadir/$p/orig.mgz --sid $p --sd $fastsurferdir > $fastsurferdir/logs/out-${p}.log & sleep 90s done < ./data/subjects_list.txt
After building the Docker (see instructions in ./Docker/README.md), you do not need to have a separate installation of FreeSurfer on your computer (included in the Docker). However, you need to register at the FreeSurfer website (https://surfer.nmr.mgh.harvard.edu/registration.html) to acquire a valid license (for free). This license need to be passed to the script via the --fs_license flag.
To run FastSurfer on a given subject using the provided Docker, execute the following command:
docker run --gpus all -v /home/user/my_mri_data:/data \ -v /home/user/my_fastsurfer_analysis:/output \ -v /home/user/my_fs_license_dir:/fs60 \ --rm --user XXXX fastsurfer:gpu \ --fs_license /fs60/.license \ --t1 /data/subject2/orig.mgz \ --sid subject2 --sd /output \ --parallel
If you use this for research publications, please cite:
Henschel L, Conjeti S, Estrada S, Diers K, Fischl B, Reuter M, FastSurfer - A fast and accurate deep learning based neuroimaging pipeline, NeuroImage 219 (2020), 117012. https://doi.org/10.1016/j.neuroimage.2020.117012
The recon-surf pipeline is largely based on FreeSurfer including mrismakesurfaces which we bundle in binary form to patch a problem with the one in FreeSurfer 6.0. https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferMethodsCitation