Getting started with Cmgui

Introduction

This page covers some of the basics of getting started with Cmgui. It includes information on the following

• What Cmgui is used for
• How to install Cmgui
• How to start using Cmgui
• Where to find more information

What is Cmgui and what can it do?

Cmgui is an advanced 3D visualisation software package with modelling capabilities. A gallery demonstrating some of the uses of Cmgui is available here: http://cmiss.bioeng.auckland.ac.nz/development/examples/a/index_thumbs.html

Cmgui is part of CMISS, a mathematical modelling environment initially developed by the University of Auckland Bioengineering Institute. CMISS stands for Continuum Mechanics, Image analysis, Signal processing and System Identification. There are three major CMISS software packages. Broadly speaking the main areas each piece of software deals with are as follows:

• CM is used for computational modelling
• Unemap is used for signal acquisition and processing
• Cmgui is used for model visualisation and manipulation

CM allows the application of finite element analysis, boundary element and collocation techniques to a variety of complex bioengineering problems. "OpenCMISS":http://www.opencmiss.org/ will be an open source equivalent of CM, and is currently under development.

Although Cmgui is a stand alone executable, it is designed to work closely with CM. In general Cmgui and CM are used in tandem to develop a mesh that describes the geometry of an object of interest (eg the eye, a femur, the heart, the lungs). CM is then used to solve a bioengineering problem over the mesh and the results are visualised using Cmgui.

Cmgui can be used without CM but you may have difficulty in creating the data files that Cmgui reads in to describe a mesh (called exnode and exelem files). It is important to realise that most users get their exnode and exelem files by exporting them from CM. Unless you are very familiar with the exelem format it is difficult to write an exelem file by hand or to write a script to generate it.

Some of the main areas of functionality of Cmgui are as follows:

• 3D visualisation of finite element and boundary element meshes
• mesh creation
• mathematical field visualisation and manipulation

Cmgui is a command line driven program. Usually script files are read or commands are typed in the cmgui command window to read in your mesh, create a 3D visualisation and manipulate it. Many tasks can also be accomplished by using the mouse to select options from various menus and dialogs. Cmgui has a large amount of functionality but it can be difficult for a new user to figure out what command to use to accomplish exactly what they want to do. Fortunately there are a large number of examples demonstrating the use of various different commands.

Cmgui is also used as part of the Zinc extension to Mozilla Firefox. The Zinc extension allows users to view Zinc applications in Firefox. A Zinc application uses Cmgui for visualisation while providing a nice customized user interface for a specific task. For example Zinc applications have been written to do the following:

• Interactively explore Colon endoscopy
• Explore the Physiome eye model
• Create data points to give a digital description of a geometry based on medical images.

Note that Zinc is compiled as a separate application from Cmgui. You do NOT have to install Cmgui to use Zinc. For more information on Zinc see http://www.cmiss.org/cmgui/zinc

Installation

Cmgui is currently available for download for a wide variety of platforms. You can download the appropriate executable for your operating system from the Release centre: http://www.cmiss.org/ReleaseCenter/cmgui .

Cmgui is quite a large application so the executable has been archived (tarred) and compressed (zipped) to make it faster to download. Once you have downloaded the executable all you need to do is untar and unzip it and it is ready to run. On Linux you can untar and unzip the tar.gz file with the command 'tar -xf filename.tar.gz'. On Windows you will need winzip or something similar to unzip the file.

You should now be able to run Cmgui by either clicking on the executable or by changing into the directory it is located in and then typing ./ followed by the name of the executable at the command prompt, eg './cmgui-wx'. This will bring up the Cmgui command window interface.

For convenience it is a good idea to place the directory containing cmgui into your PATH environmental variable. That way you will be able to run cmgui without having to be in the directory that contains the executable. To do this on a linux system you can specify your PATH variable in your .profile file. On windows you can edit your PATH variable by right clicking on my computer and then selecting: properties, advanced, environment variables. Ask your local system administrator if you do not know how to edit the PATH variable for your operating system.

How to start using Cmgui

