Skip to content

Files

Latest commit

 

History

History

Tutorial

FastSurfer Tutorial

Open In Colab Open In Colab

Overview

This repository contains two google colab files which illustrate how to run and install FastSurfer. 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".

ISMRM 2021 slides

As part of the ISMRM Software Demo 2021, a presentation giving an overview of how to use FastSurfer was created as well. This contains references to the notebooks above as well as some background information on FastSurfer. Feel free to check it out: https://docs.google.com/presentation/d/1xuMFBo-AQMwdH8MplUWgEvn9z0bJk6p1mzi2vm-mKvs/edit?usp=sharing

Requirements

If you want to follow along on your local machine, you need a working installation of FastSurfer. The steps are also covered in the second notebook (Sections B for Use case 1 and 2). In order to follow the installation instructions, some basic requirements have to be met. In general, you need either a Linux OS, MacOS (+Docker) or Windows (+Docker) to run FastSurfer. Further, the segmentation requires a little less than 10 GB RAM. If you are using Docker on MAC, you have to make sure to adjust the memory settings accordingly (by default, they are limited to 2 GB runtime memory).

1. Recommendation - Docker

Docker is an open platform for developing, shipping, and running applications. In a way, it allows the user to create software-packages which you as a user can simply download (or pull) and directly use. These include all dependencies you need for running the application. You do not need to install anything else. See the detailed documentation on how to install docker on your local machine.

2. Local installation

If you decide against using docker, you need either python + pip or anaconda (conda) to install FastSurfer.

1. Python + pip

Python 3.10 is generally recommended to run FastSurfer. In addition you will need the package manager pip to install the python dependencies used for FastSurfer (see requirements.txt in the main directory for a list). On Linux, pip is not installed by default. You can install it via

sudo apt install python3-pip

If not pre-installed, setuptools has to be installed before the contents of requirements.txt. This can be done via apt or pip:

sudo apt install python3-setuptools
pip install setuptools

The optional recon-surf dependency, scikit-sparse, can not be installed sequentially with numpy (and thus can not be included in the requirements.txt file). Therefore, it should be installed separately, after the requirements.txt install:

pip install scikit-sparse=0.4.4

It is normally recommended to run your set ups in separate virtual environments (like e.g. pipenv/virtualenv). Or you can use conda.

2. Anaconda

You can install anaconda via curl with the following command:

# The version of Anaconda may be different depending on when you are installing`
curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
sh Miniconda3-latest-Linux-x86_64.sh
# and follow the prompts. The defaults are generally good.

You may have to open a new terminal or re-source your ~/.bashrc to get access to the conda command. See also the documentation for conda as well as the section about how to manage conda environments.