Integrate the Duneuro FEM computation

tmedani commented 4 years ago

Hey all,

In this thread, we will discuss and finalize the integration of the FEM computation of the forward problem.

-We have finished the compilation of Duneuro on the main platforms: Windows, Linux, and MAC, and we have integrated all in one package.

We have also developed a whole Matlab toolbox, named 'bst-duneuro-toolbox', to test duneuro and to interface it to brainstorm with a minimal change on the main bst code.
We have tested and validated the EEG computation, MEG is in progress, and the other methods will be added later (seeg, ecog).

@ftadel : I checked how bst call openmeeg via [Gain, errMsg] = bst_openmeeg(OPTIONS). then I wrote a similar function for fem :
[Gain, errMsg] = bst_duneuro(OPTIONS) [bst_duneuro.txt]

This function will use the same argument, OPTIONS, and it uses the 'bst-duneuro-toolbox'.

However, some fields are missing in the OPTIONS and we need to add them. For this 'release', the most important is the path to the fem head model.

But there are some other steps that we need to modify, mainly related to the GUI. For now, I identified these functions : -process_headmodel -panel_headmodel -bst_get -panel_duneuro as panel_openmeeg -bst_duneuro as bst_openmeeeg

There are some parameters for the FEM that should be tuned from the GUI panel, and we will set to the default value the others.

Maybe we could discuss these points next meeting.

Kind regards Takfarinas

ftadel commented 4 years ago

I will do everything related with the interface (both the GUI and the collection of the input parameters). Do you need me to do anything at the moment?

tmedani commented 4 years ago

Hi Francois, Thank you for your precious help.

On the pull request, there are the main steps for the integration. It works as it is, but it needs improvement to fit bst code.

There is a long list of options and parameters, I set to the default value most of them, but I think it much better to have an advanced panel.

So for the Duneuro panel, we can do it in a similar way as for "Compute Source" panel. For a simple user, bst will display a basic panel with the basic parameters, the rest set to default. For advanced, bst will give the option to change these values.

I will draw, and share, a scheme that lists most of the parameters and how we should classify them. Most of the parameters are listed on the file configuration file (d4aed062ee910040f49f307c3b109a1ecb01f23a).

==> this google sheet lists most of the parameters. The most important for the GUI and for the new panel are the rows: G, H and I

(The attached text file in my previous comment is outdated, you can find a new version on my previous pull request: external/bst_duneuro/bst_duneuro.m.)

kind regards Takfarinas

ftadel commented 4 years ago

@tmedani Are you expecting me to start working on it now, or is it still a work a progress on your end? I won't have time this week, but maybe I can start reviewing this next week. What is your expected timeline for this PR to be processed?

juangpc commented 4 years ago

Hi. Im not expecting anything just trying to help with things I see while using the platform. maybe if you someday find time to look at this, let me know where i can improve the code . Thanks Francois.

On Tue, Dec 10, 2019 at 5:21 AM Francois notifications@github.com wrote:

Are you expecting me to start working on it now, or is it still a work a progress on your end? I won't have time this week, but maybe I can start reviewing this next week. What is your expected timeline for this PR to be processed?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/brainstorm-tools/brainstorm3/issues/242?email_source=notifications&email_token=ACEKMIDYJQB3NZRCWLJYBBLQX53SVA5CNFSM4JUTEF3KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEGO4SVY#issuecomment-563988823, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACEKMIHTZEPHNVX7YTWF2BTQX53SVANCNFSM4JUTEF3A .

-- Juan

ftadel commented 4 years ago

Hi. Im not expecting anything just trying to help with things I see while using the platform. maybe if you someday find time to look at this, let me know where i can improve the code . Thanks Francois.

Wrong thread? :)

tmedani commented 4 years ago

@tmedani Are you expecting me to start working on it now, or is it still a work a progress on your end? I won't have time this week, but maybe I can start reviewing this next week. What is your expected timeline for this PR to be processed?

@ftadel

Are you expecting me to start working on it now,

No, you can do it when you could. Next week is fine. For the EEG, I think it's all we need, the MEG is in progress.
Later, we need just to adapt it for seeg and ecoeg (I need to check how it works and how bst call these modalities)

ftadel commented 4 years ago

