Quick Start¶

Singularity or Docker¶

For users with a linux workstation with a GPU (8GB) and Singularity (or Docker) installed, running FastSurfer is easy and fast! If you don’t have a GPU, it will use the CPU and be quite a bit slower. And if you don’t have Docker or Singularity, see below for how to run FastSurfer in the Cloud with Google Collab!

For running this example you can use your own T1-weighted full head MRI (0.7-1 mm voxel sizes, no pre-processing, .nii or .nii.gz Nifti), or just use the example below:

# 0. Create a directory for this test
mkdir fastsurfer-test
cd fastsurfer-test

# 1. Download the docker image and create the singularity image (do this only the first time)
#    It will produce the fastsurfer-gpu.sif singularity image file locally
singularity build fastsurfer-gpu.sif docker://deepmi/fastsurfer:latest

# 2. Download an example brain MRI (if you don't have your own)
#    If you have your own, copy it to this directory and adjust 
#    the filename after --t1 below.
curl -k https://surfer.nmr.mgh.harvard.edu/pub/data/tutorial_data/buckner_data/tutorial_subjs/140/mri/orig.mgz -o "./140_orig.mgz"

# 3. Run FastSurfer (full brain segmentation only)
singularity exec --nv \
                 --no-home \
                 -B "$PWD" \
                 ./fastsurfer-gpu.sif \
                 /fastsurfer/run_fastsurfer.sh \
                 --t1 "$PWD/140_orig.mgz" \
                 --sid test-case --sd "$PWD" \
                 --seg_only --no_biasfield --no_cereb --no_hypothal

That’s it, it will run the full brain segmentation. For speed, we switched off the cerebellum and hypothalamic sub-segmentation (would add a couple minutes). We also switched off the bias field correction, which is used to compute partial volume estimates for the statsfiles, so you might want to switch it on again if you want the volume statistics text file (under test-case/stats). Also if you need the estimated total intracranial volume for correcting the stats, you would either need to run the surface stream or switch on the Talairach registration with --tal_reg in the segmentation module. For the full surface stream, just remove the --seg_only and you need a FreeSurfer license file and pass it into the container, as described in more detail later.

For your convenience here is the same procedure using Docker instead of Singularity:

# 0. Create a directory for this test
mkdir fastsurfer-test
cd fastsurfer-test

# 1. Download an example brain MRI (if you don't have your own)
#    If you have your own, copy it to this directory and adjust 
#    the filename after --t1 below.
curl -k https://surfer.nmr.mgh.harvard.edu/pub/data/tutorial_data/buckner_data/tutorial_subjs/140/mri/orig.mgz -o "./140_orig.mgz"

# 2. Run FastSurfer (full brain segmentation only)
docker run --gpus all -v "$PWD:$PWD" \
                      --rm --user $(id -u):$(id -g) \
                      deepmi/fastsurfer:latest \
                      --t1 "$PWD/140_orig.mgz" \
                      --sid test-case --sd "$PWD" \
                      --seg_only --no_biasfield --no_cereb --no_hypothal

You will find the full brain segmentation in ./test-case/mri/aparc.DKTatlas+aseg.deep.mgz in FreeSurfer’s MGZ file format. To convert it back to nifti (if you prefer), just run

# Convert mgz to nifti
singularity exec --nv \
                 --no-home \
                 -B "$PWD" \
                 ./fastsurfer-gpu.sif \
                 nib-convert "$PWD/test-case/mri/aparc.DKTatlas+aseg.deep.mgz" "$PWD/test-case/mri/aparc.DKTatlas+aseg.deep.nii.gz"

and find the segmentation in ./test-case/mri/aparc.DKTatlas+aseg.deep.nii.gz. If you have FreeSurfer installed, just use FreeView to look at the result (or really any other image viewer):

# FreeView
freeview -v 140_orig.mgz test-case/mri/aparc.DKTatlas+aseg.deep.mgz:colormap=lut:opacity=0.2

Other interesting outputs of the segmentation are the aseg.auto_noCCseg.mgz containing a reduced segmentation according to FreeSurfer’s aseg (no cortical sub-division and no corpus callosum, which is added later). Also mask.mgz can come in handy if you need a brainmask. And you get all of this within a few seconds (including startup of singularity or docker it is 20 sec in total with a GeForce RTX 4080, 40 sec with a Quadro RTX 4000 or Titan XP, CPU-only takes 5 minutes longer on my machine).

Google Colab¶

You can also run FastSurfer in the cloud with Google Colab.

In order to use the notebooks, simply click on the link or optimally the google colab icon displayed at the top of the page. This way, the plots will be rendered correctly. If you have a Google account, you can interactively execute the run cells. Without a google account you can see the files and outputs generated by the last run.

Notebook 1 - Quick and Easy - FastSurfer Segmentation with three clicks¶

Notebook 1 contains a super quick and easy scenario in which you can run FastSurferCNN in just three clicks. You do not need any programming experience to get a segmentation in less than 60 s!

Notebook 2 - Complete FastSurfer Tutorial¶

Notebook 2 is an extended version of the first one with information about how to set up FastSurfer on your local machine. It includes detailed installation instructions as well as examples of how to visualize and quality control your data.

After a quick introduction, it covers three use cases:

Use case 1: Quick and Easy - FastSurfer Segmentation with three clicks (same as the first notebook)
Use case 2: Quick and a bit more advanced - Segmentation with FastSurfer on your local machine
Use case 3: Use case 3 - Surface models, Thickness maps and more: FastSurfer’s recon-surf command

In addition, there is a small section covering python-qatools called “Bonus - Quality analysis using qatools”.