Updated for version mgui-1.0.32-alpha
This page steps you through the process of getting ModelGUI running on your machine for the first time. It then provides a few pointers on how to get accustomed to the user interface, load some data, and play around a bit.
Requirements
Since ModelGUI is completely Java-based, it is also platform-independent, given that a Java Virtual Machine (JVM) and Java3D version exists for your platform. This means that you can install it and run on Windows, Linux, Mac OS, or Solaris with (theoretically) equal ease.
The requirements are:
- Java installation. From v1.0.32, you should download the bundled version. These have Java runtimes included, and you do not need to have a system installation. Otherwise: ModelGUI is developed using Java Runtime Environment version 1.8 (from mgui-1.0.30 onwards), so you should have this version or later releases installed. You can do this here or (OpenJDK) here.
- If you wish to use the database functionality, you will need a database server installed on your system (if not, or you're not sure, you can safely ignore this; database support can always be installed later). ModelGUI currently supports PostgreSQL (recommended) and MySQL. ODBC is also supported, if for instance you want to connect to an MS Access database. ODBC comes with Windows by default (see here or here for details).
- At least 1GB of RAM; the more the merrier of course. 3D volumes in particular tend to hog a lot of space.
The dependencies for mgui are all bundled with the downloads for you.
Installation
The latest release versions of ModelGUI can be obtained here. There may be a number of options for bundles, depending upon how you want to use the program and what specialities you are interested in. These are described on the download page, or more extensively here. Choose the version that suits you.
Once you've downloaded the zip file, extract it wherever you want (NOTE: as mgui will by default write log files to this directory, you should choose a place where you (and anyone who will use the program on this machine) have write permissions. E.g., avoid "Program Files" on Windows). You should now be ready to go. The executable is located in the top directory and called "mgui-amd64.bat" for Windows 64-bit, "mgui-amd64" for Linux platforms, and "mgui-mac" for Mac platforms. Replace amd64 with i586 for 32-bit systems (experiment if you're not sure what your system architecture is). Note that for Linux platforms you may also need to make the file executable using the command chmod +x mgui-amd64.
If you encounter an exception when running mgui for the first time, don't despair. Check the Common execution exceptions page for more advice. If this doesn't have a solution, you may want to use the Discussion Forum.
For Windows users, you may want to create a desktop shortcut. To do this:
- In Windows Explorer, navigate to the executable file (e.g., mgui-amd64.bat)
- Right-click and select Send To > Desktop (create shortcut)
- Rename the new shortcut if you'd like, to something like "ModelGUI"
- Set the icon file: right-click > Properties > Change icon; navigate to the folder where you installed mgui; and select "mgui.ico".
The shortcut should look like this:
For Linux users, to make life easier you can do the following:
Set the $MGUI_HOME environment variable (in bash) by appending the following to your ~/.bashrc file:
# ModelGUI
export MGUI_HOME=/path/to/mgui/installation/
Next, make an executable file called "run_mgui" in a directory of your choosing (I have a folder in my home directory called "Apps" for this purpose). Fill the file with the following bash script:
#!/bin/bash
if [ ${MGUI_HOME:+1} ]
then
cd $MGUI_HOME
else
echo No MGUI_HOME set! See README file.
exit 0
fi
./mgui-amd64
..replacing "mgui-amd64" with "mgui-i586" if yours is a 32-bit machine. (Note: to make the file executable you need to run the command chmod +x run_mgui).
Finally, create a symlink with the following command:
sudo ln -s /home/me/Apps/run_mgui /usr/local/bin/mgui
Now you can run ModelGUI with the simple command "mgui". Conveniently, if you want to change your ModelGUI version or run multiple versions, all you now need to do is change the $MGUI_HOME variable in the ~/.bashrc file.
Note 1: If you're on a network configuration with sysadmins and whatnot, and don't have write access to /usr/local/bin, you'll have to define bin directory somewhere where you do have such access (e.g., your home directory), and ensure this directory is on your path (add export PATH=$PATH:/my/local/bin to your ~/.bashrc file).
Note 2: The addition of a Debian repository for ModelGUI is on our wish-list…
A First Tour of ModelGUI
For what follows, you will need to download the sample data for this tutorial, which provides some sample shape files which you can load and play around with to get a feel for the interface.
When you first run the program, you will be greeted with the following window:
On the left of the screen is the Combo Panel, the user interface panel where most of the interaction between the user and the underlying model will take place. At right is an empty Display Panel. We can create windows in this Display Panel using the context menu (right-click). As shown in the image, let's create a 3D window by right clicking and selecting Add Window > Graphic3D. Give the window the name "Graphic3D" and click OK. The window will turn white and the name of the window ("Graphic3D") will be displayed at its top.
The combo panel is organized such that you can choose from a number of different interface panels using the combo box at the top. As you can see, the current panel is the Tree Panel. We'll explore this panel first, and have a look at some others in a bit.
Tree Panel
The Tree Panel displays a tree which gives a nice visual representation of what data or other resources are loaded and how they are organized. The Workspace at the root of the tree represents the main "container" for the model interface; everything is contained in this panel. Let's see what it contains:
Display Panels
This is a list of the current display panels, which can be selected as tabs in the main window. Each display panel contains a set of windows, or Graphic Panels. Because you have one window open, expanding this node shows that window ("Graphic 3D"). Expanding this node reveals new nodes. The first, which has an {A} icon, is an Attribute Node; this is good to know, because many objects with which you will interface will have this node. Expanding an attribute node shows you all Attributes belonging to a given object, along with their current values. You can use these nodes to change the attribute values. For example, expand the attribute node and click the coloured rectangle next to "Background". This brings up a colour dialog which allows you to select a new colour for the background of your 3D window.
Shape Models
A Shape Model is the base object containing geometric model objects and their associated data. All shapes are contained in the shape model's root Shape 3D Set. Shapes and subordinate Shape 3D Sets can be added to this. Like the 3D window, the root shape set also has an attribute node. You can expand this node to see what sort of attributes belong to a Shape 3D Set.
Data Sources
A Data Source specifies the information needed to form a JDBC database connection. JDBC is a standard interface provided with the Java library which specifies how database engines should interface with Java classes. Any database for which a JDBC driver is installed can be accessed using this interface, and therefore through modelGUI. At present, only the MySQL JDBC driver is provided with the mgui distribution.
Graphs
A Graph object is a graph in the mathematical sense. In other words, it is comprised of a set of nodes (or vertices) and edges which connect them. Graphs are a very powerful concept which can be used to visualize and analyze complex networks, among other things. Currently mgui provides a Graph Window which visualizes graphs using the JUNG Java library.
Dynamic Models
As opposed to shape models, Dynamic Models specify how entities behave over time. While the implementation of such models is still quite experimental in mgui, a number of base model objects have been implemented, building upon the Open Source Physics project. This will be a major point of core development for ModelGUI over the near future.
Name Maps
A Name Map maps integers to text strings. This is useful for representations of discrete data, such as brain regions or geological rock types.
Variables
Variables are vectors and matrices of numeric or character data, which can be used for various computations, etc.
Queries
Queries provide an standard interface to query Interface Objects.
Projects
Projects allow the user to organize data in a coherent way, which helps simplify tasks such as querying, displaying, and processing large data sets.
Pipelines
Pipelines are a means of organizing workflows; they operate on pre-defined process libraries, which allow the user to define, save, and execute complex sequences of commands on data sets. Pipelines can be used in conjunction with Projects. We won't go into these functions in this introductory tutorial, but it's good to know where they are.
Windows
Next we want to add a new 2D window to complement our 3D window. Right-click and select Split Horizontal > Graphic2D. This will split the 3D window into halves, horizontally, with the new 2D window on the right. Call the window "Horizontal".
Graphic windows display data from Shape Models. In order to set our 3D window to show the current model, right-click and select Set source > Default model. The screen will still be empty (because no shapes are loaded yet), but a 3D axes box will appear at the top right of the window, indicating that the window now has a source.
Section Set Panel
We also want a source for our 2D window. 2D windows have Section 3D Sets as sources; these are defined as a base point and two vectors, which define a 3D plane and a 2D coordinate system. To create a section set, select "Section Set Panel" from the combo box at top left.
To create a new section set, expand the "Create/Update" category at the bottom of the panel. Here we can specify in which Shape3DSet we want to create our section set (note that a Section3DSet is treated as any other 3D shape, and thus must be added to a Shape3DSet). Currently, there is only one shape set ("Default model.Default shape set"), and it is already selected. The next combo box is a list of existing section sets; selecting one of these allows you to update an existing set instead of creating a new one. No sets yet exist, however, and the only option is "<-New set->". Below this, you can give your set a name. Ours will be a horizontal section, so let's give it the imaginative name "horizontal". Next you can specify the origin point and x- and y-axes. Since the default values already define a horizontal section at (0,0,0), simply click "Create".
To set this new section as the source of our 2D window, right-click the window and select Set source > Default model.horizontal. Your screen should appear as above.
File Panel
Okay, so far we've been playing with trees and windows, but now it's about time we loaded some geometry data into our session, which is the point of ModelGUI after all. Some sample shapes are provided in the sample data for tutorial 1, which you've presumably already downloaded. To load data, select "File Panel" from the combo box.
First let's load a surface file. The file we want is a version of the PALS template cortical surface from the Van Essen lab at Washington U. in St. Louis. To load this, select "Tri surfaces (*.tri)" from the "File type" combo box. Now click "Browse", navigate to the "tutorial1" folder, and select "PALS_B12_left.tri". Clicking "Options" will allow you to change the name of the surface or the Shape3DSet into which it is loaded, but we don't need to bother with that at the moment. Simply click "Read Data" to load the surface.
When it's first loaded, the 3D window will have the surface in view, but it will look a bit strange. This is because your view (or Camera 3D) is currently extremely zoomed. You can check this by moving the mouse over the window and noting the value for "Zoom" in the Status Bar at the bottom of the mgui frame. To zoom out, ctrl-left-drag your mouse downwards on the 3D window; you can also use your mouse wheel for this. The value for Zoom will change to something larger, and you will see the surface zooming outwards. Play with this until you can see the entire surface. You will now be looking directly downwards at the left hemisphere of the PALS cortical surface. To get a better idea of what it looks like, you can spin it around by dragging the left mouse button. You can also pan it back and forth by shift-left-dragging. Try to get the surface oriented as seen in the screenshot:
You'll note a few things from this screenshot. Firstly, there is a blue plane cutting through the surface; if you're clever you may have realized that this plane corresponds to the current (i.e., zero-th) plane of the section set we created. Any section set which is assigned as the source for a 2D window will show up like this in the 3D window (assuming the "ShowSections" attribute of the containing Shape 3D Set is set to true). The surface itself will also show up in the 2D window, as a polyline representing its intersection with the zero-th plane. To view the surface fully, right-click the 2D window and select Zoom extents.
Congratulations, you've loaded your first surface!
Volume Panel
The Volume 3D Panel provides an interface for loading and visualizing 3D volumes (or Volume3D shapes). A Volume3D object is specified by a Box3D representing its geometric boundaries, and s, t, and r "data" dimensions (analogous to x, y, and z; but defined in the coordinate system of the volume, which is not necessary orthogonal to the model coordinate system). Each element [i, j, k] in the Volume3D object specifies a location within the Box3D, with respect to the box's origin point. Thus a Volume3D represents a discrete, regular distribution of values in R3.
To load a volume, select "Volume Panel" from the combo box. Expand the "Data" category. Check the box beside "Volume File" and then click the button. You should see the dialog depicted below. You can find an Nifti-format image file in the sample data set, named "T1.nii". Click "Browse.." and find this file.
Next, we want to select a Colour Map, which maps the values in the Volume3D to colours that can be rendered in the graphics panels. Select "Greyscale" from the list. Also, ensure that the check box beside "Has alpha" is selected.
Click OK, and then from the main panel, click "Create". The image data will be loaded and will appear in the graphics panels. The Volume Panel has also changed; collapse "Data" and expand "Intensity". This category includes a 2D section view of the Volume3D (below), and allows the colour mapping parameters to be adjusted and inspected before applying any changes to the shape itself.
Before we do any adjusting, it is useful to know what our data look like. You can discover this by expanding the "Histogram" category. This shows a histogram as shown below, which portrays the distribution of values in the volume from its minimum to its maximum value (these settings can be changed to produce different histograms). The height of the bars can be adjusted with the "Y scale" value. The histogram display also shows the colour mapping window drawn over the histogram (as a red line), and the bins themselves are coloured according to the current parameters from the "Intensity" category.
The current colour mapping is greyscale, which doesn't give us much contrast; let's adjust it. Before doing so, we should briefly discuss colour maps and colour models. In mgui, there are two types of colour map: discrete, which maps a series of integers to colours; and continuous, which defines a set of "anchors" along a specified range of values, and interpolates colours between these anchors. Since the present volume is a T1 structural magnetic resonance image, it is continuous in nature and so we should apply a continuous colour map to it.
A colour model defines how a value element in list of values (such as those contained in our Volume3D) is assigned to a colour. 3D volumes map colours using a "windowed" colour model, which defines a window within the data range and applies a colour map to that window. A window is specified by two parameters: its middle (also known as "brightness") and its slope (also known as "contrast"). You can adjust these two parameters either by dragging their scroll bars, by right- or left-dragging on the image, or by dragging the three control points in the histogram window (two squares and a circle). You can watch both the image and the colour mapping line on the histogram change as you adjust these values.
Try to adjust the image so that it appears as below. Note that, when "Has alpha" is set, all values below the colour model's minimum value are made transparent. This allows the lower, noisy values in a Volume3D to be thresholded; e.g., to reveal the underlying scalp.
Click "Apply", and your graphics panels will look something like this:
Adjusting Attributes
In the 2D window, our surface intersection line is now difficult to see in its light grey colour. Let's change this colour to something a bit darker. Choose "Tree Panel" from the combo box and expand the tree nodes for Shape models > Default model > PALS_B12_left > Attributes. This will display all the Attributes for this Mesh3D shape. The attribute we're interested in is 2D.LineColour; click the coloured box in this node and a colour dialog box will appear. Select a dark red colour, as shown, and click OK. The intersection polyline will now be much more visible. (Note: if changes do not automatically appear in a 2D window, this is because ModelGUI is still alpha… you can always right-click the 2D window and select Regen window to force a regeneration of the display).
In the 3D window, the volume is mostly opaque so that all you can see is the scalp surface. Our PALS surface is completely hidden within the volume (although we can see its outline in the 2D window). To make it visible, we can adjust the general alpha parameter of the volume until it is very low (about 0.123). Click "Apply" and now you should be able to see the PALS surface inside the T1 volume:
To get an even better look inside, we can also use the section set we have defined to "clip" the 3D scene. To do this, go back to the Tree Panel and expand the attributes for the horizontal section set. Change the attribute 3D.ClipDistDown to 1000 (effectively no downwards clip), and leave 3D.ClipDistUp at 1. Now click the check box beside "3D.ApplyClip". This results in the model being clipped 1 mm on either side of the current section (below left). This clip will change to reflect any changes to the current section - check this by scrolling through the sections in the Section Set Panel. The clipping distances are specified as attributes for the section set. (Note, at present, clipping can be finicky, throwing annoying Java3D errors at inopportune moments; fair warning).
Going Further
This brief tutorial has demonstrated the basic tasks of setting up windows and section sets, as well as loading surface meshes and 3D volume data. It has also introduced some basic ModelGUI concepts such as attributes, colour maps, and tree nodes. To go further, this Wiki site provides a number of additional user tutorials illustrating the use of specific tasks, as well as a user manual describing ModelGUI concepts and objects in more detail. Additionally, you can peruse and participate in the discussion forums, where many of the questions that may arise in your use of the application may already have been addressed. Remember that ModelGUI is a dynamic project, meaning that many features will be added in the future that do not currently exist, so it is useful to check this site frequently, as well as add your own ideas for feature improvements if you have them.
Enjoy!