3D Slicer Command Line Interface(CLI)

1.ExtensionWizard创建初始框架

1.1 ExtensionWizard综述

ExtensionWizard是一个工具的集合，既可以利用Slicer中的图像用户接口（GUI）访问，也可以在一个独立的Python控制台使用命令行接口（CLI）访问。

Slicer Module通常包含几个不同种类的文件，例如CMakeList.txt、源文件、资源文件。很多情况下，文件名以及文件中的文本字符串的名字都是相关的，需要同步以便编译。

一个Extension把一个或多个Module封装成包，这个包可以通过Slicer下载。

ExtensionWizard就是一个工具，它可以简化创建Extension的流程。

1.2使用图形用户接口GUI访问ExtensionWizard

为了使用ExtensionWizard，我们只需要安装最近的Slicer版本，开启，然后选择“Extension Wizard”模块。

Extension提供了一个“模板机制”简化了创建Extension的流程。这个流程可以自动为我们创建文件，并且提供合适的文件名的代码，这样我们就能立刻上手：

点击“Create Extension”；

确定拓展文件名，并确定一个空的目录作为目标文件夹，点击OK；

点击“Add module to Extension”;

确定名称和模块类型。大多数第一次开发人员应该选择“Scripted”作为模块类型。因为只有Python脚本模块很容易创建并且不需要使用一个自己组建好的Slicer。点击“OK”；

选中我们自己的模块，然后下载。选择“Add selected module to search path”自动下载；

通过“Module List”打开我们新创建的模块。如果我们启用了开发者模式，修改之后并不需要重启Slicer，直接重新加载就好了。

1.3 使用命令行接口CLI访问ExtensionWizard（高级用户）

Extension提供了一个“模板机制”简化了创建Extension的流程。这个流程可以自动为我们创建带有合适名字的文件，我们只需要在模板内进行一些关键的内容替换就可以了。

先介绍几个术语：

模板template：包含用于创建新实体（Extension、Module）的文件目录；

templatKey：在模块文件名和标识符中使用的文本字符串；

目的地destination：放置新代码的目录；

名字name：创建新实体（Extension、Module）的名字。代码将会被放在这个名字的子目录中，同时这个名字将会取代templateKey。

实例分析：
 1 # List available templates
 2 slicerExtensionWizard --listTemplates
 3  
 4 # Create an extension with two modules; one written in C++, and one in Python
 5 slicerExtensionWizard --create MyExtension ~/code/
 6 cd ~/code/MyExtension
 7 slicerExtensionWizard --addModule loadable:MyCppModule
 8 slicerExtensionWizard --addModule scripted:MyPythonModule
 9  
10 # Create a superbuild extension with a CLI module
11 slicerExtensionWizard --create superbuild:MyCLIExtension ~/code/
12 slicerExtensionWizard --addModule cli:MyCLI ~/code/MyCLIExtension
这个拓展尝试更新Extension的CMakeLists.txt，包含新的模块。
这个常备的模板包括一个占位符，这个占位符指明了新的'add_subdirectory'应该插在哪里（如果这个占位符不存在，向导尝试在最近存在的‘add_subdirectory’后面添加一个新的‘add_subdirectory’）。
注意：目的地目录destination direction（extension）是可选的，默认情况下是当前目录。在上面的例子中，我们使用cd转到一个新创建的extension目录

Slicer中提供的常备用的模板（Extension、Module）详细参考如下网址：

https://github.com/Slicer/Slicer/tree/master/Utilities/Templates

1.4 三个模块的区别

CLI：提供自定义命令行接口的模块；

Loadable：Slicer中提供新功能的C++模块；

Scripted：Slicer中提供新功能的Python模块；

1.5 使用自定义的模板

默认情况下，ExtensionWizard使用Slicer提供的模板。当然，我们也可以通过参数'--templatePath'添加自己的模板:
1 # Add custom templates; expects to find subdirectories under the path matching
2 # a template type, e.g. 'modules'
3 slicerExtensionWizard --templatePath ~/code/Templates
4  
5 # Add custom module templates
6 slicerExtensionWizard --templatePath modules=~/code/Templates
1.6 使用Extensions

组建building

如果我们的程序并不是使用“Pure Python”编写的，为了使用Extension功能我们必须先编译。
下面的方法在大多数情况下都是有用的：
1 Slicer_DIR=/path/to/slicer/superbuild
2 cd ~/code/MyExtension
3 mkdir ../MyExtension-build
4 cd ../MyExtension-build
5  
6 # You may also want to pass '-G "<generator>"' here (required on Windows)
7 cmake -DSlicer_DIR:PATH=${Slicer_DIR} ../MyExtension
8 cmake --build . --config Release  # Or --config Debug
更多的细节，我们可以参考FAQ中的问题：How to build an extension？
https://www.slicer.org/wiki/Documentation/Nightly/Developers/FAQ#How_to_build_an_extension_.3F
安装installing

