Graphical User Interface

Overview

Internal Structure

medtool consists of a graphical user interface and a series of underlying application software (so called scripts) that manipulate existing data or create new data. The flowchart below shows how medtool’s graphical user interface (GUI) performs tasks through the use of scripts and how data is read or stored.

_images/gui-dia2.png

A user interacts with the medtool GUI by inserting data and running scripts. These scripts read data, modify them, and writes them to a data storage device. The medtool GUI do not hold big data, it only safes the script names including the applied parameters.

GUI Structure

After starting medtool a user interface appears:

_images/gui44-is.png

It consist of several parts:

  • Script Browser: This holds a list of all created scripts.
  • Script Parameters: The parameters of the active script in the script browser are shown in this area.
  • Script Output / Run Settings: After launching a script, the standard output and standard error are written to the Script Output area. The second tab (Run Settings) allows to modify run parameters like working directories, etc.
  • Viewer / Editor / Spreadsheet / Directory Manager: This area contains a simple midplane Viewer, a lightweight Editor, a simple Spreadsheet application, and a Directory Manager.

During a typical medtool GUI during a run looks like this:

_images/gui3.png

Several scripts are visible in the Script Browser. Colored flags indicate the run status. Parameters for the active scripts are shown in the Script Parameters tab. In the Viewer area three mid-planes are visible. The Script Output area shows the standard output of the currently running script. The status bar at the bottom indicates that a job is running (red dot) and the green bar shows the progress.

Since medtool 4.4, it has been possible to adapt the user interface via a user level selector. This makes it easier for new users in particular to start using the “Simple” or “Standard” levels. Advanced users still have the option to view all script options at the “Expert” level.

_images/gui44-level.png

More detailed descriptions are given in the section User Level.

Scripts Basics

A script with default parameters is loaded by clicking on the corresponding menu e.g. Image, Mesh, Material, Boundary, Solve, Post, Analyze, Publish, Fabricate or Extras menu (for details see Scripts section below). Which menu entries are visible depend on the licenced modules. All other menus (File, Edit, Run, View, Help) are medtool specific and will be described in detail in the following sections.

_images/gui44-script-open.png

To load a script (see figure above) following steps have to be done:

  1. Click on a menu entry (e.g Extras - File - Modifier 1)
  2. Insert an application name or keep the default name (here paf_). For the first character only letters (A-Z, a-z) or underlines _ are allowed. The following characters may also include numbers (0-9) or -. All other characters or blanks are forbidden. The script names have to be unique. The default script name is simple the name of the source code file plus an _ at the end.
  3. After clicking OK the new script will appear in the Script Browser and the corresponding script parameters will show up in the Script Parameters area.

Technically speaking an instance of the script is created. If the script is loaded again it has to get a different Script Browser name because it may hold different data for each parameter .

Note

For extensive projects with many scripts:
  • number the script with _01, _02
  • gives a brief hint on the script behavior e.g. segment, 3D_mesh
  • keep the script name e.g., mic, hma,
  • an informative script name is e.g.: _01_segment_mic
  • create a folder with the same name to create new files e.g.: 01_segment_mic

Info Text

Use the “Info Text” script form the “Extras” menu to document and group scripts. The scripts have to start with a __ (double) or ___ (triple) underline character.

_images/gui-script-info.png

These underlines has two effects:

  1. The scripts names are colored differently in the Script Browser (better overview) and
  2. all scripts between two Info Text scripts can be easily checked and unchecked by clicking on the check button of an Info Text script.

Script Entry Types

After loading a script all options (required and optional) appear in the Script Parameters area (see figure).

_images/gui-entry.png

