= Using FreeSurfer =
The free software !FreeSurfer can be used to extract brain and head  surfaces from a T1 MRI. It also automatically registers the individual  cortex surfaces to two atlases (Desikan-Killiany and Destrieux). The process is fully automatic and the  results can be imported in Brainstorm with just a few mouse clicks.

== Running FreeSurfer ==
 1. Downloading and installing !FreeSurfer is very easy. It just takes some time because the distribution package is huge (get ready to download several Gb).<<BR>>Just follow the instructions: http://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall
 1. Set up the !FreeSurfer environment:
  * setenv FREESURFER_HOME /.../local/freesurfer
  * setenv SUBJECTS_DIR /.../data/freesurfer/subjects
  * setenv FUNCTIONALS_DIR /.../data/freesurfer/sessions
  * cd /.../local/freesurfer
  * source !FreeSurferEnv.csh

 1. Run the reconstruction:
  * recon-all -i <mri_file> -subjid <subject_id>
  * recon-all -all -subjid <subject_id>
 1. Leave your office, come back the next day. The process is fully automatic, but quite resource-consuming.
 1. Done. Everything is ready to be imported in Brainstorm. The results are usually perfect, but depending on the quality of the structural MR, it may fail. Because of this unpredictable behavior, you always need to check visually the final surfaces. The !FreeSurfer wiki suggests that you check all the steps with !FreeSurfer. We suggest instead that you load it all in Brainstorm and go back to the manual checking/editing only if it looks bad.
 1. More detailed instructions for setting up the environment and tuning  the reconstruction here:<<BR>>http://surfer.nmr.mgh.harvard.edu/fswiki/RecommendedReconstruction
 1. More questions about !FreeSurfer: Use the text box on the top right corner of the previous page to search the wiki.

== Importing the results in Brainstorm ==
 1. Switch to the anatomy side of the database explorer
 1. Create a new subject, set the default anatomy option to "No, use individual anatomy"
 1. Right-click on the subject > Import !FreeSurfer folder...<<BR>><<BR>> {{attachment:import1.gif|importAnnot1.gif}} <<BR>><<BR>>
 1. Select the top folder of your subject <subject_id>   (/.../data/freesurfer/subjects/subject_id)
 1. Then you're prompted for the number of vertices you want in the final cortex surface. This will by extension define the number of dipoles to estimate during the source estimation process. By default we set this value to 15000 for the entire brain (it means 7500 for each hemisphere).<<BR>><<BR>> {{attachment:nVertices.gif|importAnnot1.gif}} <<BR>><<BR>>
 1. The MRI Viewer appears, and a help window asks you to validate the orientation of the MRI and to define the 6 fiducial points. If something doesn't look right at this step, for instance if the MRI is  not presented with a correct orientation, you should stop this automatic  import process and follow the manual instructions in the basic tutorial  pages. <<BR>><<BR>> {{attachment:mriviewer.gif|importAnnot1.gif}} <<BR>><<BR>>
 1. Place the six fiducials. If you need help, refer to this page: CoordinateSystems
 1. Click on Save to keep your modifications, and the automatic import will go on.
 1. The files that are imported from the subject_id folder are the following:
  * /mri/'''T1.mgz'''   (T1 MRI volume)
  * /surf/'''lh.pial'''    (grey/csf interface, left hemisphere)
  * /surf/'''rh.pial'''    (grey/csf interface, right hemisphere)
  * /surf/'''lh.smoothwm'''   (white matter, left hemisphere)
  * /surf/'''rh.smoothwm'''   (white matter, right hemisphere)
  * /label/'''lh.*.annot'''     (atlases: left hemisphere)
  * /label/'''rh.*.annot'''     (atlases: right hemisphere)
 1. The successive steps that are performed by Brainstorm:
  * Import all the surfaces (left/right, white/pial)
  * Load all the atlases available for each surface (note that the .pial and .smoothwm surfaces are matching point-to-point, so the same annotation files are imported for both surface types)
  * Downsample each hemisphere to the number specified in the options (by default 7500, half of the total default number 15000)
  * Merge left and right hemispheres for the two surface types: white matter and cortex envelope
  * Delete all the unnecessary surfaces
  * Generate a head surface from the MRI (this is not done by !FreeSurfer)
 1. The files you can see in the database explorer in the end: <<BR>><<BR>> {{attachment:checkDb.gif|importAnnot1.gif}} <<BR>><<BR>>
  * '''MGH MRI''': The T1 MRI of the subject, imported from the MGH file format (.mgz)
  * '''head mask''' (10000,0,2): Scalp surface generated by Brainstorm. The numbers indicate the parameters that were used automatically for this head: vertices=10000, erode factor=0, fill holes=2 (those are detailed later)
  * '''cortex_300000V''': High-resolution cortex surface that was generated by !FreeSurfer, that contains usually between 200,000 and 300,000 vertices.
  * '''cortex_15000V''': Low-resolution cortex surface, downsampled using the '''reducepatch''' function from Matlab (it keeps a meaningful subset of vertices from the original surface).
  * '''white_300000V''': High-resolution white matter envelope from !FreeSurfer
  * '''white_15000V''': Low-resolution white matter, processed with reducepatch
 1. A figure is automatically shown at the end of the process, to check visually that the cortex and head surfaces were properly generated and imported. If it doesn't look like the following picture, do not go any further in your source analysis, fix the anatomy first.<<BR>><<BR>> {{attachment:checkResult.gif|importAnnot1.gif}} <<BR>><<BR>>
 1.
 1. If it doesn'tlook good the options are
 1. Description of head generation