我们不需要安装extension，但是我们需要告诉Slicer去哪里找到这个extension。

After building your extension (if needed; you can skip this for pure-Python extensions), open Slicer's Application Settings dialog, select "Modules" from the list, and add additional module paths to point to the full path to your extension. For example:

~/code/MyExtension/build/lib/Slicer-<version>/qt-loadable-modules

~/code/MyExtension/build/lib/Slicer-<version>/qt-scripted-modules

~/code/MyExtension/MyPythonModule

2.在Slicer源代码树外Building模块

Slicer支持的不同类型的模块Modules很容易在源代码树外进行编译。

注意：在build C++模块之前，我们应该确保在本机上已经利用源码Build了 Slicer。

下面的例子是为Unix系列平台设计的的，但是同样适应Windows：

假设：新编写的module源代码在文件夹‘MyModule’中，外部编译可以通过下面代码实现：
1 $ mkdir MyModule-build
2 $ cd MyModule-build
3 $ cmake -DSlicer_DIR:PATH=/path/to/Slicer-Superbuild/Slicer-build ../MyModule
4 $ make
为了使上面代码有效，我们除了需要在最顶层文件“CMakeLists.txt”文件中添加“ cmake_minimum_required”,也要确保在设置模块名字“MODULE_NAME”之后，添加如下代码：
1 find_package(Slicer REQUIRED)
2 include(${Slicer_USE_FILE})
=================================================================================
最全面的代码示例如下所示：
 1 cmake_minimum_required(VERSION 2.8.9)  <- - - - ADD THIS
 2  
 3 find_package(Slicer COMPONENTS ConfigurePrerequisites)  <- - - - ADD THIS
 4 project(EmptyExtensionTemplate) <- - - - ADD THIS
 5  
 6 #-----------------------------------------------------------------------------
 7 set(MODULE_NAME ${PROJECT_NAME})
 8 set(MODULE_TITLE ${MODULE_NAME})
 9  
10 string(TOUPPER ${MODULE_NAME} MODULE_NAME_UPPER)
11  
12 #-----------------------------------------------------------------------------
13 find_package(Slicer REQUIRED)  <- - - - - - - ADD THIS
14 include(${Slicer_USE_FILE})  <- - - - - - - - ADD THIS
15  
16 #-----------------------------------------------------------------------------
17 add_subdirectory(Logic)
18  
19 #-----------------------------------------------------------------------------
20 set(MODULE_EXPORT_DIRECTIVE "Q_SLICER_QTMODULES_${MODULE_NAME_UPPER}_EXPORT")
21  
22 [...]
成功编译了Slicer模块之后，Slicer的模块可执行程序和库就位于我们的模块组建目录中build_dir/lib/Slicer-X.Y/module_type。
然后我们需要把这个目录添加到Application Setting GUI的Addition module路径中，这样就可以便面重新编译Super-build可以直接测试了。
更详细的“目录结构”可以参考如下：

https://www.slicer.org/wiki/Documentation/Nightly/Developers/DirectoryStructure
==============================================================================

关于此部分容易犯错误的地方进行总结：

2.1 在Slicer build-tree中，哪里是Slicer 模块？
Slicer模块的可执行程序和库位于Slicer组建目录中“Slicer-Superbuild/Slicer-build”中。

2.2 如何修订外部模块的本地版本？

https://www.slicer.org/wiki/Documentation/Nightly/Developers/Build_Module

2.3 如何从C++ 可加载模块中调用CLI模块？
Calling CLI module from a C++ loadable module：

http://slicer-devel-archive.65872.n3.nabble.com/Calling-CLI-module-from-a-C-loadable-module-tt4031930.html

Example: vtkSlicerCropVolumeLogic.cxx#L318-351：

https://github.com/Slicer/Slicer/blob/master/Modules/Loadable/CropVolume/Logic/vtkSlicerCropVolumeLogic.cxx#L318-351

2.4 如何从命令行中调用CLI模块？

对于Windows操作系统，我们要使用Slicer应用程序的全名（文件名+后缀）。

Slicer.exe --launch CastScalarVolume input.mha output.mha

如果想要得到CLI模块支持的命令行参数帮助，运行：

Slicer.exe --launch CastScalarVolume

c:SomeWriteAbleDirectoryusage.txt

3.学习资源

目前已经存在的CLI模块的源码：

http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Modules/CLI/