diff --git a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIControls.png b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIControls.png deleted file mode 100644 index 12c575feb9..0000000000 Binary files a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIControls.png and /dev/null differ diff --git a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIInitial.png b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIInitial.png index 4f024381ae..67af9bd8fe 100644 Binary files a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIInitial.png and b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIInitial.png differ diff --git a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLINiftyReg.png b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLINiftyReg.png index 2774e9345f..7c000de664 100644 Binary files a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLINiftyReg.png and b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLINiftyReg.png differ diff --git a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLINiftyRegRunning2.png b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLINiftyRegRunning2.png new file mode 100644 index 0000000000..3aaa4f242a Binary files /dev/null and b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLINiftyRegRunning2.png differ diff --git a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIPreferences.png b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIPreferences.png index 8da377c792..867ad141f6 100644 Binary files a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIPreferences.png and b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIPreferences.png differ diff --git a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIPreferencesAdditionalDirectories.png b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIPreferencesAdditionalDirectories.png new file mode 100644 index 0000000000..ed77784ee4 Binary files /dev/null and b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIPreferencesAdditionalDirectories.png differ diff --git a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIPreferencesAdditionalModules.png b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIPreferencesAdditionalModules.png new file mode 100644 index 0000000000..e45e2afd58 Binary files /dev/null and b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIPreferencesAdditionalModules.png differ diff --git a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIWithPrograms.png b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIWithPrograms.png index 2884bde3ef..51b7e08bbf 100644 Binary files a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIWithPrograms.png and b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/CLIWithPrograms.png differ diff --git a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/Manual.dox b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/Manual.dox index 8f235ca086..8324dd0cc1 100644 --- a/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/Manual.dox +++ b/Plugins/org.mitk.gui.qt.cli/documentation/UserManual/Manual.dox @@ -1,86 +1,132 @@ /** \bundlemainpage{org.mitk.gui.qt.cli} The Command Line Interface (CLI) View \image html icon.xpm "Icon of CLI" +\li \ref CLIIntroduction +\li \ref CLIPreferences +\li \ref CLIUsage +\li \ref CLITechnicalNotes + \section CLIIntroduction Introduction -This view provides the facility to run command line programs, and load the data back +This view provides the facility to run third party command line programs, and load the data back into the DataManager for -immediate visualisation. - -The instructions here are intended for an end-user, and technical details are ommitted. - -The main purpose of this view is that it can be used to run any other -third party external program subject to compatibility requirements. -This is achieved using the following steps: +immediate visualisation. All that is required is that the command line application can be called +with an argument of --xml and respond with a valid XML description of the necessary parameters. +This view can then generate a Graphical User Interface (GUI) dynamically to enable the user to interact with the +command line application. This provides an easy to use, and potentially very flexible way +to integrate almost any third party, medical imaging, command line application. + +As a high level introduction, this view performs the following steps: + +\li The view searches for available programs to run, and for each valid module, stores the XML document describing +the interface, and populates a searchable list of available programs. +\li When a program is selected, the GUI is generated. +\li The user can then set the necessary parameters and run the program. +\li Multiple programs can be launched simultaneously, and where available on the host platform, +the user can pause, resume or cancel running jobs and see console output for each job. + +As a consequence of the very flexible nature of this plugin, these instructions can only describe how to launch +command line modules in a general sense. The examples shown have been constructed by downloading the latest version +of the NiftyReg package, available here, and described further +here. NiftyReg provides valid XML descriptors +to enable the integration of the NiftyReg affine (RegAladin) and and non-rigid (RegF3D) image registration algorithms, as well +as utility programs to resample an image, and calculate a Jacobian image. These same XML descriptors work within +Slicer and MITK based applications. -\li This view is launched. -\li The view searches for available programs to run, and populates a list of available programs. -\li When a program is selected, the program is asked to provide a description of the required controls. -\li These controls are drawn on the screen, ready for the user to click/press/interact with them. +\section CLIPreferences Preferences -The consequence of this last point is that these instructions tell you how to operate this view in a general sense. -The details of the exact operation of each external command line program is down to the developers of those external programs. +The first time that the CLI View is launched, it may be necessary to set the default preferences for the view. Please refer +to Figure 1. + +\image html CLIPreferences.png "Figure 1. The CLI Preferences Page" -\section CLIPreferences Preferences +The first 4 preferences are to control where the view will search for valid command line programs. By default these are off +as the searching process can take a long time and slow down the startup time of the GUI. The options provided are: -\image html CLIPreferences.png "The CLI Preferences Page" +\li scan home directory: Scan the users home directory. Most useful on unix systems where users can install their own software. +\li scan current directory: This is the current working directory. Most useful on unix systems where users launch the application from the console. +\li scan installation directory: This is the directory where the actual application is stored. +\li scan CTK_MODULE_LOAD_PATH: If the environment variable CTK_MODULE_LOAD_PATH points to a valid directory, this will also be scanned. -The CLI view has preferences that control +In addition, for the first 3 of these options, the sub-directory "cli-modules" will also be scanned if it exists. +In most cases, the user will leave these options unchecked, as the user can also specify custom directories, and +even cherry-pick specific command line programs to load. Figure 2 shows a selection box that enables the user to +specify custom directories to scan, and Figure 3. shows a selection box that enables the user to select specific modules. -\li temporary directory: Images stored in the DataManager are first written to a temporary folder before being passed to each command line program. -\li module paths: The user can specify additional search paths to look for command line programs. The user is advised to keep this list to a minimum, -as the more paths used, the slower the view will initialise. -\li debug output: If checked the XML parsing will produce debug output on the console. +\image html CLIPreferencesAdditionalDirectories.png "Figure 2. The User can specify specific directories to scan". +\image html CLIPreferencesAdditionalModules.png "Figure 3. The User can specify specific command line programs to load". -When this view starts it will scan the following folders for programs that can be run via this interface: +These directory and file selection boxes enable directories or files to be added, removed and updated in a similar fashion. -\li scan installation directory: If checked, scans application installation directory. -\li scan CTK_MODULE_LOAD_PATH: If checked, scans the directory specified by the environment variable CTK_MODULE_LOAD_PATH. -\li scan home directory: If checked, scans the users home directory. -\li scan current directory: If checked, scans the current working directory that the application was launched from. +The user must make sure that the list of files selected in the "additional modules" section are not already contained within +the directories specified in the "additional module directories" section. -These all default to OFF, or un-checked as scanning many directories can take a long time. +In addition, the preferences page provides: -In addition, for the installation directory, home directory and current directory, the sub-directory "cli-modules" is also searched. +\li temporary directory: Images stored in the DataManager are first written to a temporary folder as +Nifti images before being passed to each command line program. +This temporary directory will default to a platform specific temporary folder, but the user may select their preferred choice +of temporary workspace. +\li debug output: If checked the view will try to provide more output, either on the console window or +event log depending on the host platform. \section CLIUsage Usage -When the view is launched, a simple interface is presented: +When the view is launched, a simple interface is presented, as shown in Figure 4. + +\image html CLIInitial.png "Figure 4. The initial interface, with no command line programs available." -\image html CLIInitial.png "The initial interface, with no command line programs available." +In this example, all the above check-box preferences were off, and the "additional module directories" +was empty, and the "additional modules" list was empty so no command line applications were found. +The "Search" box displays zero entries, and there is nothing to search. -In this example, all the above check-box preferences were off, and the "module paths" was empty, so no command line applications were found. -If the available search paths contain programs that are compatible (i.e. runnable) with this view, the name of the programs are displayed -in the "Search" combo-box. +If the available search paths contain programs that are compatible (i.e. runnable) with this view, +the name of the programs are displayed in the "Search" box in a nested menu, shown in Figure 5. -\image html CLIWithPrograms.png "When valid paths are set, and programs are discovered, the menu is recalculated to show available programs." +\image html CLIWithPrograms.png "Figure 5. When valid paths are set, and programs are discovered, the menu is recalculated to show available programs." When a program is selected, the relevant interface is displayed: -\image html CLINiftyReg.png "An example program, showing parameters for NiftyReg." +\image html CLINiftyReg.png "Figure 6. An example program, showing parameters for NiftyReg's program RegAladin." In this example, the parameters are displayed for NiftyReg -produced at UCL. The interface can contain a wide variety of typical controls. If a parameter for -a command line program is an image, then the widget displayed is linked to the DataManager, so that as new images are loaded, the -correct image can be easily selected. +produced at UCL, and more specifically for the affine registration program called +RegAladin. The interface can contain a wide variety of controls. If a parameter for a command line program is an image, +then the widget displayed is linked to the DataManager, so that as new images are loaded, the correct image can be easily +selected. In addition, the view contains an "About" tab containing details of the contributors, the licence and acknowledgements and also a "Help" tab containing a description and a link to any on-line documentation. These documentation features are provided by the developers of the third party plugin, and not by the host program. If information is missing, the user must contact the third party developers. -If the preferences are changed to add search paths, or the available programs within those search paths are changed, -then this view will automatically update the list of programs. +The view provides some simple controls: + +\li Green arrow: Launch (run) the current command line executable. +\li Yellow undo arrow: Resets the GUI controls to a default value, if and only if the original XML specified a default value. +\li Blue pause button: A toggle button to Pause/Resume the running program. +\li Red square: Stop (kill / cancel) the running application. Irreversible. +\li Black cross: Remove the widget from the display. + +When the module is launched the parameters are fixed, so the parameters box is disabled. When the +command line program is running, it may provide progress updates in the progress bar, or via +console output, which can be seen in the console box. Both the parameters box and console box are collapsible to save space. + +It is possible to launch multiple jobs. The number of widgets just stack vertically, as shown in Figure 7. + +\image html CLINiftyRegRunning2.png "Figure 7. Multiple programs can be run, each with individual control and console output." + +\section CLITechnicalNotes Technical Notes -Finally, there are 3 buttons to control the operation of the command line application: +From a technical perspective, the Command Line Interface (CLI) View is a simple view, harnessing the power of the CTK +command line modules framework. For technical information see: -\image html CLIControls.png "The main controls." +\li The doxygen generated manual page. +\li The wiki page. -\li The green triangle: Run the program -\li The red square: Stop the program -\li The yellow arrow: Restore the form to default parameters +and obviously the CTK code base. */ diff --git a/Plugins/org.mitk.gui.qt.cli/resources/pause.png b/Plugins/org.mitk.gui.qt.cli/resources/pause.png index 201c8b3e2b..a63d34e17e 100644 Binary files a/Plugins/org.mitk.gui.qt.cli/resources/pause.png and b/Plugins/org.mitk.gui.qt.cli/resources/pause.png differ