Explanations of the red numbers of the above picture:

  1. Is a required entry. It has no check box on the upper left corner and is always active. This parameter must be provided otherwise the script stops with an error.
  2. This is an optional entry which is activated. Click on 4 to activate it. It means this script argument IS not passed to the script during the call.
  3. This is an optional entry which is not deactivated. It means this script option value IS NOT passed to the script during the call.
  4. Toggle this button to activate/deactivate this option (e.g. here -drange).
  5. Clicking on the “help” symbol to show the help of this option in the Script Output area.
  6. Clicking on the option text (e.g. -sep) replaces the value inside the entry by the default value.
  7. This is a line edit input area. If more than one parameter are given they must be separated by a ; (semi-colon). In this case the extended input are (see 8) is opened automatically. Both fields (7 and 8) are synchronized.
  8. Extended input area to show all parameters as a list. See also 7.
  9. Number of “o” next to the labels indicates how many entries (see 4)) are activated within this tab.

Many different entry types are available:

  • input file entries
  • input file edit entries
  • output file entries
  • directory entries
  • line entries
  • split entries
  • combo box entries
  • radio entries
  • color entries
  • table entry

The dpScriptTemplate.py file shows all these different types.

Query Replace Parameters

The Replace Parameter option in the Edit Menu allows to query and replace these script entries i.e. the parameters.

_images/gui-replace.png

It is a simple string replace which can be applied on

  • the active script
  • checked scripts
  • all scripts

(see Run Menu for explanations) as well as

  • active arguments (checked entries)
  • all arguments

which are described above.

Database

xml Files

After the creation of the script instance the parameter values appear in the Script Parameters area. Several different entry types are implemented (file, combo, radio, … entries). All entries have a line edit with data in it which can be edited. The data are interpreted and passed to the scripts as strings.

_images/gui-database.png

Internally medtool creates based on these line edit entries an XML database which looks for this example like:

<!DOCTYPE MedToolXML>
<MedToolXML cpu="1" writeonly="no" resfile="" workdir="Z:/testing" exefile="" paramfile="">
 <paf_ script="paf" active="yes">
  <modulName>
   <description>Parameter File Generator</description>
  </modulName>
  <in>
   <description>Input File Name</description>
   <type>fileEntryInEdit</type>
   <value>testIn.dat</value>
   <default>testIn.dat</default>
   <optional>no</optional>
   <active>yes</active>
   <info>txt:dat:inp:*</info>
   <menu>Common</menu>
  </in>
  <par>
   <description>Parameter File Name</description>
   <type>fileEntryIn</type>
   <value>test.par</value>
   <default>test.par</default>
   <optional>no</optional>
   <active>yes</active>
   <info>txt:dat:par</info>
   <menu>Common</menu>
  </par>
  <out>
   <description>OutFile Name</description>
   <type>entry</type>
   <value>$outfile</value>
   <default>$outfile</default>
   <optional>no</optional>
   <active>yes</active>
   <info>1</info>
   <menu>Common</menu>
  </out>
 </paf_>
</MedToolXML>

This XML file can be saved and loaded via the File Menu. It is a meta data file without any heavy data in it like, for example, medical images. This file can be edited by hand if it is damaged. But only experience users should edit this file manually. In the worst case, medtool can not open the file after editing.

The name of the database appears in the GUI in the upper left corner. If the database is not saved it says untitled.xml.

Auto Save

If the database is saved once, e.g. as myMedtool.xml, medtool will save the state every minute in a file e.g. as myMedtool.xml.bak. I case of a medtool crash, rename this file e.g. to myMedtoolRecover.xml and load it to get the last state. The .xml.bak files can be deleted if not needed anymore.

Update

Script options, default values, etc are changing. Usually only options are added but not deleted. In order to be able to use new options, an old database needs to be updated. This is done via File Menu - Update. First save or re-name your old database file. Next call the update function of medtool and save the new database .xml file and test the new file if it is working correctly.

Useful Tools

User Level

As of medtool 4.4, it has been possible to adapt the user interface via a user level selector. There are three levels: Simple, Standard and Expert. Changing the user level has the following effects:

  • Script options are shown or hidden and
  • GUI areas and buttons are shown or hidden.

The following pictures show the three levels: Simple, Standard and Expert.

Simple

_images/gui44-simple.png

Standard

_images/gui44-standard.png

