Documentation/Command Line Interface

From Commontk
Jump to navigationJump to search
Home < Documentation < Command Line Interface

What are CLI modules?

"CLI (commandline interface) modules" are standalone tools (for instance, a segmentation algorithm) that offer a commandline interface and a --xml switch that outputs a machine-readable kind of --help (XML description of their supported parameters, values, hints, etc.). This makes it possible to use such CLIs as some kind of "plugins" for rich GUI applications that offer visualization and automatically generated GUI panels for parameter adjustment. Also, the whole data handling is left to the host application (which may e.g. implement a batch processing pipeline, running the CLI systematically on all relevant data for a particular study), and it becomes possible to use the same algorithm in various different host applications and contexts, by agreeing on a common standard for the --xml output.

CTK Support for CLI Modules

CTK provides an API for interfacing with such self-describing command line modules, and the XML schema for the parameter description and most of the supported feature set for a module has been adopted from the Slicer Execution Model (the first host where this idea originated).

The API provided by CTK allows the management, GUI generation, and asynchronous execution of such modules in a toolkit-independent and interoperable way. Application writers can rely on the provided libraries and their API to quickly integrate command line modules into their applications. CTK also comes with an example application, called ctkCommandLineModuleExplorer which can be used to load different kinds of modules, to verify their correctness, to run - and finally inspect their output.

More information on CTK's support for CLI modules
There is a well-written page in the Doxygen docs (and a group for the classes), as well as a separate wiki page.

Example Applications

CLI modules are already supported by a number of host applications, e.g. 3D Slicer, NiftyView / MITK Workbench, GIMIAS, MedInria, MeVisLab, nipype and more. You can see some examples on the CLI In Context page.

Background Information / Specs

Currently, the CLI module standard is documented as Slicer's Execution Model. There is an XML schema definition (auto-generated pretty-printed documentation) that was created retroactively, and not all existing modules strictly follow the spec. However, one problem is that the schema definition does not facilitate to specify that e.g. the order of author and description elements is irrelevant, so the schema is more strict than the actual implementation in some respects (and less strict in some other).

You are welcome to join the ctk-developers mailing list for discussing related questions.

TODO: The standard (Slicer execution model description) should probably be moved to the CTK domain.

Creating your own CLI modules

There is a "SlicerExecutionModel" project at GitHub that shall help you with implementing new CLIs, e.g. by offering means to automatically parse commandline arguments based on the XML spec.

The Slicer documentation also contains instructions on how to extend Slicer via CLI modules or other means.

If you want to implement a Python-based solution, you might also be interested in the code available on GitHub and the Python Package Index that was developed as part of the CLI integration in MeVisLab during the NA-MIC summer project week 2013.

Examples of CLI Modules

Wherever feasible, Slicer developers are encouraged to encapsulate functionality as CLI modules.