Quick Start¶

This example segments one brain MRI in a few minutes. Choose how you run FastSurfer: in a container on Linux (Apptainer, Singularity or Docker), with the macOS package, or without installing anything in Google Colab. Other systems are covered in the installation guide.

Segment an example image¶

With a GPU (8 GB of graphics memory) this takes well under a minute; without one, FastSurfer uses the CPU and takes a few minutes longer. You can use your own T1-weighted full head MRI (0.7 to 1 mm voxel sizes, no preprocessing, .nii, .nii.gz or .mgz), or the example image the commands download.

Note

The commands below use the tagged FastSurfer image :cu132-v2.6.0. CUDA 13.2 is the default CUDA version bundled in both :latest and that image. Images of 2.6.0 for other CUDA versions, ROCm and CPU are available on Docker Hub.

Apptainer / Singularity

# 0. Create a directory for this test
mkdir fastsurfer_test
cd fastsurfer_test

# 1. Build the Apptainer image from our Docker image (only the first time)
mkdir -p $HOME/my_singularity_images
singularity build \
    $HOME/my_singularity_images/fastsurfer-cu132-v2.6.0.sif \
    docker://deepmi/fastsurfer:cu132-v2.6.0

# 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-mount home,cwd -e \
                 -B "$PWD" \
                 $HOME/my_singularity_images/fastsurfer-cu132-v2.6.0.sif \
                 /fastsurfer/run_fastsurfer.sh \
                 --t1 "$PWD/140_orig.mgz" \
                 --sid subjectX --sd "$PWD" \
                 --seg_only --no_biasfield --no_cereb --no_hypothal

Docker

# 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:cu132-v2.6.0 \
                      --t1 "$PWD/140_orig.mgz" \
                      --sid subjectX --sd "$PWD" \
                      --seg_only --no_biasfield --no_cereb --no_hypothal

macOS package

Install the package, open the FastSurfer app from your Applications folder, and run these commands in the Terminal window it opens:

# 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)
run_fastsurfer.sh --t1 "$PWD/140_orig.mgz" \
    --sid subjectX --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 subjectX/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; you then need a FreeSurfer license file and pass it into the container, see Running FastSurfer in a container.

You will find the full brain segmentation in ./subjectX/mri/aparc.DKTatlas+aseg.deep.mgz in FreeSurfer’s MGZ file format. To convert it back to nifti (if you prefer), run nib-convert, which comes with FastSurfer, for example with the Singularity image (in the macOS console, call nib-convert directly):

Note

# Convert mgz to nifti
singularity exec --nv \
                 --no-mount home -e \
                 -B "$PWD" \
                 $HOME/my_singularity_images/fastsurfer-cu132-v2.6.0.sif \
                 nib-convert "$PWD/subjectX/mri/aparc.DKTatlas+aseg.deep.mgz" \
                             "$PWD/subjectX/mri/aparc.DKTatlas+aseg.deep.nii.gz"

and find the segmentation in ./subjectX/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 \
    subjectX/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.

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 points to the installation guide and includes examples of how to run FastSurfer, and 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: Surface models, Thickness maps and more: FastSurfer’s recon-surf command

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