FREESURFER TOOLBOX

PRESENTATION

Since the 4.2 release of BrainVISA, we propose a new toolbox which allows making some bridges with the FreeSurfer software. The toolbox will contain two separate parts:

• One is an import process (available in Import:Import From FreeSurfer to T1 pipeline in advanced user level), to import some data computed by FreeSurfer which can be used to run the Morphologist Pipeline. In a few words, from the following files orig.mgz, ribbon.mgz and talairach.auto, it is possible to complete the Morphologist Pipeline by using the segmented brain created with FreeSurfer instead of the ones computed by Morphologist. In this way, the same segmentations are preserved to complete the analysis by launching Morphologist Pipeline in order to extract cortical sulci graphs and perform an idenfication of sulci.

• The other is composed of a set of processes/pipelines (available in Freesurfer / BrainVisa full pipeline process) to run FreeSufer from within BrainVisa, and make its outputs (meshes, gyri and sulci textures, cortical thickness maps, etc) available in BrainVisa world, and viewable using Anatomist. They also can be used on data already processed by FreeSurfer outside of BrainVisa.

DATABASE

Introduction

This toolbox is a little bit unusual because you need to use database with an ontology for FreeSurfer. If you work with FreeSurfer, you know that data are organised with a specific order, looking like the following:

In order to use FreeSurfer within BrainVISA, the above description of files has written in the freesurfer ontology.

In the same way, BrainVISA has a specific organization to manage data which is described by an ontology, the "brainvisa-3.1.0" ontology. By default, datasets are always organized with it. But in the case of an interface between FreeSurfer/BrainVISA, you need to know the organization both software. For this, if you use the import process, you will need to set two databases with distinct ontologies one with a specific ontology for FreeSurfer and the other one for the Morphologist pipeline.

For more details about databases, please refer to data management section.

Configure databases

Now, please follow the instructions to properly setup the databases:

Configure the freesurfer database:

• Click on the BrainVISA -> Preferences menu.
• Select the Databases panel.
• Click on Add button.
• Select the directory which corresponds to your freesurfer directory (it can be a new empty directory if you have not run FreeSurfer yet, or an existing FreeSurfer data directory).
• Click on expert_settings.
• Select "freesurfer" in the list. It corresponds to the ontology.
• Click on OK.
• BrainVISA should open the "Update database process" with the new selected database. Click OK.

Now you have a freesurfer database in our brainvisa settings. Data will be directly available by using via a process. Note that the directory could correspond to the value of $SUBJECTS_DIR freesurfer environment variable.

Configure the brainvisa database:

• Click on the BrainVISA -> Preferences menu.
• Select the Databases panel.
• Click on Add button.
• Select a directory which will be your database.
• By default, the ontology is set to brainvisa-3.1.0. So you don't need to bother about expert_settings.
• Click on OK.
• BrainVISA should open the "Update database process" with the new selected database. Click OK.

HOW TO SETUP FREESURFER

Environment variables

To use FreeSufer, you have to set 2 environment variables:

• $SUBJECTS_DIR: path to indicate where is the directory with (analyzed) subjects.
• $FREESURFER_HOME: path to indicate where is installed FreeSurfer.

If these variables are not set, you can use the specific panel in BrainVISA -> Preferences -> FREESURFER.

In order to run FreeSurfer, BrainVISA tries to launch this program in the following order:

• At first, try to find a freesurfer command such as mri_convert, if Freesurfer is already setup, then BrainVISA can use directly commands on the system (using the system PATH).
• Otherwise, read values set in bainvisa preferences (freesurfer_home_path and subjects_dir_path).
• Then, if it doesn't work or if the values are empty, BrainVISA reads values of environment variables of the system.

If, in spite of the above trials, you still cannot use FreeSurfer, please try a last thing: launch your FreeSurfer environnment in a shell, then launch BrainVISA from within the same shell.