How to Use CranioGUI
CranioGUI is an interactive graphical user interface that is developed to demonstrate the capabilities of
our craniofacial analysis modules and provide a user-friendly environment for using them in different
workflows.
Go to http://craniolin.cs.washington.edu/craniogui.php
Download the sample data set of STL files to try with the demo. Unzip them and have at least one STL
file ready to use.
Click on the link for launching the application. This should bring up Java Web Start and the CranioGUI,
which should look like this:
Introduction:
A module is a program that does a simple task like reading a file, visualizing an output or processing
data. Modules are visualized as rectangles with their names on top of them. Each module has input and
output ports, that are visualized as small rectangles on the left (input) and right (output) sides of the
module.
There is a large empty panel at the right side of the CranioGUI, called the workspace, where modules are
added and connected in order to construct workflows. A workflow consists of multiple modules and is
used to process mesh data for craniofacial analysis.
The left panel of the CranioGUI contains a list of all modules that the system currently offers. They are
organized under seven categories. Categories can be expanded by clicking the (+) sign next to their
labels. A module is added into the workspace by double clicking on the name of the module. After
double clicking on a module name, the module icon (a rectangle) appears in the workspace. Modules
can be moved around the workspace by drag-and-dropping. They can be collapsed/restored by clicking
on the (-) button on the top right corner of the rectangle in order to use the workspace more efficiently.
Modules can be deleted from the workspace by clicking on the (x) button on the top right corner of the
rectangle.
Two modules in the workspace can be connected by dragging the output port of one module to the
input port of another module. When the mouse hovers over a port, the port turns green. Then the user
can click on the port and drag a directed edge into another port, which also turns green while the mouse
is over it. Only output ports can be dragged into input ports, and ports can only be connected if they
have the same data type.
The main function of the CranioGUI is to construct a workflow for a specific task. After the user adds all
the modules he desires and connects them, the workflow can be run by clicking the run button which
has a green triangle icon and is located on the top bar. If the workflow is correctly constructed, the
CranioGUI sends data to the server and the server starts processing. During data transfer and
processing, the run button is deactivated and the stop button, which has a red square icon, is activated.
If the user clicks the stop button, the CranioGUI waits for the server to finish processing the current
module and discards the rest of the workflow. If the workflow finishes with no errors, data flows from
the input modules through the processing modules to the visualization or output modules.
1. Input
Input modules are used to read data from your computer. The CranioGUI can read many 3D mesh file
types, but most of the modules use STL data. For some modules, you may want to read a TXT, ARFF, or
MODEL file you previously saved on your computer.
2. Output
CranioGUI can save several data types, which are most likely the output of some modules. Using the
output modules, you can browse for a directory, type in a file name, and save a copy of the output of
your workflow on your computer.
3. Visualization
The TXT Visualizer can be used to see the text output of many modules, and the ANY visualizer can be
used to see any output in a text editor (like .MODEL files in WEKA classification).
The CranioGUI provides 4 different STL visualizers. The STL Visualizer module is the simplest visualize; it
takes an STL file and shows a front view image of it. The STL Visualizer with Local Features module
requires text input of feature values for that STL. This text input can be the output of any local feature
extraction module (including azimuth or elevation angles). The STL Visualizer with Azimuth Elevation
Histogram module aims to visualize the bins each point falls into but it is not currently functional. When
it works, it will color every point according to the bin into which it falls. The STL Visualizer with
Landmarks module takes the STL and the text file produced by Landmark Detection modules and places
landmarks points on the face. For workflows using PLY data, the same modules are provided for a PLY
input.
4. Conversion
The modules in CranioGUI use either STL or PLY input but converters are provided for the user’s
convenience. In addition to 3D mesh type converters, a module to convert CT slices of a skull to a skull
mesh is provided.
5. Local Feature Extraction
These modules extract features from each vertex of a 3D mesh. Currently there are 5 modules provided:
Azimuth Angles, Elevation Angles, Gaussian Curvature, Besl-Jain Curvature and Shape Index. These
modules require an STL file as input and produce a text output for feature values at each point or cell.
These values can be visualized using a TXT visualizer or can be saved on a computer using the TXT
Output. There is an additional smoothing module which requires both an STL file and the text output of
one of the three feature extractor modules. This module applies an absolute Gaussian filter to the
feature values and outputs the smoothed values as a new text file.
6. 2D Azimuth-Elevation Histogram
There is only one module in this set. Azimuth-Elevation Angles Histogram module, will produce a twodimensional histogram of the azimuths and elevations as a single text file in the form of an array. The
parameter specifies how many azimuth bins and how many elevation bins. The default is an 8 X 8
histogram. The histogram can be used for classification and quantification purposes. It can be displayed
or written to a text file on the user’s computer.
7. Landmark Detection
This set of modules is used to place craniofacial landmarks on the face. The input of the modules is an
STL or PLY file read by a reader. The output is a text file containing the coordinates of landmark points.
The Auto-landmarks module places 17 established landmarks detected geometrically: pronasale, sellion,
subnasale, left and right alare, left and right alare curvature, left and right chelion, left and right
superaurale, left and right postaurale, left and right endocanthion, left and right exocanthion.
The Pseudo-landmarks module calculates as many pseudo-landmarks as the user wants. The pseudolandmarks are calculated on equally-spaced points on equally-spaced horizontal planes. The user inputs
the number of planes between the sellion and the chin, the number of planes above the sellion and the
number of points on each plane.
8. Symmetry Analysis
This set of modules is designed to analyze and quantize the symmetry of the face. The Mirror Symmetry
Plane module inputs a PLY file and calculates the location of the symmetry plane. This module also
outputs a text file that can be used for visualizing the plane. There are two modules for calculating
symmetry score, one based on points on either side of the symmetry plane and one based on grid
squares. Both modules output a summary file that contains the symmetry score and explanations, a PLY
file that is rotated during calculation and can be used for visualization, and text files that can be used for
visualization.
Trial Run:
1. Open, the Input tab at left, double click on the STL reader on the left, and it will bring an STL
reader icon into the center panel as shown below. Click the browse button and select the STL
file on your computer that you want to work with. You can move the icon wherever you want.
2. To see a front view of your STL file, open the Visualization tab, and double click on the STL
Visualizer, bringing its icon into the center panel. Now click your mouse on the STL output of the
STL reader icon and drag an arrow over to the STL input of the STL Visualizer. The boxes should
turn green when you hover over them.
3. Now you have the STL reader hooked up to the STL visualizer and are ready to try your first
workflow. Click the green arrow at the top left of the GUI to execute the workflow. The box to
its right will turn red until the workflow has finished executing. If you chose Indri.stl, the result
of the execution should look like this:
4. Now you can try a low-level operation on the mesh. Open the Local Feature Extraction category,
and choose the top feature Gaussian Curvature, double clicking to get an icon into the center
panel. Connect the output of the STL reader to the input of the icon. The output of the icon is a
text file of the curvatures at each point. Here are the results from both the TXT Visualizer and
TXT Outputter, both of whose inputs are connected to the output of Gaussian Curvature.
5. The curvatures can also be displayed in color by the STL Visualizer with Local Features
module. To do this
- Double click on the STL Visualizer with Local Features module to add it to the
workspace.
- Connect the original STL reader output port to the STL Visualizer with Local
Features input port.
- Connect the TXT output port of the Gaussian Curvature module to the TXT input of
the STL Visualizer with Local Features module.
- Click on the run button to execute the workflow and see the results.
6. Finally, we can add a smoothing module to smooth the local curvatures for further use.
Example run for Symmetry Analysis:
1. Use the Mirror Symmetry Plane module to calculate the symmetry plane. Note that the text output
contains the plane center and normal vector coordinates. The second text output is a feature vector that
can be used for visualizing the symmetry plane.
2. In order to analyze symmetry for every point, use the Symmetry Score (Point) module. This module
produces (1) a score that is the average point distance to the mirror symmetry plane, (2) a distance
value for every point. The distance values per point can be visualized as in the following picture.
3. In order to analyze symmetry for grids, use the Symmetry Score (Grid) module. This module produces
(1) average scores, (2) angle distance for every point, (3) curvature distance for every point, and (4)
radius distance for every point. The distance values for points can be visualized as in the following
picture.
Example run for Auto-Landmarks and Pseudo-Landmarks
1) In order to calculate the coordinates of 17 landmarks, use the Auto-Landmarks module with PLY
input. It’s possible to (1) visualize the landmarks on the face mesh, (2) print the coordinates of the
points using a TXT Visualizer or (3) save a copy of the text file that contains the coordinates in a commaseparated format using TXT Output.
2) Similarly a set of pseudo-landmarks can be calculated, visualized or saved.