Welcome to FastSurfer!

Overview

This README contains all information needed to run FastSurfer - a fast and accurate deep-learning based neuroimaging pipeline. FastSurfer provides a fully compatible FreeSurfer alternative for volumetric analysis (within minutes) and surface-based thickness analysis (within only around 1h run time). FastSurfer is transitioning to sub-millimeter resolution support throughout the pipeline.

The FastSurfer pipeline consists of two main parts for segmentation and surface reconstruction.

the segmentation sub-pipeline (seg) employs advanced deep learning networks for fast, accurate segmentation and volumetric calculation of the whole brain and selected substructures.
the surface sub-pipeline (recon-surf) reconstructs cortical surfaces, maps cortical labels and performs a traditional point-wise and ROI thickness analysis.

Segmentation Modules

approximately 5 minutes (GPU), --seg_only only runs this part.

Modules (all run by default):

asegdkt: FastSurferVINN for whole brain segmentation (deactivate with --no_asegdkt)
- the core, outputs anatomical segmentation and cortical parcellation and statistics of 95 classes, mimics FreeSurfer’s DKTatlas.
- requires a T1w image (notes on input images), supports high-res (up to 0.7mm, experimental beyond that).
- performs bias-field correction and calculates volume statistics corrected for partial volume effects (skipped if --no_biasfield is passed).
cc: CorpusCallosum for corpus callosum segmentation and shape analysis (deactivate with --no_cc)
- requires asegdkt_segfile (segmentation) and conformed mri (orig.mgz), outputs CC segmentation, thickness, and shape metrics.
- standardizes brain orientation based on AC/PC landmarks (orient_volume.lta).
cereb: CerebNet for cerebellum sub-segmentation (deactivate with --no_cereb)
- requires asegdkt_segfile, outputs cerebellar sub-segmentation with detailed WM/GM delineation.
- requires a T1w image (notes on input images), which will be resampled to 1mm isotropic images (no native high-res support).
- calculates volume statistics corrected for partial volume effects (skipped if --no_biasfield is passed).
hypothal: HypVINN for hypothalamus subsegmentation (deactivate with --no_hypothal)
- outputs a hypothalamic subsegmentation including 3rd ventricle, c. mammilare, fornix and optic tracts.
- a T1w image is highly recommended (notes on input images), supports high-res (up to 0.7mm, but experimental beyond that).
- allows the additional passing of a T2w image with --t2 <path>, which will be registered to the T1w image (see --reg_mode option).
- calculates volume statistics corrected for partial volume effects based on the T1w image (skipped if --no_biasfield is passed).

Surface reconstruction

approximately 60-90 minutes, --surf_only runs only the surface part.
supports high-resolution images (up to 0.7mm, experimental beyond that).
requires a FreeSurfer license file as it uses some FreeSurfer binaries internally.
requires outputs of the asegdkt and the cc modules as a prerequisite (can be included in the same run).

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.

Getting started

Installation

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

For Linux and Windows users, we recommend running FastSurfer in a container Singularity/Apptainer or Docker: (OS: Linux, Windows, MacOS on Intel),
for macOS users, we recommend installing the FastSurfer package, and
for developers, the native install gives full control (only documented for Linux).

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 the placeholder <*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:

For container installations, you need to set up the container (<*singularity-flags*> or <*docker-flags*>) in addition to the <*fastsurfer-flags*>:
1. For Singularity, the syntax is
```
singularity run <*singularity-flags*> \
                fastsurfer.sif \
                <*fastsurfer-flags*>
```
  This command has two placeholders for flags: <*singularity-flags*> and <*fastsurfer-flags*>. <*singularity-flags*> set up the singularity environment, <*fastsurfer-flags*> include the options that determine the behavior of FastSurfer:
  
  Basic FastSurfer Flags
  - --t1: the path to the image to process.
  - --sd: the path to the "Subjects Directory", where all results will be stored.
  - --sid: the identified for the results for this image (folder inside "Subjects Directory").
  - --fs_license: path to the FreeSurfer license file.
  All options are explained in detail in the run_fastsurfer.sh documentation.
  
  An example for a simple full FastSurfer-Singularity command is
```
singularity run --nv \
                -B $HOME/my/mri_data \
                -B $HOME/my/fastsurfer_analysis \
                -B /software/freesurfer/license.txt \
                fastsurfer.sif \
                --t1 $HOME/my/mri_data/participant1/image1.nii.gz \
                --sd $HOME/my/fastsurfer_analysis \
                --sid part1_img1 \
                --fs_license /software/freesurfer/license.txt
```
  See also Example 1 for a full singularity FastSurfer run command and the Singularity documentation for details on more singularity flags and how to create the fastsurfer.sif file.
2. For docker, the syntax is
```
docker run <*docker-flags*> \
           deepmi/fastsurfer:<device>-v<version> \
           <*fastsurfer-flags*>
```
  The options for <*docker-flags*> and <*fastsurfer-flags*> follow very similar patterns as for Singularity (but the names of <*docker-flags*> are different).
  
  Example 2 also details a full FastSurfer run inside a Docker container and the Docker documentation for more details on *docker flags* and the naming of docker images (<device>-v<version>).
For a macOS package install, start FastSurfer from Applications and call the run_fastsurfer.sh FastSurfer script with FastSurfer flags from the terminal that is opened for you.
For a native install, call the run_fastsurfer.sh FastSurfer script directly. Your FastSurfer python/conda environment needs to be set up and activated.
```
# activate fastsurfer environment
conda activate fastsurfer

/path/to/fastsurfer/run_fastsurfer.sh <*fastsurfer-flags*>
```
In addition to the Basic Flags, note that you may need to use --py python3.12 to specify your python version, see FastSurfer flags for more details.

Example 3 also illustrates the running the FastSurfer pipeline natively.

FastSurfer

Install / Use

README