How Do You Analyze SimNIBS Mesh Files in MATLAB? | SimNIBS Tutorial II, Computational Modeling in NIBS 2020

TL;DR

Analyze a SimNIBS mesh in MATLAB by adding the supplied MATLAB functions folder to your path and opening the mesh with mesh_load_gmsh4. The returned structure contains Cartesian node coordinates, three-node surface triangles, four-node volume tetrahedra, tissue-region labels, node-based voltage, and element-based electric fields. You can also extract region 2 gray-matter tetrahedra and save the result, so read on for the structure and workflow.

Transcript

after we calculate your electric fields in Sim nibs you get the mesh files from sim nibs I'm gonna explain some of the things that you can do for post-processing in MATLAB keep in mind that you can do all of these things in Python as well if you're more interested in Python or for this example I have run a like a quick random analysis of the TMS on... Read More

Key Insights

• SimNIBS includes MATLAB and Python interface functions for post-processing mesh files. Adding the installed SimNIBS MATLAB folder to the MATLAB path makes those functions readily available to analysis scripts.
• The mesh_load_gmsh4 function opens a SimNIBS mesh file in MATLAB. It receives the path to the mesh and returns a structure containing nodes, surface triangles, volume tetrahedra, region assignments, and available simulation data.
• The nodes matrix stores one mesh point per row using Cartesian X, Y, and Z coordinates. These indexed coordinates provide the geometric foundation from which every triangle and tetrahedron in the head model is constructed.
• A surface triangle is defined by the indices of three connected nodes. The triangle-region array then identifies the tissue boundary associated with each triangle, allowing surface elements from different modeled tissues to be distinguished during post-processing.
• A volume tetrahedron is defined by the indices of four connected nodes. Tetrahedron-region values associate each volume element with a tissue type, making it possible to select a specific tissue volume such as gray matter.
• Node data assigns a simulated value directly to every mesh node. In the demonstrated mesh, voltage is stored this way, and its data vector corresponds to the sequence of points represented in the nodes matrix.
• Element data assigns values to the centers of triangles and tetrahedra. Electric-field vectors are stored as X, Y, and Z components, while electric-field magnitude is stored as one scalar value for each applicable element.
• The mesh_extract_regions function creates a smaller mesh containing selected regions and element types. Specifying tetrahedra and region 2 extracts the demonstrated gray-matter volume, which can then be written with mesh_save_gmsh4 for inspection or further analysis.

Questions & Answers

Q: How do you open a SimNIBS mesh file in MATLAB?

Add the MATLAB functions folder from the SimNIBS installation to the MATLAB path. Call mesh_load_gmsh4 with the path to the mesh file and assign its output to a variable such as mesh. The resulting structure contains the geometry, region labels, and simulation data.

Q: What information does the nodes matrix contain?

Each row of the nodes matrix represents one mesh point. Its three columns store that node's Cartesian X, Y, and Z coordinates. Triangle and tetrahedron arrays reference these rows by index.

Q: How are surface triangles represented in a SimNIBS MATLAB mesh?

Each triangle is represented by three node indices. Connecting the corresponding Cartesian points forms one surface triangle. The triangle-regions array identifies the tissue surface or boundary associated with each triangle.

Q: How are volume tetrahedra represented in a SimNIBS mesh?

Each tetrahedron is represented by four node indices that point to coordinates in the nodes matrix. Connecting those four points creates a volume element. Its tetrahedron-region value identifies the associated tissue type.

Q: What is the difference between node data and element data in SimNIBS?

Node data assigns a simulated value directly to each mesh node; voltage is stored this way in the demonstrated mesh. Element data assigns values to the centers of triangles or tetrahedra. The electric field and its magnitude are stored as element data.

Q: How are electric-field vectors stored in the mesh structure?

Electric-field vectors are stored as element data for triangles and tetrahedra. Each vector has X, Y, and Z components at the center of the relevant element. Triangle data applies to surface-element centers, while tetrahedron data applies to volume-element centers.

Q: How is electric-field magnitude stored in a SimNIBS mesh?

Electric-field magnitude is stored as scalar element data. It provides one magnitude value for each applicable triangle or tetrahedron, rather than the three directional components used for an electric-field vector.

Q: How do you extract and save gray-matter tetrahedra from a SimNIBS mesh?

Use mesh_extract_regions with the loaded mesh, select tetrahedra as the element type, and specify region 2, which the tutorial identifies as gray-matter volume. The resulting smaller mesh contains the selected tissue region and can be written to a mesh file with mesh_save_gmsh4.

Summary & Key Takeaways

• SimNIBS provides MATLAB and Python functions for post-processing simulated electric fields. In MATLAB, users should add the SimNIBS MATLAB folder to their path, then call mesh_load_gmsh4 with the mesh file path. The returned structure contains the geometry, region labels, and simulation results required for custom analysis scripts.

• A mesh represents tissue surfaces with triangles formed from three indexed nodes and tissue volumes with tetrahedra formed from four indexed nodes. The nodes matrix stores Cartesian X, Y, and Z coordinates. Triangle and tetrahedron region arrays associate individual elements with particular boundaries or tissue volumes, including gray matter and white matter.

• Simulation results are divided into node data and element data. Voltage is stored at nodes, while electric fields and their magnitudes are stored at the centers of triangles or tetrahedra. Users can isolate gray-matter tetrahedra with mesh_extract_regions and write the smaller result to a mesh file using mesh_save_gmsh4.