Updated for version mgui-1.1.0-beta
This tutorial guides you through a number of ways in which you can use ModelGUI to interact with 2D and 3D shapes.
Introduction
In mgui, a shape is an entity that forms the basis of all physical models. A shape is minimally specified by a set of two- or three-dimensional Cartesian coordinates, or vertices, but the relationship and meaning of these vertices depends upon the nature of the shape in question, and can range from a single point to an entire geometrical system. Mgui also provides the capability of associating numeric data to vertices, which allows a great deal of flexibility with respect to the kinds of physical systems it can model. Future implementations will also provide support for dynamic shapes, with an additional temporal dimension that allows its geometry and/or associated data to change over time.
Mgui works in both two and three dimensions, and most of its shape types are representable in both. A 2D shape, for instance, is always associated with a 3D plane, and thus can also be represented in 3D. Likewise, a 3D shape can be cut by, or projected onto, a plane, and thus be represented in 2D. This functionality is built into the mgui framework.
Mgui currently provides support for a variety of shape types:
| Shape | Geometry | Space | Description |
|---|---|---|---|
| Polygon | Linked list of vertices | 2D/3D | A polygon represents a finite curve, and can be open (polyline) or closed (polygon). |
| Mesh | Vertices forming triangular faces | 3D | A mesh is a 2-manifold, or a tesselated surface, and can be open or closed. |
| Box | Vertex and three edge vectors | 3D | A box is a six-sided polyhedron which can have any orientation, defined by three vectors which are typically (but not necessarily) orthogonal. |
| Vector | Point and vector | 2D/3D | A vector, as an mgui shape, is defined by a start point and a vector defining its direction and magnitude. Care should be taken not to confuse a "shape vector" with a mathematical vector, which has no start point. |
| Grid | Box and grid dimensions | 3D | A grid is a box or rectangle which is internally divided into a fixed number of grid points, evenly-spaced in each dimension. |
| Point Set | Set of vertices | 2D/3D | A set of points. |
[TODO: screen shots here]
Tutorial Data
To follow this tutorial, you'll need to download and unzip the following file:
[link to download file]
Shape Loaders
Shapes are loaded into mgui using shape loaders, which are defined by the init file. All shape loaders for a given session are available in the File Data Panel, which you can access from the Combo Box at the top left of the screen. You can browse the available loaders (shape or otherwise) via the drop down box beside the "File type" combo box.
[TODO: screen shot here]
The process of loading a shape into the workspace is simple. You first select the file type from the combo box, next browse for the file containing the shape data you wish to load, and - if necessary - clicking "Options" to define the target shape or section set, shape name, and other loader-specific options. Finally, click "Read Data".
Attributes
Every shape has a generic set of attributes which influence its appearance; each typically has addition ones which are specific to that shape or any shapes derived from it. Here we will go through a few of the generic shape attributes, which we can then play with once we've actually loaded some shapes into the Workspace. Note that there are two main ways to edit a shape's attributes: 1.) the Tree Panel; and 2.) the Attributes Dialog Box. We'll try both later on.
| Attribute | Comments |
|---|---|
| IsVisible | This self-explanatory attribute causes the shape to be visible or not in all graphics windows. |
| Show2D | Determines whether the shape is to be rendered on 2D sections. |
| Show3D | Determines whether the shape is to be rendered in 3D windows. |
| FillColour | The colour of the shape's sides (e.g., the triangles of a mesh). |
| LineColour | The colour of the shape's edges. |
| HasAlpha | If true, the shape can have transparency. This will be determined both by the global alpha attribute and any vertex-wise colours with nonzero alpha. |
| Alpha | The global transparency, where 1.0 is completely transparent and 0.0 is completely opaque. |
| ShowBounds2D | Whether to render the object bounds (rectangular) on 2D sections. |
| ShowBounds3D | Whether to render the object bounds (box) in 3D. |
| BoundsColour | The colour of the rendered bounds. |
| ShowVertices | Whether to render the shape's vertices as spheres. |
| VertexColour | The colour of the vertices. |
| VertexScale | Determines the size of the vertex spheres. |
| VertexScaleExp | An exponent which is applied to the vertex scale. |
| ScaleVertices | Whether to scale the vertices by a shape's vertex-wise data. This is determined by the ScaleData attribute, and is computed as Scale = (VertexScale * {value}) ^ VertexScaleExp |
| ShowEdges | Whether to render the shape's edges as lines. |
| EdgeColour | The colour of the edges. |
| ShowData | If true, renders the current data on the shape, using the data from the CurrentData attribute. See the Vertex-wise Data section below for details on how this is done. |
| CurrentData | Specifies the data column that is currently displayed for this shape. |
| Unit | The spatial unit in which this shape's coordinates are defined. |
| ShowVertexLabels | Whether to show labels at this shape's vertices. Labels are determined by the LabelData attribute; if this column has a name map, the mapped Strings are displayed. |
| LabelColour | The colour of the labels. |
| LabelFont | The font with which to render the labels. The size of the label is a factor of the font's point size and the value of the LabelScale attribute. |
| LabelScale | Scale factor for labels. |
| LabelFormat | A string specifying how numeric labels are to be displayed. See this page for details. |
Vertex-wise Data
ModelGUI associates values with vertices with vertex data columns. Vertex data can represent many different features of the geometric shape. For example, on a cortical surface you may want to represent cortical thickness, sulcal depth, functional activation, or statistics (these are continuous data, stored as single- or double-precision floating point numbers); or associate vertices with anatomical parcels or discrete clusters (these are discrete data, stored as integers). In what follows, we will load some data into a shape, and visualize it using continuous and discrete colour maps.
Loading a Shape Model
A Shape Model is the top container for all shape objects in MoelGUI. Each Shape Model has a root Shape Set, which can contain shapes or nested Shape Sets. Shape Models can be written and loaded from XML format files with the extension ".smod", or ".smod.gz" for compressed versions. For the purposes of the present tutorial, let's load a Shape Model from the file [some_shape.smod.gz]:
Go to the File Panel, and under "Input", select "ModelGUI Shape Models (*.smod, *.smod.gz)" as the file type. Click "Browse.." and select the file you just downloaded. Next click "Read" and the Shape Model will be loaded. Let's have a look at it by selecting the Tree Panel and expanding the Shape Models branch. If you expand far enough, you should see the following:
[screenshot of tree panel]
By convention, the top Shape Set of the model is not displayed in the tree, but it's there. Contained in it is the Mesh3DInt object named "some_name". Within the shape's tree node are nodes for its Attributes, as well as its vertex data columns, which are described below. The Shape Model also contains a SectionSet3DInt object named "horizontal", which is a set of horizontal planes which can be used to display the surface mesh in a 2D window.
Visualizing
3D Window
To create a 3D window, simply right-click on the main screen (under the tab) and select "Add Window > Graphic3D". Give the window a name, and click OK. Now we want to set the Shape Model we loaded as the source for this window. Right-click again, and select "Set source > Default Model". Your shape will now be rendered in 3D, but probably is too zoomed in to recognize. To zoom out, you can either use the mouse scroll wheel, right-drag (on Windows), or Ctrl-left-drag (on Linux and Mac). Your screen should now look like:
[screenshot of 3D window]
2D Window
We also want to see what this shape looks like in 2D section. To create a 2D window, right-click and select "Split horizontal > Graphic2D". A new window will appear to the right of your 3D window. 2D windows take Section Sets as their sources, so we can use the horizontal section set that we just loaded. Right-click again, and select "Set source > Default model.horizontal". The window should now display a section of the surface mesh, and in the 3D window the plane corresponding to this section will also appear. We can change the location of this plane via the Section Set Panel. Make sure the window is selected, and expand the "Sections" heading. You can use the "Prev" and "Next" button to iterate through subsequent sections, the "Ref" button to return to section 0, and the "Current Section" text box to specify which section you want to set as current. The 3D and 2D windows will update to reflect the changes.
[screenshot: navigating section sets]
Shapes Panel
The Shapes Panel provides a useful interface for visualizing and manipulating your shapes. We will sample just a few of the possibilities here. To select the shape you want to work with, expand "Shapes", and select the selected shape to "Default model.some_name".
Name Maps
Name maps assign integer values to text strings. This is useful, since text itself cannot be associated with vertices, but integers can. For instance, the surface you loaded has a column called "aal_atlas", which is a set of integer values assigning each vertex to an anatomical area defined by the AAL atlas [1]. However, the integer value itself is not very informative. The Shapes Panel allows you to assign a name map to any vertex data column in your shape. To do this, we first need to load the Name Map which came as part of the tutorial data set. From the File Panel, set "Name Maps (*.nmap)" as the file type, and "Browse.." to "aal_78.nmap". Click "Read" and we're ready to go.
Back on the Shapes Panel, expand the "Name Maps" heading. Select "aal_atlas" as the data column, and "aal_78" as the name map, and you're done. You can see the effects of your handiwork in the Querying part of this tutorial.
Operations
The Shapes Panel also lets you perform mathematical operations on your vertex data. Let's say we have an activation pattern represented on the cortical surface by the column "activation", and we want to adjust this activation so that it is not biased by the thickness of the cortex, which is represented in the column "thickness". To do this, we could simply divide the former by the latter, to get a measure of activation per mm thickness. Let's try.
First, expand the "Data Operations" heading. For our target column (which will store the result), we want to create a new column: click "Create", name the new column "activation_per_mm", and select "Double" as the data type. Next, click "Define..", and the "Define mathematical expression" dialog box will appear. Here, we can define our operation. To add a variable to the expression, you can double-click it in the list (or simply type it out). The expression we want is "activation/thickness;" (terminating with a semi-colon). To test whether the syntax is correct, click "Verify", and you should see a "Looks good!" message. Good.
[screenshot of dialog box]
Click OK, and then click "Apply". If all went well you will get a "Success" message.
Data Display
The "Data Display" heading allows us to visualize the operation we just performed.