I pushed your modifications: https://github.com/brainstorm-tools/brainstorm3/commit/117647c0cf65e26bd6e7fda7395abf0df08f3da5

There are plenty of things that still need to be done :

What is this option "ICBM-TEMPLATE"? Shouldn't it be only the file five_layer_icbm152.mat that should be added to the ICBM template folder for subjects that use the template, rather than a separate option for subjects that have their own anatomy?
Do you want to keep this option where you can select some specific surfaces in the anatomy folder? This should be added to process_generate_fem. Is this any different from the 'bemsurf' option?
I need to add the automatic install of bst_duneuro in the .brainstorm user folder
Optimization of the display

tmedani commented 4 years ago

I pushed your modifications: 117647c

Super Thank you, this is the first version, and as you can see there are a lot of "TODO" within the code.

What is this option "ICBM-TEMPLATE"? Shouldn't it be only the file five_layer_icbm152.mat that should be added to the ICBM template folder for subjects that use the template, rather than a separate option for subjects that have their own anatomy?

Right, we don't need to put it here, we need to move this function to another place. This is the FEM template, the best place for it is in the cloud and then download it if the user want to use it (too big 62 MB for distribution) We are working to make it in the bst coordinates system ...

Do you want to keep this option where you can select some specific surfaces in the anatomy folder?

I think it could be useful for some users, it's an easy way to mesh any surfaces (from face to tetra) even for no programmers. And from the literature, many authors compare the effect of the mesh resolutions and the considered tissue to compare their results.
Later, I will also add functions that can convert the tetra mesh to hexahedral mesh, not important but it could be useful.

This should be added to process_generate_fem.

Yes, but sometimes the function "Generate FEM" does not appear in some right-click menu

Is this any different from the 'bemsurf' option?

Yes, slightly, the 'bemsurf' option call by default the inner, outer and scalp, and in the case of 4 layers, a new layer is generated (not realistic). With the new function, the user can select any surface mesh within the database.

I need to add the automatic install of bst_duneuro in the .brainstorm user folder

Yes, also, I did not try it, but do you think it's possible to download and install simnibs in a similar way to iso2mesh/roast?

Optimization of the display

Yes, very important, as it's now, for high mesh resolution, bst freezes.

Thank you!

ftadel commented 4 years ago

Right, we don't need to put it here, we need to move this function to another place. This is the FEM template, the best place for it is in the cloud and then download it if the user want to use it (too big 62 MB for distribution). We are working to make it in the bst coordinates system ...

So I will remove it from the code, and wait until you send me a file to distribute? We could add it to the full ICBM152 template, that is not part of the Brainstorm distribution, but available for download when you right-click on a subject anatomy folder > Use template > Download: ICBM152_2019 (and it would become ICBM152_2020)

do you think it's possible to download and install simnibs in a similar way to iso2mesh/roast?

No, I don't think so, the installer installs too many things... But it is fully automatic, easy to download and easy to run. In the FEM tutorial, we will just show people how to install it before running the FEM mesh generation, I don't think it will be a problem.

tmedani commented 4 years ago

Hi, @ftadel

So I will remove it from the code, and wait until you send me a file to distribute? We could add it to the full ICBM152 template, that is not part of the Brainstorm distribution, but available for download when you right-click on a subject anatomy folder > Use template > Download: ICBM152_2019 (and it would become ICBM152_2020)

Here is a link to an ICBM head mesh, (only the top head as on the MRI):

https://www.dropbox.com/transfer/AAAAAFHfAUfbjXU8IzjhsVt05TiiXGjjDdzKiiEWcSY9VCWf6lSyhGk

View of the mesh :

This model is on the bst coordinates system. (it can be also loaded to bst by the right-click on the subject and then import from Matlab.)

It is generated by the default option of headreco using only a T1 of the ICBM MRI. (do you know if there is any T2 of the ICBM?)

@juan do you think it's interesting to add some option of headreco ? like the -v option for the resolution? Do you have other interesting options that we can highlight for the 'advanced' user?

We can also build this full ICBM head if needed (@juangpc / @ftadel should we add it?) It to be regenerated and then apply the change on the CS.

TODO : we need to generate the source space for this (or these) models. @ftadel : we need to test if the mid-layer wm-pial (from freesurfer or other) will fit within the GM tetra mesh.

