Updated for release version: 1.0.8-alpha
This tutorial provides step-by-step instructions on how to transfer data from a volume to a surface mesh.
Introduction
Often it is useful to be able to transfer data from one geometric representation to another. This is not always a trivial procedure, as different spatial representations do not always have a straightforward correspondence. Additionally, the desired transfer function may depend upon the nature of the data. This tutorial describes how to use modelGUI to transfer data from a 3D volume representation to a surface mesh representation. Two methods are available: (1) enclosing voxel, which is simply an assignment to a vertex of the value of the voxel enclosing it, as is typically preferable for discrete data such as ROI indices; and (2) gaussian sampling, which is based upon a gaussian field centered on a vertex, which is biased in the direction of the surface vs. its normal.
For this tutorial you will need the following data:
Surface: surf_reg_model.tri
Volume: aal.nii.gz
Loading the data
Load the surface and its data using the File I/O panel. See also the Working with meshes tutorial.
Load the volume data using the Volume Panel. See also the Working with volumes tutorial.
For the present tutorial, the data we will be using are: (1) the Civet template surface ([http://www.bic.mni.mcgill.ca/~alan/index.html Alan Evans [1], Montreal Neurological Institute]), and (2) the AAL volumetric template, obtained from the MRIcron program [2]. When loaded they should like something like (assuming you have created a horizontal section and corresponding 2D window):
To view the volume as a section, change its "RenderMode" attribute to "As sections":
Transferring data
Open the "Mesh Panel" and select your surface from the "Shapes" section. Next expand the "Volume to Mesh" section and select the AAL volume as the source volume. Next we want to specify the transfer operation. Since our data are discrete ROI indices, we want to use the "enclosing voxel" method in our case. For completeness, however, I will first briefly describe the Gaussian method, which is preferable for continuous data.
Gaussian
The Gaussian transfer method uses a biased gaussian field, which allows a vertex to obtain values preferentially along its normal or transverse axes. This is typically preferable to an isotropic gaussian, since the direction of a surface often carries information about the underlying entity. In the case of a cortical surface, since the cortical sheet has a definite thickness, transferring volumetric data should be done in a way that seeks values along its normal, and not so far along its surface (since other vertices will capture that information). This general scheme is illustrated in the figure below, taken from [3], for the inverse operation (surface -> volume), but the same considerations hold in this case. If an isotropic field is required, the parameters specifying normal and transverse projections can be set to equal values.
Enclosing voxel
Select "Map From Volume (Enclosing voxel)" as the Operation. This will show three parameters to specify; these should be set to something like:
- grid_channel: "default"
- no_value: "-1" (or other appropriate value to assign vertices with no assigned value)
- target_column: "aal_from_volume" (or other name of your choosing)
Now click "Apply". The values should be transferred.
Viewing the results
From the "Shapes Panel", select your surface mesh and then expand the "Data Display" section. Select "aal_from_volume" from the list of columns, and "Random 600" as the discrete colour map. Next click "Apply". Your transferred ROI data will appear on the surface:
To optimize the view in 2D, you can change the global alpha of your volume in the "Intensity" section of the "Volume Panel" to 0.5 or so. You may possibly need to regenerate the 2D window to see the ROI colours, by right-clicking and selecting "Regen window" (mgui still has a few bugs to sort out).
Saving the results
To save your new surface data, open the "File Panel" and select "Minc surface data" as the Output file type. Browse to the directory you want to write the data to using the "Browse" button. Finally, click "Options", select your mesh, check the "Write" column beside your new column and perhaps change the number format to "0" if you want to write the result as integer values. Click "OK" and then "Write Data". Your data will be written as a text file with one vertex value per line.
Making local fixes
Often it may be necessary to make local fixes to your surface data, particular in the case of cortical surfaces, where the transfer of volume parcellations typically creates "islands" and does not properly respect sulcal boundaries. This section explains how to make small modifications to your data in mgui. Firstly, identify a problem area and zoom in on it in the 3D window. Visualize the triangulation by setting the surface's "ShowEdges" attribute to true (right-click, "Edit attributes..", or use the Tree Panel). You can center the rotation on individual vertices using the right-click context menu ("Center on node"). To identify the value of particular vertices, open the "Queries Panel", select "Shapes.Default", and click "Start". Now, clicking on individual vertices will bring up a table in the "Results" section; the "aal_from_volume" value for this vertex will appear at the bottom of the list (as a side note, you can assign names to these ROI indices using a Name Map). For the image below, the selected vertex (red sphere) has a value of 49:
Stop querying by clicking the "Stop" button. Now we want to select a set of "island" vertices within the "49" region and change their values to 49. From the "Tools Panel", expand the "Edit 3D" section and click the "Select nodes with polygon" button.
Now we want to define a closed polygon on the mesh by clicking individual vertices. It is important that this boundary be closed (i.e., no internal vertices have neighbours outside it), because our next step involves a flood fill. The selection below (look hard) is closed:
Once you have an enclosed region, double click any vertex in the interior. This will add all internal vertices to the selection. If you accidentally select all mesh vertices, you can clear the selection using the context menu ("Clear selection"), and try again. If it works it should look like this (note you may need to adjust the vertex size by setting the surface's "VertexScale" attribute to something like "0.5"):
Now we want to change the value of "aal_from_volume" for these selected vertices. In the "Shapes Panel", select the surface and expand the "Data Operations" section. Here, check "Only selected nodes" and select "aal_from_volume" as the target column. Now click "Define..". This will bring up a dialog that allows you to specify a mathematical expression. This expression can be elaborate if necessary, and involve other columns, if any existed. For our present purposes the expression is rather simple: "49".
Click "OK" and then "Apply". The values should update and the surface will look like this:
