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)
Furthermore, medtool acts as provenance management system. It stores work-flows, allows parameter studies based on spreadsheet data, user extensions via Python plug-ins, and can make the daily work in this field more efficient.
This manual describes the user interface of medtool and all related scripts. Depending on your license, not all described scripts may be available within your medool version.
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!
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
power shell in Windows). For example, one line of Python Code prints “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.
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.
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
circleArea.py) is executed with one or two parameters.
These parameters are:
- A required parameter
-radwhich is the radius of a circle which has a value of
- The parameter
-outis 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) # ... 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.
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:
- User friendliness
- GUI implementation
- overview of all arguments
- quick documentation
- plugin possibility (extensibility)
- Fully automated analyses
- single or series of script runs
- parameter studies via spreadsheet
- 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
- Library functionality
- re-usage of implemented software via
importfunctionality of python
- sharing of scripts and work flows with others
- re-usage of implemented software via
- documentation of new developed scripts
- documentation of work flows of projects
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.
medtool supports following platforms:
|Linux||Ubuntu 18.04 / 20.04||64 bit|
- Parallel micro Finite Element scripts are available only under Linux for parFE, parOsol, and parFeap.
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. (firstname.lastname@example.org). 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)
- max. 20 scripts
For Research or commercial license please contact Dr Pahr Ingenieurs e.U. ( email@example.com) 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.
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.
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.
The Linux installer creates a start script called
(XX stand vor the current version number). To start the medtool GUI use a terminal
and type in:
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
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.