Also, This model has only the tetra mesh, as discussed before, we can also distribute the outer surfaces, for each layer, for more flexibility for the users. For this purpose, I wrote a function that can extract all the outer surfaces from any tetra mesh. I add it in my local bst version on the right click on the FEM mesh,

So instead to distribute the surface mesh, we can extract them, quickly, from the tetra mesh. I can push this change later.

No, I don't think so, the installer installs too many things... But it is fully automatic, easy to download and easy to run. In the FEM tutorial, we will just show people how to install it before running the FEM mesh generation, I don't think it will be a problem.

Sounds good, we will explain all this in the tutorial.

ftadel commented 4 years ago

We can also build this full ICBM head if needed

Yes, for high-density EEG (with electrodes on the cheeks) it would be better to have a full head volume.

For this purpose, I wrote a function that can extract all the outer surfaces from any tetra mesh.

Done here: https://github.com/brainstorm-tools/brainstorm3/commit/a45b0d4f166aef7f5b6eaa418b48854de7d820b8

There is just one problem to be solved: the order vertices in the faces across the different methods. If we want the .msh meshes and the files obtained from meshing with Iso2mesh, we would need to change the order of one of the two. Right-now: using this menu on SimNIBS files produces surfaces with normals that are pointing inwards (displayed in a darker way in Brainstorm), while Iso2mesh normals that are point outwards.

tmedani commented 4 years ago

Hey,

We can also build this full ICBM head if needed

Yes, for high-density EEG (with electrodes on the cheeks) it would be better to have a full head volume.

Yes, it makes sense, Here a final version of the full head model within the bst coordinates 👍

We need to distribute both models, (the top and the whole head), in the case of simple EEG, (not high density), we do not need the whole head and the FEM computation time will be highly reduced.
Here are some picture of the aligned full head :

The FEM mesh is from Simnibs and the surfaces obtained from BST_SPM canonical surfaces

and the link for the bst data : https://www.dropbox.com/transfer/AAAAALP8tghtVp-p5dBuiv8WTVnWHRk68WXFVu2Kj_-SXA3LdUxQbTg

For this purpose, I wrote a function that can extract all the outer surfaces from any tetra mesh.

Done here: a45b0d4

Super...

There is just one problem to be solved: the order vertices in the faces across the different methods. If we want the .msh meshes and the files obtained from meshing with Iso2mesh, we would need to change the order of one of the two. Right-now: using this menu on SimNIBS files produces surfaces with normals that are pointing inwards (displayed in a darker way in Brainstorm), while Iso2mesh normals that are point outwards.

I will check this when I update my bst local version, I think this could be solved by reorienting the mesh in the case of the inward normals.

ftadel commented 4 years ago

and the link for the bst data

I suggest we do not update the ICBM152 template yet. We won't need this until we have a fully working tutorial and users using the FEM forward models. I guess the computation of this mesh (eg. SimNIBS options) might change a few more times before we have some stable code. Anybody with SimNIBS installed can already generate this model anyway, right?

tmedani commented 4 years ago

I suggest we do not update the ICBM152 template yet. We won't need this until we have a fully working tutorial and users using the FEM forward models. I guess the computation of this mesh (eg. SimNIBS options) might change a few more times before we have some stable code.

Yes, make sens, The EEG part is fully tested on my bst version, and the results are correct. I need to check the new online release of brainstorm.

For the MEG, it's implemented, but the duneuro results are not fully validated. I'm working on it....

Anybody with SimNIBS installed can already generate this model anyway, right? Only for the top part of the head, the full ICBM head model is obtained with another set of MRIs.

SimNibs will be installed and called only if users have their own MRI and want individual head model. Otherwise, the template is sufficient, and with the surface extraction and FEM mesh generation, they can test their scenarios (iso2mesh will be needed).

ftadel commented 4 years ago

Two new options for creating 3D meshes:

Brain2Mesh (which still needs to be fixed...)
FieldTrip (so we have something to debug all the hexahedral pipeline, but I need to finish the display of the hexa meshes)

tmedani commented 4 years ago

Hi Francois,

This is great, I'm just testing the Brain2Mesh but it fails... for now.

Regarding the fieldtrip, I have tested the pipeline also, it needs debugging and reorientation to the bst coordinate system. Also, there are some of the parameters that needs to fixe.

