diff --git a/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/FirstSteps.dox b/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/FirstSteps.dox index 537a0091b0..7b01d0b3e1 100644 --- a/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/FirstSteps.dox +++ b/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/FirstSteps.dox @@ -1,14 +1,15 @@ /** \page FirstSteps First steps in Development This section will show you how to extend MITK for your own project. */ diff --git a/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/MiniAppCommandLineTool/MiniAppCommandLineToolHowTo.dox b/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/MiniAppCommandLineTool/MiniAppCommandLineToolHowTo.dox new file mode 100644 index 0000000000..3164a26673 --- /dev/null +++ b/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/MiniAppCommandLineTool/MiniAppCommandLineToolHowTo.dox @@ -0,0 +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 + +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. + +*/ diff --git a/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/MiniAppCommandLineTool/images/generated_ui_tensor_reconstruction.png b/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/MiniAppCommandLineTool/images/generated_ui_tensor_reconstruction.png new file mode 100644 index 0000000000..7de0734e66 Binary files /dev/null and b/Documentation/Doxygen/DeveloperManual/Starting/FirstSteps/MiniAppCommandLineTool/images/generated_ui_tensor_reconstruction.png differ diff --git a/Documentation/Doxygen/UserManual/MiniApps.dox b/Documentation/Doxygen/UserManual/MiniApps.dox index 104522399f..7b7af0fa00 100644 --- a/Documentation/Doxygen/UserManual/MiniApps.dox +++ b/Documentation/Doxygen/UserManual/MiniApps.dox @@ -1,70 +1,70 @@ /** \page MiniAppExplainPage MITK MiniApps -\section MiniAppDescription What are MiniApps +\section MiniAppExplainPageDescription What are MiniApps MiniApps are small compilations of command line tools. Each of these tools is designed to fulfill one simple task, e.g. resample an image or extract image statistics of a given region of interest (ROI). Several tools that relate to -a similiar topic or research area are grouped into one MiniApp. +a similar topic or research area are grouped into one MiniApp. They are intended to provide command line access to a variety of features of MITK, thus facilitating batched processing of data. -\section MiniAppUsage Usage +\section MiniAppExplainPageUsage Usage -The MiniApps are built in a self-describing way. When calling a MiniApp without any arguements it will list +The MiniApps are built in a self-describing way. When calling a MiniApp without any arguments it will list all available sub-tools. When calling e.g. the DiffusionMiniApp it will look similarly to this: \code $./MitkDiffusionMiniApps Please choose the mini app to execute: (0) BatchedFolderRegistration (1) CopyGeometry (2) DicomFolderDump (3) DiffusionIndices (4) DwiDenoising (5) ExportShImage (6) ExtractImageStatistics (7) FiberDirectionExtraction (8) FiberProcessing (9) FileFormatConverter (10) GibbsTracking (11) LocalDirectionalFiberPlausibility (12) MultishellMethods (13) NetworkCreation (14) NetworkStatistics (15) PeakExtraction (16) PeaksAngularError (17) QballReconstruction (18) StreamlineTracking (19) TensorDerivedMapsExtraction (20) TensorReconstruction Please select: \endcode In order to select one of those tools simply append the displayed name to call, e.g. GibbsTracking this will provide a listing of the parameters of that tool: \code -$./MitkDiffusionMiniApps GibbsTracking +$./MitkDiffusionMiniApps GibbsTracking [1.081] Start GibbsTracking .. -i, --input, input image (tensor, Q-ball or FSL/MRTrix SH-coefficient image) -p, --parameters, parameter file (.gtp) -m, --mask, binary mask image (optional) -s, --shConvention, sh coefficient convention (FSL, MRtrix) (optional), (default: FSL) -o, --outFile, output fiber bundle (.fib) -f, --noFlip, do not flip input image to match MITK coordinate convention (optional) \endcode To execute the tool with parameters an exemplary call would look like this: \code -$./MitkDiffusionMiniApps GibbsTracking -i test.dti -p param.gtp -o /tmp/fiber.fib +$./MitkDiffusionMiniApps GibbsTracking -i test.dti -p param.gtp -o /tmp/fiber.fib \endcode -\section MiniAppAvailableList Available MiniApps +\section MiniAppExplainPageAvailableList Available MiniApps -\li \ref DiffusionMiniApps +\li \subpage DiffusionMiniApps */