Editing BEM surfaces in Blender¶
Sometimes when creating a BEM model the surfaces need manual correction because of a series of problems that can arise (e.g. intersection between surfaces). Here, we will see how this can be achieved by exporting the surfaces to the 3D modeling program Blender, editing them, and re-importing them.
This tutorial is based on https://github.com/ezemikulan/blender_freesurfer by Ezequiel Mikulan.
# Authors: Marijn van Vliet <firstname.lastname@example.org> # Ezequiel Mikulan <email@example.com> # Manorama Kadwani <firstname.lastname@example.org> # # License: BSD-3-Clause
In this tutorial, we are working with the MNE-Sample set, for which the surfaces have no issues. To demonstrate how to fix problematic surfaces, we are going to manually place one of the inner-skull vertices outside the outer-skill mesh.
We then convert the surfaces to .obj files and create a new
conv inside the FreeSurfer subject folder to keep them in.
# Put the converted surfaces in a separate 'conv' folder conv_dir = op.join(subjects_dir, 'sample', 'conv') os.makedirs(conv_dir, exist_ok=True) # Load the inner skull surface and create a problem # The metadata is empty in this example. In real study, we want to write the # original metadata to the fixed surface file. Set read_metadata=True to do so. coords, faces = mne.read_surface(op.join(bem_dir, 'inner_skull.surf')) coords *= 1.1 # Move the first vertex outside the skull # Write the inner skull surface as an .obj file that can be imported by # Blender. mne.write_surface(op.join(conv_dir, 'inner_skull.obj'), coords, faces, overwrite=True) # Also convert the outer skull surface. coords, faces = mne.read_surface(op.join(bem_dir, 'outer_skull.surf')) mne.write_surface(op.join(conv_dir, 'outer_skull.obj'), coords, faces, overwrite=True)
Overwriting existing file. Overwriting existing file.
We can now open Blender and import the surfaces. Go to File > Import >
Wavefront (.obj). Navigate to the
conv folder and select the file you
want to import. Make sure to select the Keep Vert Order option. You can
also select the Y Forward option to load the axes in the correct direction
For convenience, you can save these settings by pressing the
next to Operator Presets.
Repeat the procedure for all surfaces you want to import (e.g. inner_skull and outer_skull).
You can now edit the surfaces any way you like. See the Beginner Blender Tutorial Series to learn how to use Blender. Specifically, part 2 will teach you how to use the basic editing tools you need to fix the surface.
In Blender, you can export a surface as an .obj file by selecting it and go to File > Export > Wavefront (.obj). You need to again select the Y Forward option and check the Keep Vertex Order box.
Each surface needs to be exported as a separate file. We recommend saving
them in the
conv folder and ending the file name with
although this is not strictly necessary.
In order to be able to run this tutorial script top to bottom, we here simulate the edits you did manually in Blender using Python code:
Overwriting existing file.
Back in Python, you can read the fixed .obj files and save them as
FreeSurfer .surf files. For the
mne.make_bem_model() function to find
them, they need to be saved using their original names in the
bem/inner_skull.surf. Be sure to first backup the original
surfaces in case you make a mistake!
# Read the fixed surface coords, faces = mne.read_surface(op.join(conv_dir, 'inner_skull_fixed.obj')) # Backup the original surface shutil.copy(op.join(bem_dir, 'inner_skull.surf'), op.join(bem_dir, 'inner_skull_orig.surf')) # Overwrite the original surface with the fixed version # In real study you should provide the correct metadata using ``volume_info=`` # This could be accomplished for example with: # # _, _, vol_info = mne.read_surface(op.join(bem_dir, 'inner_skull.surf'), # read_metadata=True) # mne.write_surface(op.join(bem_dir, 'inner_skull.surf'), coords, faces, # volume_info=vol_info, overwrite=True)
Sometimes the head surfaces are faulty and require manual editing. We use
mne.write_head_bem() to convert the fixed surfaces to
For EEG forward modeling, it is possible that
outer_skin.surf would be
manually edited. In that case, remember to save the fixed version of
-head.fif from the edited surface file for coregistration.
# Load the fixed surface coords, faces = mne.read_surface(op.join(bem_dir, 'outer_skin.surf')) # Make sure we are in the correct directory head_dir = op.dirname(bem_dir) # Remember to backup the original head file in advance! # Overwrite the original head file # # mne.write_head_bem(op.join(head_dir, 'sample-head.fif'), coords, faces, # overwrite=True)
# If ``-head-dense.fif`` does not exist, you need to run # ``mne make_scalp_surfaces`` first. #  because a list of surfaces is returned surf = mne.read_bem_surfaces(op.join(head_dir, 'sample-head.fif')) # For consistency only coords = surf['rr'] faces = surf['tris'] # Write the head as an .obj file for editing mne.write_surface(op.join(conv_dir, 'sample-head.obj'), coords, faces, overwrite=True) # Usually here you would go and edit your meshes. # # Here we just use the same surface as if it were fixed # Read in the .obj file coords, faces = mne.read_surface(op.join(conv_dir, 'sample-head.obj')) # Remember to backup the original head file in advance! # Overwrite the original head file # # mne.write_head_bem(op.join(head_dir, 'sample-head.fif'), coords, faces, # overwrite=True)
1 BEM surfaces found Reading a surface... [done] 1 BEM surfaces read Overwriting existing file.
A particularly useful operation is the Shrinkwrap functionality, that will restrict one surface inside another surface (for example the Skull inside the Outer Skin). Here is how to use it:
(1) Select the surface that is creating the problem. (2) In Edit Mode,
press C to use the circle selection tool to select the vertices that
are outside. (3-5) In the Object Data Properties tab use the
to add a Vertex Group and click Assign to assign the current selection to
the group. (6-8) In the Modifiers tab go to Add Modifier add a
Shrinkwrap modifier and set it to snap Inside with the outer surface as
the Target and the Group that you created before as the Vertex Group.
You can then use the Offset parameter to adjust the distance. (9) In
Object Mode click on the down-pointing arrow of the Shrinkwrap modifier
and click on Apply.
That’s it! You are ready to continue with your analysis pipeline (e.g.
What if you still get an error?¶
When editing BEM surfaces/meshes in Blender, make sure to use tools that do not change the number or order of vertices, or the geometry of triangular faces. For example, avoid the extrusion tool, because it duplicates the extruded vertices.
Below are some examples of errors you might encounter when running the
mne.make_bem_model function, and the likely causes of those errors.
Cannot decimate to requested ico grade
This error is caused by having too few or too many vertices. The full error is something like:
RuntimeError: Cannot decimate to requested ico grade 4. The provided BEM surface has 20516 triangles, which cannot be isomorphic with a subdivided icosahedron. Consider manually decimating the surface to a suitable density and then use ico=None in make_bem_model.
Surface inner skull has topological defects
This error can occur when trying to match the original number of triangles by removing vertices. The full error looks like:
RuntimeError: Surface inner skull has topological defects: 12 / 20484 vertices have fewer than three neighboring triangles [733, 1014, 2068, 7732, 8435, 8489, 10181, 11120, 11121, 11122, 11304, 11788]
Surface inner skull is not complete
This error (like the previous error) reflects a problem with the surface topology (i.e., the expected pattern of vertices/edges/faces is disrupted).
RuntimeError: Surface inner skull is not complete (sum of solid angles yielded 0.999668, should be 1.)
Triangle ordering is wrong
This error reflects a mismatch between how the surface is represented in memory (the order of the vertex/face definitions) and what is expected by MNE-Python. The full error is:
RuntimeError: The source surface has a matching number of triangles but ordering is wrong
For any of these errors, it is usually easiest to start over with the unedited BEM surface and try again, making sure to only move vertices and faces without adding or deleting any. For example, select a circle of vertices, then press G to drag them to the desired location. Smoothing a group of selected vertices in Blender (by right-clicking and selecting “Smooth Vertices”) can also be helpful.
Total running time of the script: ( 0 minutes 14.112 seconds)
Estimated memory usage: 155 MB