CTK  0.1.0
The Common Toolkit is a community effort to provide support code for medical image analysis, surgical navigation, and related projects.
Libs/CommandLineModules/README.md
Go to the documentation of this file.
1 CTK Command Line Modules {#CommandLineModules_Page}
2 ========================
3 
4 \brief Overview about the Command Line Modules support in CTK.
5 
6 \internal This page is best viewed in its [Doxygen processed]
7 (http://www.commontk.org/docs/html/CommandLineModules_Page.html) form. \endinternal
8 
9 [TOC]
10 
11 CTK provides an API for interfacing with self-describing *runnable* modules which can provide an
12 XML description of their supported parameters. A runnable module is
13 usually (but not constrained to) a local executable and also referred to as a *command line module*.
14 
15 The XML schema for the parameter description and most of the supported feature set for a module
16 has been adopted from the [Slicer Execution Model](http://www.slicer.org/slicerWiki/index.php/Slicer3:Execution_Model_Documentation).
17 
18 The API provided by CTK allows the management, GUI generation, and asynchronous execution
19 of such modules in a toolkit-independent and interoperable way. Application writers can rely on the
20 provided libraries and their API to quickly integrate command line modules into their applications.
21 
22 Developers who want to create command line modules which can be run by using the provided tools will
23 want to have a look at the *Creating Modules* section below. Everything else targets application writers
24 who want to host and mange these command line modules.
25 
26 CTK also comes with an example application, called *ctkCommandLineModuleExplorer* which can be used
27 to load different kinds of modules, to verify their correctness, to run - and finally inspect their output.
28 
29 
30 Features
31 --------
32 
33 Here is short overview about the provided feature set:
34 
35 - Clear separation in front and back ends (see *Library Design* below)
36 - XML validation and error reporting
37 - Caching of XML descriptions
38 - Partially thread-safe, allowing to concurrently add and remove modules
39 - Asynchronous communication with running modules
40  + Start/pause/cancel support (back-end and operating system dependent)
41  + Result reporting
42  + Output reporting
43 
44 CTK also provides stable and feature-rich implementations of a Qt based front-end and a back-end handling local processes.
45 
46 ### Qt Gui front-end
47 
48 The provided front-end implementation creates a Qt widgets based user interface. It also allows to customize the
49 GUI generation process, see the ctkCmdLineModuleFrontendQtGui class for more information.
50 
51 ### Local process back-end
52 
53 The default back-end for running modules can handle local executables and runs them in a separate process. See
54 the ctkCmdLineModuleBackendLocalProcess class for details.
55 
56 
57 Creating Modules
58 ----------------
59 
60 Module writers usually need to create an XML file describing the parameters which are understood by the module (the actual
61 way how such an XML description is provided actually depends on the back-end for which the module is written). For locally
62 executable modules (e.g. command line programs), the XML description is usually emitted to the standard output channel by
63 the executable itself when it is called with a *--xml* command line argument.
64 
65 The valid XML structure for the parameter description is defined in the corresponding [schema documentation](ctkCmdLineModule.xsd)
66 ([absolute link](http://www.commontk.org/docs/html/ctkCmdLineModule.xsd)).
67 
68 Please note that running a module may fail due to an invalid XML description. The strictness of validation is specific to the
69 application you are using to run the module. However, making sure the XML validates agains the given schema (raw schema file
70 [here](https://raw.github.com/commontk/CTK/master/Libs/CommandLineModules/Core/Resources/ctkCmdLineModule.xsd)).
71 
72 ### Progress and Result reporting
73 
74 A module may report progress and intermediate results during its execution. The actual reporting mechanism depends on the type
75 of module. For a local executable being run for example by the ctkCmdLineModuleBackendLocalProcess back-end, reporting is done
76 by printing XML fragments to the standard output channel.
77 
78 For example a progress report containing a progress value and text would look like:
79 
80  <filter-start>
81  <filter-name>My Filter</filter-name>
82  <filter-comment>Starting custom filter...</filter-comment>
83  </filter-start>
84  <filter-progress-text progress="0.2">Current progress: 0.2 (from [0,1.0])</filter-progress-text>
85  <filter-end/>
86 
87 Here is the XML [progress and result schema documentation](ctkCmdLineModuleProcess.xsd)
88 ([absolute link](http://www.commontk.org/docs/html/ctkCmdLineModuleProcess.xsd)) describing the valid XML fragments. The raw
89 schema file is available [here](https://raw.github.com/commontk/CTK/master/Libs/CommandLineModules/Backend/LocalProcess/Resources/ctkCmdLineModuleProcess.xsd).
90 
91 
92 Library Design
93 --------------
94 
95 The Command Line Module support consists of a \subpage CommandLineModulesCore_Page library and so-called
96 \subpage CommandLineModulesBackEnds_Page and \subpage CommandLineModulesFrontEnds_Page.
97 
98 A front-end, a sub-class of ctkCmdLineModuleFrontend, represents a set of parameter values for a specific
99 module, usually associated with some kind of user interface. Front-end implementations need not be accessible outside
100 of the defining library, but may be exposed to allow the configuration of the GUI generation process by
101 sub-classing the corresponding ctkCmdLineModuleFrontendFactory implementation. A front-end can be "run" by
102 calling the ctkCmdLineModuleManager::run(ctkCmdLineModuleFrontend*) method and the object returned by the run()
103 method is used to communicate with the running module. A front-end can be "run" multiple times (with possibly different
104 parameter values) simultaneously.
105 
106 A back-end, a sub-class of ctkCmdLineModuleBackend, knows how to actually "run" a module. Back-end implementations
107 express their capabilities by overriding the ctkCmdLineModuleBackend::schemes() method and providing a list of URL
108 schemes this back-end can handle. For example, the ctkCmdLineModuleBackendLocalProcess back-end returns "file" since
109 it can handle URLs pointing to local resources (executables). Further, a back-end knows how to get a time-stamp and
110 the module XML description for a specific module.
111 
112 The central class for managing modules is the ctkCmdLineModuleManager. There must be at least one back-end registered
113 with the manager for module registrations to succeed. A module is registered by calling the
114 ctkCmdLineModuleManager::registerModule(const QUrl&) method, providing the URL to the module. If the URL scheme is not handled
115 by a previously registerd back-end, an exception is thrown. If registration succeeds, the method returns a
116 ctkCmdLineModuleReference object.
117 
118 Creating specific front-ends for a given module is actually independent of the ctkCmdLineModuleManager, except that a
119 ctkCmdLineModuleReference object is needed. To create a front-end, usually the
120 ctkCmdLineModuleFrontendFactory::create(const ctkCmdLineModuleReference&) method is called, returning a
121 ctkCmdLineModuleFrontend pointer.
122 
123 This separation of concerns in front and back ends allows for an extensible and flexible design. Front-ends and back-ends
124 work independent of each other and can be combined arbitrarly.
125 
126 
127 Quick Start
128 -----------
129 
130 Here is a small code example to get you started quickly. We first instantiate a ctkCmdLineModuleManager object, using
131 a strict validation mode and the built-in caching mechanism.
132 
133 \snippet ModuleManager/main.cpp instantiate-mm
134 
135 Next, we instantiate and register a back-end.
136 
137 \snippet ModuleManager/main.cpp register-backend
138 
139 Now we register an executable as a module with the manager.
140 
141 \snippet ModuleManager/main.cpp register-module
142 
143 To create a front-end, we use the Qt widgets implementation.
144 
145 \snippet ModuleManager/main.cpp create-frontend
146 
147 Last, we run the front-end instance, using the default values for the module parameters.
148 
149 \snippet ModuleManager/main.cpp run-module
150 
151 After the ctkCmdLineModuleManager::run() method returns, we wait for the running module to finish and print out
152 some data reported by it.
153