btw, I'm checking the gmsh option and it seems that we can generate hexa mesh. it needs more investigations (http://gmsh.info/doc/texinfo/#Specifying-mesh-element-sizes).

Regarding the display of the hexa, I have already a pseudo-solution, that don't add much change. it based on the conversion of the hexa to tetra and then use the previous functions for displaying.

load('hexa_mesh.mat') % convert hxa to tetramesh % convert the mesh to tetra in order to use plotmesh [tetraElem,tetraNode,tetraLabel]=hex2tet(elements,nodes ,labels,3); % display the mesh figure; plotmesh(tetraNode,[tetraElem tetraLabel],'x>100');

ftadel commented 4 years ago

@tmedani

This is great, I'm just testing the Brain2Mesh but it fails... for now.

I updated brain2mesh to the latest modifications. Delete the .brainstorm/brain2mesh folder and try again.

Regarding the fieldtrip, I have tested the pipeline also, it needs debugging and reorientation to the bst coordinate system. Also, there are some of the parameters that needs to fixe.

I fixed the coordinates and labels: https://github.com/brainstorm-tools/brainstorm3/commit/1f34ecf801c88a593f09d1a6807972f79c5b3835 Maybe there is an additional 0.5 voxel shift that needs to be fixed... I'm not sure, I'm getting so confused after spending the entire day on transformations... :)

Which additional parameters do you want to fix?

tmedani commented 4 years ago

This is great, I'm just testing the Brain2Mesh but it fails... for now.

I updated brain2mesh to the latest modifications. Delete the .brainstorm/brain2mesh folder and try again.

Thanks, I will check the updated version of Brain2Mesh asap.

I'm focusing on the DTI process, and I wan to finish it by the end of the next week.

Regarding the field trip process,

Which additional parameters do you want to fix?

I think only the Hexa mesh is relevant from their process. I have checked the 'tetrahedral' mesh but it fails, the quality of the mesh is not good (at least on my examples).

I have also found a solution to use headreco for hexahedral mesh. I will push my updates on the process_generate_fem asap.

tmedani commented 4 years ago

This is great, I'm just testing the Brain2Mesh but it fails... for now.

I updated brain2mesh to the latest modifications. Delete the .brainstorm/brain2mesh folder and try again.

Thanks, I will check the updated version of Brain2Mesh asap.

Hey Francois, I was able to test Brain2Mesh, I did not try to solve the problems right now Here are my feedbacks :

There is no option for the choice of the mesh resolution
There is no option to select the desired tissus.
The Tissus labels are not defined (error below)

** Error: Line 840: Undefined function or variable 'TissueLabels'.

==> from the help of the function it seems to be % 0-Air/background, 1-Scalp, 2-Skull, 3-CSF, 4-GM, 5-WM, 6-air pockets

I was able to solve quickly by replacing line 840

Line 840: ~isempty(TissueLabels) by if ~exist('TissueLabels','var')

The mesh is loaded and it looks great

However, there are 7 labels

Data exported as "brain2mesh"

brain2mesh

brain2mesh =

struct with fields:

     Comment: 'FEM 265211V (brain2mesh, 3 layers)'
    Vertices: [265211×3 double]
    Elements: [1606009×4 double]
      Tissue: [1606009×1 double]
TissueLabels: {'-1'  '0'  '1'  '2'  '3'  '4'  '5'}
     History: {1×3 cell}

We need to remove the -1 and 0 from the data, and reorder from inner to outer to keep the same logic previously used in our mesh.

Error: Line 840: Undefined function or variable 'TissueLabels'. Call stack: >process_generate_fem.m>Compute at 840 >process_generate_fem.m>ComputeInteractive at 1063 >process_generate_fem.m at 34 >tree_callbacks.m>@(h,ev)process_generate_fem('ComputeInteractive',iSubject,iAnatomy) at 1025

Error: The FEM mesh generation failed. Check the Matlab command window for additional information. **

ftadel commented 4 years ago

There is no option for the choice of the mesh resolution

Which of the brain2mesh options would you like to have access to from Brainstorm? https://github.com/fangq/brain2mesh/blob/master/brain2mesh.m#L34

There is no option to select the desired tissus.

I replaced the option to select the tissues with a merging option after computation: https://github.com/brainstorm-tools/brainstorm3/commit/26cb78d9ecb45ae361defdc3f20b0ed7dce8cde2