Expert

_images/gui44-expert.png

Which level should be chosen depends on the experience of the user.

  • Simple: A user who uses medtool for the first time. The GUI shows default options and functions that allow you to work through simple examples.
  • Standard: A user who uses medtool for daily work and also carries out parameter studies. Existing scripts are usually used and hardly changed.
  • Expert: A very experienced user who wants to have all medtool functions visible. This mode was the default for older medtool versions.

If you change the user mode from e.g. Expert on Standard and has activated an Expert function in one of the scripts, the following error appears:

_images/gui44-changeLevelError.PNG

This function prevents active options from being hidden. The user levels can only be changed if the corresponding option has been deactivated.

Script Output

Every script is producing output in form of text and (most properly other data). The text in the script ouput tells the user that a script is started, informs about the current task and finishing status. This output should be always checked. Therefore, medtool shows the Script Output tab automatically.

_images/gui-output.png

In the figure above a few more things are important:

  1. The text produced by the script. In case of plugins the user should write meaningful messages to stdout. This output is written in this area during a medtool run.
  2. The progress bar is useful in case of long parameter runs. The “big green dot” means nothing is running, medtool is ready for a new run. When it become red, a process (script) is running. It is not possible to run more than one job at the time.
  3. Click this button to delete the text inside the output area. This is done automatically before a run starts.
  4. Save the output to a text file. This can be used as logging informations.
  5. Search for strings in the output area. For examples, to look for WARNINGS.
  6. Find the next appearance of the string given in 5).

Viewer

Note

If the options shown here are not visible, change the User Level to Expert.

medtool is not design to work on data interactively. Many other tools are available for such tasks depending on the type of data. For example:

The idea is to quickly view midplane or projected data (like X-rays), to get important information about the data, and to select points or regions interactively. The image viewer in medtool was design to give such a quick insight. It shows three orthogonal planes of an image. After medtool startup the mid-planes and coordinate definitions are shown. The point 0,0 is always at the upper left corner.

_images/gui-viewer2.png

On the left hand side a panel appears which allows to set viewing options, gives image informations and shows different data.

The data files for the viewer are generate with the Image - Processor script (see figure below, annotation 1 and 2) to generate three orthogonal mid-plane files (3) or three orthogonally projected planes (4), which are simulated X-rays.

_images/gui-viewer_XM_XP.png

This options write four files

anyName-XM.png -> x midplane
anyName-YM.png -> y midplane
anyName-ZM.png -> z midplane
anyName-IM.csv -> info file

anyName” is an abitrary name (e.g. ‘test’) and the extension -XM, -YM, -ZM, -IM for midplanes or -XP, -YP, -ZP , -iP for projected planes are automically appended. To open a file using * open * in the viewer. Only one of these three files has to be selected. The remaining images are automatically recognized and loaded.

Note

All mid-planes are loaded automatically after running a script in medtool .

Standard Options

Typical standard functions of the viewer are the following:

_images/gui44-viewer-1.png
  1. Open a set of mid-plane images

  2. Load the default images (images at start-up for coordinate systems)

    _images/gui44-viewer7.png
  3. Reload all opened images

  4. Scale the images incrementally

  5. Move the view area to left / right / top / bottom

  6. Adjust the contrast of the images

    _images/gui44-viewer2.png _images/gui44-viewer3.png
  7. Change the annotation text size

  8. Show a scale bar

    _images/gui44-viewer8.png

Overlay Options

A further feature of the viewer is to overlay different images.

_images/gui44-viewer-2.png
  1. Open a set of mid-plane images

  2. Load overlays, up to 10 overlays are possible

  3. Click the Overlay Option if not active

  4. Change the opacity of the overlays

  5. Change the display style

    Gray Image / Color Mask (mask is a segmented image)

    _images/gui44-viewer5.png

    Blue Image / Red Image (both could be gray-level)

    _images/gui44-viewer6.png
  6. Clear all overlays

Image Info & ROI Options

