Updated for release version: 1.0.10-alpha
Introduction
In ModelGUI, the term "mesh" is synonymous with "surface". In more formal terminology, a surface mesh is referred to as a 2-manifold, meaning that it is a two-dimensional manifold in R3 space. A surface mesh is represented in memory as a set of 3D vertices organized into triangular faces (see data format below). This representation is a very flexible way of modelling complex geometries.
For this tutorial, you will need to download and unzip the data set located here.
Loading a mesh
First we want to load and view the surface mesh. The tutorial data includes a surface generated by averaging the cortical surfaces of a large cohort of normal brains [1]; this mesh is stored as a ASCII-based "tri" file [link to this]. To load the surface, show the File Panel, and in the Input section, select the file type "Tri surfaces (*.tri)". Click "Browse.." and navigate to wherever you downloaded the tutorial data. Select the file "surf_reg_model.tri", click "Open" and then "Read Data". The surface will be loaded. To view it, we need a 3D window; right click on the empty space beneath "Tab 1" and select "Add window > Graphic 3D". Right-click again and set the source to "Default Model". Zoom out (Right-drag or Ctrl-Left-drag) to see the whole surface. If your screen looks as below: step 1 complete :)
Discrete mesh data
Next we want to view a parcellation of the cortex; i.e., a set of pre-defined regions-of-interest (ROIs) defined by anatomical and functional criteria. For this purpose, we'll use the Automated Anatomical Labeling (AAL) atlas [2]. To load this atlas onto our surface, select the file type "Shape data files (*.txt *.sdata)", and click "Browse..". Select the file "aal_converted_both.txt" and click "Open". Now click "Options.." to define the target shape for the data. The dialog box that appears looks like this:
The correct shape is already chosen; we only need to make one small change: change the Format from Double to Integer. Now click OK and "Read Data".
Applying a colour and name map to discrete vertex data
The data we just loaded is a list of integers, each corresponding to a vertex in the surface mesh. These integers are typically indexes into a "name map", in which an actual name is assigned to each ROI. We can load these name assignments, and their associated colours, by selecting the file type "Discrete colour maps (*.cmap)", selecting the file "aal_78.cmap", and clicking "Read Data". To view this map, display the Maps Panel and expand the Discrete Colour section. Select the aal_78 map, which should look like this:
Next we need to assign these maps to the AAL atlas we loaded. Show the Shapes Panel, expand the Shapes section, click "Selected shape", and select "Default Model.surf_reg_model". Next, expand the Name Maps section, and assign the name map "aal_78" to the "aal_converted_both" column. This assigns the vertex integer values to actual ROI names. Finally, expand the Data Display section and assign the colour map "aal_78" to the "aal_converted_both" column. To display the results, click "Apply". The ROIs will be coloured accordingly:
Continuous mesh data
We can load continuous vertex data in a similar way as above. In the File Panel, select "Shape data files" as the file type and now load "mean_ct.txt" as a Double data format (this is mean cortical thickness computed from a subset of the ADNI Alzheimer's disease dataset [3]). Now there will be a new column available in the Data Display section of the Shapes Panel. Select this column and now pick a continuous colour map (these are discernible from the discrete colour maps by their associated icons). Try, for instance "matlab_jet2". A colour bar should appear at the bottom of the section. Click "Reset", which sets the colour map limits to data limits, and "Apply" to see the data plotted on the surface. The resulting colours are mostly blue and green; i.e., the bottom end of the colour map. To get a better idea of why this is, expand the Histogram section, check the "Use current data" box, click "Reset", and finally click "Apply". A histogram of the data will appear, coloured by the colour map you chose. As you can see, there is a long, narrow tail at the right end of the distribution, which is why we aren't seeing much of those colours. To fix this, we can set a narrower range: in the Data Display section, enter "2" for Min and "4" for Max, and press "Apply" again. The new colour mapping will appear in the histogram window as a red line. The result should look like:
Shape queries
Shape queries allow the user to interact with shapes, in particular to extract specific information about them, or about individual vertices. To demonstrate, open the Queries Panel and expand both sections by right-clicking Queries and selecting "Expand all". Select the "Shapes.Default" query (currently the only option available) and click "Start". Let's say we are interested in the left frontal pole. Rotate the surface in 3D (right-drag) and zoom in on that region, as shown below, and click in the area of interest. The selected vertex will appear as a red sphere in the 3D window, and the Results section will fill with the results of your query, as below:
The first four rows of the query return general information about the shape itself; the last four rows contain information about the specific vertex you selected, including its index in the mesh, its 3D location, and the values of the two data fields you loaded earlier. Notice that, because you set a name map for the "aal_converted_both" column, the name corresponding to the vertex is also displayed (in this case ITG.L, the left inferotemporal gyrus).
Click "Stop" when you are done querying.