== Cortical parcellations ==
Cortical parcellation: http://freesurfer.net/fswiki/CorticalParcellation

 1. Process your subject MRI with the full !FreeSurfer T1 analysis pipeline
 1. In Brainstorm, create a protocol and a subject, as explained in the introduction tutorials
 1. Import the following files from the !FreeSurfer architecture:
  * MRI: /mri/T1.mgz
  * Head surface: /bem/wateshed/outer_skin_surface
  * Left hemisphere: /surf/lh.pial (or lh.smoothwm)
  * Right hemisphere: /surf/lh.pial (or lh.smoothwm)<<BR>><<BR>>
 1. Add the atlas-based parcellations to each hemisphere <<BR>><<BR>> {{attachment:importAnnot1.gif}}
  * Right-click on "lh" > Labels > Import labels
  * Select one of the annotation files in the /label/ folder:
   * Destrieux atlas: lh.aparc.a2009s.annot
   * Desikan-Killiany atlas: lh.aparc.annot
  * Repeat the same operation for the right hemisphere
  * The .annot files are read with the !FreeSurfer read_annotation.m Matlab function, then converted to Brainstorm scouts, and saved in the surface files in the "Scout" field <<BR>><<BR>>
 1. Downsample each hemisphere to 7500 vertices (the scouts will be downsampled accordingly)<<BR>>Right-click > Less vertices
 1. Concatenate the two downsampled surfaces<<BR>>Select lh_7500 and rh_7500 > right-click > Merge surfaces
 1. Rename the new surface into "cortex". This last surface contains all the scouts (ie. ROIs) defined for lh and rh, which will be loaded automatically when you display the surface in Brainstorm.
 1. Double-click on "cortex", go to the Scout tab, and select a few scouts, to check that the .annot files where imported properly<<BR>><<BR>> {{attachment:importAnnot2.gif}}

== Examples ==
Desikan-Killiany atlas, in !FreeSurfer:

{{attachment:dk_fs.jpg}}

Desikan-Killiany atlas, in Brainstorm:

{{attachment:dk_bs.gif}}

Desikan-Killiany atlas, in Brainstorm after downsampling to 15000 vertices:

{{attachment:dk_bs2.gif}}

== Parcellations for the default anatomy (MNI/Colin27) ==
The !FreeSurfer cortex and white matter surfaces are available in the standard distribution of Brainstorm, they come with the all the !FreeSurfer parcellations. You can use those surfaces instead of the default Brainstorm ones, which are created with BrainVISA, which do not include the Desikan-Killiany and Destrieux atlases.

 1. In any protocol, go to the anatomy view, and select the "Default anatomy" folder.<<BR>><<BR>> {{attachment:defaultAnat.gif}}
 1. If you do not see the surfaces "!FreeSurfer: cortex *" and "!FreeSurfer: white *", your protocol is not using the most recent version of the Brainstorm default anatomy. To update:
  * Make sure you are running the latest version of Brainstorm
  * Right-click on "Default anatomy" > Use default > MNI_Colin27
  * Close the MRI Viewer when it opens. Now you should see all the !FreeSurfer surfaces
 1. Make one of the !FreeSurfer surfaces as your default cortex surface (for instance, the downsampled grey/csf interface):
  * Right-click on "!FreeSurfer: cortex 15000V" > Set surface type > Cortex
  * Right-click on the top "cortex" file > Set surface type > Other (this is not necessary, but it avoids ambiguity)
  * To make sure that everything is updated properly: Right-click on "Default anatomy" > Reload<<BR>><<BR>> {{attachment:defaultAnat2.gif}}
 1. Double-click on the new default cortex (!FreeSurfer: cortex 15000V) to open it
 1. In the "Scout" tab, click on the "Load scout" button (on the right of the scouts list)<<BR>><<BR>> {{attachment:importScout.gif}}
 1. In the list of available scout files, pick on that matches the surface that is currently displayed: '''scout_freesurfer_*_15000V.mat'''<<BR>><<BR>> {{attachment:figureCortex.gif}}
 1. You can now run source analysis (computation forward and inverse models) using this new cortex surface, and use the !FreeSurfer atlases as regions of interest