Quick Start¶

This example segments one brain MRI in a few minutes with fastsurfer, a launcher that runs FastSurfer with the same commands on Linux, Windows and macOS. It takes the flags of run_fastsurfer.sh and sets up the rest: on Linux, Windows and Intel Macs, it picks, downloads and runs the right container image; on a Mac with Apple silicon, it runs the installed macOS package. You can also try FastSurfer without installing anything in Google Colab.

The launcher is meant for getting started and for single images. For larger projects, such as whole datasets or runs on an HPC cluster, we recommend running FastSurfer directly, which gives full control over images, paths and resources: see the installation guide, Running FastSurfer in a container, and the scripts for many subjects and for SLURM clusters.

Set up your computer¶

Once, set up what the launcher runs FastSurfer with:

Linux

FastSurfer runs in a container, with Apptainer (or its predecessor Singularity) or Docker. Check whether one of them works, for example:

# Apptainer (with Singularity: singularity --version)
apptainer --version
# Docker
docker run --rm hello-world

Clusters usually provide Apptainer, often as a module (module load apptainer, see your cluster’s documentation). Installing Apptainer or Docker needs administrator rights, so if neither works, ask your administrator to install Apptainer or Docker. Docker also needs:

your user in the docker group, to run containers without sudo (log out and back in once you were added),
for NVIDIA GPUs, the NVIDIA Container Toolkit. Apptainer needs only the NVIDIA driver.

The launcher picks the image for your NVIDIA GPU (or AMD GPU, experimental, or the CPU) and downloads it on the first run. Linux explains the images.

Windows

FastSurfer runs in Docker, inside WSL2, the Linux environment of Windows:

Install WSL2: open PowerShell as administrator, run wsl --install, and restart Windows. This also installs Ubuntu.
Install Docker Desktop, start it, and switch on the WSL integration for Ubuntu under Settings > Resources > WSL integration.
For an NVIDIA GPU, install the latest NVIDIA driver for WSL in Windows.
Open Ubuntu from the Start menu. Run the FastSurfer commands in this terminal, not in PowerShell. Check Docker there, for example:
```
docker run --rm hello-world
```

WSL2 gets only part of the computer’s memory; the system requirements say how much FastSurfer needs, and the launcher warns if Docker has less.

Windows has more details.

Mac with Apple silicon

FastSurfer runs natively with the macOS package, which uses the Mac’s GPU (M1 or newer). Download and install it with the button on that page, or let the launcher do it: after step 1 below, ./fastsurfer --update downloads the package and opens the macOS Installer. macOS may block the installer, because it is not signed by Apple yet; Install explains how to allow it.

Intel Mac

FastSurfer runs in Docker, on the CPU (the macOS package needs Apple silicon):

Install Docker Desktop for Mac, start it, and under Settings > Resources set the memory to 15 GB (or the most you have; with less than that, it may fail).
Check Docker in a Terminal window, for example:
```
docker run --rm hello-world
```

If the launcher still cannot run FastSurfer, it says what is missing and how to fix it.

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. On Windows, run the commands in the Ubuntu terminal.

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

# 1. Download the launcher (only the first time)
curl -fsSLO https://deep-mi.org/FastSurfer/dev/fastsurfer
chmod +x fastsurfer

# 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)
./fastsurfer --t1 140_orig.mgz --sid subjectX --sd . \
    --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: pass it with --fs_license <path>, or set the environment variable FS_LICENSE to its path, which the launcher passes on.

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:

# Convert mgz to nifti
./fastsurfer --exec nib-convert \
    subjectX/mri/aparc.DKTatlas+aseg.deep.mgz \
    subjectX/mri/aparc.DKTatlas+aseg.deep.nii.gz

Then 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”.