3D Image Info: Shows or hides the 3D Image Info tab. Inside the tab the most important meta data are shown. These data are read from the *-IM.csv or *-IP.csv file. Maybe older medtool (4.2 and before) do not write out these files. Thus, not all fields may be filled with values.

_images/gui44-viewer9.png

2D Image Info: Allows to pick points, lines, or polylines via the mouse. Click outside of the mid-planes to delete the selection.

_images/gui44-viewer10.png

The fields contain the following information:

  • Voxel Id i;j;k : The global i,j,k voxel id of the picked voxel. Depending on the mid-plane, one of these values is always half of the voxel data size in this direction.
  • Voxel Id List i;j;.. : The local picked i,j values. These values are the i,j values of the corresponding 2D images. Depending on the mid-plane they are the global j,z (XM), i,k (YM), or i,j (ZM) values. This list can be copied to the Analyze - DXA script (din option) or previously defined values can be pasted from elsewhere to define a new ROI.
  • Gray Value: The picked gray value which is computed based on the Gray Value Range. If no range is given the default the image range is 0..255.
  • Position [mm]: The physical position of the picked point. The Offset is taken into account.
  • Length [mm]: The physical length between the last two picked points (length of a line).

ROI Selection: Allows to select cubical regions of interest (ROIs).

_images/gui44-viewer11.png

Features are:

  • The sliders (1) allow to change the bounding boxes manually in X, Y, Z.
  • The buttons on the right side of the sliders (2) allow to reset the ranges to min/max values.
  • BBOX i;j;k;di;dj;dk: This entry shows the bounding box (ROI) by giving the start voxel ids i,j,k and the size of the ROI di;dj;dk - both are numbers of voxels. This list can be copied to the Image - Processor script (cut option) in order to crop this region from a model or values can be pasted from elsewhere to define a new ROI.
  • The button on the right side of the entry (3) allows to define the ROI based on a picked Voxel Id List i;j;... Pick first a few points on a mid-plane and than click this button. It used the min/max picked i,j values as new bounding box. The third bounding box values are unchanged.

Editor

The editor is a simple lightweight editor with some basic syntax highlighting for Abaqus input files, python files, and text files which are used by medtool. Very big files (e.g. Abaqus) should be loaded with an editor with text folding.

_images/gui-editor.png

Spreadsheet

The spreadsheet allows a quick generation of parameter run files in CSV format. These files can also be created by tools like Excel. It has some commenting functionality which allow to comment lines in and out. This is especially useful for parameter runs.

_images/gui-spreadsheet.png

The spreadsheet stores data in CSV format using ; as seperator:

$filename;$thres;$cutX;$cutY;
patient1.mhd;4563;345;567;
patient2.mhd;4436;332;545;
patient3.mhd;4765;366;567;

This format is the required file format for the medtool parameter file.

Directory Manager

The directory manager is designed to help the user to manage the Project Folder Structure of a medtool project.

_images/gui-directory-viewer.png

It has following functionalities:

  1. Create a single directory under the selected directory

  2. Delete a directory. Because of the permanent deletion this function requires an empty directory.

  3. Rename a directory.

  4. Create a directory structure (Project Folder Structure ). A sub-window opens if this button is clicked (see left window):

    _images/gui-directory-viewer2.png _images/gui-directory-viewer3.png

    A predefined structure can be generated. Individual folders can be toggled to ON or OFF. New folders can be added e.g. by inserting:

    newFolder1;newFolder2;newFolder3
    

    inside the empty text edit and click Add (result is shown in right figure).

  5. Go to the home directory.

  6. Go to the current working directory.

Project Folder Structure

The Directory Manager is able to generate such structure automatically. A few more words are given on this important topic. A workflow manager like medtool is able to produce a huge amount of data which should be organized to be able to re-use them. A suggested folder structure for an image to model project could look like:

_images/folderstruct.png