The Tissus labels are not defined (error below) We need to remove the -1 and 0 from the data, and reorder from inner to outer to keep the same logic previously used in our mesh.

Done in: https://github.com/brainstorm-tools/brainstorm3/commit/26cb78d9ecb45ae361defdc3f20b0ed7dce8cde2#diff-7c3a114ee98415cadd8af55c3c3b262eR534

tmedani commented 4 years ago

Which of the brain2mesh options would you like to have access to from Brainstorm? https://github.com/fangq/brain2mesh/blob/master/brain2mesh.m#L34

Hey @ftadel , sorry, I missed this question! I will have a look at it asap.

mantonakakis commented 4 years ago

Hey Takfa et al.,

Sorry that I just come into this discussion. I was just discovered and reading your discussion here and I have to say that for https://github.com/brainstorm-tools/brainstorm3/issues/242#issuecomment-588429134 you cannot just convert a hex mesh to a tet mesh because tools for generating tet mesh need closed volumes. However, this is not the case for CSF because during the MRI scanning, the subject is in lying position and the cortex (GM+WM) touches the inner skull (see the model above in the occipital areas, https://user-images.githubusercontent.com/37831900/74871962-3790b000-5311-11ea-9b93-3842712708bd.png). Therefore, CSF cannot be a closed surface. There are tools that artificially add CSF between brain and skull in order to resolve this issue which is not absolutely wrong but it contains assumptions in order to make tet mesh usable. This is now why we need hex meshes which can model such a complex and realistic situations. but those have also their own issues as we know.

Best regards, Marios

tmedani commented 4 years ago

Hey @mantonakakis

Thank you for your feedback on this discussion.

Sorry that I just come into this discussion. I was just discovered and reading your discussion here and I have to say that for #242 (comment) you cannot just convert a hex mesh to a tet mesh because tools for generating tet mesh need closed volumes.

We have indeed functions that convert tetra to hexa and vice-versa, in the #242 (comment) it's mainly related to the visualisation process, so in order to keep the same functions that display tetra mesh, we convert the hexa on the fly and then display it using the same function as tetra.

I agree with you that the tools that generate tetra need closes surfaces, however, I think from the computation side, there is no effect either on the closed or not closed surface (and either if it's tetra or hexa ... do you agree ?).

However, this is not the case for CSF because during the MRI scanning, the subject is in lying position and the cortex (GM+WM) touches the inner skull (see the model above in the occipital areas, https://user-images.githubusercontent.com/37831900/74871962-3790b000-5311-11ea-9b93-3842712708bd.png). Therefore, CSF cannot be a closed surface. There are tools that artificially add CSF between brain and skull in order to resolve this issue which is not absolutely wrong but it contains assumptions in order to make tet mesh usable.

Totally agree, it's what SimNibs uses and we have already integrated this method.

In brainstorm we have integrated all the options that the users may need, they can use all these options. So we have added these functions that convert the mesh from tetra-hexa in order to test and check the difference between models/ computation time/results... it's up to the users to choose his methods and we will add all these comments/warnings on the tutorials.

Thanks again for your feedback.

Looking forward to your method for head model generation :) We can discuss it and see how we can integrate it to Brainstorm.

Best,

mantonakakis commented 4 years ago

Hey @tmedani

with regard to "I agree with you that the tools that generate tetra need closes surfaces, however, I think from the computation side, there is no effect either on the closed or not closed surface (and either if it's tetra or hexa ... do you agree ?)."

From the computational point of view, I think, nowadays, if there are not sophisticated tissues for modeling e.g. blood vessels, tools can provide a reasonably good solution depending on parameters like the resolution of the mesh and the number of compartments. It depends on what on the interest of the user.

So to deal with sophisticated segmentation pipelines (like discussed here), research has been done making all of us understand the complexity of the head. However, to deal with the corresponding conductivities of the modeled tissues, research is still necessary with simplified source analysis scenarios in order to move one step forward with regard to their subject-specific assignment.

tmedani commented 4 years ago

Hello,

I'm going to close this issue for now.

we may open it or refer it in the next steps.

Thanks for your contribution.

A+

brainstorm-tools / brainstorm3

Integrate the Duneuro FEM computation #242