= FEM mesh generation =
''Authors: [[https://neuroimage.usc.edu/brainstorm/AboutUs/tmedani#preview|Takfarinas Medani]], Francois Tadel''

FEM forward modeling requires the construction of a 3D model of the head tissues. The volume of the head is divided in small geometrical elements with 4 faces (tetrahedrons) or 6 faces (hexahedrons). Each element is associated with a type of biological tissue (e.g. white matter, gray matter, CSF, skull, skin) and electrical conductivity properties.

This page lists the methods integrated with Brainstorm to generate 3D meshes of the head. For a generic introduction to FEM in Brainstorm, refer to the tutorials: [[https://neuroimage.usc.edu/brainstorm/Tutorials/Duneuro|Realistic head model: FEM with DUNEuro]] and [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMedianNerveCharm|FEM median nerve example]].

<<TableOfContents(3,2)>>

== Generate FEM mesh ==
FEM meshes can be computed from surfaces (as the ones generated for the [[https://neuroimage.usc.edu/brainstorm/Tutorials/TutBem#BEM_surfaces|BEM models]]) or from MRI volumes (T1w and/or T2w). The methods that are available when using the popup menu '''Generate FEM mesh''' depend on the selected inputs.

=== Surfaces ===
Select a list of surfaces representing the separation between different tissues (holding the CTRL or SHIFT key), then right-click on any of them. The software [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#Iso2mesh|Iso2mesh]] can create a tetrahedral mesh to represent the tissues between these different layers.

{{attachment:callSurf.gif}}

=== T1 MRI ===
Right-click on a T1 MRI available in the database. Typically, this is the default MRI volume displayed in green in the subject folder. Methods available: [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#Brain2mesh|Brain2mesh]], [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#SimNIBS_3:_headreco|SimNIBS3]], [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#SimNIBS_4:_charm|SimNIBS4]], [[http://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#ROAST|ROAST]], [[http://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#FieldTrip|FieldTrip]].

{{attachment:callT1.gif}}

=== T1+T2 MRI ===
Select the T1+T2 volumes, then right-click on any of them. The different files are identified based on the tags "T1" and "T2" the file names (as displayed in the Brainstorm database explorer). If these identification tags are not found in the file names, the default MRI (in green) is used as the T1, the other as the T2. If none of the is the default MRI, the first selected file is used as the T1, the second is used as the T2. Methods  available: [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#Brain2mesh|Brain2mesh]], [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#SimNIBS_3:_headreco|SimNIBS3]], [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#SimNIBS_4:_charm|SimNIBS4]], [[http://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#ROAST|ROAST]].

{{attachment:callT1T2.gif}}

=== Anatomy folder ===
If you right-click on the subject folder > Generate FEM mesh, then Brainstorm offers all the possible options, even the ones that are not applicable to this specific subject.

 * '''Volume ''''''method''': If using a method based on MRI volumes, the T1 and T2 volumes are detected among all the volumes available based on the tags "T1" and "T2" in the file names (make sure only one file as each of these tags), otherwise use only the default MRI (in green) as the T1.
 * '''Surface method''': If using a method based on surfaces, the default surfaces (in green) from three categories as selected: the inner skull, the outer skull and the head surfaces.

{{attachment:callAnat.gif}}

== Iso2mesh ==
[[http://iso2mesh.sourceforge.net|Iso2mesh]] is a Matlab/Octave-based mesh generation and processing toolbox, available as a [[https://Tutorials/Plugins|Brainstorm plugin]].

Brainstorm uses it to generate a FEM tetrahedral mesh from a set of '''nested surfaces''' representing the separation between different tissues of the head. For example, these surfaces can be the ones generated for the computation of a [[https://neuroimage.usc.edu/brainstorm/Tutorials/TutBem#BEM_surfaces|BEM forward model]]. A full example is available in the tutorial [[https://neuroimage.usc.edu/brainstorm/Tutorials/Duneuro#FEM_mesh|Realistic head model: FEM with DUNEuro]].

{{attachment:iso2meshOptions.gif}}

==== Options ====
 * '''MergeMesh''': Simply concatenates the input surfaces without any intersection checks. Default option (faster).
 * '''MergeSurf''': Concatenates and checks for intersections, split intersecting elements. Advanced option (slower).
 * '''Max tetrahedral volume''': Maximum volume of the tetrahedral element in the mesh.
  * From our tests, a DUNEuro FEM head  model with a value of 0.1 achieves similar  results as the OpenMeeg head model computed from the same surfaces. We  have also noticed that the result with v = 0,001 is almost similar to v =  0,01.
  * Increasing the mesh resolution requires more  time to generate the mesh, more time and memory to perform the FEM computation and more storage space in the database.
 * '''Percentage of elements kept''': Parameter between 0-100%, used to keep or not the original input surface nodes.

==== Examples ====
 * FEM mesh with different values of "Max volume": [10, 1, 0.1, 0.01] - Kept ratio=100%.<<BR>><<BR>> {{attachment:iso2meshMaxvol.gif}}
 * FEM meshes with only two compartments: This could be useful for investigating the influence of a specific tissue on  the EEG/MEG forward solution or on the source localization,  or for analyzing SEEG only  within  the brain volume. On the left: head and outer skull; On the right: inner and outer  skull. <<BR>><<BR>> {{attachment:iso2Mesh2layer.gif}}

==== Troubleshooting ====
 * '''Tetget failed''': If intersections are present on the surfaces mesh, the iso2mesh FEM mesh generation fails (tetgen). You may need regenerate new surfaces from the MRI. ''' '''
 * Alternatively: You may try with the MergSurf option, this option can correct the  intersection and create new nodes and elements. However, we do not recommend to  use these models for EEG/MEG forward head computations: this is a  research topic and it's still under investigation by the FEM  communities.

== Brain2mesh ==
[[http://mcx.space/brain2mesh/|Brain2mesh]] is a MATLAB/Octave based 3D mesh generation toolbox dedicated to the creation of high-quality multi-layered brain mesh models. This software is developed by the same team developing Iso2mesh and relies heavily on it. Both are available as a [[https://Tutorials/Plugins|Brainstorm plugins]]. Warning: Requires the '''Imaging Processing Toolbox'''.

Brainstorm runs the '''SPM12 '''segmentation routine on the '''T1 '''or '''T1+T2 MRI''' volumes to obtain a 5-tissue classification (white matter, gray matter, CSF,  skull and skin), which is then passed to Brain2mesh  for 3D meshing. A full example is available in the tutorial [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemTensors#FEM_mesh|FEM tensors estimation]]. This option runs fast, but does not generate good quality cortex surfaces, which are needed for the full cortically-constrained source estimation pipeline in Brainstorm.

At the moment, Brainstorm can only use the default parameters of Brain2mesh. If you need more options to be available from the interface, please contact us on the user forum.

{{attachment:brain2meshCall.gif}}

{{attachment:brain2meshMesh.gif}}

==== Troubleshooting ====
 * '''SPM-related errors''': If you've been trying multiple methods successively, errors mentioning a spm_*.m function could be due to incompatible versions of SPM12 functions in the Matlab path. Brain2mesh, FieldTrip and ROAST all run different versions of SPM12 from the same instance of Matlab. Solution: '''Restart Matlab''' to get a fresh workspace.

== SimNIBS ==
[[https://simnibs.github.io/simnibs|SimNIBS]] software was developed to calculate the electric fields caused by Transcranial Electrical Stimulation (TES) and Transcranial Magnetic Stimulation (TMS). All its software dependencies (CAT12, Netgen, Gmsh, MeshFix) are embedded in the SimNIBS installation, which ensures a high stability and portability. However, it cannot be managed automatically as a plugin by Brainstorm, and needs to be installed manually. See: [[https://simnibs.github.io/simnibs/build/html/installation/simnibs_installer.html|Download and install SimNIBS]]. Two versions of SimNIBS are currently supported, that include different segmentation pipelines: SimNIBS 3.x (headreco) and SimNIBS 4.x (charm).

=== SimNIBS 3: headreco ===
SimNIBS 3.x includes the pipeline  [[https://simnibs.github.io/simnibs/build/html/documentation/command_line/headreco.html|headreco]] to process '''T1''' or '''T1+T2 MRI''' volumes (T1 is required, [[https://simnibs.github.io/simnibs/build/html/tutorial/head_meshing.html|T2 is recommended]]) and generate a high-quality tetrahedral FEM mesh. It calls internally [[https://neuroimage.usc.edu/brainstorm/Tutorials/SegCAT12|CAT12]] for tissue segmentation (white matter, gray matter, CSF, skull and scalp), and therefore gives us access to high-quality cortex surfaces and surface-based atlases. The tetrahedral mesh generation is done with Gmsh, Netgen  and MeshFix. Depending on your computer performances, this process will take between 2 to 5 hours.

{{attachment:simnibs.gif}}

{{attachment:simnibs2.gif}}

{{attachment:simnibs3.png}}

==== Options ====
 * '''Vertex density''': Number of node per mm2 of the surface mesh.
 * '''Number of vertices''': This is not an input parameter of SimNIBS, but a parameter to control how much to downsample the cortex surface generated by CAT12 when importing it into the Brainstorm database. See the [[https://neuroimage.usc.edu/brainstorm/Tutorials/ImportAnatomy#Import_the_anatomy|introduction tutorials]].

=== SimNIBS 4: charm ===
SimNIBS 4.x includes the pipeline [[https://simnibs.github.io/simnibs/build/html/tutorial/head_meshing.html#head-modeling-tutorial|charm]] to process '''T1''' or '''T1+T2 MRI''' volumes (T1 is required, [[https://simnibs.github.io/simnibs/build/html/tutorial/head_meshing.html|T2 is recommended]]). This pipeline generates the highest-quality tetrahedral FEM mesh we can get from Brainstorm. It creates segmentations and meshes with more tissues than SimNIBS3/headreco: white matter, gray matter, CSF, compact bone, spongy bone, scalp, eyes, blood and muscle. It also creates high-resolution cortex surfaces registered with the FSAverage template, but it does not generate the full CAT12 output folder anymore. For surface and volume-based atlases, it might be necessary to execute CAT12 from Brainstorm on top of SimNIBS.

Given  the high quality of its outputs, SimNIBS/charm is  the recommended method for FEM mesh generation in Brainstorm. A full  example is available in the tutorial: [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMedianNerveCharm#FEM_mesh_with_SimNIBS|FEM median nerve example]].

{{attachment:charm1.gif}}

{{attachment:charm2.png}}

==== Options ====
 * '''Number of vertices''': This is not an input parameter of SimNIBS,  but a parameter to control how much to downsample the cortex surface  generated by CHARM when importing it into the Brainstorm database. See  the [[https://neuroimage.usc.edu/brainstorm/Tutorials/ImportAnatomy#Import_the_anatomy|introduction tutorials]].

==== Troubleshooting ====
 * SimNIBS help: https://simnibs.github.io/simnibs/build/html/installation/throubleshooting.html
 * Forum: [[https://neuroimage.usc.edu/forums/t/brainstorm-not-recognising-path-or-command-to-simnibs-4-0-0/38963|SimNIBS library problems on Linux]]

== ROAST ==
[[https://www.parralab.org/roast/|ROAST]] is a fully automated, Realistic, vOlumetric Approach to Simulate Transcranial electric stimulation. Open-source and Matlab-based, it is available as a [[https://Tutorials/Plugins|Brainstorm plugin]]. It calls internally SPM8 for tissue segmentation of the  '''T1 '''or '''T1+T2 MRI'''  volumes to obtain a 5-tissue classification (white matter, gray matter,  CSF,  skull and skin). Then it relies mostly on iso2mesh for generating a tetrahedral mesh.

This option runs fast, but does not generate good quality cortex  surfaces, which are needed for the full cortically-constrained source  estimation pipeline in Brainstorm.

{{attachment:roast1.gif}}

{{attachment:roast2.gif}}

==== Troubleshooting ====
 * '''SPM-related errors''':  If you've been trying multiple methods successively, errors mentioning a  spm_*.m function could be due to incompatible versions of SPM12 functions in the Matlab path. Brain2mesh, FieldTrip and ROAST all run different versions of SPM12 from the same instance of Matlab. Solution: '''Restart Matlab''' to get a fresh workspace.

== Fieldtrip ==
[[http://www.fieldtriptoolbox.org/|FieldTrip]] is an open-source Matlab-based toolbox that includes a pipeline dedicated to the  generation of [[http://www.fieldtriptoolbox.org/tutorial/headmodel_eeg_fem/|hexahedral FEM mesh]]. It is available as a [[https://Tutorials/Plugins|Brainstorm plugin]].

Brainstorm calls the function [[https://github.com/fieldtrip/fieldtrip/blob/release/ft_volumesegment.m|ft_volumesegment]] on the '''T1 MRI''' volume to obtain a tissue segmentation with 5 layers (white matter, gray matter,  CSF,  skull and skin), then [[https://github.com/fieldtrip/fieldtrip/blob/release/ft_prepare_mesh.m|ft_prepare_mesh_hexa]] to create a hexahedral mesh.

The mesh generation with the method is simple and fast: it downsamples the tissue classification volume, then converts all the voxels to a hexahedral mesh. The quality of the output is relatively poor: the regular meshing of the voxels makes it inefficient for providing a good representation of the tissues geometry with a limited number of elements.

{{attachment:fieldtrip1.gif}}

{{attachment:fieldtrip2.gif}}

==== Options ====
 * '''Downsample volume before meshing''': When processing the tissue classification volume, reduce the number of voxels along each dimension by this factor.
 * '''Shift nodes to fit geometry''': The option calls the adaptative mesh generation. The process  moves the nodes located on the interface either inward or outward in  order to fit the geometry as explained in the [[http://www.fieldtriptoolbox.org/tutorial/headmodel_eeg_fem/|FieldTrip tutorial]]. Below, the example from the FieldTrip website, left=original, right=shifted.<<BR>><<BR>> {{attachment:nodeShiftFigure.JPG||width="500",height="200"}}

==== Troubleshooting ====
 * '''SPM-related errors''':   If you've been trying multiple methods successively, errors mentioning  a  spm_*.m function could be due to incompatible versions of SPM12  functions in the Matlab path. Brain2mesh, FieldTrip and ROAST all run  different versions of SPM12 from the same instance of Matlab. Solution: '''Restart Matlab''' to get a fresh workspace.

== On the hard drive ==
Right-click on a FEM mesh > File > View file contents:

{{attachment:femContents.gif}}

==== Structure of the FEM mesh files: tess_fem_*.mat ====
 * '''Comment''': String displayed in the database explorer to represent the file.
 * '''Vertices''': [Nvertices x 3], coordinates (x,y,z) of all the nodes of the tetrahedral or hexahedral mesh, in SCS coordinates.
 * '''Elements''':
  * Tetrahedral mesh: [Nelements x 4], list of indices corresponding to the rows of the  Vertices matrix, each set of 4 connected vertices identifying a  tetrahedron of the mesh.
  * Hexahedral mesh: [Nelements x 8], list of indices corresponding to the rows of the  Vertices matrix, each set of 8 connected vertices identifying a  hexahedron of the mesh.
 * '''Tissue''': [Nelements x 1], for each Element, index of the corresponding tissue (e.g. wm=1, gm=2, csf=3, skull=4, scalp=5)
 * '''TissueLabels''': Labels of the tissues, e.g. {'white'  'gray'  'csf'  'skull'  'scalp'}
 * '''Tensors''':  [Nelements x 12] if tensors are computed, otherwise empty. The 12  values are the eigenvalues and eigenvectors interpolated on each element  of the mesh.
 * '''History''': List of operations performed on this file (menu File > View file history).