diff --git a/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/MiniAppCommandLineTool/MiniAppCommandLineToolHowTo.dox b/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/MiniAppCommandLineTool/MiniAppCommandLineToolHowTo.dox index f31c70396f..3164a26673 100644 --- a/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/MiniAppCommandLineTool/MiniAppCommandLineToolHowTo.dox +++ b/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/MiniAppCommandLineTool/MiniAppCommandLineToolHowTo.dox @@ -1,138 +1,199 @@ /** \page MiniAppCommandLineToolHowToPage How to create a MiniApp command line tool \tableofcontents This page will give you an overview of creating your own command line tool that can be integrated into a MiniApp. If you don't know about MiniApps, you can read what MiniApps are at the \ref MiniAppExplainPage page. \section MiniAppCommandLineToolHowToPageDescription What's a MiniApp command line tool? A MiniApp command line tool allows for configuration of command line arguments and eases the access to these argument values. Additionally, a command line tool provides a XML representation of the configured arguments. This XML representation can be used for automatic user interface generation. \section MiniAppCommandLineToolHowToPageSetUp Setting up a command line tool This section describes the most important code parts of a command line tool using the \ref TensorReconstruction command line tool as an example. First the main function of the command line tool is specified. This function is registered at the MiniAppManager via the macro defined in \ref MiniAppManager.h \code int TensorReconstruction(int argc, char* argv[]) { } RegisterDiffusionMiniApp(TensorReconstruction); \endcode Within the body of the main function the accepted arguments of the command line tool are specified via the addArgument method of the ctkCommandLineParser located in DiffusionImaging/MiniApps directory. The \ref TensorReconstruction command line tool requires an input file, an output file, and optionally accepts a threshold of type integer. \code ctkCommandLineParser parser; parser.setArgumentPrefix("--", "-"); parser.addArgument("input", "i", ctkCommandLineParser::InputFile, "Input file", "input raw dwi (.dwi or .fsl/.fslgz)", us::Any(), false); parser.addArgument("outFile", "o", ctkCommandLineParser::OutputFile, "Output file", "output file", us::Any(), false); parser.addArgument("b0Threshold", "t", ctkCommandLineParser::Int, "b0 threshold", "baseline image intensity threshold", 0, true); \endcode Following argument types are available for the addArgument method: \li String \li Bool \li StringList \li Int \li Float \li InputDirectory \li InputFile \li OutputDirectory \li OutputFile The distinction between InputFile/OutputFile and InputDirectory/OutputDirectory respectively ensures that the appropriate UI widget is chosen. The label string passed to the addArgument method is the label for the corresponding UI widget. After specification of allowed arguments the parser's parseArguments method is called. This method returns a mapping of long argument names and their values. \code map parsedArgs = parser.parseArguments(argc, argv); if (parsedArgs.size() == 0) return EXIT_FAILURE; \endcode The following code snippet shows how argument values can be accessed and converted: \code std::string inFileName = us::any_cast(parsedArgs["input"]); std::string outFileName = us::any_cast(parsedArgs["outFile"]); int threshold = 0; if (parsedArgs.count("b0Threshold")) threshold = us::any_cast(parsedArgs["b0Threshold"]); \endcode \section MiniAppCommandLineToolHowToPageXMLRepresentation Retrieving XML argument description According to the specified command line arguments, a XML representation of the arguments is generated and emitted on the console if the MiniApp command line tool is executed with argument "--xml". In order to use the XML representation for automatic user interface generation additional information has to be provided for the parser. Please provide category, title, description and contributor as shown in code snippet below for the \ref TensorReconstruction command line tool: \code parser.setCategory("Preprocessing Tools"); parser.setTitle("Tensor Reconstruction"); parser.setDescription("Takes a .dwi, .fsl/.fslgz file as input and saves the computed reconstructed tensor to the specified file. It also allows for a threshold to be set, to exclude low b values from the reconstruction process."); parser.setContributor("MBI"); \endcode Note that in the generated UI the parameter widgets are contained in a group box. There is a default label ("Parameters") and a default description ("Groupbox containing parameters.") specified. The label of such a parameter group and the description can be set via the parser's changeParameterGroup method. The method must be called before adding the arguments. Running the \ref TensorReconstruction command line tool for MITK Diffusion MiniApp with argument "--xml" ... \code ./MitkDiffusionMiniApps TensorReconstruction --xml \endcode ... will emit following XML description: \code Preprocessing Tools Tensor Reconstruction Takes a .dwi, .fsl/.fslgz file as input and saves the computed reconstructed tensor to the specified file. It also allows for a threshold to be set, to exclude low b values from the reconstruction process. MBI Groupbox containing parameters. input input raw dwi (.dwi or .fsl/.fslgz) input i input outFile output file outFile o output b0Threshold baseline image intensity threshold b0Threshold t \endcode -The generated user interface from this XML description is depicted in the following screenshot: -\imageMacro{generated_ui_tensor_reconstruction.png, "Generated UI of TensorReconstruction command line tool", 10} +This XML description is used for automatic user interface generation in MITK Workbench. The generated user interface is depicted in the following screenshot: +\imageMacro{generated_ui_tensor_reconstruction.png, "Generated UI of TensorReconstruction command line tool in MITK Workbench", 10} + +\section MiniAppCommandLineToolHowToPageWorkbenchIntegration Integrating a command line tool into MITK Workbench + +At current state of development MiniApps are not fully supported by the MITK Workbench. +Nevertheless, there's a workaround for integrating command line tools via the Command Line Modules plug-in: + +Create an executable file (e.g. sh-file using Linux OS or bat-file using Windows OS) in the directory where your MiniApp binary is located. +The sh-file for the \ref TensorReconstruction command line tool has following content: + +\code +#!/bin/bash +if [[ $1 == "--xml" || $1 == "--XML" ]]; +then + echo ' + + Preprocessing Tools + Tensor Reconstruction + Takes a .dwi, .fsl/.fslgz file as input and saves the computed reconstructed tensor to the specified file. It also allows for a threshold to be set, to exclude low b values from the reconstruction process. + MBI + + + Groupbox containing parameters. + + input + + input raw dwi (.dwi or .fsl/.fslgz) + input + i + input + + + outFile + + output file + outFile + o + output + + + b0Threshold + + baseline image intensity threshold + b0Threshold + t + + + + ' +else + BASEDIR=$(dirname $0) + echo "Calling parameters" $* + $BASEDIR/MitkDiffusionMiniApps TensorReconstruction $* +fi +\endcode + +For each command line tool the including MiniApp binary, the concrete command line tool name, and its XML output have to be specified. + +The executable file has be to be anncounced in MITK Workbench. This can be done in Preferences window: +Click 'Window' -> 'Preferences', and select 'Command Line Modules'. You can add directories containing executable files or you can select single executable files. +Click 'OK' button. +The configured command line tools are now available via the drop-down box of the Command Line Modules tab. */