Introduction

This is the official help for medtool, a work-flow management system that generates simulation models from 3D medical images.

medtool is designed to:

• read, convert, and process medical images

• create 2D meshes (iso-surfaces) and 3D meshes

• create FEA analysis models from medical images

• convert finite element analysis (FEA) files

• map image gray-values to material parameters

• homogenize multi-phase materials

• automatically analyse and post-process FEA simulations

• produce XY plots and create PDF reports

• create 3D print models for medical images

• create 3D print models from FEA results

• do bone image analysis (CT morphometry)

In addition, medtool acts as a provenance management system. It stores workflows, enables parameter studies based on spreadsheet data, user extensions via Python plug-ins and can make daily work in this area more efficient.

This manual describes the user interface of medtool and all associated scripts. Depending on your license, not all of the described scripts may be available in your medtool version.

Getting Started

The idea behind medtool is different to other medical image processing tools. Thus, it is important to start in the right way Following steps are recommended for new users which like to start by their own with medtool:

• Download the basic webinar tutorials of medtool to get a first impression.

• Read the Introduction section and the Graphical User Interface section of the medtool help.

• Copy the installed example problems directory to a work directory where you have read/write rights.

• Go to the examples documentation and read the guidance at the beginning of this section.

• Go step by step through the recommended examples.

After these first steps you are ready to start your own medtool project. It is recommended to:

• Setup a folder structure.

• Create new scripts (one at the time) and run it in Run Active mode first. Check carefully the Script Output area.

• Save the medtool database from time to time!

• Make info text entries to structure and document your work.

• After making all required scripts, you may run them with the Run Checked option.

• In case of a parameter study, query/replace values inside your scripts by parameters from a CSV file).

• Maybe, you like to write your own medtool plug-in with python in order to do tasks which are not covered by medtool yet.

medtool has a steep learning curve but in the long run this investment will come with lots of benefits!

Feature Overview

A quick way to automate tasks on a computer is write programming code in a text file. Such a file is called a script and contains a sequence of commands for the operating system. Scripts can be written with different programming languages (python, bash, power shell, …) and are usually directly called from a shell or command prompt (known as cmd or power shell in Windows). For example, one line of Python Code prints “Hello World”:

print("Hello World")

Variables for the computations can be passed via so-called parameters or arguments to such scripts during the call. At this point medtool comes into the game. It simply provides a graphical user interface to manage such scripts. The following picture gives a first impression.

Typical tasks of a script manager are to organize the scripts in menus, to give an overview of available parameters, to provide a documentation, to show run states, etc. Furthermore, medtool allows to re-run scripts which different parameter sets via a spreadsheet and provides many other useful functions. More details are given below.

In case of medtool such scripts are used to set up a process or work flow to build up a chain of image processing steps followed by meshing, FE analyses, and results analyses.

In more detail medtool consists of a graphical user interface (GUI) and a suite of single scripts which are called from medtool. The primary intention is an automated generation, evaluation, and post-processing of simulation models based on 3D image data.

Also many other functionalities are available like material homogenization, interfaces to VTK/ITK and finite element solvers (ABAQUS, Optistruct/Nastran, Calculix, ParoSol, FEAP), post-processing tools, XY-plotting, histomorphometric analysis, reporting, etc. The following figure shows a few outputs of medtool scripts.

Users have also the possibilities to quickly write plug-ins for medtool where existing scripts can be used as libraries.

Since medtool 4.5, extensions are available to call up 3D Slicer and start a specific GUI. After manual image interaction, the user can return to medtool without interrupting a medtool run.

Ideas behind medtool

Scripts

Software can be developed and distributed in several ways:

• as graphical user interface (GUI) based application software (like office packages, web-browsers, …),

• as extension to an existing software (like macros, plug-ins),

• as library which can be used for new developments or

• as a sequence of commands collected in a text file and known as script.

Note

Scripts are programs written for a special run-time environment that automate the execution of tasks that could alternatively be executed one-by-one by a human

Scripts can be called from a command prompt (Windows) or terminal (Linux) and parameters can be passed to scripts in the simplest way by so-called arguments. Assume there is a script inside your working directory which can be called with (type the command inside a command prompt or terminal):

> python circleArea.py −rad 15.0 [−out file.txt]

This example script calculated the area of a circle and is written in python language. Thus, it starts with the python keyword. After that call, the python script (here named circleArea.py) is executed with one or two parameters. These parameters are:

• A required parameter -rad which is the radius of a circle which has a value of 15.0.

• The parameter -out is optional which is indicated by the brackets [..]. If this parameter is given (the brackets are not written in this case), the area is written to a file named file.txt. Otherwise the area is simple written to the standard output e.g. shell or command prompt where the script was started.

The code of this script reads as:

"""
This script computes the area of a circle. 

Usage :: 

  python circleArea.py -rad 15 [-out file.txt]

"""

# loading libraries
from sys import argv