In order to visualise a 3D geometry, Cmgui requires you to read in some data files (exnode and exelem files). You can then create a 3D graphics window and interactively view the mesh geometry using the mouse. You could type the required commands every time you wish to view a mesh but is often useful to put them into a command file (com file) which can then be read in by Cmgui. There are a large number of example com files with associated data files which illustrate various features of Cmgui. Once you have downloaded Cmgui it is a good idea to work through a few of these examples to learn some of the basics.

The examples can all be downloaded from the web. (If you are in the Bioengineering Institute you can just set up your CMISS_EXAMPLES environmental variable to have access to the examples). The cmgui examples are available here:

http://cmiss.bioeng.auckland.ac.nz/development/examples/a/index_thumbs.html There is also a text based index for convenience: http://cmiss.bioeng.auckland.ac.nz/development/examples/a/index.html

Try clicking on example a1 from one of the links above and you will notice several things.

Example a1

Each example has a short name (in this case a1) and a longer name (Graphical element groups: viewing a cube). Below the name is a brief description of what the example does and a screenshot. Following that is a listing of the comfile commands. The commands are usually interspersed with lots of comments, explaining what the commands do. Many com files have been written as interactive tutorials. These work best if you read through the example and run the commands as appropriate (more about this later).

After the com file listing there are links to the com file and all the data files used in the example. Below these links is a link to download the entire example. If you want to run the example and are not a member of the institute, click on the download entire example link. You will then need to use the command 'tar -xf examples_a_a1.tar.gz' to extract and unzip the example directory. (On windows machines you may run into problems if using winzip to extract the files. An alternative is to install cygwin and use the unzip utilities in cygwin to unzip the examples).

To run the example change into the directory examples/a/a1/cmiss_input and then type 'cmgui example_a1.com'. This should load up a blue cube. Other examples can be downloaded and run in a similar way. If you are a local member of the institute and have set up your CMISS environmental variables you can run an example by typing 'cmgui -example a/a1'

After the download link is some information relating to the nightly testing of the Cmgui development executables. This may be useful if you want to see if the example currently works with the latest development executable.

Stepping through an example

As well is being able to run all the commands in a comfile in one go, it is also possible to open up a comfile to view, and to then select particular lines to run. This is a good way to work through a comfile to get a feel for what each command does. To do this, change into the directory containing your cmgui input files (com files and data files). Start Cmgui, click on the file menu, then open, then comfile. Select the comfile you wish to run. This will load up an window with the comfile in it. You can either click on All to run the entire example, or you can select text using the mouse and then click on selected.

More examples

Some suggested examples to work through as a beginner are:

• a1. Graphical element groups: viewing a cube
• a2. Scene editor, graphical elements and lighting: decorating a cube
• a3. Prolate spheroidal coordinates, fibres: viewing the heart
• a7. Fields, spectrums, iso_surfaces and VRML: geothermal field
• ad. Rendered eye and surrounds
• ae. Element_glyphs, annotation, spectrum, colour_bar: element-based fields
• ah. Torso model with some of the major organs and blood vessels
• al. Computed fields and data abstraction : heart model

Where to find more information

Most of the documentation on using Cmgui is contained either in the examples or on the Cmgui wiki. http://www.cmiss.org/cmgui/wiki Browsing the wiki for a few minutes is a good way of getting a feel for what information is available and where it is located. Users are encouraged to use the search function in the upper right hand corner to search the wiki pages for content relevant to their questions. If you can not find the answer to your question on the wiki and then receive an answer from an existing user, please add this answer to the wiki so that others can benefit. The wiki is a collaborative project!

If you can not find the information you require then try contacting an existing Cmgui user, or a Cmgui developer. Bioengineering institute staff currently involved with development are: Randall Britten, Richard Christie, Alan Wu, Peter Bier and Duane Malcolm.

If you really get stuck you can try searching for questions others have posted in the past from the following tracker:

"Cmgui tracker item list":https://tracker.physiomeproject.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=cmgui&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&emailtype1=substring&email1=&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= , you can specify your search with the "advanced search" on the left or the "edit search" option at the bottom of the page and if the problem you encounter has not been posted before please fill in the form and describe your problem after clicking on the "Submit question about cmgui" or "Advanced submission" option on the left.