The main project folder is splitter into subfolders starting with A, B, C etc. The way of indicating the folders is always similar i.e. in every project folder A contains original scans (uCT, QCT, …), B contains edited gray-scale images (cropped, scaled, …), C holds registered images, in D are segmented images (masked, thresholed,..), E holds meshes (surface, solid), F contains material mappings, G boundary conditions, H finite element models, K documents, and Z always contains the medtool XML and parameter files (par, txt, xls). Inside each folder the subfolders are numbered by 01, 02, 03 etc. The scripts in the corresponding medtool file also include this name e.g. mic_calib_01. In this way someone who has never worked with the data knows immediately where one can find what. The medtool script and parameter files in the Z folder gives exactly the order and parameters for the individual operations to modify or generate data.

Plugins

medtool offers two ways to run self-written scripts with the shipped Python version and all medtool modules:

  • Python Scripts or
  • medtool plugins.

Python scripts are simply executed with the Extras - User Script Runner. A Python script is programmed using a text editor and given in the -exe option of this script, e.g.:

>  python_medtool script.py -value 10

python_medtool is recognized by the User Script Runner and replaced by the shipped Python version. Furthermore, internal enviroment variables are set such that medtool libraries can be used.

A much more comfortable option to run user scripts are medtool plugins which are described below.

Write a Plugin

All medtool scripts are plugins which can be written in any programming language. medtool has to get 2 informations from the script to be able to integrate it accordingly:

  1. The information about the script parameters (entry type, name, default value, …)
  2. The help information of the script - simply a text string.

The script parameters are obtained from the script by calling it with the -gui option. This option has to be implemented by the user. Such a gui string has the following style:

# entry             arg   description              default      opt  info"
guiInit = \
 "*modulName              'Template Script'                                   \n"\
+"*fileEntryIn     -inf   'Input File Name'        testIn.dat   no   txt;dat  \n"\
+"*fileEntryInEdit -ine   'Input/Edit File Name'   test.txt     yes  txt;TXT  \n"\
+"*fileEntryOut    -out   'Output File Name'       testOut.txt  yes  txt;dat  \n"\
...

In this example a fileEntryIn is created named Input File Name which has a default value testIn.dat and is not optional.

The help information is return by a script by calling it with -help. In case of Python, the most elegant way is to return simply the doc string.

To make live easy for new users a fully run-able script template is provided with medtool . It can be simply opened via File Menu -View Script Template.

_images/gui-script-template.png

This shown script is a python template script and can be saved, modified, etc. All possible GUI entries are presented. It can be used to add it as plugin to medtool , can be used to try out the plugin option or to use it as a starting point for the development of a new medtool plugin script. For this task please following the instructions in the template file.

Adding a Plugin

A prevously create user plugin can be easily added by the user to medtool . The plugin manager is opened via the File Menu - Add Plugin option.

_images/gui-plugin.png

Required values are:

  • Menu Name: The name of the script which will appear inside the medtool menu. If two names are given which are separated by : than a sub-menu is created.
  • Browser Name: An abbreviated name which should appear as default value for a script instance during creation.
  • Script Name: The name and location of the script on the PC (full path to the script).
  • Language: The script language. Usually python. Exec means an executable which is called without any command e.g. compiled C++ or Fortran files. User means that a user defined call of the script is provided via an -exe option inside the script. This is usually needed for abaqus python scripts.
  • Insert Before: The insert location of the script in an existing plug-in menu.

After clicking Apply an XML file (plugin.xml) is generated in the user home directory inside a directory named .medtool. medtool has to be restarted in order to recognize the new plug-in.

During a medtool start-up it loads the plugin.xml file and creates the Plugins menu inside medtool .

The Plugin Source (see Figure above) can be viewed and edited by hand. The icon at the very right of the Manage section opens this file with an editor. Plug-in deletion and moving can be done by hand. Simply select and/or delete/move the corresponding text in this file:

_images/gui-plugin4.png

After including the plug-in medtool shows the following menu entry:

_images/gui-plugin2.png

and Script Browser entry after loading the script with the default name:

_images/gui-plugin3.png

If no plugins are added there is no Plugins menu.