:tocdepth: 3 .. _SecGraphicalUserInterface: ======================== 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. .. image:: images/gui-dia2.png :scale: 80 % :align: center 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: .. image:: images/gui44-is.png :scale: 90 % 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: .. image:: images/gui3.png :scale: 90 % 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. .. image:: images/gui44-level.png :scale: 90 % More detailed descriptions are given in the section `User Level`_. .. _SecScriptsBasics: 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. .. image:: images/gui44-script-open.png :scale: 50 % 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`` .. _SecInfoText: 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. .. image:: images/gui-script-info.png :scale: 80 % 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). .. image:: images/gui-entry.png :scale: 80 % 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. .. _SecQueryReplaceParameters: Query Replace Parameters ~~~~~~~~~~~~~~~~~~~~~~~~ The **Replace Parameter** option in the `Edit Menu`_ allows to query and replace these script entries i.e. the parameters. .. image:: images/gui-replace.png :scale: 70 % 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. .. _SecDatabase: 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. .. image:: images/gui-database.png :scale: 70 % Internally medtool_ creates based on these line edit entries an XML database which looks for this example like: .. code-block:: xml Parameter File Generator Input File Name fileEntryInEdit testIn.dat testIn.dat no yes txt:dat:inp:* Common Parameter File Name fileEntryIn test.par test.par no yes txt:dat:par Common OutFile Name entry $outfile $outfile no yes 1 Common 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. Menus ===== A classical menu bar can be find at the top of the GUI. Most of the menu entries can be found at the tool bars above and beside the script browser (the icons) or other areas. File Menu --------- The "file" inside medtool_ is the database file (XML) which contains the script names, parameters and some more infos. The file menu looks like: .. image:: images/gui-file.png :scale: 70 % and holds following options: * **NEW**: creates a new (empty) medtool_ XML file. * **Open**: loads an existing medtool_ XML file. * **Update**: updates an existing medtool_ XML file (see `Database`_). * **View Script Template**: shows an example script template which can be used to create your own plugin (see `Plugins`_). * **Import**: saves checked parts from the **Script Browser** of an other medtool_ database (see also `Run Menu`_). * **Export**: loads checked parts from the **Script Browser** to a new medtool_ database (see also `Run Menu`_). * **Save**: saves the current database. * **Save As ..**: saves the current database with a new file name. * **Add Plugin**: allows to add a user plugin (see `Plugins`_). * **Exit**: closes the *medtool GUI*, checks if database needs to be saved. Edit Menu --------- The edit menu can be seen as a tool for editing a list where the list are the entries in the **Script Browser**. .. image:: images/gui-edit.png :scale: 70 % The entries in this list are allow to: * **Move Up ...** the selected (active) script inside the **Script Browser**. A faster way is to simply use drag and drop inside the **Script Browser** area. * **Move Down ...** the selected (active) script inside the **Script Browser**. A faster way is to simply use drag and drop inside the **Script Browser** area. * **Delete** the active script. * **Rename** the active script. * **Copy** the active script. * **Check All** scripts inside the **Script Browser** area. * **Uncheck All** scripts inside the **Script Browser** area. * **Replace Parameters** inside the script entries. To select/unselect blocks of scripts use `Info Text`_ scripts. .. _SecRunMenu: Archive Menu ------------ Obsolete scripts are available via the **Archive** menu for back compatibility. Avoid using these scripts because they are not further developed or ported to new platforms. .. image:: images/gui-archive.png :scale: 70 % Run Menu -------- Scripts inside the **Script Browser** (see `GUI Structure`_) may have three states: * checked and active * checked but not active * unchecked .. image:: images/gui-run-status.png :scale: 70 % The run menu covers different run types. It looks like: .. image:: images/gui-run.png :scale: 50 % and allows to: * **Run Active**: Run the active (clicked) script only. It has to be also checked. * **Run Checked**: Run all checked scripts, including the active script. * **Run Parameter Study**: Run a parameter study (see `Parameter Study`_). * **Run Parameter Batch**: Create batch files to run in a terminal (see `Parameter Study Batch`_). * **Open Python Terminal**: Open a terminal with medtool Python activated to run batch files (see `Parameter Study Batch`_). * **Stop Run**: Stop the current medtool_ run. This stops no external runs e.g. FE solver which are started via medtool_ . * **Run Settings** switches to run settings in the **Script Output / Settings** area (for more details see `Run Settings`_) Script Status ~~~~~~~~~~~~~ After the creation of a script a blue gear box is visible next to the script name in the **Script Browser** (see `GUI Structure`_): .. image:: images/gui-run-start.png :scale: 80 % This indicates that the scripts could be executed. After clicking on a run button, the blue gear box icon changes to a flag icon. Three different flag colors are possible as shown in the following: .. image:: images/gui-run-run.png :scale: 80 % .. image:: images/gui-run-failure.png :scale: 80 % The colors of the run symbol (flag) have the following meaning: - **Green**: The script run was successful. - **Orange**: The script is currently running. - **Red**: The script aborted with an error. In this case you know which script has problems. Whenever you click on an already execute script the flag changes into a blue gear box. This indicates that the script should be re-run because of possible parameter changes. Run Settings ~~~~~~~~~~~~ Usually, it is not needed to change any run settings before you start a medtool_ run. However, more advanced analysis types need additional settings. For example, of a user likes to select a working directory in order to avoid to give the full path information. This can be done via the **Run Settings** which is located next to the **Script Output** tab: .. image:: images/gui-runsettings.png :scale: 70 % Several settings are possible: * **Working Directory**: This is the name of the working directory. If no directory paths are given (e.g. file names only), medtool_ will look in this folder for the file and will write all generated data into this folder. The working folder is set automatically during startup to the directory where medtool_ is started. If it is set once and stored to a database, medtool_ checks the path. If it do not find the path an message appears like: .. image:: images/gui-workdir-warning.png :scale: 70 % * **Parameter File**: This is the name of the parameter file. I can be generated with the medtool_ 's spreadsheet tool (see `Spreadsheet`_), Excel, or similar. It has to be a CVS file separated with blanks or ``;`` as separator. * **3D Slicer Executeable**: This is the name of the 3D Slicer exe file which has to be installed separately. This field is only visible if your license includes medtool_'s 3D Slicer bridge. * **Python Executable**: All python related scripts are called by using a specific Python command. This entry shows the used python executeable as information for the user. If the entry is empty the standard python of the machine is used. * **Restart File**: During a run information is written to this file. If a script stops (indicated by a red flag, see `Script Status`_) during a *Run Checked* or *Run Parameter Study* this file can be used to restart the analysis from the point where a script stops. * **Restart Run**: If this option is active the *Restart File* (previous option) is opened and the analysis starts at the point where a script crashes. Otherwise all checked scripts are run again from the beginning.. .. _SecParameterStudy: View Menu --------- This menu allows to open additional viewers or editors. .. image:: images/gui-view.png :scale: 70 % In case of a viewer, the content is updated after every run. For more details see section `Viewer`_. Classic and Dark Mode ~~~~~~~~~~~~~~~~~~~~~ In **View Menu** under **Preferences..** it is possible to change the appearance of medtool. A *classic* and *dark* appearance is possible : Classic mode (Ubuntu): .. image:: images/gui45_classic.png :scale: 50 % Dark mode (Ubuntu): .. image:: images/gui45_dark.png :scale: 50 % Help Menu --------- Beside the medtool_ help (this document) there are some basic help options inside medtool_ . All of them work with pure text. The menu looks like: .. image:: images/gui-help.png :scale: 70 % and contains: * **Licence Info**: Way to check your licence information. * **Licence Update**: Update your license (``medtool.lic`` file). Start medtool_ wiht admin rights to change the license file. * **About medtool**: Some information about medtool_ . * **Help All**: A list of all scripts is shown and one script can be selected. The help of this script is printed into the `Script Output`_ area. * **Help Active**: Prints the help of the active script into the `Script Output`_ area. A quick way to get the help of a current script option is to click on the ``?`` symbol near inside the option: .. image:: images/gui-help2.png :scale: 45 % To get the help: 1) click on the symbol ? and 2) check the help output. The text cursor jumps directly to the help entry of this option. Advanced Run Options ==================== Both `Parameter Study`_ and `Parameter Study Batch`_ run optoins are advanced medtool_ features and will be explained in more detail below. Parameter Study --------------- A typical script call can e.g. look like: :: python circleArea.py -rad 12.3 -out /usr/work/Res1.txt There is nothing wrong but if one likes to investigate the influence of the ``-rad`` option (the radius) than the parameter and script need to be re-run again and again. It would be more convenient to use a generic variable for ``-rad``. This functionality is implemented in medtool_ and called parameter study. The basic idea behind parameter study is to use a generic run string i.e.: :: python circleArea.py -rad $radius -out $dir$filename where ``$radius``, ``$dir``, and ``$filename`` are variables which start with ``$`` in medtool_ . The values these variables are supplied by a parameter file which is given in `Run Settings`_ tab. In this way medtool_ recognizes where to read the quantities. The content of such a file may look like: :: $radius $dir $filename 12.3 /usr/work/ Res1.txt 19.7 /usr/stor/ Res2.txt For this example, medtool_ would send the following run strings to the system: :: python circleArea.py -rad 12.3 -out /usr/work/Res1.txt python circleArea.py -rad 19.7 -out /usr/stor/Res2.txt To set-up a parameter study by using medtool_ , following steps should be done. First a script is loaded and the script is executed in a regular way: .. image:: images/gui-run-param1.png :scale: 45 % This means a user: 1) inserts a value for a parameter (e.g. 12.3), 2) clicks the **Run Active** or **Run Checked** button, and 3) checks the output area to see if the run was successful. To be able run a parameter studies some pre-steps are necessary as shown in the figure: .. image:: images/gui-run-param2.png :scale: 45 % One has to: 1) create a parameter file (e.g. with `Spreadsheet`_ in medtool_ ), 2) sets this file in the `Run Settings`_ - *Parameter File* option, 3) replaces the value by the parameter (e.g. ``$radius`` instead of 12.3). This replacement can also be done by the `Query Replace Parameters`_ functionality. Now the script can be run as parameter study by: 4) clicking the **Run Parameter Study** button. 5) Finally, the output area should be checked where two successful run outputs are visible. .. image:: images/gui-run-param3.png :scale: 45 % Internally medtool_ does a simple replacement of the ``$radius`` string by ``12.3``, ``19.7``. Thus, * more parameters can be appear in one entry including other characters (e.g. ``$dir$file.png``) . * but the names have to be unique in sense of a query/replace operation. For example ``$radius`` and ``$radius2`` would be problematic because ``$radius`` is part of ``$radius2``! Simply change in this case ``$radius`` to ``$radius1`` and the replacement works correctly. Parameter Study Batch --------------------- The above described **Run Parameter Study** function in medtool is very helpful when you have to process many data sets. The option does not require special skills but is limited to one CPU on your server. If you want to run a parameter study in parallel, you can generate batch files and start them manually. This is called the **Run Parameter Batch** function. .. NOTE:: An additional license is necessary to activate this option. The following steps are necessary for this: * set up an **Run Parameter Study** as described in `Parameter Study`_. 1) Change your entries to parameters, 2) create a parameter file, and 3) select the parameter file in the **Run Settings** tab as shown here: .. image:: images/gui-run-batch-1.png :scale: 40 % * edit the **Run Batch Settings** Panel: 1) Choose a batch file name. In windows the extension '.bat' will be added automatically. 2) Choose the number of CPUs you like to use. as shown here: .. image:: images/gui-run-batch-2.png :scale: 40 % * now the batch script can be creating by clicking the **Run Parameter Batch** button (F4) and two batch scripts are created. .. image:: images/gui-run-batch-3.png :scale: 40 % * to run these scripts open a terminal under the **Run** menu, click **Open Python Terminal**. This 1) opens a terminal, 2) activates the current medtool python version, 3) sets all enviroment variables, and 4) changes to the working directory. For example, the ``dir`` command (Windows) or ``ls`` command (Linux) shows the content of the current working directory. .. image:: images/gui-run-batch-4.png :scale: 40 % * two batch scripts are created ``circleArea_batch_1.bat`` and ``circleArea_batch_2.bat`` because we have chosen two CPUs. Looking into one of the files using the **Editor** shows :: "C:/Program Files/medtool47/Python39/python.exe" "C:/myWorkingDir/circleArea_gui.py" -rad "12.3" This shows the start of a medtool Python script with one parameter. * Start this batch script by typing ``circleArea_batch_1.bat`` in the terminal:: (Python39) C:\myWorkingDir> circleArea_batch_1.bat * We see the same output as in the medtool GUI :: S T A R T circleClass V_07.01.2014 - D. H. Pahr ... get / compute area Area = 475.291 E N D E D SUCCESSFULLY in TOT : 0.0 sec * open a second terminal and start ``circleArea_batch_2.bat``. Now two medtool scripts run in parallel. .. NOTE:: - If you do not run a "Parameter Study" but like to use this functionality, simply select a dummy parameter file and choose only one CPU. - If you run job in parallel, every job needs memory. Check that you are not running out of memory during a run. Otherwise the job gets very slown. - Do not use another Python version, because of the binary compatibility. Furthermore, all environment variables need to be set manually, which is tricky. - When medtool is closed, all terminals are also closed. Own Python Scripts ------------------ There are three possibilities to use own Python scripts together with medtool libraries: 1) use medtool `Plugins`_: - Pro: full medtool GUI support (options) - Con: medtool plugin must be written. 2) use ``python_medtool`` via the *Extras* - *User Script Runner* script (see :ref:`examples `, Grid Data Scripting). - Pro: no Plugin needs to be written - Con: no GUI for parameters. 3) use the *Run* - *Open Python Terminal* function to start the script in a terminal with activated medtool python (see `Parameter Study Batch`_) - Pro: full freedom to start a Python scripts with or without medtool libraries. - Con: only for experiences users, limited to modules includes in the medtool distribution. 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 .. image:: images/gui44-simple.png :scale: 40 % Standard .. image:: images/gui44-standard.png :scale: 40 % Expert .. image:: images/gui44-expert.png :scale: 40 % 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: .. image:: images/gui44-changeLevelError.PNG :scale: 60 % This function prevents active options from being hidden. The user levels can only be changed if the corresponding option has been deactivated. .. _SecScriptOutput: 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. .. image:: images/gui-output.png :scale: 45 % 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: * medical imaging data: 3D slicer (http://www.slicer.org/), ImageJ (http://imagej.nih.gov/ij/) * point & cell data: Paraview (http://www.paraview.org/) * Finite Element data: Solver specific pre- and post processors (Abaqus Viewer, HyperView, ... ) 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. .. image:: images/gui-viewer2.png :scale: 65 % 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. .. image:: images/gui-viewer_XM_XP.png :scale: 50 % 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: .. image:: images/gui-viewer_1_med46.png :scale: 65 % 1) Open a set of mid-plane images 2) Load the default images (images at start-up for coordinate systems) .. image:: images/gui44-viewer7.png :scale: 45 % 3) Reload all opened images 4) Scale the images incrementally 5) Adjust the contrast of the images .. image:: images/gui44-viewer2.png :scale: 70 % .. image:: images/gui44-viewer3.png :scale: 70 % 6) Change the annotation text size 7) Change the annotation pen size 8) Show a scale bar .. image:: images/gui44-viewer8.png :scale: 45 % Overlay Options ~~~~~~~~~~~~~~~ A further feature of the viewer is to overlay different images. .. image:: images/gui44-viewer-2.png :scale: 65 % 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) .. image:: images/gui44-viewer5.png :scale: 70 % Blue Image / Red Image (both could be gray-level) .. image:: images/gui44-viewer6.png :scale: 85 % 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. .. image:: images/gui44-viewer9.png :scale: 50 % *2D Image Info*: Allows to pick points, lines, or polylines via the mouse. Click outside of the mid-planes to delete the selection. .. image:: images/gui44-viewer10.png :scale: 50 % 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. A list of gray-values can be picked and displayed. * ``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). .. image:: images/gui44-viewer11.png :scale: 50 % 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. .. image:: images/gui46-editor-1.png :scale: 60 % .. _SecSpreadsheet: The editor can also be used to edit parameter files (tools underlines in red). .. image:: images/gui46-editor-2.png :scale: 60 % 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. .. image:: images/gui-spreadsheet.png :scale: 60 % 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. .. image:: images/gui-directory-viewer.png :scale: 60 % 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): .. image:: images/gui-directory-viewer2.png :scale: 60 % .. image:: images/gui-directory-viewer3.png :scale: 60 % 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. .. _SecProjectFolderStructure: 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: .. image:: images/folderstruct.png :scale: 90 % 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. Quick Directory Creation ------------------------ Sometimes when you create a script, you want to create a folder with the same name. If the script and folder names are identical, you can immediately see which script writes data to which location. This can be realized in medtool_ with a few clicks. .. image:: images/gui-quick-dir.png :scale: 50 % 1) Select a working directory where you like to create you folder 2) Click on the script which contains the folder name 3) Create a new folder/directory by clicking the button in the **Directory Manager** 4) A message box pops-up which shows the script name (with out ``_`` underline) as suggestion for the new folder name. After you click ``OK``, a new folder is created within the working directory. .. image:: images/gui-quick-dir-2.PNG :scale: 80 % Toogle Working Directory ------------------------ When opening a file in medtool, it often happens that very long file names are displayed, which affects the clarity. .. image:: images/gui-toogle-1.PNG :scale: 50 % You can switch very quickly between the long and an abbreviation ie. to the ``.\`` which is known as *current directory* in Linux). The *current directory* is the working directory (see `Run Settings`_) in medtool_. Simply click the **Right** mouse button (not the left) and a pop up window appears. .. image:: images/gui-toogle-2.PNG :scale: 50 % Select the **Toogle Working Directory** options and you see after that .. image:: images/gui-toogle-3.PNG :scale: 50 % This allows switching (toogle) between the short and long directory path versions. .. _SecPlugins: 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*. .. image:: images/gui-script-template.png :scale: 70 % 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. .. image:: images/gui-plugin.png :scale: 70 % 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: .. image:: images/gui-plugin4.png :scale: 70 % After including the plug-in medtool_ shows the following menu entry: .. image:: images/gui-plugin2.png :scale: 70 % and **Script Browser** entry after loading the script with the default name: .. image:: images/gui-plugin3.png :scale: 70 % If no plugins are added there is no **Plugins** menu. .. _medtool: http://www.dr-pahr.at/medtool/