Introduction to FastSurfer

Getting started

Installation

There are two ways to run FastSurfer (links are to installation instructions):

1. In a container (Singularity or Docker) (OS: Linux, Windows, MacOS on Intel),

2. As a native install (all OS for segmentation part).

We recommended you use Singularity or Docker on a Linux host system with a GPU. The images we provide on DockerHub conveniently include everything needed for FastSurfer. You will also need a FreeSurfer license file for the Surface pipeline. We have detailed per-OS Installation instructions in the INSTALL.md file.

Usage

All installation methods use the run_fastsurfer.sh call interface (replace *fastsurfer-flags* with FastSurfer flags), which is the general starting point for FastSurfer. However, there are different ways to call this script depending on the installation, which we explain here:

1. For container installations, you need to define the hardware and mount the folders with the input (/data) and output data (/output): (a) For singularity, the syntax is

   singularity exec --nv \
                    --no-home \
                    -B /home/user/my_mri_data:/data \
                    -B /home/user/my_fastsurfer_analysis:/output \
                    -B /home/user/my_fs_license_dir:/fs_license \
                    ./fastsurfer-gpu.sif \
                    /fastsurfer/run_fastsurfer.sh
                    *fastsurfer-flags*
   

   The --nv flag is needed to allow FastSurfer to run on the GPU (otherwise FastSurfer will run on the CPU).

   The --no-home flag tells singularity to not mount the home directory (see Singularity documentation for more info).

   The -B flag is used to tell singularity, which folders FastSurfer can read and write to.

   See also Example 2 for a full singularity FastSurfer run command and the Singularity documentation for details on more singularity flags.

   (b) For docker, the syntax is

   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:/fs_license \
              --rm --user $(id -u):$(id -g) \
              deepmi/fastsurfer:latest \
              *fastsurfer-flags*
   

   The --gpus flag is needed to allow FastSurfer to run on the GPU (otherwise FastSurfer will run on the CPU).

   The -v flag is used to tell docker, which folders FastSurfer can read and write to.

   See also Example 1 for a full FastSurfer run inside a Docker container and the Docker documentation for more details on the docker flags including --rm and --user.

2. For a native install, you need to activate your FastSurfer environment (e.g. conda activate fastsurfer_gpu) and make sure you have added the FastSurfer path to your PYTHONPATH variable, e.g. export PYTHONPATH=$(pwd).

   You will then be able to run fastsurfer with ./run_fastsurfer.sh *fastsurfer-flags*.

   See also Example 3 for an illustration of the commands to run the entire FastSurfer pipeline (FastSurferCNN + recon-surf) natively.

Requirements to input images

All pipeline parts and modules require good quality MRI images, preferably from a 3T MR scanner. FastSurfer expects a similar image quality as FreeSurfer, so what works with FreeSurfer should also work with FastSurfer. Notwithstanding module-specific limitations, resolution should be between 1mm and 0.7mm isotropic (slice thickness should not exceed 1.5mm). Preferred sequence is Siemens MPRAGE or multi-echo MPRAGE. GE SPGR should also work. See --vox_size flag for high-res behaviour.

System Requirements

Recommendation: At least 8 GB system memory and 8 GB NVIDIA graphics memory --viewagg_device gpu

Minimum: 7 GB system memory and 2 GB graphics memory --viewagg_device cpu --vox_size 1

Minimum CPU-only: 8 GB system memory (much slower, not recommended) --device cpu --vox_size 1

Minimum Requirements:

	–viewagg_device	Min GPU (in GB)	Min CPU (in GB)
1mm	gpu	5	5
1mm	cpu	2	7
0.8mm	gpu	8	6
0.8mm	cpu	3	9
0.7mm	gpu	8	6
0.7mm	cpu	3	9

Expert usage

Individual modules and the surface pipeline can be run independently of the full pipeline script documented in this documentation. This is documented in READMEs in subfolders, for example: whole brain segmentation only with FastSurferVINN, cerebellum sub-segmentation, hypothalamic sub-segmentation and surface pipeline only (recon-surf).

Specifically, the segmentation modules feature options for optimized parallelization of batch processing.

FreeSurfer Downstream Modules

FreeSurfer provides several Add-on modules for downstream processing, such as subfield segmentation ( hippocampus/amygdala, brainstem, thalamus and hypothalamus ) as well as TRACULA. We now provide symlinks to the required files, as FastSurfer creates them with a different name (e.g. using “mapped” or “DKT” to make clear that these file are from our segmentation using the DKT Atlas protocol, and mapped to the surface). Most subfield segmentations require wmparc.mgz and work very well with FastSurfer, so feel free to run those pipelines after FastSurfer. TRACULA requires aparc+aseg.mgz which we now link, but have not tested if it works, given that DKT-atlas merged a few labels. You should source FreeSurfer 7.3.2 to run these modules.

Intended Use

This software can be used to compute statistics from an MR image for research purposes. Estimates can be used to aggregate population data, compare groups etc. The data should not be used for clinical decision support in individual cases and, therefore, does not benefit the individual patient. Be aware that for a single image, produced results may be unreliable (e.g. due to head motion, imaging artefacts, processing errors etc). We always recommend to perform visual quality checks on your data, as also your MR-sequence may differ from the ones that we tested. No contributor shall be liable to any damages, see also our software LICENSE.

References

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

Henschel L*, Kuegler D*, Reuter M. (*co-first). FastSurferVINN: Building Resolution-Independence into Deep Learning Segmentation Methods - A Solution for HighRes Brain MRI. NeuroImage 251 (2022), 118933. http://dx.doi.org/10.1016/j.neuroimage.2022.118933

Faber J*, Kuegler D*, Bahrami E*, et al. (*co-first). CerebNet: A fast and reliable deep-learning pipeline for detailed cerebellum sub-segmentation. NeuroImage 264 (2022), 119703. https://doi.org/10.1016/j.neuroimage.2022.119703

Estrada S, Kuegler D, Bahrami E, Xu P, Mousa D, Breteler MMB, Aziz NA, Reuter M. FastSurfer-HypVINN: Automated sub-segmentation of the hypothalamus and adjacent structures on high-resolutional brain MRI. Imaging Neuroscience 2023; 1 1–32. https://doi.org/10.1162/imag_a_00034

Stay tuned for updates and follow us on X/Twitter.

Acknowledgements

This project is partially funded by:

• Chan Zuckerberg Initiative

• German Federal Ministry of Education and Research

The recon-surf pipeline is largely based on FreeSurfer.