# main program
if __name__ == '__main__':
	
  # ... get parameter from argument list
  radius = float(argv[2])
  
  # ... compute area
  area = radius**2 * 3.14159
  
  # ... output results
  print("\n** Program: circleArea.py **")
  print("   r =", radius)
  print("   A =", area, "\n")

Challenges when working with such scripts are usually that:

• users have many of such scripts,

• every script may include many of arguments, and

• often no documentation is available.

After some time it is hard for a user to remember all scripts and even harder to be aware of all possible arguments. Therefore, usually such scripts are:

• hard to handle and maintain as well as

• nearly impossible to share with others.

medtool is designed to overcome these drawbacks and assist users with their own scripts but allows also an easy exchange of scripts from different developers.

Scripts Manager

When talking about medtool one have to distinguished that it consists of two essential parts:

• a graphical user interface (GUI) - the medtool GUI

• and scripts to generate, analyse, and post-process simulation models from 3D image data - the medtool scripts.

In the following the compound of these two parts is called medtool.

The idea behind medtool was to make it easier for users to handle third-party scripts and their own scripts, as described above. Simply put, medtool is a script manager. The requirements for the development of medtool were:

1. User friendliness

   • GUI implementation

   • overview of all arguments

   • quick documentation

   • plugin possibility (extensibility)

2. Fully automated analyses

   • single or series of script runs

   • parameter studies via spreadsheet

3. All-purpose usage

   • handle any scripts/arguments

   • simple including of new scripts (own or external)

   • independent script languages

   • usage of third party software and libraries like VTK, ITK, CGAL

4. Library functionality

   • re-usage of implemented software via import functionality of python

   • sharing of scripts and work flows with others

5. Documentation

   • documentation of new developed scripts

   • documentation of work flows of projects

Distribution Infos

The medtool framework consists of a pre-compiled medtool GUI and individual medtool scripts written in Python, Fortran, or C++. Externals scripts or user scripts can be inserted via a plug-in function. An example plugin file is provided inside the GUI.

Platform Support

medtool supports following platforms:

OS	Version	Architecture
Windows	10	64 bit
Linux	Ubuntu 20.04	64 bit

Most of the medtool scripts are based on Python. The medtool installation includes a complete Python environment which is not part of the licensed software.

Note

• Parallel micro Finite Element scripts are available only under Linux for parFE, parOsol, and parFeap.

License

Trial, research, and commercial licenses are available. The usage of the software is based on the license agreement which is coming with medtool. The 3D Slicer bridge of medtool requires an additional license.

A trail license is available upon request from Dr Pahr Ingenieurs e.U. (office@medtool.at). It can be downloaded from http://www.medtool.at for free. Users are allowed to use it for testing and teaching, but NOT for any research or commercial purposes. The trial version is hardware independent (no MAC required) and shows several limitations :

• Windows OS

• single license

• limited duration (max. 3 month)

For Research or commercial license please contact Dr Pahr Ingenieurs e.U. ( office@medtool.at) and ask for an offer. Annual rental licenses or purchase licenses are available. They are node locked licenses and are based on the specific MAC address of the computer being used

The MAC address of our computer can be checked by medtool by clicking on Help - License Information.

In case of a missing license, medtool starts in a viewer mode. This mode allows to:

• open medtool XML files,

• check the license information or

• install a new license file.

Note

Usually medtool is installed with Admin rights at C:\Program Files\medtoolXX. To install a new license, you need to start medtool once with Admins rights. Check in your OS how to start an application as an administrator (in Windows right click on the app and click Run as administrator).

Alternatively you can copy the medtool.lic license directly to the bin folder inside the installation filder e.g. C:\Program Files\medtoolXX\bin.

If medtool did not start due to a license error, please check your license information (see above) first. Second open the Task Manager and check how many medtool sessions have already been started on your PC.

Installation

medtool comes with installer scripts for both platforms which contains the code, examples, and the documentation. Additionally, a Python distribution is shipped with medtool.

Windows

Execute the installer, and select a location for installation location. In case of Windows a start menu entry is created where medtool, examples, and the help can be accessed.

Linux

The Linux installer creates a start script called medXX (XX stand vor the current version number). To start the medtool GUI use a terminal and type in:

$ /pathToMedtool/medXX

A medtool database (xml file) can be passed directly during the call by writing:

$ /pathToMedtool/medXX myFile.xml

The medtool help can be started from the terminal with:

$ /pathToMedtool/medXX -h

Prerequisites

All included python scripts are compiled with the shipped Python and will not work with different Python distributions (e.g. from your system). Depending on the operating system the following should be noted:

• Windows: Required system libraries are shipped.

• Linux: Required system libraries are NOT shipped.

medtool searches for libraries, scripts, external software, etc in the medtool installation path which is given by MEDTOOLPATH environment variable. The Windows installer is setting this path automatically. In case of Linux, this path is set when medtool is called via the medXX start script.