:tocdepth: 3 ============ Introduction ============ This is the official help for medtool_, a work-flow management system that generates simulation models from 3D medical images. .. image:: images/medtool_overview_3.png :scale: 100 % :align: center 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 :ref:`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 :ref:`examples ` documentation and read the guidance at the beginning of this section. - Go step by step through the recommended :ref:`examples `. After these first steps you are ready to start your own medtool_ project. It is recommended to: - Setup a :ref:`folder structure `. - Create :ref:`new scripts ` (one at the time) and run it in :ref:`Run Active ` mode first. Check carefully the :ref:`Script Output ` area. - Save the :ref:`medtool database ` from time to time! - Make :ref:`info text entries ` to structure and document your work. - After making all required scripts, you may run them with the :ref:`Run Checked ` option. - In case of a :ref:`parameter study `, :ref:`query/replace values ` inside your scripts by parameters from a :ref:`CSV file `). - Maybe, you like to write your own medtool_ :ref:`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. .. image:: images/gui4.png :scale: 100 % :align: center 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. .. image:: images/medtool_overview.png :scale: 50 % 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. .. image:: images/medtool_overview2.png :scale: 55 % 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. .. image:: images/msb.png :scale: 80% 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: .. literalinclude:: src/circleArea.py *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 ======= ================================ ============ .. Recommended platforms are *Windows 10* and *Ubuntu 20.04* 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*. .. image:: images/gui-license-info.PNG :scale: 70 % 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. .. image:: images/gui-viewer-mode.png :scale: 48 % .. image:: images/gui-viewer-mode2.png :scale: 48 % .. 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. .. image:: images/gui-lic.png :scale: 70 % 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. .. image:: images/gui-start.png :scale: 70 % 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. .. _`3D Slicer`: https://www.slicer.org/ .. _`Dr Pahr Ingenieurs e.U.`: http://www.dr-pahr.at/wordpress5/ .. _medtool: http://www.dr-pahr.at/medtool/ .. _webinar: http://www.dr-pahr.at/medtool/?page_id=24