Slicer Wiki - User contributions [en]

Documentation/Nightly/Developers/Build Instructions

2017-04-25T21:20:11Z

Fbudin: /* error when starting Slicer: NameError: name 'getSlicerRCFileName' is not defined */

<noinclude>{{documentation/versioncheck}}</noinclude>
{{:{{FULLPAGENAME}}/Prerequisites}}

 

{{:{{FULLPAGENAME}}/CheckoutSourceCode}}

 

{{:{{FULLPAGENAME}}/Configure}}

 

{{:{{FULLPAGENAME}}/Compile}}

 

{{:{{FULLPAGENAME}}/Run}}

 

{{:{{FULLPAGENAME}}/Test}}

 

{{:{{FULLPAGENAME}}/Package}}



== Common errors ==

=== CMake complains during configuration ===
CMake may not directly show what's wrong; try to look for log files of the form BUILD/CMakeFiles/*.log (where BUILD is your build directory) to glean further information.

=== A tool returned an error code from "Generating vtksysProcessFwd9xEnc.c" ===
The application has failed to start because its side-by-side configuration is incorrect.
Please see the application event log or use the command-line sxstrace.exe tool for more detail.
Project : error PRJ0019: A tool returned an error code from "Generating
vtksysProcessFwd9xEnc.c"
'''Suggested solution: [[Documentation/{{documentation/version}}/Developers/Build_Instructions/Prerequisites#Windows|Install SP1 of Visual Studio]]'''

See also:

* [http://www.kitware.com/blog/home/post/4|"Deploying on Windows with DLL Manifest Issues"] (Bill Hoffman, Kitware blog).
* [https://stackoverflow.com/questions/13217174/how-to-properly-setup-vs2008-for-x64-programing/13222870#13222870| How to create a custom installer to correct a missing WinSXS manifest entry] (StackOverflow).

=== error: ‘class QList<QString>’ has no member named ‘reserve’ ===
/nfs/Users/blowekamp/QtSDK/Desktop/Qt/474/gcc/include/QtCore/qdatastream.h: In function ‘QDataStream& operator>>(QDataStream&, QList<T>&) [with T = QString]’:
/nfs/Users/blowekamp/QtSDK/Desktop/Qt/474/gcc/include/QtCore/qstringlist.h:247: instantiated from here
/nfs/Users/blowekamp/QtSDK/Desktop/Qt/474/gcc/include/QtCore/qdatastream.h:246: error: ‘class QList<QString>’ has no member named ‘reserve’
You have multiple Qt versions installed on your machine. Try removing the Qt version installed on the system.

=== libarchive.so: undefined reference to `SHA256_Update' ===

Linking CXX executable ../../../../../bin/MRMLLogicCxxTests
/home/benjaminlong/work/slicer/Slicer-SuperBuild-Debug/LibArchive-install/lib/libarchive.so: undefined reference to `SHA256_Update'
/home/benjaminlong/work/slicer/Slicer-SuperBuild-Debug/LibArchive-install/lib/libarchive.so: undefined reference to `SHA256_Final'
/home/benjaminlong/work/slicer/Slicer-SuperBuild-Debug/LibArchive-install/lib/libarchive.so: undefined reference to `SHA256_Init'
/home/benjaminlong/work/slicer/Slicer-SuperBuild-Debug/LibArchive-install/lib/libarchive.so: undefined reference to `MD5_Init'

Solution:
cd Slicer-SuperBuild
rm -rf LibArchive-*
make -j4

Details:
* http://na-mic.org/Mantis/view.php?id=1616
* http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=18923
* http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=18969

=== No rule to make target `/usr/lib/x86_64-linux-gnu/libGL.so' ===
See http://techtidings.blogspot.com/2012/01/problem-with-libglso-on-64-bit-ubuntu.html

=== X11 Window errors at start time ===
<pre>
X Error: BadWindow (invalid Window parameter) 3
Extension: 137 (Uknown extension)
Minor opcode: 4 (Unknown request)
Resource id: 0x4200199
X Error: BadWindow (invalid Window parameter) 3
Extension: 137 (Uknown extension)
Minor opcode: 4 (Unknown request)
Resource id: 0x42001a6
X Error: BadWindow (invalid Window parameter) 3
Extension: 137 (Uknown extension)
Minor opcode: 4 (Unknown request)
Resource id: 0x42001b3
</pre>

Solution:
* Reinstall Nvidia drivers (that also rewrite the xorg.conf file).

=== error C2061: syntax error : identifier 'ssize_t' ===
<pre>
4>1>Compiling...
4>1>version.c
4>1>c:\chene\winbin64\slicer4\cmcurl\urldata.h(585) : error C2061: syntax error : identifier 'ssize_t'
4>1>c:\chene\winbin64\slicer4\cmcurl\urldata.h(593) : error C2365: 'fread' : redefinition; previous definition was 'function'
4>1> C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\include\stdio.h(248) : see declaration of 'fread'
4>1>c:\chene\winbin64\slicer4\cmcurl\urldata.h(610) : error C2059: syntax error : '}'
</pre>

Solution:
* See [[#A_tool_returned_an_error_code_from_.22Performing_configure_step_for_....22]]

=== ld: framework not found QtWebKit ===

<pre>
[...]
Linking CXX shared library libPythonQt.dylib
ld: framework not found QtWebKit
clang: error: linker command failed with exit code 1 (use -v to see invocation)
make[8]: *** [libPythonQt.dylib] Error 1
[...]
</pre>

See Slicer issue [http://na-mic.org/Mantis/view.php?id=2860 #2860]

Workaround:
* See http://public.kitware.com/Bug/view.php?id=13765#c31824

Solution:
* Use a [http://www.cmake.org/files/dev/?C=M;O=D recent nightly build of CMake]. It includes patch [http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=cc676c3a cc676c3a]. Note also that the coming version of CMake 2.8.11 will work as expected.

=== On MacOSX 10.8, CMake hangs forever ===

Issue: http://www.na-mic.org/Bug/view.php?id=2957

Solution: Use CMake build >= 2.8.10.20130220-g53b279. See http://www.cmake.org/files/dev/cmake-2.8.10.20130220-g53b279-Darwin-universal.tar.gz

Details:

CMake folks (Thanks Brad King :)) fixed an issue that was preventing the most recent nightly from being used to successfully compile Slicer. The fix has been tested and is known to work. Tomorrow nightly build of CMake and by extension the coming release of CMake 2.8.11 will work.

If you are curious about the details, check the commit message:

http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=1df09e57 [^]

The associated CMake test have also been updated:

http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=bff3d9ce [^]

 

=== On MacOSX 10.8/10.9 with XQuartz, 'X11/Xlib.h' file not found ===

Issue: http://www.na-mic.org/Bug/view.php?id=3405

Workaround: Build with -DSlicer_USE_PYTHONQT_WITH_TCL:BOOL=OFF

Tcl is required only for EMSegment module.

Details: See http://www.na-mic.org/Bug/view.php?id=3405
 

=== svn: E175002: Unable to connect to a repository at URL XXX ===

Issue: Cisco AnyConnect is installed with the "Web Security" option checked (default), which blocks Subversion checkouts even when inactive!

Solution: Uninstall and reinstall Cisco AnyConnect, deselecting the "Web Security" feature during install

[[File:CiscoAnyConnectInstallOptions.png]]

=== My antivirus software reports that files in my build directory are infected ===

Although usually antivirus software does not interfere with the build process, it is recommended to disable antivirus and search indexing for build directories to improve performance and minimize the chance of concurrent file access problems.

=== Visual Studio compiler crashes ===

* If you use Visual Studio 2008, make sure Visual Studio 2008 service pack 1 is installed
* Build Slicer in a short directory, for example source code in C:\S4, binary directory C:\S4D or C:\S4R

=== 'QSslSocket' : is not a class or namespace name ===

This error message occurs if Slicer is configured to use SSL but Qt is built without SSL support.

Either set Slicer_USE_PYTHONQT_WITH_OPENSSL to OFF when configuring Slicer build in CMake, or build Qt with SSL support.

=== error: Missing Qt module QTWEBKIT ===

CMake Error at CMake/SlicerBlockFindQtAndCheckVersion.cmake:43 (message):
error: Missing Qt module QTWEBKIT
Call Stack (most recent call first):
CMake/SlicerBlockFindQtAndCheckVersion.cmake:88 (__SlicerBlockFindQtAndCheckVersion_find_qt)
CMakeLists.txt:607 (include)

Solution:
sudo apt-get -y install libqtwebkit-dev

Details:
* http://slicer-devel.65872.n3.nabble.com/Re-slicer-devel-Digest-Vol-143-Issue-39-td4037122.html

=== error when starting Slicer: NameError: name 'getSlicerRCFileName' is not defined ===

./Slicer
Traceback (most recent call last):
File "<string>", line 7, in <module>
File "/home/fbudin/Devel/Slicer-SuperBuild-Release/Slicer-build/bin/Python/slicer/slicerqt.py", line 6, in <module>
import vtk
File "/home/fbudin/Devel/Slicer-SuperBuild-Release/VTKv7-build/Wrapping/Python/vtk/__init__.py", line 41, in <module>
from .vtkCommonKit import *
File "/home/fbudin/Devel/Slicer-SuperBuild-Release/VTKv7-build/Wrapping/Python/vtk/vtkCommonKit.py", line 9, in <module>
from vtkCommonKitPython import *
ImportError: /home/fbudin/Devel/Slicer-SuperBuild-Release/VTKv7-build/lib/./libvtkCommonKitPython27D-7.1.so.1: undefined symbol: PyUnicodeUCS2_DecodeUTF8
Traceback (most recent call last):
File "<string>", line 1, in <module>
NameError: name 'getSlicerRCFileName' is not defined
Number of registered modules: 138
error: [/home/fbudin/Devel/Slicer-SuperBuild-Release/Slicer-build/bin/./SlicerApp-real] exit abnormally - Report the problem.

Solution and details [http://na-mic.org/Mantis/view.php?id=3574 here]

== Quick Build on Debian ==
sudo aptitude update
sudo aptitude install subversion git gcc g++ make cmake-curses-gui libqt4-dev
svn co http://svn.slicer.org/Slicer4/trunk Slicer
mkdir Slicer-SuperBuild-Debug
cd Slicer-SuperBuild-Debug
cmake ../Slicer
make -j5

# runtime dependency:
sudo aptitude install python-tk

== Quick Build on Fedora 20 ==

Thanks to Bill Lorensen, you will find below the instruction to quickly build Slicer on Fedora 20:

yum groupinstall "C Development Tools"
yum install git-core
yum install svn
yum install libX11-devel
yum install libXt-devel
yum install mesa-libGL-devel
yum install mesa-libGLU-devel
yum install cmake
yum install tcl-devel
yum install python-devel
yum install qt-devel
yum install qt-webkit-devel

svn co http://svn.slicer.org/Slicer4/trunk Slicer
mkdir Slicer-SuperBuild-Debug
cd Slicer-SuperBuild-Debug
cmake ../Slicer
make -j5

Reference: http://slicer-devel.65872.n3.nabble.com/Fedora-20-Slicer-Experience-tt4030845.html

Documentation/Nightly/Developers/Build Instructions

2017-04-25T21:19:37Z

Fbudin: /* Common errors */

<noinclude>{{documentation/versioncheck}}</noinclude>
{{:{{FULLPAGENAME}}/Prerequisites}}

 

{{:{{FULLPAGENAME}}/CheckoutSourceCode}}

 

{{:{{FULLPAGENAME}}/Configure}}

 

{{:{{FULLPAGENAME}}/Compile}}

 

{{:{{FULLPAGENAME}}/Run}}

 

{{:{{FULLPAGENAME}}/Test}}

 

{{:{{FULLPAGENAME}}/Package}}



== Common errors ==

=== CMake complains during configuration ===
CMake may not directly show what's wrong; try to look for log files of the form BUILD/CMakeFiles/*.log (where BUILD is your build directory) to glean further information.

=== A tool returned an error code from "Generating vtksysProcessFwd9xEnc.c" ===
The application has failed to start because its side-by-side configuration is incorrect.
Please see the application event log or use the command-line sxstrace.exe tool for more detail.
Project : error PRJ0019: A tool returned an error code from "Generating
vtksysProcessFwd9xEnc.c"
'''Suggested solution: [[Documentation/{{documentation/version}}/Developers/Build_Instructions/Prerequisites#Windows|Install SP1 of Visual Studio]]'''

See also:

* [http://www.kitware.com/blog/home/post/4|"Deploying on Windows with DLL Manifest Issues"] (Bill Hoffman, Kitware blog).
* [https://stackoverflow.com/questions/13217174/how-to-properly-setup-vs2008-for-x64-programing/13222870#13222870| How to create a custom installer to correct a missing WinSXS manifest entry] (StackOverflow).

=== error: ‘class QList<QString>’ has no member named ‘reserve’ ===
/nfs/Users/blowekamp/QtSDK/Desktop/Qt/474/gcc/include/QtCore/qdatastream.h: In function ‘QDataStream& operator>>(QDataStream&, QList<T>&) [with T = QString]’:
/nfs/Users/blowekamp/QtSDK/Desktop/Qt/474/gcc/include/QtCore/qstringlist.h:247: instantiated from here
/nfs/Users/blowekamp/QtSDK/Desktop/Qt/474/gcc/include/QtCore/qdatastream.h:246: error: ‘class QList<QString>’ has no member named ‘reserve’
You have multiple Qt versions installed on your machine. Try removing the Qt version installed on the system.

=== libarchive.so: undefined reference to `SHA256_Update' ===

Linking CXX executable ../../../../../bin/MRMLLogicCxxTests
/home/benjaminlong/work/slicer/Slicer-SuperBuild-Debug/LibArchive-install/lib/libarchive.so: undefined reference to `SHA256_Update'
/home/benjaminlong/work/slicer/Slicer-SuperBuild-Debug/LibArchive-install/lib/libarchive.so: undefined reference to `SHA256_Final'
/home/benjaminlong/work/slicer/Slicer-SuperBuild-Debug/LibArchive-install/lib/libarchive.so: undefined reference to `SHA256_Init'
/home/benjaminlong/work/slicer/Slicer-SuperBuild-Debug/LibArchive-install/lib/libarchive.so: undefined reference to `MD5_Init'

Solution:
cd Slicer-SuperBuild
rm -rf LibArchive-*
make -j4

Details:
* http://na-mic.org/Mantis/view.php?id=1616
* http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=18923
* http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=18969

=== No rule to make target `/usr/lib/x86_64-linux-gnu/libGL.so' ===
See http://techtidings.blogspot.com/2012/01/problem-with-libglso-on-64-bit-ubuntu.html

=== X11 Window errors at start time ===
<pre>
X Error: BadWindow (invalid Window parameter) 3
Extension: 137 (Uknown extension)
Minor opcode: 4 (Unknown request)
Resource id: 0x4200199
X Error: BadWindow (invalid Window parameter) 3
Extension: 137 (Uknown extension)
Minor opcode: 4 (Unknown request)
Resource id: 0x42001a6
X Error: BadWindow (invalid Window parameter) 3
Extension: 137 (Uknown extension)
Minor opcode: 4 (Unknown request)
Resource id: 0x42001b3
</pre>

Solution:
* Reinstall Nvidia drivers (that also rewrite the xorg.conf file).

=== error C2061: syntax error : identifier 'ssize_t' ===
<pre>
4>1>Compiling...
4>1>version.c
4>1>c:\chene\winbin64\slicer4\cmcurl\urldata.h(585) : error C2061: syntax error : identifier 'ssize_t'
4>1>c:\chene\winbin64\slicer4\cmcurl\urldata.h(593) : error C2365: 'fread' : redefinition; previous definition was 'function'
4>1> C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\include\stdio.h(248) : see declaration of 'fread'
4>1>c:\chene\winbin64\slicer4\cmcurl\urldata.h(610) : error C2059: syntax error : '}'
</pre>

Solution:
* See [[#A_tool_returned_an_error_code_from_.22Performing_configure_step_for_....22]]

=== ld: framework not found QtWebKit ===

<pre>
[...]
Linking CXX shared library libPythonQt.dylib
ld: framework not found QtWebKit
clang: error: linker command failed with exit code 1 (use -v to see invocation)
make[8]: *** [libPythonQt.dylib] Error 1
[...]
</pre>

See Slicer issue [http://na-mic.org/Mantis/view.php?id=2860 #2860]

Workaround:
* See http://public.kitware.com/Bug/view.php?id=13765#c31824

Solution:
* Use a [http://www.cmake.org/files/dev/?C=M;O=D recent nightly build of CMake]. It includes patch [http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=cc676c3a cc676c3a]. Note also that the coming version of CMake 2.8.11 will work as expected.

=== On MacOSX 10.8, CMake hangs forever ===

Issue: http://www.na-mic.org/Bug/view.php?id=2957

Solution: Use CMake build >= 2.8.10.20130220-g53b279. See http://www.cmake.org/files/dev/cmake-2.8.10.20130220-g53b279-Darwin-universal.tar.gz

Details:

CMake folks (Thanks Brad King :)) fixed an issue that was preventing the most recent nightly from being used to successfully compile Slicer. The fix has been tested and is known to work. Tomorrow nightly build of CMake and by extension the coming release of CMake 2.8.11 will work.

If you are curious about the details, check the commit message:

http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=1df09e57 [^]

The associated CMake test have also been updated:

http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=bff3d9ce [^]

 

=== On MacOSX 10.8/10.9 with XQuartz, 'X11/Xlib.h' file not found ===

Issue: http://www.na-mic.org/Bug/view.php?id=3405

Workaround: Build with -DSlicer_USE_PYTHONQT_WITH_TCL:BOOL=OFF

Tcl is required only for EMSegment module.

Details: See http://www.na-mic.org/Bug/view.php?id=3405
 

=== svn: E175002: Unable to connect to a repository at URL XXX ===

Issue: Cisco AnyConnect is installed with the "Web Security" option checked (default), which blocks Subversion checkouts even when inactive!

Solution: Uninstall and reinstall Cisco AnyConnect, deselecting the "Web Security" feature during install

[[File:CiscoAnyConnectInstallOptions.png]]

=== My antivirus software reports that files in my build directory are infected ===

Although usually antivirus software does not interfere with the build process, it is recommended to disable antivirus and search indexing for build directories to improve performance and minimize the chance of concurrent file access problems.

=== Visual Studio compiler crashes ===

* If you use Visual Studio 2008, make sure Visual Studio 2008 service pack 1 is installed
* Build Slicer in a short directory, for example source code in C:\S4, binary directory C:\S4D or C:\S4R

=== 'QSslSocket' : is not a class or namespace name ===

This error message occurs if Slicer is configured to use SSL but Qt is built without SSL support.

Either set Slicer_USE_PYTHONQT_WITH_OPENSSL to OFF when configuring Slicer build in CMake, or build Qt with SSL support.

=== error: Missing Qt module QTWEBKIT ===

CMake Error at CMake/SlicerBlockFindQtAndCheckVersion.cmake:43 (message):
error: Missing Qt module QTWEBKIT
Call Stack (most recent call first):
CMake/SlicerBlockFindQtAndCheckVersion.cmake:88 (__SlicerBlockFindQtAndCheckVersion_find_qt)
CMakeLists.txt:607 (include)

Solution:
sudo apt-get -y install libqtwebkit-dev

Details:
* http://slicer-devel.65872.n3.nabble.com/Re-slicer-devel-Digest-Vol-143-Issue-39-td4037122.html

=== error when starting Slicer: NameError: name 'getSlicerRCFileName' is not defined ===

./Slicer
Traceback (most recent call last):
File "<string>", line 7, in <module>
File "/home/fbudin/Devel/Slicer-SuperBuild-Release/Slicer-build/bin/Python/slicer/slicerqt.py", line 6, in <module>
import vtk
File "/home/fbudin/Devel/Slicer-SuperBuild-Release/VTKv7-build/Wrapping/Python/vtk/__init__.py", line 41, in <module>
from .vtkCommonKit import *
File "/home/fbudin/Devel/Slicer-SuperBuild-Release/VTKv7-build/Wrapping/Python/vtk/vtkCommonKit.py", line 9, in <module>
from vtkCommonKitPython import *
ImportError: /home/fbudin/Devel/Slicer-SuperBuild-Release/VTKv7-build/lib/./libvtkCommonKitPython27D-7.1.so.1: undefined symbol: PyUnicodeUCS2_DecodeUTF8
Traceback (most recent call last):
File "<string>", line 1, in <module>
NameError: name 'getSlicerRCFileName' is not defined
Number of registered modules: 138
error: [/home/fbudin/Devel/Slicer-SuperBuild-Release/Slicer-build/bin/./SlicerApp-real] exit abnormally - Report the problem.

Solution [http://na-mic.org/Mantis/view.php?id=3574 here]

== Quick Build on Debian ==
sudo aptitude update
sudo aptitude install subversion git gcc g++ make cmake-curses-gui libqt4-dev
svn co http://svn.slicer.org/Slicer4/trunk Slicer
mkdir Slicer-SuperBuild-Debug
cd Slicer-SuperBuild-Debug
cmake ../Slicer
make -j5

# runtime dependency:
sudo aptitude install python-tk

== Quick Build on Fedora 20 ==

Thanks to Bill Lorensen, you will find below the instruction to quickly build Slicer on Fedora 20:

yum groupinstall "C Development Tools"
yum install git-core
yum install svn
yum install libX11-devel
yum install libXt-devel
yum install mesa-libGL-devel
yum install mesa-libGLU-devel
yum install cmake
yum install tcl-devel
yum install python-devel
yum install qt-devel
yum install qt-webkit-devel

svn co http://svn.slicer.org/Slicer4/trunk Slicer
mkdir Slicer-SuperBuild-Debug
cd Slicer-SuperBuild-Debug
cmake ../Slicer
make -j5

Reference: http://slicer-devel.65872.n3.nabble.com/Fedora-20-Slicer-Experience-tt4030845.html

Documentation/Nightly/Developers/Build Instructions/Configure

2017-04-25T21:15:50Z

Fbudin: /* Unix-like */

<noinclude>{{documentation/versioncheck}}</noinclude>

== CONFIGURE and generate Slicer solution files ==
There are many ways of customizing Slicer's user interface or feature set. This section describes how a custom Slicer build can be configured at build-time. See an overview of various other options in [http://www.na-mic.org/Wiki/images/b/b0/Slicelets2016.pdf this presentation].

You can configure and generate Slicer solution files using either <code>ccmake</code> or <code>cmake-gui</code>.


=== Customizing application build ===
Customized editions of Slicer can be generated without changing Slicer source code, just by modifying CMake variables:
* SlicerApp_APPLICATION_NAME: Custom application name to be used, instead of default "Slicer". The name is used in installation package name, window title bar, etc.
* Slicer_DISCLAIMER_AT_STARTUP: String that is displayed to the user after first startup of Slicer after installation (disclaimer, welcome message, etc).
* Slicer_DEFAULT_HOME_MODULE: Module name that is activated automatically on application start.
* Slicer_DEFAULT_FAVORITE_MODULES: Modules that will be added to the toolbar by default for easy access. List contains module names, separated by space character.
* Slicer_CLIMODULES_DISABLED: Built-in CLI modules that will be removed from the application. List contains module names, separated by semicolon character.
* Slicer_QTLOADABLEMODULES_DISABLED: Built-in Qt loadable modules that will be removed from the application. List contains module names, separated by semicolon character.
* Slicer_QTSCRIPTEDMODULES_DISABLED: Built-in scripted loadable modules that will be removed from the application. List contains module names, separated by semicolon character.
* Slicer_USE_PYTHONQT_WITH_OPENSSL: enable/disable building the application with SSL support (ON/OFF)
* Slicer_USE_SimpleITK: enable/disable SimpleITK support (ON/OFF)
* Slicer_BUILD_SimpleFilters: enable/disable building SimpleFilters. Requires SimpleITK. (ON/OFF)
* Slicer_BUILD_EMSegment: enable/disable building EM segmenter (ON/OFF)
* Slicer_USE_PYTHONQT_WITH_TCL: TCL support (ON/OFF)
* Slicer_EXTENSION_SOURCE_DIRS: Defines additional extensions that will be included in the application package as built-in modules. Full paths of extension source directories has to be specified, separated by semicolons.

=== Per-platform instructions===
==== Windows ====
*'''Recommended''': run ''CMake (cmake-gui)'' from the Windows Start menu
** Set the build directory. For example: <code>C:\Slicer-SuperBuild-Debug</code> or <code>C:\Slicer-SuperBuild-Release</code>.
*** Because Windows [http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath doesn't support file path longer than 260 characters] and has a [http://massmail.spl.harvard.edu/public-archives/slicer-devel/2014/016113.html maximum command line length], please make sure that the total path name of your <code>Slicer-build</code> directory is no longer than 50 characters (for example <code>c:\work\Slicer\Slicer-SuperBuild</code> may work). In case of ''any'' build error, use very short directory names: C:\S4 for source directory, C:\S4D for debug build, C:\S4R for release build.
*** You cannot use the same build tree for both release or debug mode builds. If both build types are needed, then the same source directory can be used, but a separate build directory should be created and configured for each build type.
** Select your compiler: Visual Studio 12 2013 Win64
** Configure using default options. You may get a configuration error that <code>QT_QMAKE_EXECUTABLE</code> is not set, which is normal.
** Verify that <code>QT_QMAKE_EXECUTABLE</code> variable is set correctly:
*** CMake may automatically detect an installed version of Qt, but you may want to use a custom built version of Qt (e.g. in Debug mode for use with the designer).
*** Set <code>QT_QMAKE_EXECUTABLE</code> to the path of the <code>qmake.exe</code>, which is inside the <code>bin</code> directory (for example, <code>C:/path/to/qt-everywhere-opensource-build-4.8.6/bin/qmake.exe</code>).
** If building in debug mode: <code>Slicer_USE_SimpleITK</code> option must be turned off to disable building SimpleITK. See more information about why SimpleITK has to be disabled for building in debug mode at http://www.na-mic.org/Bug/view.php?id=3816. You are going to get this build error if you attempt to build in debug mode with SimpleITK enabled: LINK : fatal error LNK1104: cannot open file 'python27_d.lib'
** Click generate then close cmake-gui.
** If building in release mode:
*** Open the top-level Slicer.sln file in the build directory in Visual Studio
*** Set active configuration to Release. Visual Studio will select Debug build configuration by default when you first open the solution in the Visual Studio GUI. If you build Slicer in release mode and accidentally forget to switch the build configuration to Release then the build will fail. Note: you can avoid this manual configuration mode selection by setting <code>CMAKE_CONFIGURATION_TYPES</code> to <code>Release</code> in cmake-gui.
** If building in debug mode:
*** Start Visual Studio using the Slicer launcher as described in [[Documentation/{{documentation/version}}/Developers/Tutorials/Debug_Instructions|Step-by-step debug instuctions]]
** Build the ALL_BUILD project

==== Unix-like ====
*'''Recommended''':
** Configure using the following commands. By default '''CMAKE_BUILD_TYPE''' is set to '''Debug'''.
<pre>
mkdir Slicer-SuperBuild-Debug
cd Slicer-SuperBuild-Debug
cmake -DCMAKE_BUILD_TYPE:STRING=Debug -DQT_QMAKE_EXECUTABLE:FILEPATH=/path/to/QtSDK/Desktop/Qt/486/gcc/bin/qmake ../Slicer
</pre>
where you replace ''/path/to/QtSDK'' with the real path on your machine where QtSDK is located

If '''using Qt from the system''', do not forget to add the following CMake variable to your configuration command line:
<pre>-DSlicer_USE_SYSTEM_QT:BOOL=1
</pre>

* '''Remarks''':
# Instead of <code>cmake</code>, you can use <code>ccmake</code> or <code>cmake-gui</code> to visually inspect and edit configure options.
# Using top-level directory name like <code>Slicer-SuperBuild-Release</code> or <code>Slicer-SuperBuild-Debug</code> is recommended.
# [[Documentation/{{documentation/version}}/Developers/Tutorials/Debug_Instructions|Step-by-step debug instuctions]]

* On Mac OS X 10.9 (Mavericks) / 10.10 (Yosemite) / 10.11 (El Capitan), also set the following variables (see [http://massmail.spl.harvard.edu/public-archives/slicer-devel/2014/thread.html#16440 discussion]):
{| border="0" cellpadding="4" cellspacing="4"
|-
| bgcolor="#abcdef" height="8" | '''Variable'''
| bgcolor="#abcdef" height="8" | '''Description'''
|-
| Slicer_USE_PYTHONQT_WITH_TCL || OFF
|-
| CMAKE_OSX_DEPLOYMENT_TARGET || 10.9 or 10.10 or 10.11
|-
|}

=== General information ===

Two projects are generated by either <code>cmake</code>, <code>ccmake</code> or <code>cmake-gui</code>.

One of them is in the top-level bin directory <code>Slicer-SuperBuild</code> and the other one is in the subdirectory <code>Slicer-build</code>:

<pre>Slicer-SuperBuild/Slicer-build</pre>

# The first project in <code>Slicer-SuperBuild</code> manages all the external dependencies of Slicer (VTK, ITK, Python, ...). To build Slicer for the first time, run make (or build the solution file in Visual Studio) in <code>Slicer-SuperBuild</code>, which will update and build the external libraries and if successful will then build the subproject Slicer-build. 
# The second project in <code>Slicer-SuperBuild/Slicer-build</code> is the "traditional" build directory of Slicer. After local changes in Slicer (or after an svn update on the source directory of Slicer), only running make (or building the solution file in Visual Studio) in <code>Slicer-SuperBuild/Slicer-build</code> is necessary (the external libraries are considered built and up to date). 
#'''Warning''': An significant amount of disk space is required to compile Slicer in Debug (>10GB on Windows)

=== Workaround for if the firewall is blocking git protocol ===
* Some firewalls will block the git protocol. A possible workaround is to configure Slicer by disabling the option <code>Slicer_USE_GIT_PROTOCOL</code>. Then the http protocol will be used instead. Consider also reading https://github.com/commontk/CTK/issues/33

Documentation/Nightly/Extensions/pyLARSlicerExtension

2016-03-18T19:24:26Z

Fbudin:

<noinclude>{{documentation/versioncheck}}</noinclude>

{{documentation/{{documentation/version}}/module-header}}



{{documentation/{{documentation/version}}/module-section|Introduction and Acknowledgements}}
{{documentation/{{documentation/version}}/module-introduction-start|{{documentation/modulename}}}}
{{documentation/{{documentation/version}}/module-introduction-row}}
Extension: [[Documentation/{{documentation/version}}/Extensions/pyLARSlicerExtension|pyLAR Slicer Extension]] 
Acknowledgments:
This work was supported, in-part, by the NIBIB (R41EB015775), the NINDS (R41NS081792) and the NSF (EECS-1148870) 
Integration of pyLAR, a python implementation of Low-rank Atlas-to-image Registration framework and its applications, as a Slicer extension 
More information about pyLAR is available [https://github.com/KitwareMedical/pyLAR here] . 
Author: Francois Budin ({{collaborator|name|kitware}}) 
Contributor1: Xiaoxiao Liu ({{collaborator|name|kitware}}) 
Contributor2: Deepak Roy Chittajallu ({{collaborator|name|kitware}}) 
Contributor3: Roland Kwitt ({{collaborator|name|kitware}}) 
Contact: Francois Budin, <email>francois.budin@kitware.com</email> 
{{documentation/{{documentation/version}}/module-introduction-row}}
{{documentation/{{documentation/version}}/module-introduction-logo-gallery
|{{collaborator|logo|kitware}}|{{collaborator|longname|kitware}}
|{{collaborator|logo|namic}}|{{collaborator|longname|namic}}
|Image:PyLAR-SlicerExtension-Icon512x512.png|Icon
}}

{{documentation/{{documentation/version}}/module-introduction-end}}


{{documentation/{{documentation/version}}/module-section|Module Description}}


{{documentation/{{documentation/version}}/module-section|Use Cases}}
{|
|[[Image:PyLAR-SlicerExtension_-_GUI_-_while_processing.png|thumb|340px|GUI]]
|[[Image:SkullStripperSurface-3-6.png|thumb|375px|Brain surface]]
|}


{{documentation/{{documentation/version}}/module-section|Tutorials}}


{{documentation/{{documentation/version}}/module-section|Panels and their use}}

{|
|[[Image:PyLAR-SlicerExtension_-_Examples_panel.png|thumb|280px|Examples panel]]
|}
The example panel presents two options:
* Create sample configuration files: They can be edited and adapted to process the researcher's data. Most likely, the file containing the list of images to process (file_list_file_name) will also have to be updated before one runs the algorithm.

* Downloading sample data from http://slicer.kitware.com/midas3 and http://insight-journal.org/midas
** Synthetic data (bull's eye)
** Healthy volunteer (T1-Flash)
** Healthy volunteer (T1-MPRage)
** Healthy volunteer (T2)
** Healthy volunteer (MRA)

{|
|[[Image:PyLAR-SlicerExtension_-_GUI_-_while_processing.png|thumb|280px|Module UI]]
|}

The user needs to select a configuration file and the algorithm to run (unbiased atlas creation, low rank/Sparse decomposition, Low Rank Atlas Creation). The user then presses "Apply"
and the result will be automatically loaded in Slicer. All the temporary images that were used and computed while the algorithm is running are saved in "result_dir" specified in the configuration file. The researcher can also specify an additional image that is not listed in the file containing the list of images. This image will be added at computation time. This is convenient for example if one needs to compute the Low Rank/Sparse decomposition of subjects one at the time, using a list of healthy control that does not need to be modified.


{{documentation/{{documentation/version}}/module-section|Configuration files}}

* Unbiased atlas creation
** clean (boolean): Removes content of output directory before starting computation
** data_dir (string): directory containing 'file_list_file_name'
** file_list_file_name (string): text file containing a list of image file paths, one per line
** verbose (boolean): Displays more or less information while running
** result_dir (string): output directory where outputs will be saved.
** selection (list): select images that are processed in given list [must contain at least 2 values].
** reference_im_fn (string): reference image used for the registration.
** num_of_iterations_per_level (int): Number of iteration per level for the registration [>=0]
** num_of_levels (int): Number of levels (starting the registration at a down-sampled level) for the registration [>=1]
** ants_params (see example and ANTS documentation):
** number_of_cpu (integer/optional): Number of diffeomorphic registration run in parallel. In not specified, it will run as many processes as there are CPU available. Beware, the processes might already be multithreaded.

* Low Rank/Sparse decomposition
** clean (boolean): Removes content of output directory before starting computation
** data_dir (string): directory containing 'file_list_file_name'
** file_list_file_name (string): text file containing a list of image file paths, one per line
** verbose (boolean): Displays more or less information while running
** lamda (float): the tuning parameter that weights between the low-rank component and the sparse component.
** sigma (float): blurring kernel size.
** result_dir (string): output directory where outputs will be saved.
** selection (list): select images that are processed in given list [must contain at least 1 value].
** reference_im_fn (string): reference image used for the registration.
** registration (string): 'affine', 'rigid', or 'none'
** histogram_matching (boolean/optional): If not specified or set to False, no histogram matching performed.

* Low Rank Atlas Creation
** clean (boolean): Removes content of output directory before starting computation
** data_dir (string): directory containing 'file_list_file_name'
** file_list_file_name (string): text file containing a list of image file paths, one per line
** verbose (boolean): Displays more or less information while running
** lamda (float): the tuning parameter that weights between the low-rank component and the sparse component.
** sigma (float): blurring kernel size.
** result_dir (string): output directory where outputs will be saved.
** selection (list): select images that are processed in given list [must contain at least 2 values].
** reference_im_fn (string): reference image used for the registration.
** use_healthy_atlas (boolean): use a specified healthy atlas as reference image or compute a reference image from the average of all the low-ranked images computed from the selected input images.
** num_of_iterations_per_level (int): Number of iteration per level for the registration [>=0]
** num_of_levels (int): Number of levels (starting the registration at a down-sampled level) for the registration [>=1]
** registration_type (string): Type of registration performed, selected among [BSpline,ANTS,Demons]
** ants_params (see example and ANTS documentation): Only necessary if registration_type is set to ANTS.
** number_of_cpu (integer/optional): Number of diffeomorphic registration run in parallel. In not specified, it will run as many processes as there are CPU available. Beware, the processes might already be multithreaded.
* File List File Name: text file containing a list of image file paths, one per line
/path/to/first/image.nrrd
/path/to/second/image2.nrrd
/path/to/third/image3.nii.gz

{{documentation/{{documentation/version}}/module-section|References}}
* Liu et al., "Low-Rank to the Rescue – Atlas-Based Analyses in the Presence of Pathologies", MICCAI 2014, pp97-104
* Liu et al., "Low-Rank Atlas Image Analyses in the Presence of Pathologies", IEEE Transactions on Medical Imaging, Vol. 34, No. 12, December 2015
* Candes et al., "Robust Principal Component Analysis?", Journal of the ACM, Vol. 58, No. 3, 2011
* Lin et al., "The Augmented Lagrangian Multiplier Method for Exact Recovery of Corrupted Low-Rank Matrices", 2011 (available online on archivX)


{{documentation/{{documentation/version}}/module-section|Information for Developers}}
{{documentation/{{documentation/version}}/module-developerinfo}}


{{documentation/{{documentation/version}}/module-footer}}
[[Category:Documentation/{{documentation/version}}/Modules/Segmentation]]

Documentation/Nightly/Extensions/pyLARSlicerExtension

2016-03-18T19:21:06Z

Fbudin:

<noinclude>{{documentation/versioncheck}}</noinclude>

{{documentation/{{documentation/version}}/module-header}}



{{documentation/{{documentation/version}}/module-section|Introduction and Acknowledgements}}
{{documentation/{{documentation/version}}/module-introduction-start|{{documentation/modulename}}}}
{{documentation/{{documentation/version}}/module-introduction-row}}
Extension: [[Documentation/{{documentation/version}}/Extensions/pyLARSlicerExtension|pyLAR Slicer Extension]] 
Acknowledgments:
This work was supported, in-part, by the NIBIB (R41EB015775), the NINDS (R41NS081792) and the NSF (EECS-1148870) 
Integration of pyLAR, a python implementation of Low-rank Atlas-to-image Registration framework and its applications, as a Slicer extension 
More information about pyLAR is available [https://github.com/KitwareMedical/pyLAR here] . 
Author: Francois Budin ({{collaborator|name|kitware}}) 
Contributor1: Xiaoxiao Liu ({{collaborator|name|kitware}}) 
Contributor2: Deepak Roy Chittajallu ({{collaborator|name|kitware}}) 
Contributor3: Roland Kwitt ({{collaborator|name|kitware}}) 
Contact: Francois Budin, <email>francois.budin@kitware.com</email> 
{{documentation/{{documentation/version}}/module-introduction-row}}
{{documentation/{{documentation/version}}/module-introduction-logo-gallery
|{{collaborator|logo|kitware}}|{{collaborator|longname|kitware}}
|{{collaborator|logo|namic}}|{{collaborator|longname|namic}}
|Image:PyLAR-SlicerExtension-Icon512x512.png|Icon
}}

{{documentation/{{documentation/version}}/module-introduction-end}}


{{documentation/{{documentation/version}}/module-section|Module Description}}


{{documentation/{{documentation/version}}/module-section|Use Cases}}
{|
|[[Image:PyLAR-SlicerExtension_-_GUI_-_while_processing.png|thumb|340px|GUI]]
|[[Image:SkullStripperSurface-3-6.png|thumb|375px|Brain surface]]
|}


{{documentation/{{documentation/version}}/module-section|Tutorials}}


{{documentation/{{documentation/version}}/module-section|Panels and their use}}

{|
|[[Image:PyLAR-SlicerExtension_-_Examples_panel.png|thumb|280px|Examples panel]]
|}
The example panel presents two options:
* Create sample configuration files: They can be edited and adapted to process the researcher's data. Most likely, the file containing the list of images to process (file_list_file_name) will also have to be updated before one runs the algorithm.

* Downloading sample data from http://slicer.kitware.com/midas3 and http://insight-journal.org/midas
** Synthetic data (bull's eye)
** Healthy volunteer (T1-Flash)
** Healthy volunteer (T1-MPRage)
** Healthy volunteer (T2)
** Healthy volunteer (MRA)

{|
|[[Image:PyLAR-SlicerExtension_-_GUI_-_while_processing.png|thumb|280px|Module UI]]
|}

The user needs to select a configuration file and the algorithm to run (unbiased atlas creation, low rank/Sparse decomposition, Low Rank Atlas Creation). The user then presses "Apply"
and the result will be automatically loaded in Slicer. All the temporary images that were used and computed while the algorithm is running are saved in "result_dir" specified in the configuration file. The researcher can also specify an additional image that is not listed in the file containing the list of images. This image will be added at computation time. This is convenient for example if one needs to compute the Low Rank/Sparse decomposition of subjects one at the time, using a list of healthy control that does not need to be modified.


{{documentation/{{documentation/version}}/module-section|Configuration files}}

* Unbiased atlas creation
clean (boolean): Removes content of output directory before starting computation
data_dir (string): directory containing 'file_list_file_name'
file_list_file_name (string): text file containing a list of image file paths, one per line
verbose (boolean): Displays more or less information while running
result_dir (string): output directory where outputs will be saved.
selection (list): select images that are processed in given list [must contain at least 2 values].
reference_im_fn (string): reference image used for the registration.
num_of_iterations_per_level (int): Number of iteration per level for the registration [>=0]
num_of_levels (int): Number of levels (starting the registration at a down-sampled level) for the registration [>=1]
ants_params (see example and ANTS documentation):
ants_params = {'Convergence' : '[100x50x25,1e-6,10]',\
'Dimension': 3,\
'ShrinkFactors' : '4x2x1',\
'SmoothingSigmas' : '2x1x0vox',\
'Transform' :'SyN[0.5]',\
'Metric': 'Mattes[fixedIm,movingIm,1,50,Regular,0.95]'}
number_of_cpu (integer/optional): Number of diffeomorphic registration run in parallel. In not specified,
it will run as many processes as there are CPU available. Beware, the processes might
already be multithreaded.

* Low Rank/Sparse decomposition
clean (boolean): Removes content of output directory before starting computation
data_dir (string): directory containing 'file_list_file_name'
file_list_file_name (string): text file containing a list of image file paths, one per line
verbose (boolean): Displays more or less information while running
lamda (float): the tuning parameter that weights between the low-rank component and the sparse component.
sigma (float): blurring kernel size.
result_dir (string): output directory where outputs will be saved.
selection (list): select images that are processed in given list [must contain at least 1 value].
reference_im_fn (string): reference image used for the registration.
registration (string): 'affine', 'rigid', or 'none'
histogram_matching (boolean/optional): If not specified or set to False, no histogram matching performed.

* Low Rank Atlas Creation
clean (boolean): Removes content of output directory before starting computation
data_dir (string): directory containing 'file_list_file_name'
file_list_file_name (string): text file containing a list of image file paths, one per line
verbose (boolean): Displays more or less information while running
lamda (float): the tuning parameter that weights between the low-rank component and the sparse component.
sigma (float): blurring kernel size.
result_dir (string): output directory where outputs will be saved.
selection (list): select images that are processed in given list [must contain at least 2 values].
reference_im_fn (string): reference image used for the registration.
use_healthy_atlas (boolean): use a specified healthy atlas as reference image or compute a reference image from
the average of all the low-ranked images computed from the selected input images.
num_of_iterations_per_level (int): Number of iteration per level for the registration [>=0]
num_of_levels (int): Number of levels (starting the registration at a down-sampled level) for the registration [>=1]
registration_type (string): Type of registration performed, selected among [BSpline,ANTS,Demons]
ants_params (see example and ANTS documentation): Only necessary if registration_type is set to ANTS.
ants_params = {'Convergence' : '[100x50x25,1e-6,10]',\
'Dimension': 3,\
'ShrinkFactors' : '4x2x1',\
'SmoothingSigmas' : '2x1x0vox',\
'Transform' :'SyN[0.5]',\
'Metric': 'Mattes[fixedIm,movingIm,1,50,Regular,0.95]'}
number_of_cpu (integer/optional): Number of diffeomorphic registration run in parallel. In not specified,
it will run as many processes as there are CPU available. Beware, the processes might
already be multithreaded.
* File List File Name: text file containing a list of image file paths, one per line
/path/to/first/image.nrrd
/path/to/second/image2.nrrd
/path/to/third/image3.nii.gz

{{documentation/{{documentation/version}}/module-section|References}}
* Liu et al., "Low-Rank to the Rescue – Atlas-Based Analyses in the Presence of Pathologies", MICCAI 2014, pp97-104
* Liu et al., "Low-Rank Atlas Image Analyses in the Presence of Pathologies", IEEE Transactions on Medical Imaging, Vol. 34, No. 12, December 2015
* Candes et al., "Robust Principal Component Analysis?", Journal of the ACM, Vol. 58, No. 3, 2011
* Lin et al., "The Augmented Lagrangian Multiplier Method for Exact Recovery of Corrupted Low-Rank Matrices", 2011 (available online on archivX)


{{documentation/{{documentation/version}}/module-section|Information for Developers}}
{{documentation/{{documentation/version}}/module-developerinfo}}


{{documentation/{{documentation/version}}/module-footer}}
[[Category:Documentation/{{documentation/version}}/Modules/Segmentation]]

Documentation/Nightly/Extensions/pyLARSlicerExtension

2016-03-18T19:18:45Z

Fbudin: Created page with "<noinclude>{{documentation/versioncheck}}</noinclude>  {{documentation/{{documentation/version}}/module-header}} <!-- --------------------..."

<noinclude>{{documentation/versioncheck}}</noinclude>

{{documentation/{{documentation/version}}/module-header}}



{{documentation/{{documentation/version}}/module-section|Introduction and Acknowledgements}}
{{documentation/{{documentation/version}}/module-introduction-start|{{documentation/modulename}}}}
{{documentation/{{documentation/version}}/module-introduction-row}}
Extension: [[Documentation/{{documentation/version}}/Extensions/pyLARSlicerExtension|pyLAR Slicer Extension]] 
Acknowledgments:
This work was supported, in-part, by the NIBIB (R41EB015775), the NINDS (R41NS081792) and the NSF (EECS-1148870) 
Integration of pyLAR, a python implementation of Low-rank Atlas-to-image Registration framework and its applications, as a Slicer extension 
More information about pyLAR is available [https://github.com/KitwareMedical/pyLAR here] . 
Author: Francois Budin ({{collaborator|name|kitware}}) 
Contributor1: Xiaoxiao Liu ({{collaborator|name|kitware}}) 
Contributor2: Deepak Roy Chittajallu ({{collaborator|name|kitware}}) 
Contributor3: Roland Kwitt ({{collaborator|name|kitware}}) 
Contact: Francois Budin, <email>francois.budin@kitware.com</email> 
{{documentation/{{documentation/version}}/module-introduction-row}}
{{documentation/{{documentation/version}}/module-introduction-logo-gallery
|{{collaborator|logo|kitware}}|{{collaborator|longname|kitware}}
|{{collaborator|logo|namic}}|{{collaborator|longname|namic}}
|Image:PyLAR-SlicerExtension-Icon512x512.png|Icon
}}

{{documentation/{{documentation/version}}/module-introduction-end}}


{{documentation/{{documentation/version}}/module-section|Module Description}}


{{documentation/{{documentation/version}}/module-section|Use Cases}}
{|
|[[Image:PyLAR-SlicerExtension_-_GUI_-_while_processing.png|thumb|340px|GUI]]
|[[Image:SkullStripperSurface-3-6.png|thumb|375px|Brain surface]]
|}


{{documentation/{{documentation/version}}/module-section|Tutorials}}


{{documentation/{{documentation/version}}/module-section|Panels and their use}}

{|
|[[Image:PyLAR-SlicerExtension_-_Examples_panel.png|thumb|280px|Examples panel]]
|}
The example panel presents two options:
* Create sample configuration files: They can be edited and adapted to process the researcher's data. Most likely, the file containing the list of images to process (file_list_file_name) will also have to be updated before one runs the algorithm.

* Downloading sample data from http://slicer.kitware.com/midas3 and http://insight-journal.org/midas
** Synthetic data (bull's eye)
** Healthy volunteer (T1-Flash)
** Healthy volunteer (T1-MPRage)
** Healthy volunteer (T2)
** Healthy volunteer (MRA)

{|
|[[Image:PyLAR-SlicerExtension_-_GUI_-_while_processing.png|thumb|280px|Module UI]]
|}

The user needs to select a configuration file and the algorithm to run (unbiased atlas creation, low rank/Sparse decomposition, Low Rank Atlas Creation). The user then presses "Apply"
and the result will be automatically loaded in Slicer. All the temporary images that were used and computed while the algorithm is running are saved in "result_dir" specified in the configuration file. The researcher can also specify an additional image that is not listed in the file containing the list of images. This image will be added at computation time. This is convenient for example if one needs to compute the Low Rank/Sparse decomposition of subjects one at the time, using a list of healthy control that does not need to be modified.


{{documentation/{{documentation/version}}/module-section|Configuration files}}

Unbiased atlas creation
clean (boolean): Removes content of output directory before starting computation
data_dir (string): directory containing 'file_list_file_name'
file_list_file_name (string): text file containing a list of image file paths, one per line
verbose (boolean): Displays more or less information while running
result_dir (string): output directory where outputs will be saved.
selection (list): select images that are processed in given list [must contain at least 2 values].
reference_im_fn (string): reference image used for the registration.
num_of_iterations_per_level (int): Number of iteration per level for the registration [>=0]
num_of_levels (int): Number of levels (starting the registration at a down-sampled level) for the registration [>=1]
ants_params (see example and ANTS documentation):
ants_params = {'Convergence' : '[100x50x25,1e-6,10]',\
'Dimension': 3,\
'ShrinkFactors' : '4x2x1',\
'SmoothingSigmas' : '2x1x0vox',\
'Transform' :'SyN[0.5]',\
'Metric': 'Mattes[fixedIm,movingIm,1,50,Regular,0.95]'}
number_of_cpu (integer/optional): Number of diffeomorphic registration run in parallel. In not specified,
it will run as many processes as there are CPU available. Beware, the processes might
already be multithreaded.

Low Rank/Sparse decomposition
clean (boolean): Removes content of output directory before starting computation
data_dir (string): directory containing 'file_list_file_name'
file_list_file_name (string): text file containing a list of image file paths, one per line
verbose (boolean): Displays more or less information while running
lamda (float): the tuning parameter that weights between the low-rank component and the sparse component.
sigma (float): blurring kernel size.
result_dir (string): output directory where outputs will be saved.
selection (list): select images that are processed in given list [must contain at least 1 value].
reference_im_fn (string): reference image used for the registration.
registration (string): 'affine', 'rigid', or 'none'
histogram_matching (boolean/optional): If not specified or set to False, no histogram matching performed.

Low Rank Atlas Creation
clean (boolean): Removes content of output directory before starting computation
data_dir (string): directory containing 'file_list_file_name'
file_list_file_name (string): text file containing a list of image file paths, one per line
verbose (boolean): Displays more or less information while running
lamda (float): the tuning parameter that weights between the low-rank component and the sparse component.
sigma (float): blurring kernel size.
result_dir (string): output directory where outputs will be saved.
selection (list): select images that are processed in given list [must contain at least 2 values].
reference_im_fn (string): reference image used for the registration.
use_healthy_atlas (boolean): use a specified healthy atlas as reference image or compute a reference image from
the average of all the low-ranked images computed from the selected input images.
num_of_iterations_per_level (int): Number of iteration per level for the registration [>=0]
num_of_levels (int): Number of levels (starting the registration at a down-sampled level) for the registration [>=1]
registration_type (string): Type of registration performed, selected among [BSpline,ANTS,Demons]
ants_params (see example and ANTS documentation): Only necessary if registration_type is set to ANTS.
ants_params = {'Convergence' : '[100x50x25,1e-6,10]',\
'Dimension': 3,\
'ShrinkFactors' : '4x2x1',\
'SmoothingSigmas' : '2x1x0vox',\
'Transform' :'SyN[0.5]',\
'Metric': 'Mattes[fixedIm,movingIm,1,50,Regular,0.95]'}
number_of_cpu (integer/optional): Number of diffeomorphic registration run in parallel. In not specified,
it will run as many processes as there are CPU available. Beware, the processes might
already be multithreaded.

{{documentation/{{documentation/version}}/module-section|References}}
* Liu et al., "Low-Rank to the Rescue – Atlas-Based Analyses in the Presence of Pathologies", MICCAI 2014, pp97-104
* Liu et al., "Low-Rank Atlas Image Analyses in the Presence of Pathologies", IEEE Transactions on Medical Imaging, Vol. 34, No. 12, December 2015
* Candes et al., "Robust Principal Component Analysis?", Journal of the ACM, Vol. 58, No. 3, 2011
* Lin et al., "The Augmented Lagrangian Multiplier Method for Exact Recovery of Corrupted Low-Rank Matrices", 2011 (available online on archivX)


{{documentation/{{documentation/version}}/module-section|Information for Developers}}
{{documentation/{{documentation/version}}/module-developerinfo}}


{{documentation/{{documentation/version}}/module-footer}}
[[Category:Documentation/{{documentation/version}}/Modules/Segmentation]]

File:PyLAR-SlicerExtension - Examples panel.png

2016-03-18T18:22:16Z

Fbudin:

File:PyLAR-SlicerExtension - GUI - while processing.png

2016-03-18T18:20:53Z

Fbudin:

File:PyLAR-SlicerExtension-Icon512x512.png

2016-03-18T18:18:02Z

Fbudin: Icon of pyLAR Slicer extension

Icon of pyLAR Slicer extension

Documentation/Nightly/ModuleExtensionListing/Extensions by category

2016-03-18T18:04:33Z

Fbudin: /* Extensions by category */

__NOTOC__
* [[#Extensions_by_category|Extensions by category]]
= Extensions by category =
24 categories:
* [[#Extensions_by_category_Cardiac|Cardiac]]
* [[#Extensions_by_category_Cardiac_MRI_toolkit|Cardiac MRI toolkit]]
* [[#Extensions_by_category_Chest_Imaging_Platform|Chest Imaging Platform]]
* [[#Extensions_by_category_Converters|Converters]]
* [[#Extensions_by_category_Developer_Tools|Developer Tools]]
* [[#Extensions_by_category_Diffusion|Diffusion]]
* [[#Extensions_by_category_Editor_Effects|Editor Effects]]
* [[#Extensions_by_category_Exporter|Exporter]]
* [[#Extensions_by_category_Filtering|Filtering]]
* [[#Extensions_by_category_IGT|IGT]]
* [[#Extensions_by_category_Informatics|Informatics]]
* [[#Extensions_by_category_Mesh_Generation|Mesh Generation]]
* [[#Extensions_by_category_Microscopy|Microscopy]]
* [[#Extensions_by_category_Nuclear_Medicine|Nuclear Medicine]]
* [[#Extensions_by_category_Quantification|Quantification]]
* [[#Extensions_by_category_Radiotherapy|Radiotherapy]]
* [[#Extensions_by_category_Registration|Registration]]
* [[#Extensions_by_category_Scoliosis|Scoliosis]]
* [[#Extensions_by_category_Segmentation|Segmentation]]
* [[#Extensions_by_category_Sequences|Sequences]]
* [[#Extensions_by_category_Shape_Analysis|Shape Analysis]]
* [[#Extensions_by_category_Tractography|Tractography]]
* [[#Extensions_by_category_Training|Training]]
* [[#Extensions_by_category_Vascular_Modeling_Toolkit|Vascular Modeling Toolkit]]
* [[#Extensions_by_category_Wizards|Wizards]]

== Cardiac ==
* [[Documentation/Nightly/Extensions/SlicerHeart|Slicer Heart]]
* [http://brainsia.github.io/CardiacAgatstonMeasures/ Cardiac Agatston Measures]

== Cardiac MRI toolkit ==
* [http://capulet.med.utah.edu/namic/cmrslicer/ Cardiac MRI Toolkit]

== Chest Imaging Platform ==
* [http://www.chestimagingplatform.org Chest Imaging Platform]

== Converters ==
* [http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/PETDICOM PETDICOMExtension]

== Developer Tools ==
* [[Documentation/Nightly/Extensions/DeveloperToolsForExtensions|Developer Tools For Extensions]]
* [[Documentation/Nightly/Extensions/DebuggingTools|Debugging Tools]]
* [[Documentation/Nightly/Extensions/MatlabBridge|Matlab Bridge]]
* [[Documentation/Nightly/Extensions/ImageMaker|Image Maker]]

== Diffusion ==
* [[Documentation/Nightly/Extensions/ResampleDTIlogEuclidean|Resample DTIlog Euclidean]]

== Editor Effects ==
* [[Documentation/Nightly/Extensions/WindowLevelEffect|Window Level Effect]]

== Exporter ==
* [[Documentation/Nightly/Extensions/SlicerToKiwiExporter|Slicer To Kiwi Exporter]]

== Filtering ==
* [[Documentation/Nightly/Extensions/pyLARSlicerExtension|pyLAR Slicer Extension]]

== IGT ==
* [[Documentation/Nightly/Extensions/NeedleFinder|Needle Finder]]
* [http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/TrackerStabilizer Tracker Stabilizer]
* [[Documentation/Nightly/Extensions/GyroGuide|Gyro Guide]]
* [[Documentation/Nightly/Extensions/CornerAnnotation|Corner Annotation]]
* [https://github.com/SlicerIGT/LumpNav Lump Nav]
* [[Documentation/Nightly/Extensions/PercutaneousApproachAnalysis|Percutaneous Approach Analysis]]
* [[Documentation/Nightly/Extensions/SlicerIGT|Slicer IGT]]
* [[Documentation/Nightly/Extensions/iGyne|i Gyne]]
* [[Documentation/Nightly/Extensions/ResectionPlanner|Resection Planner]]

== Informatics ==
* [[Documentation/Nightly/Extensions/CurveMaker|Curve Maker]]
* [[Documentation/Nightly/Extensions/LongitudinalPETCT|Longitudinal PETCT]]
* [[Documentation/Nightly/Extensions/Reporting|Reporting]]
* [[Documentation/Nightly/Extensions/mpReview|mp Review]]
* [[Documentation/Nightly/Extensions/TCIABrowser|TCIABrowser]]
* [[Documentation/Nightly/Extensions/SlicerProstate|Slicer Prostate]]

== Mesh Generation ==
* [[Documentation/Nightly/Extensions/CBC_3D_I2MConversion|CBC 3D I2MConversion]]
* [[Documentation/Nightly/Extensions/CleaverExtension|Cleaver Extension]]

== Microscopy ==
* [[Documentation/Nightly/Extensions/IASEM|IASEM]]

== Nuclear Medicine ==
* [http://gti-fing.github.io/SlicerPetSpectAnalysis Pet Spect Analysis]

== Quantification ==
* [http://slicer.org/slicerWiki/index.php/Documentation/Nightly/Modules/DSC_MRI_Analysis DSCMRIAnalysis]
* [[Documentation/Nightly/Extensions/T1Mapping|T1Mapping]]
* [[Documentation/Nightly/Extensions/DiceComputation|Dice Computation]]
* [[Documentation/Nightly/Extensions/PET-IndiC|PET-Indi C]]
* [[Documentation/Nightly/Extensions/PkModeling|Pk Modeling]]

== Radiotherapy ==
* [[Documentation/Nightly/Extensions/MarginCalculator|Margin Calculator]]
* [[Documentation/Nightly/Extensions/SlicerRT|Slicer RT]]
* [http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Modules/GelDosimetry Gel Dosimetry Analysis]

== Registration ==
* [[Documentation/Nightly/Extensions/CMFreg|CMFreg]]
* [[Documentation/Nightly/Extensions/PBNRR|PBNRR]]

== Scoliosis ==
* [[Documentation/Nightly/Extensions/Scoliosis|Scoliosis]]

== Segmentation ==
* [http://publish.uwo.ca/~dchen285/GraphCutSegment/GraphCutSegment.html Graph Cut Segment]
* [http://www.nitrc.org/projects/abc ABC]
* [http://wiki.slicer.org/slicerWiki/index.php/Documentation/Nightly/Modules/CarreraSliceInteractiveSegmenter Carrera Slice]
* [[Documentation/Nightly/Extensions/SkullStripper|Skull Stripper]]
* [[Documentation/Nightly/Extensions/PETTumorSegmentation|PETTumor Segmentation]]
* [[Documentation/Nightly/Extensions/SwissSkullStripper|Swiss Skull Stripper]]
* [[Documentation/Nightly/Extensions/LAScarSegmenter|LAScar Segmenter]]
* [[Documentation/Nightly/Extensions/OpenCAD|Open CAD]]
* [[Documentation/Nightly/Extensions/IntensitySegmenter|Intensity Segmenter]]
* [https://github.com/Tomnl/Slicer-Wasp Wasp]
* [http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/AirwaySegmentation Airway Segmentation]
* [https://www.slicer.org/slicerWiki/index.php/Documentation/4.3/Modules/FastGrowCut Fast Grow Cut Effect]
* [[Documentation/Nightly/Extensions/VolumeClip|Volume Clip]]

== Sequences ==
* [[Documentation/Nightly/Extensions/Sequences|Sequences]]

== Shape Analysis ==
* [[Documentation/Nightly/Extensions/MeshToLabelMap|Mesh To Label Map]]
* [[Documentation/Nightly/Extensions/Q3DC|Q3DC]]
* [[Documentation/Nightly/Extensions/ModelToModelDistance|Model To Model Distance]]
* [[Documentation/Nightly/Extensions/EasyClip|Easy Clip]]
* [http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/PickAndPaint Pick And Paint Extension]
* [http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/AnglePlanes Angle Planes Extension]

== Tractography ==
* [[Documentation/Nightly/Extensions/FinslerTractography|Finsler Tractography]]
* [[Documentation/Nightly/Extensions/UKFTractography|UKFTractography]]

== Training ==
* [[Documentation/Nightly/Extensions/PerkTutor|Perk Tutor]]

== Vascular Modeling Toolkit ==
* [http://slicer.vmtk.org/ VMTK]

== Wizards ==
* [[Documentation/Nightly/Extensions/ChangeTracker|Change Tracker]]
__NOTOC__

Documentation/Nightly/Extensions/CatalogPolicies

2016-03-18T15:22:41Z

Fbudin: /* Category 3 */

<noinclude>{{documentation/versioncheck}}</noinclude>
<noinclude>
__TOC__

= Disclaimer =

This is work in progress as of April 2012 - people with an interest in policies and practice related to this topic should contact Ron Kikinis.

The following text details the policies for Slicer Extensions. These policies are subject to change without notice at the discretion of the Slicer PI. It is expected that this will happen rarely and after consultation with the Slicer community.

</noinclude>

= Requirements for Slicer Extensions =
== Category 1 ==

Category 1 extensions must meet the following conditions:
* comply with the [http://www.slicer.org/pages/LicenseText Slicer License]
* compile and install on [[Documentation/{{documentation/version}}/SlicerApplication/HardwareConfiguration|all platforms supported by Slicer]]
* <del>have test coverage of better than 60%</del>. See issue [http://www.na-mic.org/Bug/view.php?id=2172 #2172]
* have [[Documentation/{{documentation/version}}/HowTo|documentation]] at a level of quality comparable to slicer core modules
* have a designated person to [http://massmail.bwh.harvard.edu/mailman/listinfo/slicer-devel answer emails] in relation to the extension which are posted on both the [http://massmail.bwh.harvard.edu/mailman/listinfo/slicer-users users] and [http://massmail.bwh.harvard.edu/mailman/listinfo/slicer-devel developers] Slicer mailing lists.
* are updated to support new versions of the OS, new versions of packages (such as VTK, ITK), etc.
* have clear description, icon, screenshots and tutorials

== Category 2 ==
Category 2 extensions must meet the following conditions:
* be available under a compatible [https://en.wikipedia.org/wiki/Open_source open source] license
* have a designated maintainer to [http://massmail.bwh.harvard.edu/mailman/listinfo/slicer-devel respond to questions] about the extension
* have a clear declaration about the license under which the code is distributed
* have [[Documentation/{{documentation/version}}/Developers/Tutorials/DocumentExtension|documentation]] page
* have clear description, icon, screenshots and optionally tutorials

== Category 3 ==
Category 3 Slicer Extensions cover everything else, including developers who do not want to share their source code or extensions.
* I do not want to share my source code: When source code is not shared, it is not possible to inspect the code for malicious content. This is a potential security risk that we will not accept for the Slicer website.
* Developers are free to set up their own Midas servers for hosting extensions if they want to host category 3 extensions, or can just make .tar.gz files and either install the package manually from the [[Documentation/{{documentation/version}}/SlicerApplication/ExtensionsManager|Extension manager]] or set the module path in Slicer manually.

<noinclude>

= What is an extension ? =
{{:Documentation/{{documentation/version}}/Extensions/Description}}
</noinclude>

Documentation/Nightly/Extensions/CatalogPolicies

2016-03-18T15:21:02Z

Fbudin: Addition of information: missing information concerning the possibility to install an extension manually from the extension manager.

<noinclude>{{documentation/versioncheck}}</noinclude>
<noinclude>
__TOC__

= Disclaimer =

This is work in progress as of April 2012 - people with an interest in policies and practice related to this topic should contact Ron Kikinis.

The following text details the policies for Slicer Extensions. These policies are subject to change without notice at the discretion of the Slicer PI. It is expected that this will happen rarely and after consultation with the Slicer community.

</noinclude>

= Requirements for Slicer Extensions =
== Category 1 ==

Category 1 extensions must meet the following conditions:
* comply with the [http://www.slicer.org/pages/LicenseText Slicer License]
* compile and install on [[Documentation/{{documentation/version}}/SlicerApplication/HardwareConfiguration|all platforms supported by Slicer]]
* <del>have test coverage of better than 60%</del>. See issue [http://www.na-mic.org/Bug/view.php?id=2172 #2172]
* have [[Documentation/{{documentation/version}}/HowTo|documentation]] at a level of quality comparable to slicer core modules
* have a designated person to [http://massmail.bwh.harvard.edu/mailman/listinfo/slicer-devel answer emails] in relation to the extension which are posted on both the [http://massmail.bwh.harvard.edu/mailman/listinfo/slicer-users users] and [http://massmail.bwh.harvard.edu/mailman/listinfo/slicer-devel developers] Slicer mailing lists.
* are updated to support new versions of the OS, new versions of packages (such as VTK, ITK), etc.
* have clear description, icon, screenshots and tutorials

== Category 2 ==
Category 2 extensions must meet the following conditions:
* be available under a compatible [https://en.wikipedia.org/wiki/Open_source open source] license
* have a designated maintainer to [http://massmail.bwh.harvard.edu/mailman/listinfo/slicer-devel respond to questions] about the extension
* have a clear declaration about the license under which the code is distributed
* have [[Documentation/{{documentation/version}}/Developers/Tutorials/DocumentExtension|documentation]] page
* have clear description, icon, screenshots and optionally tutorials

== Category 3 ==
Category 3 Slicer Extensions cover everything else, including developers who do not want to share their source code or extensions.
* I do not want to share my source code: When source code is not shared, it is not possible to inspect the code for malicious content. This is a potential security risk that we will not accept for the Slicer website.
* Developers are free to set up their own Midas servers for hosting extensions if they want to host category 3 extensions, or can just make .tar.gz files and either install the package manually from the extension manager or set the module path in Slicer manually.

<noinclude>

= What is an extension ? =
{{:Documentation/{{documentation/version}}/Extensions/Description}}
</noinclude>

Documentation/4.5/ScriptRepository

2016-03-08T17:09:38Z

Fbudin: Missing import statement

<noinclude>{{documentation/versioncheck}}</noinclude>
__TOC__

=Community-contributed modules=

Usage: save the .py file to a directory, add the directory to the additional module paths in the Slicer application settings (choose in the menu: Edit / Application settings, click Modules, click >> next to Additional module paths, click Add, and choose the .py file's location).

==Filters==
* [https://raw.github.com/pieper/VolumeMasker/master/VolumeMasker.py VolumeMasker.py]: Update a target volume with the results of setting all input volume voxels to 0 except for those that correspond to a selected label value in an input label map (Used for example in the volume rendering in [https://www.youtube.com/watch?v=dfu2gugHLHs this video).

==DICOM==
* [https://gist.github.com/pieper/6186477 dicom header browser] to easily scroll through dicom files using dcmdump.
* [https://subversion.assembla.com/svn/slicerrt/trunk/SlicerRt/src/BatchProcessing SlicerRT batch processing] to batch convert RT structure sets to labelmap NRRD files.

==Informatics==
* [https://subversion.assembla.com/svn/slicerrt/trunk/SlicerRt/sandbox/MarkupsInfoModule/MarkupsInfo.py MarkupsInfo.py]: Compute the total length between all the points of a markup list.
* [https://subversion.assembla.com/svn/slicerrt/trunk/SlicerRt/sandbox/LineProfile/LineProfile.py LineProfile.py]: Compute intensity profile in a volume along a line.

=Community-contributed examples=

Usage: Copy-paste the shown code lines or linked .py file contents into Python console in Slicer.

==Capture==
* Get a MRML node in the scene based on the node name and call methods of that object. For the MRHead sample data:
vol=slicer.util.getNode('MR*')
vol.GetImageData().GetDimensions()
* Capture the full Slicer screen and save it into a file
img = qt.QPixmap.grabWidget(slicer.util.mainWindow()).toImage()
img.save('c:/tmp/test.png')
* [https://subversion.assembla.com/svn/slicerrt/trunk/SlicerRt/sandbox/CaptureRotationVideo/CaptureRotationVideo.py CaptureRotationVideo.py]: Capture a video of the scene rotating in the 3D view

==Launching Slicer==
* How to open an .mrb file with Slicer at the command line?
Slicer.exe --python-code "slicer.util.loadScene( 'f:/2013-08-23-Scene.mrb' )"
* How to run a script in the Slicer environment in batch mode (without showing any graphical user interface)?
Slicer.exe --python-code "doSomething; doSomethingElse; etc." --testing --no-splash --no-main-window

==DICOM==
* How to access tags of DICOM images imported into Slicer? For example, to print the first patient's first study's first series' "0020,0032" field:
db=slicer.dicomDatabase
patientList=db.patients()
studyList=db.studiesForPatient(patientList[0])
seriesList=db.seriesForStudy(studyList[0])
fileList=db.filesForSeries(seriesList[0])
print db.fileValue(fileList[0],'0020,0032')

* How to access tag of a volume loaded from DICOM? For example, get the patient position stored in a volume:
volumeName='2: ENT IMRT'
n=slicer.util.getNode(volumeName)
instUids=n.GetAttribute('DICOM.instanceUIDs').split()
filename=slicer.dicomDatabase.fileForInstance(instUids[0])
print slicer.dicomDatabase.fileValue(filename,'0018,5100')

* How to access tag of an item in the Subject Hierachy tree? For example, get the content time tag of a structure set:
rtStructName = '3: RTSTRUCT: PROS'
rtStructNode = slicer.util.getNode(rtStructName)
rtStructSubjectHierarchyNode = slicer.vtkMRMLSubjectHierarchyNode.GetAssociatedSubjectHierarchyNode(rtStructNode)
ctSliceInstanceUids = rtStructSubjectHierarchyNode.GetAttribute('DICOM.ReferencedInstanceUIDs').split()
filename = slicer.dicomDatabase.fileForInstance(ctSliceInstanceUids[0])
print slicer.dicomDatabase.fileValue(filename,'0008,0033')

==Toolbar functions==
* How to turn on slice intersections in the crosshair menu on the toolbar:
viewNodes = slicer.mrmlScene.GetNodesByClass('vtkMRMLSliceCompositeNode')
viewNodes.UnRegister(slicer.mrmlScene)
viewNodes.InitTraversal()
viewNode = viewNodes.GetNextItemAsObject()
while viewNode:
viewNode.SetSliceIntersectionVisibility(1)
viewNode = viewNodes.GetNextItemAsObject()

How to find similar functions? For this one I searched for "slice intersections" text in the whole slicer source code, found that the function is implemented in Base\QTGUI\qSlicerViewersToolBar.cxx, then translated the qSlicerViewersToolBarPrivate::setSliceIntersectionVisible(bool visible) method to Python.

==Manipulating objects in the slice viewer==
* How to define/edit a circular region of interest in a slice viewer?

Drop two markup points on a slice view and copy-paste the code below into the Python console. After this, as you move the markups you’ll see a circle following the markups.

# Update the sphere from the fiducial points
def UpdateSphere(param1, param2):
centerPointCoord = [0.0, 0.0, 0.0]
markups.GetNthFiducialPosition(0,centerPointCoord)
circumferencePointCoord = [0.0, 0.0, 0.0]
markups.GetNthFiducialPosition(1,circumferencePointCoord)
sphere.SetCenter(centerPointCoord)
radius=math.sqrt((centerPointCoord[0]-circumferencePointCoord[0])**2+(centerPointCoord[1]-circumferencePointCoord[1])**2+(centerPointCoord[2]-circumferencePointCoord[2])**2)
sphere.SetRadius(radius)
sphere.SetPhiResolution(30)
sphere.SetThetaResolution(30)
sphere.Update()

# Get a reference to the markup
markups=slicer.util.getNode('F')
# Create the sphere that will intersect the slice viewer
sphere = vtk.vtkSphereSource()
# Initial positioning of the sphere
UpdateSphere(0,0)
# Create model node and add to scene
model = slicer.vtkMRMLModelNode()
model.SetAndObservePolyData(sphere.GetOutput())
modelDisplay = slicer.vtkMRMLModelDisplayNode()
modelDisplay.SetSliceIntersectionVisibility(True) # Show in slice view
modelDisplay.SetVisibility(False) # Hide in 3D view
slicer.mrmlScene.AddNode(modelDisplay)
model.SetAndObserveDisplayNodeID(modelDisplay.GetID())
modelDisplay.SetInputPolyData(model.GetPolyData())
slicer.mrmlScene.AddNode(model)
# Call UpdateSphere whenever the fiducials are changed
markups.AddObserver("ModifiedEvent", UpdateSphere, 2)

== Add a texture mapped plane to the scene as a model ==
Note that model textures are not exposed in the GUI and are not saved in the scene
<pre>
# use dummy image data here
e = vtk.vtkImageEllipsoidSource()

scene = slicer.mrmlScene

# Create model node
model = slicer.vtkMRMLModelNode()
model.SetScene(scene)
model.SetName(scene.GenerateUniqueName("2DImageModel"))

planeSource = vtk.vtkPlaneSource()
model.SetAndObservePolyData(planeSource.GetOutput())

# Create display node
modelDisplay = slicer.vtkMRMLModelDisplayNode()
modelDisplay.SetColor(1,1,0) # yellow
modelDisplay.SetBackfaceCulling(0)
modelDisplay.SetScene(scene)
scene.AddNode(modelDisplay)
model.SetAndObserveDisplayNodeID(modelDisplay.GetID())

# Add to scene
modelDisplay.SetAndObserveTextureImageData(e.GetOutput())
scene.AddNode(model)

transform = slicer.vtkMRMLLinearTransformNode()
scene.AddNode(transform)
model.SetAndObserveTransformNodeID(transform.GetID())

vTransform = vtk.vtkTransform()
vTransform.Scale(50,50,50)
vTransform.RotateX(30)
transform.SetAndObserveMatrixTransformToParent(vTransform.GetMatrix())
</pre>

== Export a model to Blender, including color ==

<pre>
plyFilePath = "/tmp/fibers.ply"

lineDisplayNode = getNode("*LineDisplay*")

tuber = vtk.vtkTubeFilter()
tuber.SetInput(lineDisplayNode.GetOutputPolyData())

tubes = tuber.GetOutput()
tubes.Update()
scalars = tubes.GetPointData().GetArray(0)
scalars.SetName("scalars")

triangles = vtk.vtkTriangleFilter()
triangles.SetInput(tubes)

colorNode = lineDisplayNode.GetColorNode()
lookupTable = vtk.vtkLookupTable()
lookupTable.DeepCopy(colorNode.GetLookupTable())
lookupTable.SetTableRange(0,1)

plyWriter = vtk.vtkPLYWriter()
plyWriter.SetInput(triangles.GetOutput())
plyWriter.SetLookupTable(lookupTable)
plyWriter.SetArrayName("scalars")

plyWriter.SetFileName(plyFilePath)
plyWriter.Write()
</pre>

== Clone a volume ==
This example shows how to clone the MRHead sample volume, including its pixel data and display settings.
<pre>
sourceVolumeNode = slicer.util.getNode('MRHead')
volumesLogic = slicer.modules.volumes.logic()
clonedVolumeNode = volumesLogic.CloneVolume(slicer.mrmlScene, sourceVolumeNode, 'Cloned volume')
</pre>

== Create a new volume ==
This example shows how to create a new empty volume.
<pre>
imageSize=[512, 512, 512]
imageSpacing=[1.0, 1.0, 1.0]
voxelType=vtk.VTK_UNSIGNED_CHAR
# Create an empty image volume
imageData=vtk.vtkImageData()
imageData.SetDimensions(imageSize)
imageData.AllocateScalars(voxelType, 1)
thresholder=vtk.vtkImageThreshold()
thresholder.SetInputData(imageData)
thresholder.SetInValue(0)
thresholder.SetOutValue(0)
# Create volume node
volumeNode=slicer.vtkMRMLScalarVolumeNode()
volumeNode.SetSpacing(imageSpacing)
volumeNode.SetImageDataConnection(thresholder.GetOutputPort())
# Add volume to scene
slicer.mrmlScene.AddNode(volumeNode)
displayNode=slicer.vtkMRMLScalarVolumeDisplayNode()
slicer.mrmlScene.AddNode(displayNode)
colorNode = slicer.util.getNode('Grey')
displayNode.SetAndObserveColorNodeID(colorNode.GetID())
volumeNode.SetAndObserveDisplayNodeID(displayNode.GetID())
volumeNode.CreateDefaultStorageNode()
</pre>

== Modify voxels in a volume ==
This example shows how to change voxels values of the MRHead sample volume.
The values will be computed by function f(r,a,s,) = (r-10)*(r-10)+(a+15)*(a+15)+s*s.
<pre>
volumeNode=slicer.util.getNode('MRHead')
ijkToRas = vtk.vtkMatrix4x4()
volumeNode.GetIJKToRASMatrix(ijkToRas)
imageData=volumeNode.GetImageData()
extent = imageData.GetExtent()
for k in xrange(extent[4], extent[5]+1):
for j in xrange(extent[2], extent[3]+1):
for i in xrange(extent[0], extent[1]+1):
position_Ijk=[i, j, k, 1]
position_Ras=ijkToRas.MultiplyPoint(position_Ijk)
r=position_Ras[0]
a=position_Ras[1]
s=position_Ras[2]
functionValue=(r-10)*(r-10)+(a+15)*(a+15)+s*s
imageData.SetScalarComponentFromDouble(i,j,k,0,functionValue)
imageData.SetScalarComponentFromFloat(distortionVectorPosition_Ijk[0], distortionVectorPosition_Ijk[1], distortionVectorPosition_Ijk[2], 0, fillValue)
imageData.Modified()
</pre>

== Manipulate a Slice View ==

<pre>
lm = slicer.app.layoutManager()
red = lm.sliceWidget('Red')
redLogic = red.sliceLogic()
# Print current slice offset position
print redLogic.GetSliceOffset()
# Change slice position
redLogic.SetSliceOffset(20)
</pre>

== Show a volume in the Slice Views ==

<pre>
volumeNode = slicer.util.getNode('YourVolumeNode')
applicationLogic = slicer.app.applicationLogic()
selectionNode = applicationLogic.GetSelectionNode()
selectionNode.SetSecondaryVolumeID(volumeNode.GetID())
applicationLogic.PropagateForegroundVolumeSelection(0)
</pre>

or

<pre>
n = slicer.util.getNode('YourVolumeNode')
for color in ['Red', 'Yellow', 'Green']:
slicer.app.layoutManager().sliceWidget(color).sliceLogic().GetSliceCompositeNode().SetForegroundVolumeID(n.GetID())
</pre>

== Center the 3D View on the Scene ==
<pre>
layoutManager = slicer.app.layoutManager()
threeDWidget = layoutManager.threeDWidget(0)
threeDView = threeDWidget.threeDView()
threeDView.resetFocalPoint()
</pre>

== Display text in a 3D view or slice view ==

The easiest way to show information overlaid on a viewer is to use corner annotations.

<pre>
view=slicer.app.layoutManager().threeDWidget(0).threeDView()
# Set text to "Something"
view.cornerAnnotation().SetText(vtk.vtkCornerAnnotation.UpperRight,"Something")
# Set color to red
view.cornerAnnotation().GetTextProperty().SetColor(1,0,0)
# Update the view
view.forceRender()
</pre>

== Customize viewer layout ==

Show a custom layout of a 3D view on top of the red slice view:

<pre>
customLayout = ("<layout type=\"vertical\" split=\"true\" >"
" <item>"
" <view class=\"vtkMRMLViewNode\" singletontag=\"1\">"
" <property name=\"viewlabel\" action=\"default\">1</property>"
" </view>"
" </item>"
" <item>"
" <view class=\"vtkMRMLSliceNode\" singletontag=\"Red\">"
" <property name=\"orientation\" action=\"default\">Axial</property>"
" <property name=\"viewlabel\" action=\"default\">R</property>"
" <property name=\"viewcolor\" action=\"default\">#F34A33</property>"
" </view>"
" </item>"
"</layout>")

customLayoutId=501

layoutManager = slicer.app.layoutManager()
layoutManager.layoutLogic().GetLayoutNode().AddLayoutDescription(customLayoutId, customLayout)
layoutManager.setLayout(customLayoutId)
</pre>

See description of standard layouts (that can be used as examples) here:
https://github.com/Slicer/Slicer/blob/master/Libs/MRML/Logic/vtkMRMLLayoutLogic.cxx

== Running an ITK filter in Python using SimpleITK ==
Open the "Sample Data" module and download "MR Head", then paste the following snippet in Python interactor:
<pre>
import sitkUtils
inputImage = sitkUtils.PullFromSlicer('MRHead')
filter = sitk.SignedMaurerDistanceMapImageFilter()
outputImage = filter.Execute(inputImage)
sitkUtils.PushToSlicer(outputImage,'outputImage')
</pre>

More information:
* See the SimpleITK documentation for SimpleITK examples: http://www.itk.org/SimpleITKDoxygen/html/examples.html
* sitkUtils in Slicer is used for pushing and pulling images from Slicer to SimpleITK: https://github.com/Slicer/Slicer/blob/master/Base/Python/sitkUtils.py

== Get current mouse coordinates in a slice view ==

You can get 3D (RAS) coordinates of the current mouse cursor from the crosshair singleton node as shown in the example below:

<pre>
def onMouseMoved(observer,eventid):
ras=[0,0,0]
crosshairNode.GetCursorPositionRAS(ras)
print(ras)

crosshairNode=slicer.util.getNode('Crosshair')
crosshairNode.AddObserver(slicer.vtkMRMLCrosshairNode.CursorPositionModifiedEvent, onMouseMoved)
</pre>

Documentation/4.5

2016-02-09T22:02:14Z

Fbudin: Link to users mailing list was broken

<noinclude>{{documentation/versioncheck}}</noinclude>
__NOTOC__
{{documentation/versionlist}}

{| border="0" align="center" width="100%" valign="top" cellspacing="7" cellpadding="2"
|-
! width="33%"|
! |
! width="33%"|
! |
! width="33%"|
|-
|valign="top"|
----
Where to start ?
----
* [[Documentation/{{documentation/version}}/Training|Training pages]]
: Information on how to use Slicer {{documentation/version}}

* [[Documentation/{{documentation/version}}/FAQ|FAQ]]
: Set of common questions/answers
* [http://massmail.spl.harvard.edu/mailman/listinfo/slicer-users Users mailing list] / [http://massmail.spl.harvard.edu/mailman/listinfo/slicer-users Sign-up] / [http://slicer-users.65878.n3.nabble.com/ Browse archives]
----
How to
----
* [[Documentation/{{documentation/version}}/Report a problem|Report a problem]] / [[Documentation/{{documentation/version}}/Create_a_feature_request|Create a feature request]]{{new}}
----
{{:{{FULLPAGENAME}}/SlicerApplication}}

|bgcolor="#CCCCCC"|
|valign="top"|
----
Modules and Extensions
----
{{:{{FULLPAGENAME}}/ModuleExtensionListing/TOC}}



|bgcolor="#CCCCCC"|
|valign="top"|
----
Developers Corner
----
* [[Documentation/Nightly/Developers | Information for Software Developers]]{{updated}}
: Source code, contribute patch, develop modules

* [http://massmail.bwh.harvard.edu/mailman/listinfo/slicer-devel Developers mailing list] / [http://slicer-devel.65872.n3.nabble.com/ Browse archives]
: Intended for discussion of programming related questions
----
Miscellaneous
----


* [[Documentation/{{documentation/version}}/HowTo|Documentation guidelines]]
: Slicer user documentation principle and guidelines

* [[Slicer4:VisualBlog|Visual blog]]
: Set of screenshots showing Slicer in action.

* [[Documentation/{{documentation/version}}/ReleaseNotes|Release Notes]]
: Platform specific issues and considerations

* [[Documentation/{{documentation/version}}/Announcements|Announcements]] & [[Documentation/{{documentation/version}}/Acknowledgments|Acknowledgments]]

* [http://wiki.slicer.org/slicerWiki/index.php/Documentation/Nightly/Registration/RegistrationLibrary Registration Library]
: Real-life example cases of using the Slicer registration tools, incl. datasets and step-by-step instructions to follow and try yourself.

----
Documentación en Español {{new}}
----
* [http://robustiana.com/156-intro-a-3d-slicer Introducción a 3D Slicer en Español]
: Breve descripción de proyecto y un breve viaje por sus principales herramientas y funcionalidades.

* [http://robustiana.com/157-recon-volumetricas Reconstrucciones volumétricas con 3D Slicer]
: Guía de uso para la herramienta de creación de reconstrucciones volumétricas de 3D Slicer.

* [http://robustiana.com/158-contornos-3d-slicer Crear modelos/contornos de órganos con 3D Slicer]
: Guía rápida introductoria para la creación de contornos de órganos para generar vistas volumétricas.

* [http://robustiana.com/159-endoscopias-3d-slicer Endoscopías virtuales con 3D Slicer]
: Manual de uso de la herramienta para 3D Slicer desarrollada por Steve Pieper para realizar endoscopías virtuales.

* [http://robustiana.com/163-rt-slicer-3d Creando curvas de isodosis con SlicerRT de 3D Slicer]
: Introducción a la extensión SlicerRT para 3D Slicer enfocada en investigación en radioterapia.

|}

{{:{{FULLPAGENAME}}/ModuleExtensionListing}}

Documentation/Nightly/Developers/Build Instructions/CheckoutSourceCode

Documentation/Nightly/Modules/SurfaceRegistration

2015-10-12T21:29:39Z

Fbudin:

Documentation/Nightly/Developers/SlicerExecutionModel

2015-10-07T16:11:08Z

Fbudin: /* XML Schema */

== Introduction ==

The Slicer Execution Model is designed to improve the acceptance and productivity of Slicer application developers. The Execution Model provides a simple mechanism for incorporating command line programs as Slicer modules. These command line modules are self-describing, emitting an XML description of its command line arguments. Slicer uses this XML description to construct a GUI for the module.

=== Types of Slicer Plugins ===

There are various types of plugins that Slicer supports as command line modules. This variety allows a breadth of integration choices to balance performance and flexibility.

==== Shared object plugins (dll, so) with global symbols ====

Shared object plugins with global symbols integrate into Slicer tighter than the Executable plugins. Shared object plugins with global symbols can transfer data directly to/from a MRML scene using standard itk::ImageFileReader and itk::ImageFileWriter (and the ImageIO class provided with Slicer, itk::MRMLIDImageIO). Communicating directly with the MRML scene avoids the overhead of reading and writing images to disk. Slicer looks for a standard entry point to execute the module called ModuleEntryPoint defined as

int ModuleEntryPoint(int argc, char* argv[]);

Slicer also looks for the global symbols XMLModuleDescription, ModuleLogoImage, ModuleLogoWidth, ModuleLogoHeight, ModuleLogoPixelSize, and ModuleLogoLength. These global symbols provide the xml module description and data for the module logo. The data types for these symbols are

char *XMLModuleDescription;
unsigned char *ModuleLogoImage;
int ModuleLogoWidth;
int ModuleLogoHeight;
int ModuleLogoPixelSize;
unsigned long ModuleLogoLength;

These global symbols are accessed during module discovery. The ModuleLogoImage, ModuleLogoWidth, ModuleLogoHeight, ModuleLogoPixelSize, and ModuleLogoLength are optional.

=====Controlling what symbols are exported from a shared library module=====

Shared Object Modules are loaded into Slicer using standard "dlopen" style calls. The ModuleEntryPoint is located within the shared library and cached for later use. The ModuleEntryPoint, however, may not be the only function accessible to Slicer within the shared library. To protect against symbol clash at runtime, all functions and variables accessible within file scope of the shared library should be put in an anonymous namespace.

<pre>
// Use an anonymous namespace to keep class types and function names
// from colliding when module is used as shared object module. Every
// thing should be in an anonymous namespace except for the module
// entry point, e.g. main() or ModuleEntryPoint()
//
namespace {
// functions like DoIt() should be put in the anonymous namespace
template<class T> int DoIt( int argc, char * argv[], const T& targ)
{
}
} // end of anonymous namespace

int main(int argc, char* argv[] )
{
}

</pre>

==== Shared object plugins (dll, so) with entry points ====

Shared object plugins with entry points integrate into Slicer tighter than the Executable plugins. Shared object plugins with entry points can transfer data directly to/from a MRML scene using standard itk::ImageFileReader and itk::ImageFileWriter (and the ImageIO class provided with Slicer, itk::MRMLIDImageIO). Communicating directly with the MRML scene avoids the overhead of reading and writing images to disk. Slicer looks for standard entry points for executing the module as well as for querying the module for its xml description and logos. The entry points are defined as

int ModuleEntryPoint(int argc, char* argv[]);
char *GetXMLModuleDescription();
unsigned char *GetModuleLogo()(int *width, int *height, int *pixel_size, unsigned long *bufferLength);

GetXMLModuleDescription() and GetModuleLogo() are accessed during module discovery. GetModuleLogo() is optional.

==== Executable plugins with global symbols ====

Executable plugins with global symbols allow for a single executable to be developed that can be integrated into Slicer 3 or run standalone on a cluster. Plugins of this type are opened but not executed at module discovery time. Slicer 3 looks for the global symbols XMLModuleDescription, ModuleLogoImage, ModuleLogoWidth, ModuleLogoHeight, ModuleLogoPixelSize, and ModuleLogoLength. The data types for these symbols are

char *XMLModuleDescription;
unsigned char *ModuleLogoImage;
int ModuleLogoWidth;
int ModuleLogoHeight;
int ModuleLogoPixelSize;
unsigned long ModuleLogoLength;

These global symbols are access during module discovery. ModuleLogoImage, ModuleLogoWidth, ModuleLogoHeight, ModuleLogoPixelSize, ModuleLogoLength are optional.

==== Executable plugins (exe) with command line options ====

Executable plugins with command line options are the most flexible type of plugin. This approach allows for legacy applications to be integrated into Slicer using a wrapper around the legacy application. Plugins of this type are executed at module discovery time, passing in the command line argument "--xml". The plugin responds to the "--xml" query by emitting the xml description of the module. The plugin is also executed at module discovery time with a "--logo" command line argument. The plugin responds to the "--logo" query by emitting a logo description.

This type of plugin allows for legacy applications to be integrated into Slicer. A developer can provide Slicer with a small executable or shell script that responds to the "--xml" and "--logo" command line arguments needed for Slicer 3 integration and otherwise spawns the legacy executable passing down any command line arguments.

> module.exe --xml
> module.exe --logo

==== Script plugins with Python ====

Python scripts are found using the discovery mechanisms for the other plugins. Since Python plugins are fundamentally different from the shared and executable plugins, they are documented on their own [[Documentation/Nightly/Developers/SlicerExecutionModel/Python|page]].

=== Calling Command Line Modules from Other Code ===

In addition to the automated GUI that shows up in the Slicer user interface, the Execution Model can be used to encapsulate functionality that is invoked by other parts of the program. For instance, the Editor Module can invoke the Model Maker Module to build models. By invoking a command line module in this way, you get the advantage of background processing with progress reporting. See [[Documentation/Nightly/Developers/SlicerExecutionModel/Programmatic Invocation|this page]] for more details.

=== Architecture ===
[[Image:ExecutionModelPlugins.png|600px|Plugin architecture]]
[[Image:CommandLineModule.png|400px|Module architecture]]
[[Image:ModuleFactory.png|400px|Module factory ]]
[[Image:Class_parser_state_coll_graph.png|400px|Module description]]

== Module Description ==

Modules are described using XML. The XML is used to generate the C++ command line code and the GUI for the application.

=== XML Schema ===

At a minimum, each module description must contain:

<?xml version="1.0" encoding="utf-8"?>
<executable>
<title>A title</title>
<description>A description</description>
<parameters>
At least one parameter
</parameters>
</executable>

In the following descriptions of each XML tag, CLP means command line processing and GUI means graphical user interface. Unless otherwise specified, tags are optional.

; <executable> (required)

;; <category>
:: Classifies the executable (e.g. Filtering, Segmentation). Category can be a ''dot'' separated string. Multiple categories can be given and should be separated by a ''semicolon''.
:: ''for CLP'', not used.
:: ''for GUI'', used on the menu selector to group executables. ''Dot'' separated strings can be used to generate sub-menus. ''Semicolon'' separated strings can be used to create multiple categories.
;; </category>

;; <title> (required)
:: A word or two describing the executable (e.g. Median Filter, Anisotropic Diffusion
:: ''for CLP'', not used.
:: ''for GUI'', used to label the frame containing the GUI for the executable. Also, GUI names for volumes use this label as a prefix.
;; </title>

;; <description> (required)
:: A long description of the executable. Any double quotes will be converted to single quotes.
:: ''for CLP'', appears at the end of the --help.
:: ''for GUI'', appears in the help frame.
;; </description>

;; <version>
:: The version of the command line executable. A suggested format is:
::: ''major''.''minor''.''patch''.''build''.''status''
::: where status is
:::: vc: version controlled (pre-alpha), build can be a serial revision number, if any (like svn might have).
:::: a: alpha
:::: b: beta
:::: rc: release candidate
:::: fcs: first customer ship
:: ''for CLP'', reported in response to --version.
:: ''for GUI'', not used.
;; </version>

;; <documentation-url>
:: The location of extended documentation for the executable, (e.g. http://www.na-mic.org/foo.html).
;; </documentation-url>

;; <license>
:: The type of license or a url containing the license, (e.g. Berkeley, Apache, http://www.slicer.org/copyright/copyright.txt).
:: ''for CLP'', not used.
:: ''for GUI'', may show up in the Help or About section.
;; </license>

;; <contributor>
:: The author(s) of the command line executable (e.g. Pieper, Jim Miller).
:: for ''CLP'', appears as part of --help
:: for ''GUI'', may show up in the Help or About section.
;; </contributor>

;; <acknowledgements>
:: Acknowledgements for funding agency, employer, colleague, (e.g. This work is part of the National Alliance for Medical Image Computing NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149).
:: for ''CLP'', appears as part of --help
:: for ''GUI'', may show up in the Help of About section.
;; </acknowledgements>

;; <parameters [advanced="true|''false''"]> (required for each group of parameters)
:: Starts a group of parameters.
:: for ''CLP'', not used.
:: for ''GUI'', defines a widget (in tk, a frame) that contains other widgets. If ''advanced'' is true, the frame will be closed initially.

;;; <label> (required)
::: A short string that summarizes a parameter group, (e.g. I/O, Diffusion)
::: for ''CLP'', not used.
::: for ''GUI'', used to label the frame.
;;; </label>

;;; <description> (required)
::: A short description of the parameter group, (e.g. Input/Output Parameters, Anitostropic Diffusion Parameters). Any double quotes will be converted to single quotes.
::: ''for CLP'', not used.
::: ''for GUI'', used in balloon help for the frame containing the parameter group.
;;; </description>

;;; <integer> | <float> | <double> | <boolean> | <string> | <integer-vector> | <float-vector> | <double-vector> | <string-vector> | <integer-enumeration> | <float-enumeration> | <double-enumeration> | <string-enumeration> | <file> | <directory> | <image [type="''scalar''|''label''|''tensor''|''diffusion-weighted''|''vector''|''model''"]> | <geometry [type="''fiberbundle''|''model''"]> | <point [multiple="''true''|''false''"] [coordinateSystem="''lps''|''ras''|''ijk''"]> | <region [multiple="''true''|''false''"] [coordinateSystem="''lps''|''ras''|''ijk''"]>
::: The type of the parameter.
:::: The scalar types ('''integer''', '''float''', etc.) correspond to the usual programming language types.
:::: The '''-vector''' types are represented by comma separated values of the scalar type.
:::: The '''-enumeration''' types use the '''<element>''' tag to enumerate choices of the scalar type.
:::: '''<image>''' is a special type that indicates that the parameter is a file name that specifies images.
:::: If the attribute ''multiple'' is "true", multiple arguments are allowed for '''scalar''', '''file''', '''directory''', '''image''', '''geometry''', '''point''' and '''region''' parameters. BUG: the automatically built GUI will not support selecting multiple volumes for the '''image''' argument, but they can be passed on the command line. If the parameter has a ''flag'' or ''longflag'', then the flag may be specified multiple times on the command line. The resulting C++ variable will be a std::vector of the scalar type. If the multiple parameter does not have a flag, then multiple arguments can appear on the command line. However, a multiple parameter with no flags must be the last parameter specified.
:::: The attribute ''coordinateSystem'' is allowed for the parameters '''point''' and '''region'''.
:::: The attribute ''fileExtensions'' is allowed for '''file''', '''image''' and '''geometry'''. fileExtensions can contain a list of comma separated file extensions for optional use by the GUI.

;;;; <name> (required if longflag is not specified)
:::: The name of a command line argument. If name is not specified, longflag will be used (e.g. conductance, numberOfIterations). The name must be usable as a C++ variable. For example, it CANNOT have spaces or special characters and must start with a letter.
:::: ''for CLP'', the name of the C++ variable.
:::: ''for GUI'', used internally.
;;;; </name>

;;;; <description> (required)
:::: A brief description of the parameter. Any double quotes will be converted to single quotes.
:::: ''for CLP'', describes the parameter for --usage and --help.
:::: ''for GUI'', describes the parameter when the cursor is placed over the widget for the parameter (balloon help).
;;;; </description>

;;;; <label> (required)
:::: A label for parameter (e.g. Dicom Directory, Conductance).
:::: ''for'' CLP, not used.
:::: ''for'' GUI, the label for the parameter widget.
;;;; </label>

;;;; <default>
:::: A default value for the parameter. The default must be a type that is compatible with the parameter type. The vector parameters are specified as comma separated values of the atomic parameter type.
:::: ''for CLP'', contains the default for the parameter unless the parameter is a ''boolean''. The default for ''boolean'' parameters is always set to ''false''.
:::: ''for GUI'', contains the default for the parameter.
;;;; </default>

;;;; <flag [alias="a,b"] [deprecatedalias="c,d"]> (not required if longflag is present)
:::: A single character command line flag (e.g. s, W). Can provide "alias"'s (comma separated) if different flags can be used to activate the same parameter. Can provide "deprecatedalias"'s (comma separated) if different flags can be used to set the same parameter but the user should be notified of which "updated" flag to use. Parameters with flags are considered "optional" and do not have be specified or assigned. Parameters with flags allow one to override a default behavior.
:::: ''for CLP'', used as the short flag on the command line.
:::: ''for GUI'', used when running the module.
;;;; </flag>

;;;; <longflag [alias="foo,bar"] [deprecatedalias="garf"]> (not required if flag is present)
:::: A command line flag (e.g. spacing, Watcher). Can provide "alias"'s (comma separated) if different long flags can be used to activate the same parameter. Can provide "deprecatedalias"'s (comma separated) if different long flags can be used to set the same parameter but the user should be notified of which "updated" long flag to use. Parameters with flags are considered "optional" and do not have be specified or assigned. Parameters with flags allow one to override a default behavior.
:::: Note: apparently you can't use hyphens in the longflag, so things like --my-option are not allows. -gcs
:::: ''for CLP'', used as the long flag on the command line.
:::: ''for GUI'', used when running the module.
;;;; </longflag>

;;;; <constraints>
:::: Encloses constraints on the value of a non-vector, non-enumerated parameter.
:::: ''for CLP'', not used.
:::: ''for GUI'', if present, a slider will be created using the minimum, maximum and step specified.

;;;;; <minimum>
::::: The minimum allowed value for the parameter. If not specified, the minimum is the smallest possible value for the parameter type.
;;;;; </minimum>

;;;;; <maximum>
::::: The maximum allowed value for the parameter. If not specified, the maximum is the largest possible value for the parameter type.
;;;;; </maximum>

;;;;; <step>
::::: The increment for the parameter.
;;;;; </step>

;;;; </constraints>

;;;; <channel> (required for file, directory and image parameters)
:::: Specifies whether the parameter is an input or output parameter.
:::: ''for CLP'', not used.
:::: ''for GUI'', selects the proper widget for file handling.
;;;; </channel>

;;;; <index> (required if there are no flags specified)
:::: An integer starting at 0, that specifies a command line argument that has no flags.
:::: Note: if you use index for, say, an image, the user must enter some input value into the GUI. If the user does not fill in a value, the plugin is not run at all. However, slicer will "seem" to run it, and no error message is given. -gcs
:::: ''for CLP'', specifies the order of an argument that has no flags.
:::: ''for GUI'', used when running the module.
;;;; </index>

;;;; <enumeration> (required for enumeration parameters)
:::: Encloses elements for the parameter. The parameter is restricted one and only one element.
:::: ''for CLP'', not used.
:::: ''for GUI'', defines a radio button with choices.

;;;;; <element>
::::: Defines the choice. Must be of the proper type for a parameter.
::::: ''for CLP'', not used.
::::: ''for GUI'', used as the label for the raido button.
;;;;; </element>

;;;; </enumeration>

;;; </integer> | </float> | </double> | </boolean> | </string> | </integer-vector> | </float-vector> | </double-vector> | </string-vector> | </integer-enumeration> | </float-enumeration> | </double-enumeration> | </string-enumeration> | </file> | </directory> | </image> | </geometry> | </point> | </region>
;; </parameters>

; </executable>

== Slicer GUI Generation ==

Slicer generates GUI's for each executable discovered during the startup process. Slicer searches directories stored in the Slicer Module Path. This path is set from the Slicer application in View->Application Settings->Modules->Additional module paths. Slicer attempts to run every executable in the prescribed directories and look for a valid XML file in response to a "--xml" command line.

Here are a few representative examples.

=== A tour of the Execution Model XML ===

This example is a sampler of the parameters available in the Execution Model.

<div class="floatright">[[Image:ExectionModelTourGUI.png|[[Image:ExectionModelTourGUI.png]]]]</div>

<?xml version="1.0" encoding="utf-8"?>
<executable>
<category>Tours</category>
<title>Execution Model Tour</title>
<description>
Shows one of each type of parameter.
</description>
<version>1.0</version>
<documentation-url></documentation-url>
<license></license>
<contributor>Daniel Blezek</contributor>

<parameters>
<label>Scalar Parameters</label>
<description>
Variations on scalar parameters
</description>
<integer>
<name>integerVariable</name>
<flag>i</flag>
<longflag>integer</longflag>
<description>
An integer without constraints
</description>
<label>Integer Parameter</label>
<default>30</default>
</integer>
<label>Scalar Parameters With Constraints</label>
<description>Variations on scalar parameters</description>
<double>
<name>doubleVariable</name>
<flag>d</flag>
<longflag>double</longflag>
<description>An double with constraints</description>
<label>Double Parameter</label>
<default>30</default>
<constraints>
<minimum>0</minimum>
<maximum>1.e3</maximum>
<step>0</step>
</constraints>
</double>
</parameters>

<parameters>
<label>Vector Parameters</label>
<description>Variations on vector parameters</description>
<float-vector>
<name>floatVector</name>
<flag>f</flag>
<description>A vector of floats</description>
<label>Float Vector Parameter</label>
<default>1.3,2,-14</default>
</float-vector>
<string-vector>
<name>stringVector</name>
<longflag>string_vector</longflag>
<description>A vector of strings</description>
<label>String Vector Parameter</label>
<default>"foo",bar,"foobar"</default>
</string-vector>
</parameters>

<parameters>
<label>Enumeration Parameters</label>
<description>Variations on enumeration parameters</description>
<string-enumeration>
<name>stringChoice</name>
<flag>e</flag>
<longflag>enumeration</longflag>
<description>An enumeration of strings</description>
<label>String Enumeration Parameter</label>
<default>foo</default>
<element>foo</element>
<element>"foobar"</element>
<element>foofoo</element>
</string-enumeration>
</parameters>
</executable>

=== Module with an integer-vector, one input image and one output image ===

Here is the XML that describes the MedianImageFilter. The image on the right shows the generated Slicer 3 GUI. The help frame has been expanded by the user.

<div class="floatright">[[Image:MedianFilterGUI.png|[[Image:MedianFilterGUI.png]]]]</div>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<executable>
<category>
Filtering.Denoising
</category>
<title>
Median Filter
</title>
<description>
The MedianImageFilter is commonly used as a robust approach for
noise reduction. This filter is particularly efficient against
"salt-and-pepper" noise. In other words, it is robust to the presence
of gray-level outliers. MedianImageFilter computes the value of each output
pixel as the statistical median of the neighborhood of values around the
corresponding input pixel.
</description>
<version>0.1.0.$Revision: 2085 $(alpha)</version>
<documentation-url></documentation-url>
<license></license>
<contributor>Bill Lorensen</contributor>
<acknowledgements>This command module was derived from
Insight/Examples/Filtering/MedianImageFilter (copyright) Insight Software Consortium
</acknowledgements>
<parameters>
<label>Median Filter Parameters</label>
<description>Parameters for the median filter</description>

<integer-vector>
<name>neighborhood</name>
<longflag>--neighborhood</longflag>
<description>The size of the neighborhood in each dimension</description>
<label>Neighborhood Size</label>
<default>1,1,1</default>
</integer-vector>

</parameters>

<parameters>
<label>IO</label>
<description>Input/output parameters</description>
<image>
<name>inputVolume</name>
<label>Input Volume</label>
<channel>input</channel>
<index>0</index>
<description>Input volume to be filtered</description>
</image>
<image>
<name>outputVolume</name>
<label>Output Volume</label>
<channel>output</channel>
<index>1</index>
<description>Output filtered</description>
</image>
</parameters>

</executable>
</pre>

=== Module with a multiple scalars, one Input image and one output image ===

A module with

<div class="floatright">[[Image:AnisotropicDiffusionFilterGUI.png|[[Image:AnisotropicDiffusionFilterGUI.png]]]]</div>

<?xml version="1.0" encoding="utf-8"?>
<executable>
<category>filtering</category>
<title>Anisotropic Diffusion</title>
<description>
Runs anisotropic diffusion on a volume
</description>
<version>1.0</version>
<documentation-url></documentation-url>
<license></license>
<contributor>Bill Lorensen</contributor>

<parameters>
<label>
Anisotropic Diffusion Parameters
</label>
<description>
Parameters for the anisotropic
diffusion algorithm
</description>

<double>
<name>conductance</name>
<longflag>conductance</longflag>
<description>Conductance</description>
<label>Conductance</label>
<default>1</default>
<constraints>
<minimum>0</minimum>
<maximum>10</maximum>
<step>.01</step>
</constraints>
</double>

<double>
<name>timeStep</name>
<longflag>timeStep</longflag>
<description>Time Step</description>
<label>Time Step</label>
<default>0.0625</default>
<constraints>
<minimum>.001</minimum>
<maximum>1</maximum>
<step>.001</step>
</constraints>
</double>

<integer>
<name>numberOfIterations</name>
<longflag>iterations</longflag>
<description>Number of iterations</description>
<label>Iterations</label>
<default>1</default>
<constraints>
<minimum>1</minimum>
<maximum>30</maximum>
<step>1</step>
</constraints>
</integer>

</parameters>

<parameters>
<label>IO</label>
<description>Input/output parameters</description>
<image>
<name>inputVolume</name>
<label>Input Volume</label>
<channel>input</channel>
<index>0</index>
<description>Input volume to be filtered</description>
</image>
<image>
<name>outputVolume</name>
<label>Output Volume</label>
<channel>output</channel>
<index>1</index>
<description>Output filtered</description>
</image>
</parameters>

</executable>

=== Module with output text presented in GUI ===

Slicer auto generates GUI to display output from the command line module after execution is complete.
The flag [--returnparameterfile <file name>] is used to provide a name of a file that the module uses to store key=value pairs that are displayed in the Slicer GUI. The keys are described in the command line module xml schema using the output channel.

This example demonstrates a portion of an XML schema containing 1 string-enumeration input and 7 string outputs.

<div class="floatright">[[Image:RadnosticsBetaOsteoporosisAnalysisGUI.png|[[Image:RadnosticsBetaOsteoporosisAnalysisGUI.png]]]]</div>

<parameters>
<label>Radnostics Beta Osteoporosis Analysis</label>
<string-enumeration>
<name>Osteoporosis</name>
<longflag>--osteoporosis</longflag>
<label>After Segmentation Perform Osteoporosis Analysis</label>
<description>Osteoporosis Analysis will provide a Radnostics Osteoporosis score for the patient.</description>
<default>yes</default>
<element>yes</element>
<element>no</element>
</string-enumeration>
<string>
<name>PatientGender</name>
<label>Gender</label>
<channel>output</channel>
<description>Patient Gender</description>
<default>na</default>
</string>
<string>
<name>PatientAge</name>
<label>Age</label>
<channel>output</channel>
<description>Patient Age</description>
<default>na</default>
</string>
<string>
<name>RadnosticsOsteoporosisScore</name>
<label>Radnostics Osteoporosis Score</label>
<channel>output</channel>
<description>Radnostics Osteoporosis Score</description>
<default>na</default>
</string>
<string>
<name>OsteoporosisComment1</name>
<channel>output</channel>
<label>*</label>
<description>Comment 1</description>
</string>
<string>
<name>OsteoporosisComment2</name>
<channel>output</channel>
<label>*</label>
<description>Comment 2</description>
</string>
<string>
<name>OsteoporosisComment3</name>
<channel>output</channel>
<label>*</label>
<description>Comment 3</description>
</string>
<string>
<name>OsteoporosisComment4</name>
<channel>output</channel>
<label>*</label>
<description>Comment 4</description>
</string>
</parameters>

The command line module outputs key=value pairs to the file supplied by –-returnparameterfile as shown below:
PatientGender = F
PatientAge = 059Y
RadnosticsOsteoporosisScore = 8 (high)
OsteoporosisComment1 = vertebra label 58 has biconcave fracture
OsteoporosisComment2 = vertebra label 56 has mean density of 120 HU

== Command Line Parsing ==

The Slicer Execution Model has support for parsing executable command lines. The C++ code to parse the command line arguments is generated automatically from the same XML description that generates the GUI. ''GenerateCLP,'' located in ''SlicerExecutionModel/GenerateCLP'' reads the XML Module Description and creates an include file ''"Executable"CLP.h'' in the build tree. The executable includes this header file and accesses the code with the macro PARSE_ARGS.

GenerateCLP provides the following to the executable:

# A brief usage command if required arguments are missing
# A full help command if ''-h'' or ''--help'' is specified on the command line
# A copy of the xml description if ''--xml'' is specified on the command line
# An echo of the command line parameters and their values if ''--echo'' is specified

GenerateCLP provides the following source code:

# A C++ declaration of the proper type for each parameter assigning the default value if specified by the XML
# For ''-vector'' parameters, a ''std::vector'' containing the proper C++ type fo the parameter. The generated code parses the comma separated strings to generate the ''std::vector''

=== Using GenerateCLP ===

GenerateCLP is normally used via CMake where it is implemented as a CUSTOM_COMMAND. To use GenerateCLP from CMake, you must first include the GenerateCLP package from your CMakeLists.txt file, which will make some macros available to you:

find_package(SlicerExecutionModel REQUIRED)
include(${SlicerExecutionModel_USE_FILE})

Note that the HelloSlicer command line module example provides a good starting point and can be used as a skeleton to build your own. It can be found in the [http://na-mic.org/ViewVC/index.cgi/trunk/Modules/CommandLineModule/Testing/HelloSlicer/?sortby=file#dirlist Modules/CommandLineModule/Testing/HelloSlicer] subdirectory.

For each executable, include the following, replacing '''MyFilter''' with the name of your C++ source:

set('''MyFilter'''_SOURCE '''MyFilter'''.cxx)
GENERATECLP('''MyFilter'''_SOURCE '''MyFilter'''.xml)

To generate a stand-alone executable add the lines:

add_executable('''MyFilter''' ${'''MyFilter'''_SOURCE})
target_link_libraries('''MyFilter''' ${ITK_LIBRARIES})

Slicer expects modules and plugins to be stored in a specific subdirectory, so that they can be discovered and loaded at run-time. To make sure your CLP module is built in said subdirectory, add the line:

SEMMacroBuildCLI(
NAME '''MyFilter'''
LOGO_HEADER ${Slicer_SOURCE_DIR}/Resources/NAMICLogo.h
ADDITIONAL_SRCS
'''MyFilter'''.cxx
TARGET_LIBRARIES ModuleDescriptionParser ${ITK_LIBRARIES} vtkTeem MRMLCore SlicerBaseCLI ${VTK_LIBRARIES}
INCLUDE_DIRECTORIES
${vtkTeem_INCLUDE_DIRS}
${MRMLCore_INCLUDE_DIRS}
${vtkITK_INCLUDE_DIRS}
${SlicerBaseCLI_SOURCE_DIR} ${SlicerBaseCLI_BINARY_DIR}
)

The add_executable target creates a stand-alone executable that can be run from a command line. The add_library target creates a shared library that is discovered at Slicer 3 startup.

Although this example linked to ITK libraries, other libraries can be specified.

=== Short Example ===

This example uses the XML for the [http://www.slicer.org/slicerWiki/index.php/Slicer3:Execution_Model_Documentation#Module_with_an_integer-vector.2C_one_input_image_and_one_output_image|Median Image Filter example].
 
'''Note:''' The program '''MUST NOT''' write anything to stdout before the ''PARSE_ARGS'' statement. If something is written, the plugin discovery mechanism will not recognize the program as a plugin.

<nowiki>#include "MedianImageFilterCLP.h"
int main (int argc, char * argv[])
{
PARSE_ARGS;
std::cout << "The size of the neighborhood is: " << neighborhood.size()
<< " and the first element of the neighborhood is: " << neighborhood[0]
<< std::endl;
std::cout << "The input volume is: " << inputVolume << std::endl;
std::cout << "The output volume is: " << outputVolume << std::endl;
return EXIT_SUCCESS;
}
</nowiki>

Here is the output --help:

<pre>

USAGE:

./MedianImageFilter [--processinformationaddress <std::string>] [--xml]
[--echo] [--neighborhood <std::vector<int>>] [--]
[--version] [-h] <std::string> <std::string>

Where:

--processinformationaddress <std::string>
Address of a structure to store process information (progress, abort,
etc.). (default: 0)

--xml
Produce xml description of command line arguments (default: 0)

--echo
Echo the command line arguments (default: 0)

--neighborhood <std::vector<int>>
The size of the neighborhood in each dimension (default: 1,1,1)

--, --ignore_rest
Ignores the rest of the labeled arguments following this flag.

--version
Displays version information and exits.

-h, --help
Displays usage information and exits.

<std::string>
(required) Input volume to be filtered

<std::string>
(required) Output filtered

The MedianImageFilter is commonly used as a robust approach for noise
reduction. This filter is particularly efficient against
'salt-and-pepper' noise. In other words, it is robust to the presence of
gray-level outliers. MedianImageFilter computes the value of each output
pixel as the statistical median of the neighborhood of values around the
corresponding input pixel.

Author(s): Bill Lorensen

Acknowledgements: This command module was derived from
Insight/Examples/Filtering/MedianImageFilter (copyright) Insight
Software Consortium

</pre>

=== Parameters and C++ code ===

This table shows how parameters are defined in the C++ code and how they are specified on the command line.

{| border="1"
! XML
! C++ Declaration
! Command Line
|-
|
<integer> <name>count</name> <flag>c</flag> </integer>
|
int count;
|
''prog'' -c 10
|-
|
<float> <name>stepSize</name> <default>.0625</default> <longflag>stepSize</longflag> </float>
|
float stepSize=.0625;
|
''prog'' --stepSize .003
|-
|
<integer multiple="true"> <name>iterations</name> <flag>i</flag> <default>100</default> </integer>
|
std::vector<int> iterations; iterations.push_back(100); 
|
''prog'' -i 20 -i 30 -i 100
|-
|
<float-vector> <name>variation</name> <flag>v</flag> <default>1,2,3</default> </float-vector>
|
std::vector<float> variation; iterations.push_back(1); iterations.push_back(2); iterations.push_back(3); 
|
''prog'' -v 10,20,3
|-
|
<string-vector> <name>sites</name> <longflag>sites</longflag> </string-vector>
|
std::vector<std::string> sites;
|
''prog'' --sites BWH,GE,Kitware,UNC,MIT,UTAH,GT
|-
|
<string-enumeration> <name>leaders</name> <default>Bill</default> <element>Ron</element> <element>Bill</element> <element>Steve</element> </string-enumeration>
|
std::string leaders = "Bill";
|
''prog'' --leaders Ron
|-
|
<boolean> <name>debugSwitch</name> <flag>d</flag> <default>true</default> </boolean>
|
bool debugSwitch = true;
|
''prog'' -d
|-
|
<file> <longflag>file1</longflag> <file>
|
std::string file1;
|
''prog'' --file1 mytext.txt
|-
|
<image> <name>image</name> <index>0</index> </image>
|
std::string image;
|
''prog'' c:/lorensen/Data/ct.nrrd
|-
|
<file multiple="true"> <name>args</name> <index>1</index> </file>
|
std::vector<std::string> args;
|
''prog'' --otherFlags file1 file2 ... filen
|-
|
<point multiple="true" coordinateSystem="ras"> <name>seed</name> <longflag>--seed</longflag>
|
std::vector<std::vector<float> > seed;
|
''prog'' --seed 10,100,23 --seed 5,240,17
|}

== Accessing Module Information at Runtime ==

All of the information contained in the XML description of a module can be accessed at run-time by the command line program. The ''ModuleDescriptionParser'' class library can parse an XML module description and populate a ''ModuleDescription'' instance.
<pre>
// Module Description Parser Class Library
#include "ModuleDescriptionParser.h"
#include "ModuleDescription.h"
#include "ModuleParameterGroup.h"
#include "ModuleParameter.h"
.
.
.
// Create a module and a parser
ModuleDescription module;
ModuleDescriptionParser parser;
// Parse the XML
if (parser.Parse(GetXMLModuleDescription(), module))
{
std::cerr << argv[0] << ": One or more XML errors detected." << std::endl;
return EXIT_FAILURE;
}
// Access the module description information
std::cout << "Module Description Information" << std::endl;
std::cout << "\tCategory is: " << module.GetCategory() << std::endl;
std::cout << "\tTitle is: " << module.GetTitle() << std::endl;
std::cout << "\tDescription is: " << module.GetDescription() << std::endl;
std::cout << "\tVersion is: " << module.GetVersion() << std::endl;
std::cout << "\tDocumentationURL is: " << module.GetDocumentationURL() << std::endl;
std::cout << "\tLicense is: " << module.GetLicense() << std::endl;
std::cout << "\tContributor is: " << module.GetContributor() << std::endl;
</pre>

''GetXMLModuleDescription'' is automatically generated by ''GenerateCLP''. Information about parameter groups and parameters is also available [[Accessing_Module_Information_at_Runtime|here]].

The ''CMakeLists.txt'' file that creates the command line module should point to the ''ModuleDescriptionParser'' library.
<pre>
target_link_libraries(${CLP}
ModuleDescriptionParser
)
</pre>

== Error Handling ==

GenerateCLP attempts to do error checking so that the generated C++ code will compile. These errors will show up as custom command errors during the build process.

* XML Errors
** ''mismatched tag at line xx'' : The closing tag (a tag with </ >) does not have a matching opening tag.
** ''not well-formed (invalid token) at line xx'' : Probably a blank in the token name.
* ModuleDescriptionParser Errors
** ''<executable> must be the outer most tag''
** ''<executable> was found inside another tag''
** ''<parameters> can only be inside <executable>''
** ''<xxx> can only be used inside <parameters>''
** ''<flag> can only contain one character''
** ''<longname> can only contain letters, numbers and underscores and must start with an _ or letter''
** ''<name> can only contain letters, numbers and underscores and must start with an _ or letter''

* ModuleDescriptionParser Warnings
** ''<xxx> is an unknown parameter tag'' : Probably a misspelled parameter type.

* Compiler Errors
** The generated C++ code may have syntax errors if invalid defaults are specified. These will show up during the C++ compilation.

== Interfacing Legacy Executables ==

GenerateCLP is only provided as a convenience. Users can use the same XML Module Description to interface C++, shell scripts, tcl programs and even Matlab.

Example: [http://www.slicer.org/slicerWiki/index.php/Slicer3:FiberTrackingIntegration FiberTracking Integration]

== Showing Progress in an Application ==

Programs can communicate progress to the user in two ways. If the program is running an a stand-alone executable, it communicates with a simple XML syntax. If the program is loaded at run-time as a plugin library, it communicates through a C structure.

The XML syntax is:

<filter-start>
<filter-name>
''name of program section or algorithm''
</filter-name>
<filter-comment>
''description of program section or algorithm''
</filter-comment>
</filter-start>

<filter-progress>
''floating number from 0 to 1''
</filter-progress>

<filter-end>
<filter-name>
''name of program section or algorithm''
</filter-name>
<filter-time>
''execution time''
</filter-time>
</filter-end>

The C structure that library plugins use is:

extern "C" {
struct ModuleProcessInformation
{
/** Inputs from calling application to the module **/
unsigned char Abort;
/** Outputs from the module to the calling application **/
float Progress;
char ProgressMessage[1024];
void (*ProgressCallbackFunction)(void *);
void *ProgressCallbackClientData;
double ElapsedTime;
}
}

Details on how to use this mechanism are illustrated in [https://github.com/Slicer/Slicer/blob/master/Base/CLI/itkPluginFilterWatcher.h itkPluginFilterWatcher.h].

For vtk and itk execution model programs, two classes are available that make it simple to add progress. The classes, ''vtkPluginFilterWatcher'' and ''itk::PluginFilterWatcher'' use the vtk and itk command/observer mechanism to report progress.

vtkPluginFilterWatcher (vtkAlgorithm *'''filter''', const char* '''comment''', ModuleProcessInformation *'''inf''', double '''fraction''', double '''start''') itk::PluginFilterWatcher (itk::ProcessObject '''filter''', const char* '''comment''', ModuleProcessInformation *'''inf''', double '''fraction''', double '''start''')

: where:
;; filter
:: is the vtkAlgorithm or itk::ProcessObject to be watched.
;; comment
:: is a string that describes the algorithm.
;; inf
:: is an optional pointer to a structure that is used to communicate with the invoking program when the called program is used as a library plugin. If the pointer is 0, this prgram will not report progress if it is run as a library plugin. Default is 0.
;; fraction
:: is the fraction (0-1) of progress that will be reported by this watcher. This is used when multiple filters are run and each filter represents a proportion of the total progress. Default is 1.
;; start
:: is the offset (0-1) of the progress for this filter. This is added to the progress of the filter. The reported progress of the watched filter is ''start + fraction * filter_progress''.

 The following example produces progress for a simple vtk program. The variable CLPProcessInformation is automatically declared and set in the program's ''program''CLP.h file.

<nowiki>#include "vtkPluginFilterWatcher.h"
...
vtkMarchingCubes *cubes = vtkMarchingCubes::New();
cubes->SetInput(reader->GetOutput());
vtkPluginFilterWatcher watchCubes(cubes, "Generate Isosurface", CLPProcessInformation, .5, 0.0);
vtkDecimatePro *decimate = vtkDecimatePro::New();
decimate->SetInput(cubes->GetOutput());
vtkPluginFilterWatcher watchDecimate(decimate, "Reduce Triangle Count", CLPProcessInformation, .5, 0.5);
decimate->Update();
</nowiki>

The following example produces progress for a simple itk program:

<nowiki>#include "itkPluginFilterWatcher.h
...
typedef itk::MedianImageFilter<ImageType,ImageType> FilterType;
FilterType::Pointer median = FilterType::New();
itk::PluginFilterWatcher watchMedian(median, "Denoise Image", CLPProcessInformation);
</nowiki>

== Adding Module Logos to Slicer ==
Slicer plugins, both libraries and executables, can specify plugin-specific logos. These appear in Slicer when a module is selected. The logos are specified in a .h header file. The KWWidget utility, KWConvertImageToHeader, converts a .png file into a .h header file containing the encoded image and additional information such as width, height and pixel size. [[Documentation-3.5#Requirements_for_Modules|See here for additional information.]]

For Slicer, execution model plugin logos are stored in Modules/CLI/Resources. The corresponding image in .png format should be stored in Modules/CLI/ImageData. Othere plugins, created outside the Slicer tree, should store the logo and image in a similar location.

To add a logo to a plugin:
* Create a png image of the logo. The height of the logo should not exceed 40 pixels.
* Convert the logo to the KWWidget icon format as follows. '''NOTE:''' the prefix of the image and header file must be the same for a plugin logo.
<pre>
cd Modules/CLI
KWConvertImageToHeader --base64 --zlib Resources/ITKLogo.h ImageData/ITKLogo.png
</pre>
* Add the logo to the SEMMacroBuildCLImacro in the CMakeLists.txt file for the plugin using LOGO_HEADER parameter.

=== Runtime specification of filter types ===

ITK filters are templated over the images they process. The following code snippet shows how an execution model program can select the image types for filters based on the input images.

First, include the utilites for plugin's:
<pre>
#include "itkPluginUtilities.h"
</pre>

Then, turn your main program into a templated procedure called ''DoIt'':
<pre>
template<class T> int DoIt( int argc, char * argv[], T )
{
PARSE_ARGS;

typedef itk::Image< T, 3 > InputImageType;
typedef itk::Image< T, 3 > OutputImageType;
.
.
.
}
</pre>
Then, create a main program that gets the native component type from one of the input file. Here that input file is ''inputVolume'':
<pre>
int main( int argc, char * argv[] )
{

PARSE_ARGS;

itk::ImageIOBase::IOPixelType pixelType;
itk::ImageIOBase::IOComponentType componentType;

try
{
itk::GetImageType (inputVolume, pixelType, componentType);

// This filter handles all types

switch (componentType)
{
case itk::ImageIOBase::UCHAR:
return DoIt( argc, argv, static_cast<unsigned char>(0));
break;
case itk::ImageIOBase::CHAR:
return DoIt( argc, argv, static_cast<char>(0));
break;
case itk::ImageIOBase::USHORT:
return DoIt( argc, argv, static_cast<unsigned short>(0));
break;
case itk::ImageIOBase::SHORT:
return DoIt( argc, argv, static_cast<short>(0));
break;
case itk::ImageIOBase::UINT:
return DoIt( argc, argv, static_cast<unsigned int>(0));
break;
case itk::ImageIOBase::INT:
return DoIt( argc, argv, static_cast<int>(0));
break;
case itk::ImageIOBase::ULONG:
return DoIt( argc, argv, static_cast<unsigned long>(0));
break;
case itk::ImageIOBase::LONG:
return DoIt( argc, argv, static_cast<long>(0));
break;
case itk::ImageIOBase::FLOAT:
return DoIt( argc, argv, static_cast<float>(0));
break;
case itk::ImageIOBase::DOUBLE:
return DoIt( argc, argv, static_cast<double>(0));
break;
case itk::ImageIOBase::UNKNOWNCOMPONENTTYPE:
default:
std::cout << "unknown component type" << std::endl;
break;
}
}
catch( itk::ExceptionObject &excep)
{
std::cerr << argv[0] << ": exception caught !" << std::endl;
std::cerr << excep << std::endl;
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}

</pre>

== Behind the Scenes ==

A primary goal of the execution model is to relieve developers from developing GUI code and command line parsing code. This section describes the major components of the execution model implementation.

=== Command Line Processing ===

Command line processing parses command line arguments and populates internal program variables. Every Unix (and windows) program can receive an argument list through its main entry point. All C and C++ programmers are familiar with the ''int main (int argc, char *[] argv)'' entry point in their programs. Most computer languages including scripting languages provide a similar mechanism to retrieve command line arguments. Simple command line processing directly accesses the strings defined in argv.

This snippet shows simple commmand line processing:

int main (int argc, char *argv[])
{
if (argc < 2)
{
std::cout << "Usage: " << argv[0] << " filename" << std::endl;
return -1;
}
std::cout << "The File is " << argv[1] << std::endl;
return 0;
}

The simple approach works great for a small number of arguments. But larger numbers of arguments of varying types quickly make the processing code more complex and subject to error, both in coding and usage.

int main (int argc, char *argv[])
{
if (argc < 5)
{
std::cout << "Usage: " << argv[0] << " iterations epsilon inputfile outputfile " << std::endl;
return -1;
}
std::string inputfile(argv[3]);
std::string outputfile(argv[4]);
unsigned int iterations = atoi(argv[1]);
float epsilon = atof(argv[2]);
...
return 0;
}

Adding flags (or options) to the command line makes the program easier to use but places a larger burden on the program developer. Each developer must ''invent'' a command line argument syntax and implement code to parse the command line. Even a simple example of this is too long to include in this description. This code snippet looks for just two command line arguments.

int main (int argc, char *argv[])
{
if (argc < 3)
{
std::cout << "Usage: " << argv[0] << " [-i iterations] [-e epsilon] inputfile outputfile " << std::endl;
return -1;
}
std::string inputfile;
std::string outputfile;
unsigned int iterations = 10; /* a default */
float epsilon = .001; /* a defualt */
++argc; /* skip program name */
while (argc > 0)
{
if (strcmp(argv[argc], "-i")
{
iterations = atoi(argv[argc+1]);
argc+=2;
continue;

else if (strcmp(argv[argc], "-e")
{
epsilon = atof(argv[argc+1]);
argc+=2;
continue;
...
}

The code gets longer and longer as more options are added and must be rewritten every time a new programs is open.

To solve this complexity issue, people have developed command line argument libraries. There are dozens, if not hundreds, of command line processing tools. For Slicer3 we looked at argument processors in vxl, nrrd, meta, kwsys and tclap. Each has its strengths and weaknesses. We chose [http://tclap.sourceforge.net/ The Templatized C++ Command Line Parser Library], '''TCLAP'''. '''TCLAP''' is implemented in ''include'' files and does not require a separate library build. As you will see later, the particular command line processing tool is, for the most part, transparent to the Slicer3 developer or user.

But even these libraries require some work to use.

==== TCLAP ====

This example uses '''TCLAP''' to process a command line with 10 possible entries:

int main ( int argc, char* argv[] ) {
//
// Define default values
int HistogramBins = 30;
int RandomSeed = 1234567;
int SpatialSamples = 10000;
float TranslationScale = 100.0;
int Iterations = 200;
int SplineOrder = 3;
double MinimumStepSize = 0.00001;
double MaximumStepSize = 0.005;
bool PrintTransform = false;
string fixedImageFileName;
string movingImageFileName;
string resampledImageFileName;
//
// Setup command line parsing
try
{
TCLAP::CmdLine cl ( "Register2d", ' ', "$Revision: 1.1 $" );
TCLAP::ValueArg<int> HistogramBinsArg ( "b", "histogrambins", "Number of histogram bins", false, 30, "integer", cl );
TCLAP::ValueArg<int> IterationsArg ( "i", "iterations", "Number of Iterations", false, Iterations, "int", cl );
TCLAP::ValueArg<double> MinimumStepSizeArg ( "m", "minstepsize", "Minimum Step Size", false, MinimumStepSize, "double", cl );
TCLAP::ValueArg<double> MaximumStepSizeArg ( "x", "maxstepsize", "Maximum Step Size", false, MaximumStepSize, "double", cl );
TCLAP::ValueArg<int> RandomSeedArg ( "r", "randomseed", "Random Seed", false, RandomSeed, "int", cl );
TCLAP::ValueArg<int> SpatialSamplesArg ( "s", "spatialsamples", "Number of spatial samples", false, SpatialSamples, "int", cl );
TCLAP::ValueArg<int> SplineOrderArg ( "o", "splineorder", "Order of spline for registration", false, SplineOrder, "int", cl );
TCLAP::SwitchArg PrintTransformArg ( "p", "printtransform", "Print the final transform", PrintTransform, cl );
TCLAP::ValueArg<float> TranslationScaleArg ( "t", "translationscale", "Translation scale", false, TranslationScale, "float", cl );
TCLAP::UnlabeledValueArg<string> FixedImageArg ( "fixed", "Fixed image filename", "", "string", cl );
TCLAP::UnlabeledValueArg<string> MovingImageArg ( "moving", "Moving image filename", "", "string", cl );
TCLAP::UnlabeledValueArg<string> ResampledImageArg ( "resampled", "Resampled image filename", "", "string", cl );
//
// Parse the command line
cl.parse ( argc, argv );
//
// Access the variables
HistogramBins = HistogramBinsArg.getValue();
Iterations = IterationsArg.getValue();
MinimumStepSize = MinimumStepSizeArg.getValue();
MaximumStepSize = MaximumStepSizeArg.getValue();
RandomSeed = RandomSeedArg.getValue();
SpatialSamples = SpatialSamplesArg.getValue();
TranslationScale = TranslationScaleArg.getValue();
PrintTransform = PrintTransformArg.getValue();
fixedImageFileName = FixedImageArg.getValue();
movingImageFileName = MovingImageArg.getValue();
resampledImageFileName = ResampledImageArg.getValue();
}
catch ( ArgException e )
{
cerr << "error: " << e.error() << " for arg " << e.argId() << endl;
exit ( EXIT_FAILURE );
}

You do get a lot for your investment here. Good error handling and help.

=== Module Description Parser ===
The XML parsing is done by the [https://github.com/Slicer/SlicerExecutionModel/tree/master/ModuleDescriptionParser ModuleDescriptionParser] class library. ''GenerateCLP'' and Slicer3 use this class library to parse the module XML descriptions. The class ''ModuleDescriptionParser'' has one method, '''Parse''', that converts the XML description into an object model. The resulting object model has one ''ModuleDescription'', one or more ''ModuleParameterGroup'' each of which has one or more ''ModuleParameter''. Each instance has access methods to retrieve information from the XML.
* '''ModuleDescriptionParser''' - parser for command line module XML description.
*: ''Parse(std::string xml, ModuleDescription module)'' - parse an xml string and populate a ModuleDescription.
* '''ModuleDescription''' - contains information about a module
*: const std::string ''GetCategory()'' : returns the contents of '''<category>'''.
*: const std::string ''GetTitle()'' : returns the contents of '''<title>'''.
*: const std::string ''GetDescription()'' : returns the contents of '''<description>'''.
*: const std::string ''GetVersion()'' : returns the contents of '''<version>'''.
*: const std::string ''GetDocumentationURL()'' : returns the contents of '''<documentationURL>'''.
*: const std::string ''GetLicense()'' : returns the contents of '''<license>'''.
*: const std::string ''GetContributor()'' : returns the contents of '''<contributor>'''.
*: const std::vector<ModuleParameterGroup>& ''GetParameterGroups()'' : returns a vector of parameter groups.
* '''ModuleParameterGroup''' - contains ModuleParameters for each parameter group.
*: const std::string ''GetLabel'' - returns the contents of '''<label>'''.
*: const std::string ''GetDescription()'' - returns the contents of the parameter group's '''<description>'''.
*: const std::string ''GetAdvanced()'' - returns advanced attribute. Either "true" of "false".
* '''ModuleParameter''' - contains information for a parameter.
*:GetTag() - returns the parameter's tag, e.g. '''<integer>, <image>''', etc.
*:GetName() - returns the parameter's '''<name>'''.
*:GetLongFlag() - returns the parameter's '''<longflag>'''.
*:GetLabel() - returns the parameter's '''<label>'''.
*:GetMaximum() - returns the parameter's '''<maximum>''' constraint.
*:GetMinimum() - returns the parameter's '''<minimum>''' constraint.
*:GetStep() - returns the parameter's '''<step>'''.
*:GetDescription() - returns the parameter's '''<description>'''.
*:GetChannel() - returns the parameter's '''<channel>'''.
*:GetIndex() - returns the parameter's '''<index>'''.
*:GetDefault() - returns the parameter's '''<default>'''.
*:GetFlag() - returns the parameter's '''<flag>'''.
*:GetMultiple() - returns the parameter's multiple attribute, either "true" or "false".
*:GetCoordinateSystem() - returns the parameter's coordinate system attribute, one of "lps", "ras", or "ijk".

= Adding a new parameter type =

Adding a ''new parameter type'' to the execution model involves several modifications:

# A new XML tag needs to be defined to represent the new parameter type.
# ModuleDescriptionParser needs to be modified to parse the new parameter tag type and specify how the command line processing code generation is going to represent the parameter type
# CommandLineModuleGUI needs to be modified to construct the appropriate GUI element for the parameter type
# CommandLineModuleLogic needs to be modified to put the parameter type onto the command line and request outputs parameter types be loaded back into Slicer and the MRML tree.
# SlicerApplicationLogic needs to be modified to ingest any output parameter types back into Slicer and the MRML tree.
# Additional modification are needed if the parameter is to be passed directly from the MRML tree without using the filesystem.
# Updating the documentation.

Simple parameter types can be passed directly on the command line. For instance, scalars, small lists, positions, etc. Complicated parameter types are passed to the module via '''abstract files'''. In some cases, these parameters are actually passed as files, where Slicer reads/write the data to the filesystem. In other cases, the parameters are passed as '''abstract files''' which are really references to within the Slicer memory model but appear to the Command Line Module as being a file. The Command Line Module is written using standard ITK ImageFileReader/ImageFileWriter classes but the ITK ImageIO factory mechanism is used to direct the ImageFileReader/ImageFileWriter to talk directly to the Slicer MRML tree instead of to the filesystem.

== XML tag ==

This is by far the easiest of the tasks involved in adding a new parameter type but it should not approached hastily. The XML description of a module is designed to be application agnostic. As such, parameter types should be described abstractly or generically. For instance, '''<geometry>''' tag corresponds to the Slicer model node, the '''<point>''' tag corresponds to the Slicer fiducial node, etc.

Once the tag name is defined, you need to decide whether the parameter type could or should support the attributes '''multiple''', '''coordinateSystem''', or '''fileExtensions''' or perhaps a new attribute type.

== Modifying ModuleDescriptionParser ==

SlicerExecutionModel/ModuleDescriptionParser/ModuleDescriptionParser.cxx contains the code to parse the XML description of a module and represent that module description in C++ data structures. To add a new parameter type, this code needs to be modified.

Two routines need to be modified in ModuleDescriptionParser, ''startElement()'' and ''endElement()''. For ''startElement()'', a new case block needs to be added for the parameter type. You can start by copying the case block for a similar parameter type. This case block is responsible for processing all the attributes for the tag and managing and reporting any errors. The case block may define the '''CPPType''', the ''ArgType''', and the '''StringToType''' needed for the code generation of the command line parsing. The '''CPPType''' is used by in the generated command line processing code to represent the parameter. This may be a simple C++ type or an STL container. The '''ArgType''' is the canonical type of each component of the parameter. The '''StringToType''' is the name of the method to use to convert the ASCII command line parameter to the final '''ArgType'''. The ''endElement()'' method merely needs a new case block to add the parameter to the description.

ModuleDescriptionParser is fairly general, handling scalars, lists of scalars, and file types as parameter types. A parameter which does not fit these models will require considerable alterations to the ModuleDescriptionParser as well as the GenerateCLP.

== Constructing a GUI for a new parameter type ==

To have a GUI element appear in the module GUI for a new parameter type, Base\QTCLI\qSlicerCLIModuleUIHelper.cxx and Base\QTCLI\vtkSlicerCLIModuleLogic.cxx have to be modified. A new case block needs to be added to the '''BuildGUI()''' method for the new parameter type. This case block is triggered off the XML tag for the parameter type. The case block is responsible for the constructing the appropriate GUI element for the parameter, complete with specifying the label and help text. The design is very simple. A single widget is used for each parameter. If a more complicated GUI is needed with multiple widgets, then perhaps a new widget is needed to encapsulated a set of widgets or a naming convention can be added to manage all the widgets associated with a parameter. The widgets for the parameters are stored in a map, indexed by the '''name''' of the parameter.

The vtkCommandLineModuleGUI (and vtkCommandLineModuleLogic) are designed to operate very generically with sets of parameters. The aforementioned map of widgets indexed by parameter '''name''' is one such example. The implementation of several of the methods in the vtkCommandLineModuleGUI (and vtkCommandLineModuleLogic) generically iterate over the widget map or over the parameter list. It is important to keep this in mind as new parameters are added. The design goal is to minimize the number of ''special cases'' in the code.

Note that there may be separate case blocks for '''input''' and '''output''' parameter types.

== Communicating the new parameter to the Command Line Module ==

To communicate the new parameter type to and from a Command Line Module, the '''ApplyTask()''' method Slicer3/Modules/CommandLineModule/vtkCommandLineModuleLogic.cxx needs to be modified.

If the parameter type is communicated to the command line module as a file (as opposed to directly on the command line as a number or srting), then there are several blocks of code to construct a temporary file name, keep track of whether that node needs to be written to the filesystem before execution, read from the filesystem after the execution, and deleted after execution completes. These blocks may need to be modified based on your new parameter type.

The command line is constructed in two passes. First, a pass is made over the parameter list, building the portion of the command line for any parameters that have flags. Note that whether a parameter has a flag or not is up to the discretion of the module author and is not defined by the parameter type. Second, a pass is made to construction the portion of the command line for the parameters that do not have flags. These parameters are ordered appropriately, then placed on the command line. For parameters with flags, this code emits the flag and the parameter value. For the parameters without flags, this code emits just the parameter value. You will need to edit both of these passes to emit your parameter type. In most cases, this is simply a matter of grabbing the parameter value from the parameter and pushing it onto the command line. But some parameter types do require translation to a string appropriate for the command line.

== Output parameters from the Command Line Modules ==

Any outputs from a Command Line Module that are communicated via files are queued to be read by the main application thread. Command Line Modules run in a separate execution thread from the main GUI. This thread is not allowed to modify the Slicer GUI, so any results from the module that need to be read back into Slicer and displayed are queued for the main thread.

The '''ProcessReadData()''' method of Slicer3/Base/Logic/vtkSlicerApplicationLogic.cxx pulls data from the queue to load back into Slicer and display. You may need to a case block for your new parameter type to construct the appropriate storage node and display node.

== Communicating directly with the MRML tree ==

Currently scalar image types can sent as parameters to shared object command line modules without going through the filesystem. Slicer provides a new ITK ImageIO factory that can communicated directly with the Slicer MRML tree. This ImageIO factory is in Slicer/Libs/MRMLIDImageIO. This approach can be extended for other image types such as vector or tensor volumes.

For other constructs such as models and transforms, we'll need to see if an existing factory mechanism can be leverage to communicate directly with the Slicer MRML tree. An alternative may be to construct bridges specific to interfacing from a command line module to the Slicer MRML tree.

== Adding new image types ==

The Command Line Module support scalar, vector, tensor, and diffusion weighted images. Adding a new image type to the Command Line Module requires modify the sections of the code outlined above to manage GUI for the module, to construct temporary file names, to write image to disk, and load them back into the MRML tree. These blocks are easy to identify as case blocks on vtkMRMLScalarVolumeNode, vtkMRMLDiffusionTensorVolumeNode, etc. Note that the '''<image>''' tag supports a '''type''' attribute that can scalar, label, vector, tensor, or diffusion-weighted. The case block for '''image''' in the '''startElement()''' method of ModuleDescriptionParser would need to be extended to recognize a new type of image.

=FAQ=

==What facilities are available for third party software to interface with the NA-MIC Kit?==

NA-MIC has committed to developing and supporting a generic batch processing interface. This is the Slicer3 Command Line Interface (CLI). The application programming interface (API) for CLI was worked out based on interactions with the community including input from those familiar with LONI, ITK, Python and Matlab software development practices.

We believe this API already supports all the features required by to implement batch processing with BatchMake, the LONI Pipeline, and any other systems that we may want to work with in the future. The [[Slicer3:Execution_Model_Documentation|Slicer3 Execution Model]] provides a simple XML-based descriptor for command line arguments for input/output volumes and related parameters.

==Which Third Party software has currently been interfaced to the NA-MIC Kit using the CLI?==

*Batchmake (Kitware)
*Python
*Matlab

== How do I debug my command line module? ==

See [http://www.slicer.org/slicerWiki/index.php/Slicer3:Execution_Model_Documentation:Debugging Debugging]

== How do I specify a Logo? ==

You need to create a logo.h file (embedding the zipped pixel data as base64 strings in a C source code). There is a utility bundled with kwwidgets that accomplishes this. From a Slicer3 build directory you can do something like this:

./Slicer3 --launch ../Slicer3-lib/KWWidgets-build/bin/KWConvertImageToHeader --base64 --zlib ~/Desktop/bioimagesuite_logo_www.h ~/Desktop/bioimagesuite_logo_www.png

The resulting .h header file can then be used as an argument to the 'generateclp' cmake macro like this:

generateclp(${CLP}_SOURCE ${CLP}.xml ${Slicer3_SOURCE_DIR}/Resources/bioimagesuite_logo_www.h)

''Note: logos are limited in size: if your .h file contains a symbol like 'image_bioimagesuite_logo_www' it will work. But if it has several symbols like 'image_bioimagesuite_logo_www_1' 'image_bioimagesuite_logo_www_2' etc then the logo was too large and needs to be downsampled for use.''

== What do I do if I want to use the CLI outside of slicer? ==

In general CLI executables will depend on shared libraries provided by Slicer (such as ITKCommon, etc). To be sure your run-time environment resolves to the correct versions, you should always use a form like:
./Slicer3 --launch <CLI>
or, you can start a shell from which you can run multiple CLI modules. Something like:
./Slicer3 --launch xterm &

We do not suggest hard-coding the runtime paths into, for example, your .bashrc since this may interfere with other programs and can make it hard to use multiple versions of slicer on the same account.

= Laundry List =

Use this section to describe any features that are missing, not documented, or require additional work.

* Comments from Hans Johnson, June 4, 2010:
** Enumerated types can only have about 3 characters in them, otherwise they don’t render in the slicer wizard at all.
** There is no way to unset an enumerated type, and the values are cached even after leaving the module. If the default enumerated type is to be blank, and you select it, then you must restart slicer in order to make the blank option available again.
** There is no way to have conditional options. For example if one flag is used, then other flag can not be used, so it should be disabled.

* Documenting your module:
** a convenience script has been developed by Hans Johnson, which creates a wiki page describing the command line module by extracting the information from the xml description [[SEMToMediaWiki.py]]. TODO: extract the default values for the parameters to be included in the documentation

Documentation/Nightly/Developers/SlicerExecutionModel

2015-10-07T16:10:17Z

Fbudin: /* XML Schema */

== Introduction ==

The Slicer Execution Model is designed to improve the acceptance and productivity of Slicer application developers. The Execution Model provides a simple mechanism for incorporating command line programs as Slicer modules. These command line modules are self-describing, emitting an XML description of its command line arguments. Slicer uses this XML description to construct a GUI for the module.

=== Types of Slicer Plugins ===

There are various types of plugins that Slicer supports as command line modules. This variety allows a breadth of integration choices to balance performance and flexibility.

==== Shared object plugins (dll, so) with global symbols ====

Shared object plugins with global symbols integrate into Slicer tighter than the Executable plugins. Shared object plugins with global symbols can transfer data directly to/from a MRML scene using standard itk::ImageFileReader and itk::ImageFileWriter (and the ImageIO class provided with Slicer, itk::MRMLIDImageIO). Communicating directly with the MRML scene avoids the overhead of reading and writing images to disk. Slicer looks for a standard entry point to execute the module called ModuleEntryPoint defined as

int ModuleEntryPoint(int argc, char* argv[]);

Slicer also looks for the global symbols XMLModuleDescription, ModuleLogoImage, ModuleLogoWidth, ModuleLogoHeight, ModuleLogoPixelSize, and ModuleLogoLength. These global symbols provide the xml module description and data for the module logo. The data types for these symbols are

char *XMLModuleDescription;
unsigned char *ModuleLogoImage;
int ModuleLogoWidth;
int ModuleLogoHeight;
int ModuleLogoPixelSize;
unsigned long ModuleLogoLength;

These global symbols are accessed during module discovery. The ModuleLogoImage, ModuleLogoWidth, ModuleLogoHeight, ModuleLogoPixelSize, and ModuleLogoLength are optional.

=====Controlling what symbols are exported from a shared library module=====

Shared Object Modules are loaded into Slicer using standard "dlopen" style calls. The ModuleEntryPoint is located within the shared library and cached for later use. The ModuleEntryPoint, however, may not be the only function accessible to Slicer within the shared library. To protect against symbol clash at runtime, all functions and variables accessible within file scope of the shared library should be put in an anonymous namespace.

<pre>
// Use an anonymous namespace to keep class types and function names
// from colliding when module is used as shared object module. Every
// thing should be in an anonymous namespace except for the module
// entry point, e.g. main() or ModuleEntryPoint()
//
namespace {
// functions like DoIt() should be put in the anonymous namespace
template<class T> int DoIt( int argc, char * argv[], const T& targ)
{
}
} // end of anonymous namespace

int main(int argc, char* argv[] )
{
}

</pre>

==== Shared object plugins (dll, so) with entry points ====

Shared object plugins with entry points integrate into Slicer tighter than the Executable plugins. Shared object plugins with entry points can transfer data directly to/from a MRML scene using standard itk::ImageFileReader and itk::ImageFileWriter (and the ImageIO class provided with Slicer, itk::MRMLIDImageIO). Communicating directly with the MRML scene avoids the overhead of reading and writing images to disk. Slicer looks for standard entry points for executing the module as well as for querying the module for its xml description and logos. The entry points are defined as

int ModuleEntryPoint(int argc, char* argv[]);
char *GetXMLModuleDescription();
unsigned char *GetModuleLogo()(int *width, int *height, int *pixel_size, unsigned long *bufferLength);

GetXMLModuleDescription() and GetModuleLogo() are accessed during module discovery. GetModuleLogo() is optional.

==== Executable plugins with global symbols ====

Executable plugins with global symbols allow for a single executable to be developed that can be integrated into Slicer 3 or run standalone on a cluster. Plugins of this type are opened but not executed at module discovery time. Slicer 3 looks for the global symbols XMLModuleDescription, ModuleLogoImage, ModuleLogoWidth, ModuleLogoHeight, ModuleLogoPixelSize, and ModuleLogoLength. The data types for these symbols are

char *XMLModuleDescription;
unsigned char *ModuleLogoImage;
int ModuleLogoWidth;
int ModuleLogoHeight;
int ModuleLogoPixelSize;
unsigned long ModuleLogoLength;

These global symbols are access during module discovery. ModuleLogoImage, ModuleLogoWidth, ModuleLogoHeight, ModuleLogoPixelSize, ModuleLogoLength are optional.

==== Executable plugins (exe) with command line options ====

Executable plugins with command line options are the most flexible type of plugin. This approach allows for legacy applications to be integrated into Slicer using a wrapper around the legacy application. Plugins of this type are executed at module discovery time, passing in the command line argument "--xml". The plugin responds to the "--xml" query by emitting the xml description of the module. The plugin is also executed at module discovery time with a "--logo" command line argument. The plugin responds to the "--logo" query by emitting a logo description.

This type of plugin allows for legacy applications to be integrated into Slicer. A developer can provide Slicer with a small executable or shell script that responds to the "--xml" and "--logo" command line arguments needed for Slicer 3 integration and otherwise spawns the legacy executable passing down any command line arguments.

> module.exe --xml
> module.exe --logo

==== Script plugins with Python ====

Python scripts are found using the discovery mechanisms for the other plugins. Since Python plugins are fundamentally different from the shared and executable plugins, they are documented on their own [[Documentation/Nightly/Developers/SlicerExecutionModel/Python|page]].

=== Calling Command Line Modules from Other Code ===

In addition to the automated GUI that shows up in the Slicer user interface, the Execution Model can be used to encapsulate functionality that is invoked by other parts of the program. For instance, the Editor Module can invoke the Model Maker Module to build models. By invoking a command line module in this way, you get the advantage of background processing with progress reporting. See [[Documentation/Nightly/Developers/SlicerExecutionModel/Programmatic Invocation|this page]] for more details.

=== Architecture ===
[[Image:ExecutionModelPlugins.png|600px|Plugin architecture]]
[[Image:CommandLineModule.png|400px|Module architecture]]
[[Image:ModuleFactory.png|400px|Module factory ]]
[[Image:Class_parser_state_coll_graph.png|400px|Module description]]

== Module Description ==

Modules are described using XML. The XML is used to generate the C++ command line code and the GUI for the application.

=== XML Schema ===

At a minimum, each module description must contain:

<?xml version="1.0" encoding="utf-8"?>
<executable>
<title>A title</title>
<description>A description</description>
<parameters>
At least one parameter
</parameters>
</executable>

In the following descriptions of each XML tag, CLP means command line processing and GUI means graphical user interface. Unless otherwise specified, tags are optional.

; <executable> (required)

;; <category>
:: Classifies the executable (e.g. Filtering, Segmentation). Category can be a ''dot'' separated string. Multiple categories can be given and should be separated by a ''semicolon''.
:: ''for CLP'', not used.
:: ''for GUI'', used on the menu selector to group executables. ''Dot'' separated strings can be used to generate sub-menus. ''Semicolon'' creates multiple categories.
;; </category>

;; <title> (required)
:: A word or two describing the executable (e.g. Median Filter, Anisotropic Diffusion
:: ''for CLP'', not used.
:: ''for GUI'', used to label the frame containing the GUI for the executable. Also, GUI names for volumes use this label as a prefix.
;; </title>

;; <description> (required)
:: A long description of the executable. Any double quotes will be converted to single quotes.
:: ''for CLP'', appears at the end of the --help.
:: ''for GUI'', appears in the help frame.
;; </description>

;; <version>
:: The version of the command line executable. A suggested format is:
::: ''major''.''minor''.''patch''.''build''.''status''
::: where status is
:::: vc: version controlled (pre-alpha), build can be a serial revision number, if any (like svn might have).
:::: a: alpha
:::: b: beta
:::: rc: release candidate
:::: fcs: first customer ship
:: ''for CLP'', reported in response to --version.
:: ''for GUI'', not used.
;; </version>

;; <documentation-url>
:: The location of extended documentation for the executable, (e.g. http://www.na-mic.org/foo.html).
;; </documentation-url>

;; <license>
:: The type of license or a url containing the license, (e.g. Berkeley, Apache, http://www.slicer.org/copyright/copyright.txt).
:: ''for CLP'', not used.
:: ''for GUI'', may show up in the Help or About section.
;; </license>

;; <contributor>
:: The author(s) of the command line executable (e.g. Pieper, Jim Miller).
:: for ''CLP'', appears as part of --help
:: for ''GUI'', may show up in the Help or About section.
;; </contributor>

;; <acknowledgements>
:: Acknowledgements for funding agency, employer, colleague, (e.g. This work is part of the National Alliance for Medical Image Computing NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149).
:: for ''CLP'', appears as part of --help
:: for ''GUI'', may show up in the Help of About section.
;; </acknowledgements>

;; <parameters [advanced="true|''false''"]> (required for each group of parameters)
:: Starts a group of parameters.
:: for ''CLP'', not used.
:: for ''GUI'', defines a widget (in tk, a frame) that contains other widgets. If ''advanced'' is true, the frame will be closed initially.

;;; <label> (required)
::: A short string that summarizes a parameter group, (e.g. I/O, Diffusion)
::: for ''CLP'', not used.
::: for ''GUI'', used to label the frame.
;;; </label>

;;; <description> (required)
::: A short description of the parameter group, (e.g. Input/Output Parameters, Anitostropic Diffusion Parameters). Any double quotes will be converted to single quotes.
::: ''for CLP'', not used.
::: ''for GUI'', used in balloon help for the frame containing the parameter group.
;;; </description>

;;; <integer> | <float> | <double> | <boolean> | <string> | <integer-vector> | <float-vector> | <double-vector> | <string-vector> | <integer-enumeration> | <float-enumeration> | <double-enumeration> | <string-enumeration> | <file> | <directory> | <image [type="''scalar''|''label''|''tensor''|''diffusion-weighted''|''vector''|''model''"]> | <geometry [type="''fiberbundle''|''model''"]> | <point [multiple="''true''|''false''"] [coordinateSystem="''lps''|''ras''|''ijk''"]> | <region [multiple="''true''|''false''"] [coordinateSystem="''lps''|''ras''|''ijk''"]>
::: The type of the parameter.
:::: The scalar types ('''integer''', '''float''', etc.) correspond to the usual programming language types.
:::: The '''-vector''' types are represented by comma separated values of the scalar type.
:::: The '''-enumeration''' types use the '''<element>''' tag to enumerate choices of the scalar type.
:::: '''<image>''' is a special type that indicates that the parameter is a file name that specifies images.
:::: If the attribute ''multiple'' is "true", multiple arguments are allowed for '''scalar''', '''file''', '''directory''', '''image''', '''geometry''', '''point''' and '''region''' parameters. BUG: the automatically built GUI will not support selecting multiple volumes for the '''image''' argument, but they can be passed on the command line. If the parameter has a ''flag'' or ''longflag'', then the flag may be specified multiple times on the command line. The resulting C++ variable will be a std::vector of the scalar type. If the multiple parameter does not have a flag, then multiple arguments can appear on the command line. However, a multiple parameter with no flags must be the last parameter specified.
:::: The attribute ''coordinateSystem'' is allowed for the parameters '''point''' and '''region'''.
:::: The attribute ''fileExtensions'' is allowed for '''file''', '''image''' and '''geometry'''. fileExtensions can contain a list of comma separated file extensions for optional use by the GUI.

;;;; <name> (required if longflag is not specified)
:::: The name of a command line argument. If name is not specified, longflag will be used (e.g. conductance, numberOfIterations). The name must be usable as a C++ variable. For example, it CANNOT have spaces or special characters and must start with a letter.
:::: ''for CLP'', the name of the C++ variable.
:::: ''for GUI'', used internally.
;;;; </name>

;;;; <description> (required)
:::: A brief description of the parameter. Any double quotes will be converted to single quotes.
:::: ''for CLP'', describes the parameter for --usage and --help.
:::: ''for GUI'', describes the parameter when the cursor is placed over the widget for the parameter (balloon help).
;;;; </description>

;;;; <label> (required)
:::: A label for parameter (e.g. Dicom Directory, Conductance).
:::: ''for'' CLP, not used.
:::: ''for'' GUI, the label for the parameter widget.
;;;; </label>

;;;; <default>
:::: A default value for the parameter. The default must be a type that is compatible with the parameter type. The vector parameters are specified as comma separated values of the atomic parameter type.
:::: ''for CLP'', contains the default for the parameter unless the parameter is a ''boolean''. The default for ''boolean'' parameters is always set to ''false''.
:::: ''for GUI'', contains the default for the parameter.
;;;; </default>

;;;; <flag [alias="a,b"] [deprecatedalias="c,d"]> (not required if longflag is present)
:::: A single character command line flag (e.g. s, W). Can provide "alias"'s (comma separated) if different flags can be used to activate the same parameter. Can provide "deprecatedalias"'s (comma separated) if different flags can be used to set the same parameter but the user should be notified of which "updated" flag to use. Parameters with flags are considered "optional" and do not have be specified or assigned. Parameters with flags allow one to override a default behavior.
:::: ''for CLP'', used as the short flag on the command line.
:::: ''for GUI'', used when running the module.
;;;; </flag>

;;;; <longflag [alias="foo,bar"] [deprecatedalias="garf"]> (not required if flag is present)
:::: A command line flag (e.g. spacing, Watcher). Can provide "alias"'s (comma separated) if different long flags can be used to activate the same parameter. Can provide "deprecatedalias"'s (comma separated) if different long flags can be used to set the same parameter but the user should be notified of which "updated" long flag to use. Parameters with flags are considered "optional" and do not have be specified or assigned. Parameters with flags allow one to override a default behavior.
:::: Note: apparently you can't use hyphens in the longflag, so things like --my-option are not allows. -gcs
:::: ''for CLP'', used as the long flag on the command line.
:::: ''for GUI'', used when running the module.
;;;; </longflag>

;;;; <constraints>
:::: Encloses constraints on the value of a non-vector, non-enumerated parameter.
:::: ''for CLP'', not used.
:::: ''for GUI'', if present, a slider will be created using the minimum, maximum and step specified.

;;;;; <minimum>
::::: The minimum allowed value for the parameter. If not specified, the minimum is the smallest possible value for the parameter type.
;;;;; </minimum>

;;;;; <maximum>
::::: The maximum allowed value for the parameter. If not specified, the maximum is the largest possible value for the parameter type.
;;;;; </maximum>

;;;;; <step>
::::: The increment for the parameter.
;;;;; </step>

;;;; </constraints>

;;;; <channel> (required for file, directory and image parameters)
:::: Specifies whether the parameter is an input or output parameter.
:::: ''for CLP'', not used.
:::: ''for GUI'', selects the proper widget for file handling.
;;;; </channel>

;;;; <index> (required if there are no flags specified)
:::: An integer starting at 0, that specifies a command line argument that has no flags.
:::: Note: if you use index for, say, an image, the user must enter some input value into the GUI. If the user does not fill in a value, the plugin is not run at all. However, slicer will "seem" to run it, and no error message is given. -gcs
:::: ''for CLP'', specifies the order of an argument that has no flags.
:::: ''for GUI'', used when running the module.
;;;; </index>

;;;; <enumeration> (required for enumeration parameters)
:::: Encloses elements for the parameter. The parameter is restricted one and only one element.
:::: ''for CLP'', not used.
:::: ''for GUI'', defines a radio button with choices.

;;;;; <element>
::::: Defines the choice. Must be of the proper type for a parameter.
::::: ''for CLP'', not used.
::::: ''for GUI'', used as the label for the raido button.
;;;;; </element>

;;;; </enumeration>

;;; </integer> | </float> | </double> | </boolean> | </string> | </integer-vector> | </float-vector> | </double-vector> | </string-vector> | </integer-enumeration> | </float-enumeration> | </double-enumeration> | </string-enumeration> | </file> | </directory> | </image> | </geometry> | </point> | </region>
;; </parameters>

; </executable>

== Slicer GUI Generation ==

Slicer generates GUI's for each executable discovered during the startup process. Slicer searches directories stored in the Slicer Module Path. This path is set from the Slicer application in View->Application Settings->Modules->Additional module paths. Slicer attempts to run every executable in the prescribed directories and look for a valid XML file in response to a "--xml" command line.

Here are a few representative examples.

=== A tour of the Execution Model XML ===

This example is a sampler of the parameters available in the Execution Model.

<div class="floatright">[[Image:ExectionModelTourGUI.png|[[Image:ExectionModelTourGUI.png]]]]</div>

<?xml version="1.0" encoding="utf-8"?>
<executable>
<category>Tours</category>
<title>Execution Model Tour</title>
<description>
Shows one of each type of parameter.
</description>
<version>1.0</version>
<documentation-url></documentation-url>
<license></license>
<contributor>Daniel Blezek</contributor>

<parameters>
<label>Scalar Parameters</label>
<description>
Variations on scalar parameters
</description>
<integer>
<name>integerVariable</name>
<flag>i</flag>
<longflag>integer</longflag>
<description>
An integer without constraints
</description>
<label>Integer Parameter</label>
<default>30</default>
</integer>
<label>Scalar Parameters With Constraints</label>
<description>Variations on scalar parameters</description>
<double>
<name>doubleVariable</name>
<flag>d</flag>
<longflag>double</longflag>
<description>An double with constraints</description>
<label>Double Parameter</label>
<default>30</default>
<constraints>
<minimum>0</minimum>
<maximum>1.e3</maximum>
<step>0</step>
</constraints>
</double>
</parameters>

<parameters>
<label>Vector Parameters</label>
<description>Variations on vector parameters</description>
<float-vector>
<name>floatVector</name>
<flag>f</flag>
<description>A vector of floats</description>
<label>Float Vector Parameter</label>
<default>1.3,2,-14</default>
</float-vector>
<string-vector>
<name>stringVector</name>
<longflag>string_vector</longflag>
<description>A vector of strings</description>
<label>String Vector Parameter</label>
<default>"foo",bar,"foobar"</default>
</string-vector>
</parameters>

<parameters>
<label>Enumeration Parameters</label>
<description>Variations on enumeration parameters</description>
<string-enumeration>
<name>stringChoice</name>
<flag>e</flag>
<longflag>enumeration</longflag>
<description>An enumeration of strings</description>
<label>String Enumeration Parameter</label>
<default>foo</default>
<element>foo</element>
<element>"foobar"</element>
<element>foofoo</element>
</string-enumeration>
</parameters>
</executable>

=== Module with an integer-vector, one input image and one output image ===

Here is the XML that describes the MedianImageFilter. The image on the right shows the generated Slicer 3 GUI. The help frame has been expanded by the user.

<div class="floatright">[[Image:MedianFilterGUI.png|[[Image:MedianFilterGUI.png]]]]</div>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<executable>
<category>
Filtering.Denoising
</category>
<title>
Median Filter
</title>
<description>
The MedianImageFilter is commonly used as a robust approach for
noise reduction. This filter is particularly efficient against
"salt-and-pepper" noise. In other words, it is robust to the presence
of gray-level outliers. MedianImageFilter computes the value of each output
pixel as the statistical median of the neighborhood of values around the
corresponding input pixel.
</description>
<version>0.1.0.$Revision: 2085 $(alpha)</version>
<documentation-url></documentation-url>
<license></license>
<contributor>Bill Lorensen</contributor>
<acknowledgements>This command module was derived from
Insight/Examples/Filtering/MedianImageFilter (copyright) Insight Software Consortium
</acknowledgements>
<parameters>
<label>Median Filter Parameters</label>
<description>Parameters for the median filter</description>

<integer-vector>
<name>neighborhood</name>
<longflag>--neighborhood</longflag>
<description>The size of the neighborhood in each dimension</description>
<label>Neighborhood Size</label>
<default>1,1,1</default>
</integer-vector>

</parameters>

<parameters>
<label>IO</label>
<description>Input/output parameters</description>
<image>
<name>inputVolume</name>
<label>Input Volume</label>
<channel>input</channel>
<index>0</index>
<description>Input volume to be filtered</description>
</image>
<image>
<name>outputVolume</name>
<label>Output Volume</label>
<channel>output</channel>
<index>1</index>
<description>Output filtered</description>
</image>
</parameters>

</executable>
</pre>

=== Module with a multiple scalars, one Input image and one output image ===

A module with

<div class="floatright">[[Image:AnisotropicDiffusionFilterGUI.png|[[Image:AnisotropicDiffusionFilterGUI.png]]]]</div>

<?xml version="1.0" encoding="utf-8"?>
<executable>
<category>filtering</category>
<title>Anisotropic Diffusion</title>
<description>
Runs anisotropic diffusion on a volume
</description>
<version>1.0</version>
<documentation-url></documentation-url>
<license></license>
<contributor>Bill Lorensen</contributor>

<parameters>
<label>
Anisotropic Diffusion Parameters
</label>
<description>
Parameters for the anisotropic
diffusion algorithm
</description>

<double>
<name>conductance</name>
<longflag>conductance</longflag>
<description>Conductance</description>
<label>Conductance</label>
<default>1</default>
<constraints>
<minimum>0</minimum>
<maximum>10</maximum>
<step>.01</step>
</constraints>
</double>

<double>
<name>timeStep</name>
<longflag>timeStep</longflag>
<description>Time Step</description>
<label>Time Step</label>
<default>0.0625</default>
<constraints>
<minimum>.001</minimum>
<maximum>1</maximum>
<step>.001</step>
</constraints>
</double>

<integer>
<name>numberOfIterations</name>
<longflag>iterations</longflag>
<description>Number of iterations</description>
<label>Iterations</label>
<default>1</default>
<constraints>
<minimum>1</minimum>
<maximum>30</maximum>
<step>1</step>
</constraints>
</integer>

</parameters>

<parameters>
<label>IO</label>
<description>Input/output parameters</description>
<image>
<name>inputVolume</name>
<label>Input Volume</label>
<channel>input</channel>
<index>0</index>
<description>Input volume to be filtered</description>
</image>
<image>
<name>outputVolume</name>
<label>Output Volume</label>
<channel>output</channel>
<index>1</index>
<description>Output filtered</description>
</image>
</parameters>

</executable>

=== Module with output text presented in GUI ===

Slicer auto generates GUI to display output from the command line module after execution is complete.
The flag [--returnparameterfile <file name>] is used to provide a name of a file that the module uses to store key=value pairs that are displayed in the Slicer GUI. The keys are described in the command line module xml schema using the output channel.

This example demonstrates a portion of an XML schema containing 1 string-enumeration input and 7 string outputs.

<div class="floatright">[[Image:RadnosticsBetaOsteoporosisAnalysisGUI.png|[[Image:RadnosticsBetaOsteoporosisAnalysisGUI.png]]]]</div>

<parameters>
<label>Radnostics Beta Osteoporosis Analysis</label>
<string-enumeration>
<name>Osteoporosis</name>
<longflag>--osteoporosis</longflag>
<label>After Segmentation Perform Osteoporosis Analysis</label>
<description>Osteoporosis Analysis will provide a Radnostics Osteoporosis score for the patient.</description>
<default>yes</default>
<element>yes</element>
<element>no</element>
</string-enumeration>
<string>
<name>PatientGender</name>
<label>Gender</label>
<channel>output</channel>
<description>Patient Gender</description>
<default>na</default>
</string>
<string>
<name>PatientAge</name>
<label>Age</label>
<channel>output</channel>
<description>Patient Age</description>
<default>na</default>
</string>
<string>
<name>RadnosticsOsteoporosisScore</name>
<label>Radnostics Osteoporosis Score</label>
<channel>output</channel>
<description>Radnostics Osteoporosis Score</description>
<default>na</default>
</string>
<string>
<name>OsteoporosisComment1</name>
<channel>output</channel>
<label>*</label>
<description>Comment 1</description>
</string>
<string>
<name>OsteoporosisComment2</name>
<channel>output</channel>
<label>*</label>
<description>Comment 2</description>
</string>
<string>
<name>OsteoporosisComment3</name>
<channel>output</channel>
<label>*</label>
<description>Comment 3</description>
</string>
<string>
<name>OsteoporosisComment4</name>
<channel>output</channel>
<label>*</label>
<description>Comment 4</description>
</string>
</parameters>

The command line module outputs key=value pairs to the file supplied by –-returnparameterfile as shown below:
PatientGender = F
PatientAge = 059Y
RadnosticsOsteoporosisScore = 8 (high)
OsteoporosisComment1 = vertebra label 58 has biconcave fracture
OsteoporosisComment2 = vertebra label 56 has mean density of 120 HU

== Command Line Parsing ==

The Slicer Execution Model has support for parsing executable command lines. The C++ code to parse the command line arguments is generated automatically from the same XML description that generates the GUI. ''GenerateCLP,'' located in ''SlicerExecutionModel/GenerateCLP'' reads the XML Module Description and creates an include file ''"Executable"CLP.h'' in the build tree. The executable includes this header file and accesses the code with the macro PARSE_ARGS.

GenerateCLP provides the following to the executable:

# A brief usage command if required arguments are missing
# A full help command if ''-h'' or ''--help'' is specified on the command line
# A copy of the xml description if ''--xml'' is specified on the command line
# An echo of the command line parameters and their values if ''--echo'' is specified

GenerateCLP provides the following source code:

# A C++ declaration of the proper type for each parameter assigning the default value if specified by the XML
# For ''-vector'' parameters, a ''std::vector'' containing the proper C++ type fo the parameter. The generated code parses the comma separated strings to generate the ''std::vector''

=== Using GenerateCLP ===

GenerateCLP is normally used via CMake where it is implemented as a CUSTOM_COMMAND. To use GenerateCLP from CMake, you must first include the GenerateCLP package from your CMakeLists.txt file, which will make some macros available to you:

find_package(SlicerExecutionModel REQUIRED)
include(${SlicerExecutionModel_USE_FILE})

Note that the HelloSlicer command line module example provides a good starting point and can be used as a skeleton to build your own. It can be found in the [http://na-mic.org/ViewVC/index.cgi/trunk/Modules/CommandLineModule/Testing/HelloSlicer/?sortby=file#dirlist Modules/CommandLineModule/Testing/HelloSlicer] subdirectory.

For each executable, include the following, replacing '''MyFilter''' with the name of your C++ source:

set('''MyFilter'''_SOURCE '''MyFilter'''.cxx)
GENERATECLP('''MyFilter'''_SOURCE '''MyFilter'''.xml)

To generate a stand-alone executable add the lines:

add_executable('''MyFilter''' ${'''MyFilter'''_SOURCE})
target_link_libraries('''MyFilter''' ${ITK_LIBRARIES})

Slicer expects modules and plugins to be stored in a specific subdirectory, so that they can be discovered and loaded at run-time. To make sure your CLP module is built in said subdirectory, add the line:

SEMMacroBuildCLI(
NAME '''MyFilter'''
LOGO_HEADER ${Slicer_SOURCE_DIR}/Resources/NAMICLogo.h
ADDITIONAL_SRCS
'''MyFilter'''.cxx
TARGET_LIBRARIES ModuleDescriptionParser ${ITK_LIBRARIES} vtkTeem MRMLCore SlicerBaseCLI ${VTK_LIBRARIES}
INCLUDE_DIRECTORIES
${vtkTeem_INCLUDE_DIRS}
${MRMLCore_INCLUDE_DIRS}
${vtkITK_INCLUDE_DIRS}
${SlicerBaseCLI_SOURCE_DIR} ${SlicerBaseCLI_BINARY_DIR}
)

The add_executable target creates a stand-alone executable that can be run from a command line. The add_library target creates a shared library that is discovered at Slicer 3 startup.

Although this example linked to ITK libraries, other libraries can be specified.

=== Short Example ===

This example uses the XML for the [http://www.slicer.org/slicerWiki/index.php/Slicer3:Execution_Model_Documentation#Module_with_an_integer-vector.2C_one_input_image_and_one_output_image|Median Image Filter example].
 
'''Note:''' The program '''MUST NOT''' write anything to stdout before the ''PARSE_ARGS'' statement. If something is written, the plugin discovery mechanism will not recognize the program as a plugin.

<nowiki>#include "MedianImageFilterCLP.h"
int main (int argc, char * argv[])
{
PARSE_ARGS;
std::cout << "The size of the neighborhood is: " << neighborhood.size()
<< " and the first element of the neighborhood is: " << neighborhood[0]
<< std::endl;
std::cout << "The input volume is: " << inputVolume << std::endl;
std::cout << "The output volume is: " << outputVolume << std::endl;
return EXIT_SUCCESS;
}
</nowiki>

Here is the output --help:

<pre>

USAGE:

./MedianImageFilter [--processinformationaddress <std::string>] [--xml]
[--echo] [--neighborhood <std::vector<int>>] [--]
[--version] [-h] <std::string> <std::string>

Where:

--processinformationaddress <std::string>
Address of a structure to store process information (progress, abort,
etc.). (default: 0)

--xml
Produce xml description of command line arguments (default: 0)

--echo
Echo the command line arguments (default: 0)

--neighborhood <std::vector<int>>
The size of the neighborhood in each dimension (default: 1,1,1)

--, --ignore_rest
Ignores the rest of the labeled arguments following this flag.

--version
Displays version information and exits.

-h, --help
Displays usage information and exits.

<std::string>
(required) Input volume to be filtered

<std::string>
(required) Output filtered

The MedianImageFilter is commonly used as a robust approach for noise
reduction. This filter is particularly efficient against
'salt-and-pepper' noise. In other words, it is robust to the presence of
gray-level outliers. MedianImageFilter computes the value of each output
pixel as the statistical median of the neighborhood of values around the
corresponding input pixel.

Author(s): Bill Lorensen

Acknowledgements: This command module was derived from
Insight/Examples/Filtering/MedianImageFilter (copyright) Insight
Software Consortium

</pre>

=== Parameters and C++ code ===

This table shows how parameters are defined in the C++ code and how they are specified on the command line.

{| border="1"
! XML
! C++ Declaration
! Command Line
|-
|
<integer> <name>count</name> <flag>c</flag> </integer>
|
int count;
|
''prog'' -c 10
|-
|
<float> <name>stepSize</name> <default>.0625</default> <longflag>stepSize</longflag> </float>
|
float stepSize=.0625;
|
''prog'' --stepSize .003
|-
|
<integer multiple="true"> <name>iterations</name> <flag>i</flag> <default>100</default> </integer>
|
std::vector<int> iterations; iterations.push_back(100); 
|
''prog'' -i 20 -i 30 -i 100
|-
|
<float-vector> <name>variation</name> <flag>v</flag> <default>1,2,3</default> </float-vector>
|
std::vector<float> variation; iterations.push_back(1); iterations.push_back(2); iterations.push_back(3); 
|
''prog'' -v 10,20,3
|-
|
<string-vector> <name>sites</name> <longflag>sites</longflag> </string-vector>
|
std::vector<std::string> sites;
|
''prog'' --sites BWH,GE,Kitware,UNC,MIT,UTAH,GT
|-
|
<string-enumeration> <name>leaders</name> <default>Bill</default> <element>Ron</element> <element>Bill</element> <element>Steve</element> </string-enumeration>
|
std::string leaders = "Bill";
|
''prog'' --leaders Ron
|-
|
<boolean> <name>debugSwitch</name> <flag>d</flag> <default>true</default> </boolean>
|
bool debugSwitch = true;
|
''prog'' -d
|-
|
<file> <longflag>file1</longflag> <file>
|
std::string file1;
|
''prog'' --file1 mytext.txt
|-
|
<image> <name>image</name> <index>0</index> </image>
|
std::string image;
|
''prog'' c:/lorensen/Data/ct.nrrd
|-
|
<file multiple="true"> <name>args</name> <index>1</index> </file>
|
std::vector<std::string> args;
|
''prog'' --otherFlags file1 file2 ... filen
|-
|
<point multiple="true" coordinateSystem="ras"> <name>seed</name> <longflag>--seed</longflag>
|
std::vector<std::vector<float> > seed;
|
''prog'' --seed 10,100,23 --seed 5,240,17
|}

== Accessing Module Information at Runtime ==

All of the information contained in the XML description of a module can be accessed at run-time by the command line program. The ''ModuleDescriptionParser'' class library can parse an XML module description and populate a ''ModuleDescription'' instance.
<pre>
// Module Description Parser Class Library
#include "ModuleDescriptionParser.h"
#include "ModuleDescription.h"
#include "ModuleParameterGroup.h"
#include "ModuleParameter.h"
.
.
.
// Create a module and a parser
ModuleDescription module;
ModuleDescriptionParser parser;
// Parse the XML
if (parser.Parse(GetXMLModuleDescription(), module))
{
std::cerr << argv[0] << ": One or more XML errors detected." << std::endl;
return EXIT_FAILURE;
}
// Access the module description information
std::cout << "Module Description Information" << std::endl;
std::cout << "\tCategory is: " << module.GetCategory() << std::endl;
std::cout << "\tTitle is: " << module.GetTitle() << std::endl;
std::cout << "\tDescription is: " << module.GetDescription() << std::endl;
std::cout << "\tVersion is: " << module.GetVersion() << std::endl;
std::cout << "\tDocumentationURL is: " << module.GetDocumentationURL() << std::endl;
std::cout << "\tLicense is: " << module.GetLicense() << std::endl;
std::cout << "\tContributor is: " << module.GetContributor() << std::endl;
</pre>

''GetXMLModuleDescription'' is automatically generated by ''GenerateCLP''. Information about parameter groups and parameters is also available [[Accessing_Module_Information_at_Runtime|here]].

The ''CMakeLists.txt'' file that creates the command line module should point to the ''ModuleDescriptionParser'' library.
<pre>
target_link_libraries(${CLP}
ModuleDescriptionParser
)
</pre>

== Error Handling ==

GenerateCLP attempts to do error checking so that the generated C++ code will compile. These errors will show up as custom command errors during the build process.

* XML Errors
** ''mismatched tag at line xx'' : The closing tag (a tag with </ >) does not have a matching opening tag.
** ''not well-formed (invalid token) at line xx'' : Probably a blank in the token name.
* ModuleDescriptionParser Errors
** ''<executable> must be the outer most tag''
** ''<executable> was found inside another tag''
** ''<parameters> can only be inside <executable>''
** ''<xxx> can only be used inside <parameters>''
** ''<flag> can only contain one character''
** ''<longname> can only contain letters, numbers and underscores and must start with an _ or letter''
** ''<name> can only contain letters, numbers and underscores and must start with an _ or letter''

* ModuleDescriptionParser Warnings
** ''<xxx> is an unknown parameter tag'' : Probably a misspelled parameter type.

* Compiler Errors
** The generated C++ code may have syntax errors if invalid defaults are specified. These will show up during the C++ compilation.

== Interfacing Legacy Executables ==

GenerateCLP is only provided as a convenience. Users can use the same XML Module Description to interface C++, shell scripts, tcl programs and even Matlab.

Example: [http://www.slicer.org/slicerWiki/index.php/Slicer3:FiberTrackingIntegration FiberTracking Integration]

== Showing Progress in an Application ==

Programs can communicate progress to the user in two ways. If the program is running an a stand-alone executable, it communicates with a simple XML syntax. If the program is loaded at run-time as a plugin library, it communicates through a C structure.

The XML syntax is:

<filter-start>
<filter-name>
''name of program section or algorithm''
</filter-name>
<filter-comment>
''description of program section or algorithm''
</filter-comment>
</filter-start>

<filter-progress>
''floating number from 0 to 1''
</filter-progress>

<filter-end>
<filter-name>
''name of program section or algorithm''
</filter-name>
<filter-time>
''execution time''
</filter-time>
</filter-end>

The C structure that library plugins use is:

extern "C" {
struct ModuleProcessInformation
{
/** Inputs from calling application to the module **/
unsigned char Abort;
/** Outputs from the module to the calling application **/
float Progress;
char ProgressMessage[1024];
void (*ProgressCallbackFunction)(void *);
void *ProgressCallbackClientData;
double ElapsedTime;
}
}

Details on how to use this mechanism are illustrated in [https://github.com/Slicer/Slicer/blob/master/Base/CLI/itkPluginFilterWatcher.h itkPluginFilterWatcher.h].

For vtk and itk execution model programs, two classes are available that make it simple to add progress. The classes, ''vtkPluginFilterWatcher'' and ''itk::PluginFilterWatcher'' use the vtk and itk command/observer mechanism to report progress.

vtkPluginFilterWatcher (vtkAlgorithm *'''filter''', const char* '''comment''', ModuleProcessInformation *'''inf''', double '''fraction''', double '''start''') itk::PluginFilterWatcher (itk::ProcessObject '''filter''', const char* '''comment''', ModuleProcessInformation *'''inf''', double '''fraction''', double '''start''')

: where:
;; filter
:: is the vtkAlgorithm or itk::ProcessObject to be watched.
;; comment
:: is a string that describes the algorithm.
;; inf
:: is an optional pointer to a structure that is used to communicate with the invoking program when the called program is used as a library plugin. If the pointer is 0, this prgram will not report progress if it is run as a library plugin. Default is 0.
;; fraction
:: is the fraction (0-1) of progress that will be reported by this watcher. This is used when multiple filters are run and each filter represents a proportion of the total progress. Default is 1.
;; start
:: is the offset (0-1) of the progress for this filter. This is added to the progress of the filter. The reported progress of the watched filter is ''start + fraction * filter_progress''.

 The following example produces progress for a simple vtk program. The variable CLPProcessInformation is automatically declared and set in the program's ''program''CLP.h file.

<nowiki>#include "vtkPluginFilterWatcher.h"
...
vtkMarchingCubes *cubes = vtkMarchingCubes::New();
cubes->SetInput(reader->GetOutput());
vtkPluginFilterWatcher watchCubes(cubes, "Generate Isosurface", CLPProcessInformation, .5, 0.0);
vtkDecimatePro *decimate = vtkDecimatePro::New();
decimate->SetInput(cubes->GetOutput());
vtkPluginFilterWatcher watchDecimate(decimate, "Reduce Triangle Count", CLPProcessInformation, .5, 0.5);
decimate->Update();
</nowiki>

The following example produces progress for a simple itk program:

<nowiki>#include "itkPluginFilterWatcher.h
...
typedef itk::MedianImageFilter<ImageType,ImageType> FilterType;
FilterType::Pointer median = FilterType::New();
itk::PluginFilterWatcher watchMedian(median, "Denoise Image", CLPProcessInformation);
</nowiki>

== Adding Module Logos to Slicer ==
Slicer plugins, both libraries and executables, can specify plugin-specific logos. These appear in Slicer when a module is selected. The logos are specified in a .h header file. The KWWidget utility, KWConvertImageToHeader, converts a .png file into a .h header file containing the encoded image and additional information such as width, height and pixel size. [[Documentation-3.5#Requirements_for_Modules|See here for additional information.]]

For Slicer, execution model plugin logos are stored in Modules/CLI/Resources. The corresponding image in .png format should be stored in Modules/CLI/ImageData. Othere plugins, created outside the Slicer tree, should store the logo and image in a similar location.

To add a logo to a plugin:
* Create a png image of the logo. The height of the logo should not exceed 40 pixels.
* Convert the logo to the KWWidget icon format as follows. '''NOTE:''' the prefix of the image and header file must be the same for a plugin logo.
<pre>
cd Modules/CLI
KWConvertImageToHeader --base64 --zlib Resources/ITKLogo.h ImageData/ITKLogo.png
</pre>
* Add the logo to the SEMMacroBuildCLImacro in the CMakeLists.txt file for the plugin using LOGO_HEADER parameter.

=== Runtime specification of filter types ===

ITK filters are templated over the images they process. The following code snippet shows how an execution model program can select the image types for filters based on the input images.

First, include the utilites for plugin's:
<pre>
#include "itkPluginUtilities.h"
</pre>

Then, turn your main program into a templated procedure called ''DoIt'':
<pre>
template<class T> int DoIt( int argc, char * argv[], T )
{
PARSE_ARGS;

typedef itk::Image< T, 3 > InputImageType;
typedef itk::Image< T, 3 > OutputImageType;
.
.
.
}
</pre>
Then, create a main program that gets the native component type from one of the input file. Here that input file is ''inputVolume'':
<pre>
int main( int argc, char * argv[] )
{

PARSE_ARGS;

itk::ImageIOBase::IOPixelType pixelType;
itk::ImageIOBase::IOComponentType componentType;

try
{
itk::GetImageType (inputVolume, pixelType, componentType);

// This filter handles all types

switch (componentType)
{
case itk::ImageIOBase::UCHAR:
return DoIt( argc, argv, static_cast<unsigned char>(0));
break;
case itk::ImageIOBase::CHAR:
return DoIt( argc, argv, static_cast<char>(0));
break;
case itk::ImageIOBase::USHORT:
return DoIt( argc, argv, static_cast<unsigned short>(0));
break;
case itk::ImageIOBase::SHORT:
return DoIt( argc, argv, static_cast<short>(0));
break;
case itk::ImageIOBase::UINT:
return DoIt( argc, argv, static_cast<unsigned int>(0));
break;
case itk::ImageIOBase::INT:
return DoIt( argc, argv, static_cast<int>(0));
break;
case itk::ImageIOBase::ULONG:
return DoIt( argc, argv, static_cast<unsigned long>(0));
break;
case itk::ImageIOBase::LONG:
return DoIt( argc, argv, static_cast<long>(0));
break;
case itk::ImageIOBase::FLOAT:
return DoIt( argc, argv, static_cast<float>(0));
break;
case itk::ImageIOBase::DOUBLE:
return DoIt( argc, argv, static_cast<double>(0));
break;
case itk::ImageIOBase::UNKNOWNCOMPONENTTYPE:
default:
std::cout << "unknown component type" << std::endl;
break;
}
}
catch( itk::ExceptionObject &excep)
{
std::cerr << argv[0] << ": exception caught !" << std::endl;
std::cerr << excep << std::endl;
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}

</pre>

== Behind the Scenes ==

A primary goal of the execution model is to relieve developers from developing GUI code and command line parsing code. This section describes the major components of the execution model implementation.

=== Command Line Processing ===

Command line processing parses command line arguments and populates internal program variables. Every Unix (and windows) program can receive an argument list through its main entry point. All C and C++ programmers are familiar with the ''int main (int argc, char *[] argv)'' entry point in their programs. Most computer languages including scripting languages provide a similar mechanism to retrieve command line arguments. Simple command line processing directly accesses the strings defined in argv.

This snippet shows simple commmand line processing:

int main (int argc, char *argv[])
{
if (argc < 2)
{
std::cout << "Usage: " << argv[0] << " filename" << std::endl;
return -1;
}
std::cout << "The File is " << argv[1] << std::endl;
return 0;
}

The simple approach works great for a small number of arguments. But larger numbers of arguments of varying types quickly make the processing code more complex and subject to error, both in coding and usage.

int main (int argc, char *argv[])
{
if (argc < 5)
{
std::cout << "Usage: " << argv[0] << " iterations epsilon inputfile outputfile " << std::endl;
return -1;
}
std::string inputfile(argv[3]);
std::string outputfile(argv[4]);
unsigned int iterations = atoi(argv[1]);
float epsilon = atof(argv[2]);
...
return 0;
}

Adding flags (or options) to the command line makes the program easier to use but places a larger burden on the program developer. Each developer must ''invent'' a command line argument syntax and implement code to parse the command line. Even a simple example of this is too long to include in this description. This code snippet looks for just two command line arguments.

int main (int argc, char *argv[])
{
if (argc < 3)
{
std::cout << "Usage: " << argv[0] << " [-i iterations] [-e epsilon] inputfile outputfile " << std::endl;
return -1;
}
std::string inputfile;
std::string outputfile;
unsigned int iterations = 10; /* a default */
float epsilon = .001; /* a defualt */
++argc; /* skip program name */
while (argc > 0)
{
if (strcmp(argv[argc], "-i")
{
iterations = atoi(argv[argc+1]);
argc+=2;
continue;

else if (strcmp(argv[argc], "-e")
{
epsilon = atof(argv[argc+1]);
argc+=2;
continue;
...
}

The code gets longer and longer as more options are added and must be rewritten every time a new programs is open.

To solve this complexity issue, people have developed command line argument libraries. There are dozens, if not hundreds, of command line processing tools. For Slicer3 we looked at argument processors in vxl, nrrd, meta, kwsys and tclap. Each has its strengths and weaknesses. We chose [http://tclap.sourceforge.net/ The Templatized C++ Command Line Parser Library], '''TCLAP'''. '''TCLAP''' is implemented in ''include'' files and does not require a separate library build. As you will see later, the particular command line processing tool is, for the most part, transparent to the Slicer3 developer or user.

But even these libraries require some work to use.

==== TCLAP ====

This example uses '''TCLAP''' to process a command line with 10 possible entries:

int main ( int argc, char* argv[] ) {
//
// Define default values
int HistogramBins = 30;
int RandomSeed = 1234567;
int SpatialSamples = 10000;
float TranslationScale = 100.0;
int Iterations = 200;
int SplineOrder = 3;
double MinimumStepSize = 0.00001;
double MaximumStepSize = 0.005;
bool PrintTransform = false;
string fixedImageFileName;
string movingImageFileName;
string resampledImageFileName;
//
// Setup command line parsing
try
{
TCLAP::CmdLine cl ( "Register2d", ' ', "$Revision: 1.1 $" );
TCLAP::ValueArg<int> HistogramBinsArg ( "b", "histogrambins", "Number of histogram bins", false, 30, "integer", cl );
TCLAP::ValueArg<int> IterationsArg ( "i", "iterations", "Number of Iterations", false, Iterations, "int", cl );
TCLAP::ValueArg<double> MinimumStepSizeArg ( "m", "minstepsize", "Minimum Step Size", false, MinimumStepSize, "double", cl );
TCLAP::ValueArg<double> MaximumStepSizeArg ( "x", "maxstepsize", "Maximum Step Size", false, MaximumStepSize, "double", cl );
TCLAP::ValueArg<int> RandomSeedArg ( "r", "randomseed", "Random Seed", false, RandomSeed, "int", cl );
TCLAP::ValueArg<int> SpatialSamplesArg ( "s", "spatialsamples", "Number of spatial samples", false, SpatialSamples, "int", cl );
TCLAP::ValueArg<int> SplineOrderArg ( "o", "splineorder", "Order of spline for registration", false, SplineOrder, "int", cl );
TCLAP::SwitchArg PrintTransformArg ( "p", "printtransform", "Print the final transform", PrintTransform, cl );
TCLAP::ValueArg<float> TranslationScaleArg ( "t", "translationscale", "Translation scale", false, TranslationScale, "float", cl );
TCLAP::UnlabeledValueArg<string> FixedImageArg ( "fixed", "Fixed image filename", "", "string", cl );
TCLAP::UnlabeledValueArg<string> MovingImageArg ( "moving", "Moving image filename", "", "string", cl );
TCLAP::UnlabeledValueArg<string> ResampledImageArg ( "resampled", "Resampled image filename", "", "string", cl );
//
// Parse the command line
cl.parse ( argc, argv );
//
// Access the variables
HistogramBins = HistogramBinsArg.getValue();
Iterations = IterationsArg.getValue();
MinimumStepSize = MinimumStepSizeArg.getValue();
MaximumStepSize = MaximumStepSizeArg.getValue();
RandomSeed = RandomSeedArg.getValue();
SpatialSamples = SpatialSamplesArg.getValue();
TranslationScale = TranslationScaleArg.getValue();
PrintTransform = PrintTransformArg.getValue();
fixedImageFileName = FixedImageArg.getValue();
movingImageFileName = MovingImageArg.getValue();
resampledImageFileName = ResampledImageArg.getValue();
}
catch ( ArgException e )
{
cerr << "error: " << e.error() << " for arg " << e.argId() << endl;
exit ( EXIT_FAILURE );
}

You do get a lot for your investment here. Good error handling and help.

=== Module Description Parser ===
The XML parsing is done by the [https://github.com/Slicer/SlicerExecutionModel/tree/master/ModuleDescriptionParser ModuleDescriptionParser] class library. ''GenerateCLP'' and Slicer3 use this class library to parse the module XML descriptions. The class ''ModuleDescriptionParser'' has one method, '''Parse''', that converts the XML description into an object model. The resulting object model has one ''ModuleDescription'', one or more ''ModuleParameterGroup'' each of which has one or more ''ModuleParameter''. Each instance has access methods to retrieve information from the XML.
* '''ModuleDescriptionParser''' - parser for command line module XML description.
*: ''Parse(std::string xml, ModuleDescription module)'' - parse an xml string and populate a ModuleDescription.
* '''ModuleDescription''' - contains information about a module
*: const std::string ''GetCategory()'' : returns the contents of '''<category>'''.
*: const std::string ''GetTitle()'' : returns the contents of '''<title>'''.
*: const std::string ''GetDescription()'' : returns the contents of '''<description>'''.
*: const std::string ''GetVersion()'' : returns the contents of '''<version>'''.
*: const std::string ''GetDocumentationURL()'' : returns the contents of '''<documentationURL>'''.
*: const std::string ''GetLicense()'' : returns the contents of '''<license>'''.
*: const std::string ''GetContributor()'' : returns the contents of '''<contributor>'''.
*: const std::vector<ModuleParameterGroup>& ''GetParameterGroups()'' : returns a vector of parameter groups.
* '''ModuleParameterGroup''' - contains ModuleParameters for each parameter group.
*: const std::string ''GetLabel'' - returns the contents of '''<label>'''.
*: const std::string ''GetDescription()'' - returns the contents of the parameter group's '''<description>'''.
*: const std::string ''GetAdvanced()'' - returns advanced attribute. Either "true" of "false".
* '''ModuleParameter''' - contains information for a parameter.
*:GetTag() - returns the parameter's tag, e.g. '''<integer>, <image>''', etc.
*:GetName() - returns the parameter's '''<name>'''.
*:GetLongFlag() - returns the parameter's '''<longflag>'''.
*:GetLabel() - returns the parameter's '''<label>'''.
*:GetMaximum() - returns the parameter's '''<maximum>''' constraint.
*:GetMinimum() - returns the parameter's '''<minimum>''' constraint.
*:GetStep() - returns the parameter's '''<step>'''.
*:GetDescription() - returns the parameter's '''<description>'''.
*:GetChannel() - returns the parameter's '''<channel>'''.
*:GetIndex() - returns the parameter's '''<index>'''.
*:GetDefault() - returns the parameter's '''<default>'''.
*:GetFlag() - returns the parameter's '''<flag>'''.
*:GetMultiple() - returns the parameter's multiple attribute, either "true" or "false".
*:GetCoordinateSystem() - returns the parameter's coordinate system attribute, one of "lps", "ras", or "ijk".

= Adding a new parameter type =

Adding a ''new parameter type'' to the execution model involves several modifications:

# A new XML tag needs to be defined to represent the new parameter type.
# ModuleDescriptionParser needs to be modified to parse the new parameter tag type and specify how the command line processing code generation is going to represent the parameter type
# CommandLineModuleGUI needs to be modified to construct the appropriate GUI element for the parameter type
# CommandLineModuleLogic needs to be modified to put the parameter type onto the command line and request outputs parameter types be loaded back into Slicer and the MRML tree.
# SlicerApplicationLogic needs to be modified to ingest any output parameter types back into Slicer and the MRML tree.
# Additional modification are needed if the parameter is to be passed directly from the MRML tree without using the filesystem.
# Updating the documentation.

Simple parameter types can be passed directly on the command line. For instance, scalars, small lists, positions, etc. Complicated parameter types are passed to the module via '''abstract files'''. In some cases, these parameters are actually passed as files, where Slicer reads/write the data to the filesystem. In other cases, the parameters are passed as '''abstract files''' which are really references to within the Slicer memory model but appear to the Command Line Module as being a file. The Command Line Module is written using standard ITK ImageFileReader/ImageFileWriter classes but the ITK ImageIO factory mechanism is used to direct the ImageFileReader/ImageFileWriter to talk directly to the Slicer MRML tree instead of to the filesystem.

== XML tag ==

This is by far the easiest of the tasks involved in adding a new parameter type but it should not approached hastily. The XML description of a module is designed to be application agnostic. As such, parameter types should be described abstractly or generically. For instance, '''<geometry>''' tag corresponds to the Slicer model node, the '''<point>''' tag corresponds to the Slicer fiducial node, etc.

Once the tag name is defined, you need to decide whether the parameter type could or should support the attributes '''multiple''', '''coordinateSystem''', or '''fileExtensions''' or perhaps a new attribute type.

== Modifying ModuleDescriptionParser ==

SlicerExecutionModel/ModuleDescriptionParser/ModuleDescriptionParser.cxx contains the code to parse the XML description of a module and represent that module description in C++ data structures. To add a new parameter type, this code needs to be modified.

Two routines need to be modified in ModuleDescriptionParser, ''startElement()'' and ''endElement()''. For ''startElement()'', a new case block needs to be added for the parameter type. You can start by copying the case block for a similar parameter type. This case block is responsible for processing all the attributes for the tag and managing and reporting any errors. The case block may define the '''CPPType''', the ''ArgType''', and the '''StringToType''' needed for the code generation of the command line parsing. The '''CPPType''' is used by in the generated command line processing code to represent the parameter. This may be a simple C++ type or an STL container. The '''ArgType''' is the canonical type of each component of the parameter. The '''StringToType''' is the name of the method to use to convert the ASCII command line parameter to the final '''ArgType'''. The ''endElement()'' method merely needs a new case block to add the parameter to the description.

ModuleDescriptionParser is fairly general, handling scalars, lists of scalars, and file types as parameter types. A parameter which does not fit these models will require considerable alterations to the ModuleDescriptionParser as well as the GenerateCLP.

== Constructing a GUI for a new parameter type ==

To have a GUI element appear in the module GUI for a new parameter type, Base\QTCLI\qSlicerCLIModuleUIHelper.cxx and Base\QTCLI\vtkSlicerCLIModuleLogic.cxx have to be modified. A new case block needs to be added to the '''BuildGUI()''' method for the new parameter type. This case block is triggered off the XML tag for the parameter type. The case block is responsible for the constructing the appropriate GUI element for the parameter, complete with specifying the label and help text. The design is very simple. A single widget is used for each parameter. If a more complicated GUI is needed with multiple widgets, then perhaps a new widget is needed to encapsulated a set of widgets or a naming convention can be added to manage all the widgets associated with a parameter. The widgets for the parameters are stored in a map, indexed by the '''name''' of the parameter.

The vtkCommandLineModuleGUI (and vtkCommandLineModuleLogic) are designed to operate very generically with sets of parameters. The aforementioned map of widgets indexed by parameter '''name''' is one such example. The implementation of several of the methods in the vtkCommandLineModuleGUI (and vtkCommandLineModuleLogic) generically iterate over the widget map or over the parameter list. It is important to keep this in mind as new parameters are added. The design goal is to minimize the number of ''special cases'' in the code.

Note that there may be separate case blocks for '''input''' and '''output''' parameter types.

== Communicating the new parameter to the Command Line Module ==

To communicate the new parameter type to and from a Command Line Module, the '''ApplyTask()''' method Slicer3/Modules/CommandLineModule/vtkCommandLineModuleLogic.cxx needs to be modified.

If the parameter type is communicated to the command line module as a file (as opposed to directly on the command line as a number or srting), then there are several blocks of code to construct a temporary file name, keep track of whether that node needs to be written to the filesystem before execution, read from the filesystem after the execution, and deleted after execution completes. These blocks may need to be modified based on your new parameter type.

The command line is constructed in two passes. First, a pass is made over the parameter list, building the portion of the command line for any parameters that have flags. Note that whether a parameter has a flag or not is up to the discretion of the module author and is not defined by the parameter type. Second, a pass is made to construction the portion of the command line for the parameters that do not have flags. These parameters are ordered appropriately, then placed on the command line. For parameters with flags, this code emits the flag and the parameter value. For the parameters without flags, this code emits just the parameter value. You will need to edit both of these passes to emit your parameter type. In most cases, this is simply a matter of grabbing the parameter value from the parameter and pushing it onto the command line. But some parameter types do require translation to a string appropriate for the command line.

== Output parameters from the Command Line Modules ==

Any outputs from a Command Line Module that are communicated via files are queued to be read by the main application thread. Command Line Modules run in a separate execution thread from the main GUI. This thread is not allowed to modify the Slicer GUI, so any results from the module that need to be read back into Slicer and displayed are queued for the main thread.

The '''ProcessReadData()''' method of Slicer3/Base/Logic/vtkSlicerApplicationLogic.cxx pulls data from the queue to load back into Slicer and display. You may need to a case block for your new parameter type to construct the appropriate storage node and display node.

== Communicating directly with the MRML tree ==

Currently scalar image types can sent as parameters to shared object command line modules without going through the filesystem. Slicer provides a new ITK ImageIO factory that can communicated directly with the Slicer MRML tree. This ImageIO factory is in Slicer/Libs/MRMLIDImageIO. This approach can be extended for other image types such as vector or tensor volumes.

For other constructs such as models and transforms, we'll need to see if an existing factory mechanism can be leverage to communicate directly with the Slicer MRML tree. An alternative may be to construct bridges specific to interfacing from a command line module to the Slicer MRML tree.

== Adding new image types ==

The Command Line Module support scalar, vector, tensor, and diffusion weighted images. Adding a new image type to the Command Line Module requires modify the sections of the code outlined above to manage GUI for the module, to construct temporary file names, to write image to disk, and load them back into the MRML tree. These blocks are easy to identify as case blocks on vtkMRMLScalarVolumeNode, vtkMRMLDiffusionTensorVolumeNode, etc. Note that the '''<image>''' tag supports a '''type''' attribute that can scalar, label, vector, tensor, or diffusion-weighted. The case block for '''image''' in the '''startElement()''' method of ModuleDescriptionParser would need to be extended to recognize a new type of image.

=FAQ=

==What facilities are available for third party software to interface with the NA-MIC Kit?==

NA-MIC has committed to developing and supporting a generic batch processing interface. This is the Slicer3 Command Line Interface (CLI). The application programming interface (API) for CLI was worked out based on interactions with the community including input from those familiar with LONI, ITK, Python and Matlab software development practices.

We believe this API already supports all the features required by to implement batch processing with BatchMake, the LONI Pipeline, and any other systems that we may want to work with in the future. The [[Slicer3:Execution_Model_Documentation|Slicer3 Execution Model]] provides a simple XML-based descriptor for command line arguments for input/output volumes and related parameters.

==Which Third Party software has currently been interfaced to the NA-MIC Kit using the CLI?==

*Batchmake (Kitware)
*Python
*Matlab

== How do I debug my command line module? ==

See [http://www.slicer.org/slicerWiki/index.php/Slicer3:Execution_Model_Documentation:Debugging Debugging]

== How do I specify a Logo? ==

You need to create a logo.h file (embedding the zipped pixel data as base64 strings in a C source code). There is a utility bundled with kwwidgets that accomplishes this. From a Slicer3 build directory you can do something like this:

./Slicer3 --launch ../Slicer3-lib/KWWidgets-build/bin/KWConvertImageToHeader --base64 --zlib ~/Desktop/bioimagesuite_logo_www.h ~/Desktop/bioimagesuite_logo_www.png

The resulting .h header file can then be used as an argument to the 'generateclp' cmake macro like this:

generateclp(${CLP}_SOURCE ${CLP}.xml ${Slicer3_SOURCE_DIR}/Resources/bioimagesuite_logo_www.h)

''Note: logos are limited in size: if your .h file contains a symbol like 'image_bioimagesuite_logo_www' it will work. But if it has several symbols like 'image_bioimagesuite_logo_www_1' 'image_bioimagesuite_logo_www_2' etc then the logo was too large and needs to be downsampled for use.''

== What do I do if I want to use the CLI outside of slicer? ==

In general CLI executables will depend on shared libraries provided by Slicer (such as ITKCommon, etc). To be sure your run-time environment resolves to the correct versions, you should always use a form like:
./Slicer3 --launch <CLI>
or, you can start a shell from which you can run multiple CLI modules. Something like:
./Slicer3 --launch xterm &

We do not suggest hard-coding the runtime paths into, for example, your .bashrc since this may interfere with other programs and can make it hard to use multiple versions of slicer on the same account.

= Laundry List =

Use this section to describe any features that are missing, not documented, or require additional work.

* Comments from Hans Johnson, June 4, 2010:
** Enumerated types can only have about 3 characters in them, otherwise they don’t render in the slicer wizard at all.
** There is no way to unset an enumerated type, and the values are cached even after leaving the module. If the default enumerated type is to be blank, and you select it, then you must restart slicer in order to make the blank option available again.
** There is no way to have conditional options. For example if one flag is used, then other flag can not be used, so it should be disabled.

* Documenting your module:
** a convenience script has been developed by Hans Johnson, which creates a wiki page describing the command line module by extracting the information from the xml description [[SEMToMediaWiki.py]]. TODO: extract the default values for the parameters to be included in the documentation

Documentation/Nightly/Developers/Build Instructions/Prerequisites

2015-10-02T15:09:30Z

Fbudin: /* Ubuntu */

<noinclude>{{documentation/versioncheck}}</noinclude>
__TOC__

== PREREQUISITES ==
 

Consider reading platform specific requirements listed below.

=== Linux ===
* [{{tool|download|cmake}} CMake] >= 3.x
* [{{tool|download|git}} Git] >= 1.7.10
* [{{tool|download|svn}} Svn] >= 1.7
* Qt 4.8.6. See details [http://na-mic.org/Mantis/view.php?id=3325#bugnotes here] (Note that any version >= Qt 4.7.4 can be used only for Ubuntu < 12.04)

==== Debian ====

* Debian squeeze/wheezy/testing(jessie) users, start by pasting the following lines in a terminal
sudo apt-get install subversion git-core git-svn
sudo apt-get install make gcc g++ libX11-dev libXt-dev libgl1-mesa-dev libosmesa6-dev libglu1-mesa-dev libfontconfig-dev libxrender-dev libncurses5-dev
sudo apt-get install cmake
sudo apt-get install qt-sdk

==== Ubuntu ====

* Ubuntu users, start by pasting the following lines in a terminal
sudo apt-get install subversion git-core git-svn
sudo apt-get install make gcc g++ libX11-dev libXt-dev libgl1-mesa-dev libglu1-mesa-dev libfontconfig-dev libxrender-dev libncurses5-dev

'''For Ubuntu < 12.04''':
sudo apt-get install cmake # Only for Ubuntu < 12.04

'''For Ubuntu < 14.04.3''':
sudo apt-get install libosmesa6-dev

* NOTE: on Ubuntu 14.04.3 LTS, attempting to install <tt>libosmesa6-dev</tt> results in an error:
The following packages have unmet dependencies:
libosmesa6-dev : Depends: libosmesa6 (= 10.1.3-0ubuntu0.4) but it is not going to be installed
E: Unable to correct problems, you have held broken packages.
See [https://bugs.launchpad.net/ubuntu/+source/mesa-lts-utopic/+bug/1424059 Bug 1424059].

Slicer compiles successfully without that package, but <tt>VTK_OPENGL_HAS_OSMESA</tt> is disabled.

'''For Ubuntu 12.04 and above''': You *MUST download the standard CMake binary* from http://cmake.org/download because the distributed version of CMake cannot be used to build slicer. For example, on a 64-bit system, you will download the file <code>cmake-X.Y.Z-Linux-x86_64.tar.gz</code> associated with the latest stable version.


References:

* Why distributed CMake can not be used on Ubuntu 12.04 and above ?
** http://slicer-devel.65872.n3.nabble.com/PYTHON-INCLUDE-DIR2-when-building-Slicer4-td4028557.html
** Slicer issue [http://na-mic.org/Mantis/view.php?id=3103 #3103]
** Slicer issue [http://na-mic.org/Mantis/view.php?id=3116#c8649 #3116]
** CMake issue [http://public.kitware.com/Bug/view.php?id=14156 #14156]





'''For Ubuntu 12.04, 12.10, 13.04 and 13.10''': Qt 4 >= 4.8.5 MUST be used. See reference below for more details.

<pre>
cd ~/Support # This is where we will build Qt and dependent libraries

# Keep track of our working directory
cwd=$(pwd)

# This will download, then build zlib and openssl in the current folder
rm -f get-and-build-openssl-for-slicer.sh
wget https://gist.githubusercontent.com/jcfr/9513568/raw/21f4e4cabca5ad03435ecc17ab546dab5e2c1a2f/get-and-build-openssl-for-slicer.sh
chmod u+x get-and-build-openssl-for-slicer.sh
./get-and-build-openssl-for-slicer.sh

# This will download Qt source in the current folder
wget http://packages.kitware.com/download/item/6175/qt-everywhere-opensource-src-4.8.6.tar.gz
md5=`md5sum ./qt-everywhere-opensource-src-4.8.6.tar.gz | awk '{ print $1 }'` &&
[ $md5 == "2edbe4d6c2eff33ef91732602f3518eb" ] || echo "MD5 mismatch. Problem downloading Qt"

# This will configure and build Qt in RELEASE against the zlib and openssl previously built
tar -xzvf qt-everywhere-opensource-src-4.8.6.tar.gz
mv qt-everywhere-opensource-src-4.8.6 qt-everywhere-opensource-release-src-4.8.6
mkdir qt-everywhere-opensource-release-build-4.8.6
cd qt-everywhere-opensource-release-src-4.8.6
./configure -prefix $cwd/qt-everywhere-opensource-release-build-4.8.6 \
-release \
-opensource -confirm-license \
-no-qt3support \
-webkit \
-nomake examples -nomake demos \
-openssl -I $cwd/openssl-1.0.1e/include -L $cwd/openssl-1.0.1e \
&& make -j7 && make install
</pre>


References:

* Why Qt 4 >= 4.8.5 should be used on Ubuntu 12.04 and above ?
** Slicer issue [http://www.na-mic.org/Bug/view.php?id=3325 #3325]


==== CentOS ====
*CentOS user type:
yum install make gcc-c++ libX11-devel libXt-devel libXext-devel libGLU-devel mesa-libOSMesa-devel mesa-libGL-devel mesa-libGLU-devel ncurses



=== MacOSX ===

'''MacOSX 10.9.4 (Maverick):'''

''' (1) Make sure to install this update: http://support.apple.com/kb/DL1754'''

''' (2) Use CMake 3.0.1 - it is known to be working and is supported''' (if you want to use CMake already installed on your system, 2.8.12.2 is known to work on Mac OS X 10.9.5)

* Mac Os X >= 10.5 (Leopard)
* [{{tool|download|cmake}} CMake] >= 2.8.9
** For Mac Os X >= 10.8 ([http://en.wikipedia.org/wiki/OS_X_Mountain_Lion Mountain Lion]) and/or recent XCode >= 4.5.X - [{{tool|download|cmake}} CMake] >= 2.8.11 is required. See http://www.cmake.org/files/v2.8/cmake-2.8.11-Darwin64-universal.tar.gz


$ curl -O http://www.cmake.org/files/v2.8/cmake-2.8.11-Darwin64-universal.tar.gz
$ tar -xzvf cmake-2.8.11-Darwin64-universal.tar.gz --strip-components=1

$ CMake\ 2.8-11.app/Contents/bin/cmake --version
cmake version 2.8.11

* [{{tool|download|git}} Git] >= 1.7.10
* [{{tool|download|svn}} Svn] >= 1.7

* XCode (for the SDK libs)
* Qt 4 >= 4.8.5. We recommend you install the following two packages:
** Download and install [http://download.qt-project.org/official_releases/qt/4.8/4.8.6/qt-opensource-mac-4.8.6-1.dmg qt-opensource-mac-4.8.6-1.dmg]
** Download and install [http://download.qt-project.org/official_releases/qt/4.8/4.8.6/qt-opensource-mac-4.8.6-1-debug-libs.dmg qt-opensource-mac-4.8.6-1-debug-libs.dmg]
** For more details [[Documentation/{{documentation/version}}/Developers/Build_Instructions/Prerequisites/Qt#Mac|here]]
* XQuartz - For Mac Os X >= 10.8 ([http://en.wikipedia.org/wiki/OS_X_Mountain_Lion Mountain Lion]) install XQuartz (http://xquartz.macosforge.org) to get X11 (no longer a default in OS X).


=== Windows ===
* [{{tool|download|cmake}} CMake] >= 3.0
* [{{tool|download|git}} Git] >= 1.7.10


** {{note}}For convenience, you could update the PATH variable so that ''git'' can be automatically discovered when configuring Slicer. If not, you will have to specify the GIT_EXECUTABLE at configure time.

* [http://www.sliksvn.com/en/download SlikSvn] . If using TortoiseSVN (versions that support command line tools), make sure you install Command line tools (disabled by default)

* NSIS (optional): Needed if packaging Slicer - Click [http://nsis.sourceforge.net/Download here] to download.

* Qt 4.8.6 (for VS2008). See details [[Documentation/{{documentation/version}}/Developers/Build_Instructions/Prerequisites/Qt#Windows|here]]
** Normally you should plan to build Qt from source to have complete control over the process. See [https://github.com/jcfr/qt-easy-build one-liner build command] 
** You may find that the '''unsigned''' binary downloads from this site are usable: http://sourceforge.net/projects/qt64ng/files/qt/x86-64/4.8.6/msvc2008/ (If you use .7z varaints extract them in the default location C:\Qt\ otherwise that installation will not be properly configured for use with CMake)
** '''Details''': Using the Qt Designer on Windows requires that the Slicer plugins are compiled in the same mode as Qt. If Qt was compiled in Release mode (default), Slicer would have to be compiled in Release mode as well. However if Qt is compiled in Debug mode only, Slicer has to be compiled in Debug too. When Qt is in "Release and Debug" mode only the Release version of Designer.exe is generated, Slicer would have to be compiled in Release. So for developers, the Debug mode is recommended.
** For VS2012 Qt needs to be build from source. Build will fail, which can be fixed with this diff: https://gist.github.com/Vitallium/5220503 (read the comment too)

* IDE
** '''Tested/Recommended''': [https://www.microsoft.com/visualstudio/en-us/products/2008-editions Microsoft Visual Studio 9 2008] (Any edition). [http://go.microsoft.com/?linkid=7729279 VS Express 2008 with SP1 direct link] (functional as of Jan 11, 2014)
*** Make sure to install:
**** SP1. Click [http://www.microsoft.com/download/en/details.aspx?id=10986 here] to download SP1 and click [http://massmail.spl.harvard.edu/public-archives/slicer-devel/2012/008206.html here] to understand the motivation.
*** Make sure to patch VS2008 using the script [https://gist.github.com/jcfr/3c7bef3f8b32f9f6ad4b fix-vc9-redist-manifests.ps1]
** '''Experimental''': The plan is to support [https://www.microsoft.com/visualstudio/en-us/products/2010-editions Microsoft Visual Studio 2010] (Any edition). {{note}} NOTE THAT EXPERIMENTAL MEANS THIS DOESN'T YET WORK :)
*** Make sure to build or install:
**** Qt 4.8
*** Make sure to install:
**** SP1. Click [http://www.microsoft.com/download/en/details.aspx?id=23691 here] to download SP1 and click [http://developer.qt.nokia.com/faq/answer/why_do_all_qt_4.7_applications_crash_when_using_windows_7_x64_w_vs_2010 here] to understand the motivation.
**** SP1 Compiler update. Click [https://www.microsoft.com/download/en/details.aspx?id=4422 here] to download and [http://slicer-devel.65872.n3.nabble.com/Windows-7-64Bits-Slicer-4-Build-with-VC-2010-problem-tt3730524.html#a3731661 here] to understand the motivation.


** '''Experimental''' (Visual Studio 2012): Use a desktop version such as [http://www.microsoft.com/visualstudio/eng/downloads#d-express-windows-desktop Visual Studio 2012 Express for Windows Desktop] and remember [http://www.microsoft.com/en-us/download/details.aspx?id=38188 Visual Studio 2012 Update 2]). Do not use Visual Studio Express 2012 for Windows 8. You must install [http://msdn.microsoft.com/en-us/library/ms717422.aspx Windows SDK], otherwise CMake will not even find the C compiler during configure. In CMake, choose <tt>Visual Studio 11 Win64</tt> as generator.
** '''Experimental''' (Visual Studio 2013 with Update 5, as of [https://github.com/Slicer/Slicer/commit/e5eb47826bacc172b7d1c3f2c2c32d0344fc04f9 commit e5eb478]): Slicer compilation is successful, with some caveats. Steps:
*** CMake >= 3.3.1
*** Build Qt 4.8.7 with SSL support using [https://github.com/jcfr/qt-easy-build/tree/4.8.7 qt-easy-build].
*** For Debug mode, disable <code>Slicer_USE_NUMPY</code> and <code>Slicer_USE_SimpleITK</code> in CMake.
*** For Release mode, disable <code>Slicer_USE_NUMPY</code> in CMake.
** '''Un-tested''': Cygwin suite (building with cygwin gcc not supported, but the cygwin shell environment can be used to run git, svn, etc).

Documentation/Nightly/Developers/Build Instructions/Prerequisites

2015-10-01T21:44:26Z

Fbudin: /* Ubuntu */

<noinclude>{{documentation/versioncheck}}</noinclude>
__TOC__

== PREREQUISITES ==
 

Consider reading platform specific requirements listed below.

=== Linux ===
* [{{tool|download|cmake}} CMake] >= 3.x
* [{{tool|download|git}} Git] >= 1.7.10
* [{{tool|download|svn}} Svn] >= 1.7
* Qt 4.8.6. See details [http://na-mic.org/Mantis/view.php?id=3325#bugnotes here] (Note that any version >= Qt 4.7.4 can be used only for Ubuntu < 12.04)

==== Debian ====

* Debian squeeze/wheezy/testing(jessie) users, start by pasting the following lines in a terminal
sudo apt-get install subversion git-core git-svn
sudo apt-get install make gcc g++ libX11-dev libXt-dev libgl1-mesa-dev libosmesa6-dev libglu1-mesa-dev libfontconfig-dev libxrender-dev libncurses5-dev
sudo apt-get install cmake
sudo apt-get install qt-sdk

==== Ubuntu ====

* Ubuntu users, start by pasting the following lines in a terminal
sudo apt-get install subversion git-core git-svn
sudo apt-get install make gcc g++ libX11-dev libXt-dev libgl1-mesa-dev libglu1-mesa-dev libfontconfig-dev libxrender-dev libncurses5-dev

'''For Ubuntu < 12.04''':
sudo apt-get install cmake # Only for Ubuntu < 12.04

'''For Ubuntu < 14.04.3''':
sudo apt-get install libosmesa6-dev

* NOTE: on Ubuntu 14.04.3 LTS, attempting to install <tt>libosmesa6-dev</tt> results in an error:
The following packages have unmet dependencies:
libosmesa6-dev : Depends: libosmesa6 (= 10.1.3-0ubuntu0.4) but it is not going to be installed
E: Unable to correct problems, you have held broken packages.
See [https://bugs.launchpad.net/ubuntu/+source/mesa-lts-utopic/+bug/1424059 Bug 1424059].

Slicer compiles successfully without that package, but <tt>VTK_OPENGL_HAS_OSMESA</tt> is disabled.

'''For Ubuntu 12.04 and above''': You *MUST download the standard CMake binary* from http://cmake.org/download because the distributed version of CMake cannot be used to build slicer. For example, on a 64-bit system, you will download the file <code>cmake-X.Y.Z-Linux-x86_64.tar.gz</code> associated with the latest stable version.


References:

* Why distributed CMake can not be used on Ubuntu 12.04 and above ?
** http://slicer-devel.65872.n3.nabble.com/PYTHON-INCLUDE-DIR2-when-building-Slicer4-td4028557.html
** Slicer issue [http://na-mic.org/Mantis/view.php?id=3103 #3103]
** Slicer issue [http://na-mic.org/Mantis/view.php?id=3116#c8649 #3116]
** CMake issue [http://public.kitware.com/Bug/view.php?id=14156 #14156]





'''For Ubuntu 12.04, 12.10, 13.04 and 13.10''': Qt 4 >= 4.8.5 MUST be used. See reference below for more details.

<pre>
cd ~/Support # This is where we will build Qt and dependent libraries

# Keep track of our working directory
cwd=$(pwd)

# This will download, then build zlib and openssl in the current folder
rm -f get-and-build-openssl-for-slicer.sh
wget https://gist.githubusercontent.com/jcfr/9513568/raw/21f4e4cabca5ad03435ecc17ab546dab5e2c1a2f/get-and-build-openssl-for-slicer.sh
chmod u+x get-and-build-openssl-for-slicer.sh
./get-and-build-openssl-for-slicer.sh

# This will download Qt source in the current folder
wget http://packages.kitware.com/download/item/6175/qt-everywhere-opensource-src-4.8.6.tar.gz
md5=`md5sum ./qt-everywhere-opensource-src-4.8.6.tar.gz | awk '{ print $1 }'` &&
[ $md5 == "2edbe4d6c2eff33ef91732602f3518eb" ] || echo "MD5 mismatch. Problem downloading Qt"

# This will configure and build Qt in RELEASE against the zlib and openssl previously built
tar -xzvf qt-everywhere-opensource-src-4.8.6.tar.gz
mv qt-everywhere-opensource-src-4.8.6 qt-everywhere-opensource-release-src-4.8.6
mkdir qt-everywhere-opensource-release-build-4.8.6
cd qt-everywhere-opensource-release-src-4.8.6
./configure -prefix $cwd/qt-everywhere-opensource-release-build-4.8.6/ \
-release \
-opensource -confirm-license \
-no-qt3support \
-webkit \
-nomake examples -nomake demos \
-openssl -I $cwd/openssl-1.0.1e/include -L $cwd/openssl-1.0.1e \
&& make -j7 && make install
</pre>


References:

* Why Qt 4 >= 4.8.5 should be used on Ubuntu 12.04 and above ?
** Slicer issue [http://www.na-mic.org/Bug/view.php?id=3325 #3325]


==== CentOS ====
*CentOS user type:
yum install make gcc-c++ libX11-devel libXt-devel libXext-devel libGLU-devel mesa-libOSMesa-devel mesa-libGL-devel mesa-libGLU-devel ncurses



=== MacOSX ===

'''MacOSX 10.9.4 (Maverick):'''

''' (1) Make sure to install this update: http://support.apple.com/kb/DL1754'''

''' (2) Use CMake 3.0.1 - it is known to be working and is supported''' (if you want to use CMake already installed on your system, 2.8.12.2 is known to work on Mac OS X 10.9.5)

* Mac Os X >= 10.5 (Leopard)
* [{{tool|download|cmake}} CMake] >= 2.8.9
** For Mac Os X >= 10.8 ([http://en.wikipedia.org/wiki/OS_X_Mountain_Lion Mountain Lion]) and/or recent XCode >= 4.5.X - [{{tool|download|cmake}} CMake] >= 2.8.11 is required. See http://www.cmake.org/files/v2.8/cmake-2.8.11-Darwin64-universal.tar.gz


$ curl -O http://www.cmake.org/files/v2.8/cmake-2.8.11-Darwin64-universal.tar.gz
$ tar -xzvf cmake-2.8.11-Darwin64-universal.tar.gz --strip-components=1

$ CMake\ 2.8-11.app/Contents/bin/cmake --version
cmake version 2.8.11

* [{{tool|download|git}} Git] >= 1.7.10
* [{{tool|download|svn}} Svn] >= 1.7

* XCode (for the SDK libs)
* Qt 4 >= 4.8.5. We recommend you install the following two packages:
** Download and install [http://download.qt-project.org/official_releases/qt/4.8/4.8.6/qt-opensource-mac-4.8.6-1.dmg qt-opensource-mac-4.8.6-1.dmg]
** Download and install [http://download.qt-project.org/official_releases/qt/4.8/4.8.6/qt-opensource-mac-4.8.6-1-debug-libs.dmg qt-opensource-mac-4.8.6-1-debug-libs.dmg]
** For more details [[Documentation/{{documentation/version}}/Developers/Build_Instructions/Prerequisites/Qt#Mac|here]]
* XQuartz - For Mac Os X >= 10.8 ([http://en.wikipedia.org/wiki/OS_X_Mountain_Lion Mountain Lion]) install XQuartz (http://xquartz.macosforge.org) to get X11 (no longer a default in OS X).


=== Windows ===
* [{{tool|download|cmake}} CMake] >= 3.0
* [{{tool|download|git}} Git] >= 1.7.10


** {{note}}For convenience, you could update the PATH variable so that ''git'' can be automatically discovered when configuring Slicer. If not, you will have to specify the GIT_EXECUTABLE at configure time.

* [http://www.sliksvn.com/en/download SlikSvn] . If using TortoiseSVN (versions that support command line tools), make sure you install Command line tools (disabled by default)

* NSIS (optional): Needed if packaging Slicer - Click [http://nsis.sourceforge.net/Download here] to download.

* Qt 4.8.6 (for VS2008). See details [[Documentation/{{documentation/version}}/Developers/Build_Instructions/Prerequisites/Qt#Windows|here]]
** Normally you should plan to build Qt from source to have complete control over the process. See [https://github.com/jcfr/qt-easy-build one-liner build command] 
** You may find that the '''unsigned''' binary downloads from this site are usable: http://sourceforge.net/projects/qt64ng/files/qt/x86-64/4.8.6/msvc2008/ (If you use .7z varaints extract them in the default location C:\Qt\ otherwise that installation will not be properly configured for use with CMake)
** '''Details''': Using the Qt Designer on Windows requires that the Slicer plugins are compiled in the same mode as Qt. If Qt was compiled in Release mode (default), Slicer would have to be compiled in Release mode as well. However if Qt is compiled in Debug mode only, Slicer has to be compiled in Debug too. When Qt is in "Release and Debug" mode only the Release version of Designer.exe is generated, Slicer would have to be compiled in Release. So for developers, the Debug mode is recommended.
** For VS2012 Qt needs to be build from source. Build will fail, which can be fixed with this diff: https://gist.github.com/Vitallium/5220503 (read the comment too)

* IDE
** '''Tested/Recommended''': [https://www.microsoft.com/visualstudio/en-us/products/2008-editions Microsoft Visual Studio 9 2008] (Any edition). [http://go.microsoft.com/?linkid=7729279 VS Express 2008 with SP1 direct link] (functional as of Jan 11, 2014)
*** Make sure to install:
**** SP1. Click [http://www.microsoft.com/download/en/details.aspx?id=10986 here] to download SP1 and click [http://massmail.spl.harvard.edu/public-archives/slicer-devel/2012/008206.html here] to understand the motivation.
*** Make sure to patch VS2008 using the script [https://gist.github.com/jcfr/3c7bef3f8b32f9f6ad4b fix-vc9-redist-manifests.ps1]
** '''Experimental''': The plan is to support [https://www.microsoft.com/visualstudio/en-us/products/2010-editions Microsoft Visual Studio 2010] (Any edition). {{note}} NOTE THAT EXPERIMENTAL MEANS THIS DOESN'T YET WORK :)
*** Make sure to build or install:
**** Qt 4.8
*** Make sure to install:
**** SP1. Click [http://www.microsoft.com/download/en/details.aspx?id=23691 here] to download SP1 and click [http://developer.qt.nokia.com/faq/answer/why_do_all_qt_4.7_applications_crash_when_using_windows_7_x64_w_vs_2010 here] to understand the motivation.
**** SP1 Compiler update. Click [https://www.microsoft.com/download/en/details.aspx?id=4422 here] to download and [http://slicer-devel.65872.n3.nabble.com/Windows-7-64Bits-Slicer-4-Build-with-VC-2010-problem-tt3730524.html#a3731661 here] to understand the motivation.


** '''Experimental''' (Visual Studio 2012): Use a desktop version such as [http://www.microsoft.com/visualstudio/eng/downloads#d-express-windows-desktop Visual Studio 2012 Express for Windows Desktop] and remember [http://www.microsoft.com/en-us/download/details.aspx?id=38188 Visual Studio 2012 Update 2]). Do not use Visual Studio Express 2012 for Windows 8. You must install [http://msdn.microsoft.com/en-us/library/ms717422.aspx Windows SDK], otherwise CMake will not even find the C compiler during configure. In CMake, choose <tt>Visual Studio 11 Win64</tt> as generator.
** '''Experimental''' (Visual Studio 2013 with Update 5, as of [https://github.com/Slicer/Slicer/commit/e5eb47826bacc172b7d1c3f2c2c32d0344fc04f9 commit e5eb478]): Slicer compilation is successful, with some caveats. Steps:
*** CMake >= 3.3.1
*** Build Qt 4.8.7 with SSL support using [https://github.com/jcfr/qt-easy-build/tree/4.8.7 qt-easy-build].
*** For Debug mode, disable <code>Slicer_USE_NUMPY</code> and <code>Slicer_USE_SimpleITK</code> in CMake.
*** For Release mode, disable <code>Slicer_USE_NUMPY</code> in CMake.
** '''Un-tested''': Cygwin suite (building with cygwin gcc not supported, but the cygwin shell environment can be used to run git, svn, etc).

Documentation/4.3/Modules/Markups

2015-09-23T14:14:42Z

Fbudin: /* Adding Fiducials via Mouse Clicks */

<noinclude>{{documentation/versioncheck}}</noinclude>

{{documentation/{{documentation/version}}/module-header}}



{{documentation/{{documentation/version}}/module-section|Introduction and Acknowledgements}}
{{documentation/{{documentation/version}}/module-introduction-start|{{documentation/modulename}}}}
{{documentation/{{documentation/version}}/module-introduction-row}}
This work is part of the National Alliance for Medical Image Computing (NA-MIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Information on NA-MIC can be obtained from the [http://www.na-mic.org/ NA-MIC website]. 
Author: Nicole Aucoin, SPL, BWH 
Contact: Nicole Aucoin, <email>nicole@bwh.harvard.edu</email> 
{{documentation/{{documentation/version}}/module-introduction-row}}
{{documentation/{{documentation/version}}/module-introduction-logo-gallery
|{{collaborator|logo|spl}}|{{collaborator|longname|spl}}
}}
{{documentation/{{documentation/version}}/module-introduction-end}}


{{documentation/{{documentation/version}}/module-section|Module Description}}
This module is used to manage markups in Slicer.

It is based on the functionality in the Slicer 3.6 Fiducials module, with elements from the Slicer 4.2 Annotations module.

Currently, only fiducials are supported.

{{documentation/{{documentation/version}}/module-description}}

Development history can be found in the [[documentation/{{documentation/version}}/Modules/{{documentation/modulename}}#References|references]].


{{documentation/{{documentation/version}}/module-section|Use Cases}}

This module allows you to add new markups, edit markups in a list, delete markups and modify display properties of markups.

Markups can be passed to command line modules (CLIs) using the <pre>--point</pre> argument.

The Mouse mode tool bar can be used to place new markups by positioning the mouse and left clicking in the viewers. Once you are in Place mode and placing Markups fiducials, you can use the 'p' key to place a new fiducial while the Markups GUI is open. You can also use a right button click to stop placing fiducials when in persistent mode.

The Markups module can convert Annotation fiducials into Markups fiducials, and will offer the user the option of doing it automatically when the Markups GUI is entered. There is also a manual button under the Advanced tab.


{{documentation/{{documentation/version}}/module-section|Tutorials}}

N/A



== Panels ==

<gallery>
File:Markups-GUI-Collapsed.png | GUI
File:Markups-ModifyList.png | Select the active list, set visibility and lock flags, set uniform scale.
File:Markups-JumpSlices.png | Jump the 2D slice view windows to the coordinates of the highlighted markup.
File:Markups-ModifyMarkupsInList.png | Modify Markups in list: toggle visibility, selected, and lock flags, delete.
File:Markups-Table.png | Table showing the fiducials in the active Markups list
File:Markups-Advanced.png | Advanced panel: move markups up or down, add a markup, name format, convert annotation fiducials, display properties for the list of markups
File:Markups-DisplayProperties.png | Display properties, inside the Advaned panel, includes 2d projection settings.
File:Markups-MouseToolbar.png | Place Markup fiducials by setting the Mouse mode in the tool bar
</gallery>
{{documentation/{{documentation/version}}/module-section|Panels and their use}}

{{documentation/{{documentation/version}}/module-parametersdescription}}


{{documentation/{{documentation/version}}/module-section|Similar Modules}}

*[[Documentation/Nightly/Modules/Annotations | Annotations]] module is similar, and will be deprecated as the functionality is moved to the Markups module.
*[https://github.com/Slicer/Slicer/blob/master/Modules/Scripted/Endoscopy/Endoscopy.py#L303 Endoscopy module] uses fiducials


{{documentation/{{documentation/version}}/module-section|References}}

*[http://wiki.na-mic.org/Wiki/index.php/2013_Summer_Project_Week:MarkupsModuleSummer2013 Summer 2013 Project Week project page]
*[http://wiki.na-mic.org/Wiki/index.php/2013_Project_Week:MarkupsModule Winter 2013 Project Week project page]
*[http://wiki.na-mic.org/Wiki/index.php/2012_Summer_Project_Week:AnnotationModule Summer 2012 Project Week project page]


{{documentation/{{documentation/version}}/module-section|Information for Developers}}
{{documentation/{{documentation/version}}/module-developerinfo}}

== Python ==

=== Load From File ===

Markups fiducials can be loaded from file:

slicer.util.loadMarkupsFiducialList('/path/to/list/F.fcsv')

=== Adding Fiducials Programatically ===

Markups fiducials can be added to the currently active list from the python console by using the following module logic command:

slicer.modules.markups.logic().AddFiducial()

The command with no arguments will place a new fiducial at the origin. You can also pass it an initial location:

slicer.modules.markups.logic().AddFiducial(1.0, -2.0, 3.3)

=== Adding Fiducials via Mouse Clicks ===

You can also set the mouse mode into Markups fiducial placement by calling:

placeModePersistence = 1
slicer.modules.markups.logic().StartPlaceMode(placeModePersistence)

A lower level way to do this is via the selection and interaction nodes:
selectionNode = slicer.mrmlScene.GetNodeByID("vtkMRMLSelectionNodeSingleton")
selectionNode.SetReferenceActivePlaceNodeClassName("vtkMRMLMarkupsFiducialNode")
interactionNode = slicer.mrmlScene.GetNodeByID("vtkMRMLInteractionNodeSingleton")
placeModePersistence = 1
interactionNode.SetPlaceModePersistence(placeModePersistence)
# mode 1 is Place, can also be accessed via slicer.vtkMRMLInteractionNode().Place
interactionNode.SetCurrentInteractionMode(1)

If you want to interact with a specific fiducial list node, let's say "vtkMRMLMarkupsFiducialNode1", add the following line of code:
selectionNode.SetActivePlaceNodeID("vtkMRMLMarkupsFiducialNode1")

If you use the previous command with an ID that does not exist, Slicer will create a new vtkMRMLMarkupsFiducialNode with an ID of the form "vtkMRMLMarkupsFiducialNode#" where # is the last vtkMRMLMarkupsFiducialNode ID that already exists increased by one.

=== Access to Fiducial Properties ===

Each vtkMRMLMarkupsFiducialNode has a vector of points in it which can be accessed from python:

fidNode = getNode("vtkMRMLMarkupsFiducialNode1")
n = fidNode.AddFiducial(4.0, 5.5, -6.0)
fidNode.SetNthFiducialLabel(n, "new label")
# each markup is given a unique id which can be accessed from the superclass level
id1 = fidNode.GetNthMarkupID(n)
# manually set the position
fidNode.SetNthFiducialPosition(n, 6.0, 7.0, 8.0)
# set the label
fidNode.SetNthFiducialLabel(n, "New label")
# set the selected flag, only selected = 1 fiducials will be passed to CLIs
fidNode.SetNthFiducialSelected(n, 1)
# set the visibility flag
fidNode.SetNthFiducialVisibility(n, 0)

You can also look at the sample code in the [https://github.com/Slicer/Slicer/blob/master/Modules/Scripted/Endoscopy/Endoscopy.py#L287 Endoscopy module] to see how python is used to access fiducials from a scripted module.

=== VTK Widget access ===

The Markups 3D fiducial displayable manager can be accessed from python allowing debugging of the vtkSeedWidget:

lm = slicer.app.layoutManager()
td = lm.threeDWidget(0)
ms = vtk.vtkCollection()
td.getDisplayableManagers(ms)
for i in range(ms.GetNumberOfItems()):
m = ms.GetItemAsObject(i)
if m.GetClassName() == "vtkMRMLMarkupsFiducialDisplayableManager3D":
print i, m.GetClassName()
h = m.GetHelper()
seedWidget = h.GetWidget(fidNode)
seedRepresentation = seedWidget.GetSeedRepresentation()
handleRep2 = seedRepresentation.GetHandleRepresentation(2)
print handleRep2.GetDisplayPosition()
print handleRep2.GetWorldPosition()

== C++ ==

===Selection and Interaction===

For the selection and interaction nodes, make sure that you access the singleton nodes already in the scene (rather than making your own) via (caveat: this call works on displayable managers, you may have to go a different route to get at the application logic):
vtkMRMLApplicationLogic *mrmlAppLogic = this->GetMRMLApplicationLogic();
vtkMRMLInteractionNode *inode = mrmlAppLogic->GetInteractionNode();
vtkMRMLSelectionNode *snode = mrmlAppLogic->GetSelectionNode();
If you can't get at the mrml application logic, you can get the nodes from the scene:
vtkMRMLInteractionNode *interactionNode = vtkMRMLInteractionNode::SafeDownCast(this->GetMRMLScene()->GetNodeByID("vtkMRMLInteractionNodeSingleton"));

You can then call methods on the nodes or add your own event observers as in
vtkSlicerMarkupsModuleLogic::ObserveMRMLScene
You can see vtkSlicerMarkupsModuleLogic::ProcessMRMLNodesEvents to see how to respond to interaction node changes.

Slicer4/Base/QTGUI/qSlicerMouseModeToolBar.cxx has a lot of the code you'll need as well, with a slightly different way of getting at the mrml app logic to access the nodes.

The calls you need to make to switch into placing fiducials with the mouse are:
selectionNode->SetReferenceActivePlaceNodeClassName("vtkMRMLMarkupsFiducialNode");
interactionNode->SetCurrentInteractionMode(vtkMRMLInteractionNode::Place);
If you don't set PlaceModePersistence on the interaction node to 1, the mouse mode/current interaction mode will automatically go back to view transform after one fiducial has been placed, and you just need to reset the current interaction mode for future placing (the active place node class name and ID are persistent).

=== Programmatic Access to Fiducials ===

This section explains how to access fiducial nodes added into the scene by the user.

In your module's Logic class, overwrite SetMRMLSceneInternal to observe the NodeAddedEvent of the scene:
void vtkSlicerMYMODULEModuleLogic::SetMRMLSceneInternal(vtkMRMLScene * newScene)
{
vtkIntArray *events = vtkIntArray::New();
events->InsertNextValue(vtkMRMLScene::NodeAddedEvent);
// Optionally you can add more events here,
// such as vtkMRMLScene::NodeRemovedEvent
this->SetAndObserveMRMLSceneEventsInternal(newScene, events);
events->Delete();
}
Via the set and observe mrml scene macro, anytime a node is added into the scene, it will trigger the base Logic class method
[http://slicer.org/doc/html/classvtkMRMLAbstractLogic.html#a51fdf00ecfc18c1a1465d4bccb789ef1 vtkMRMLAbstractLogic::ProcessMRMLNodesEvents] which calls the virtual method <code>vtkMRMLAbstractLogic::OnMRMLSceneNodeAdded(vtkMRMLNode* node)</code>
Reimplement that method in your logic class:
void vtkSlicerMYMODULEModuleLogic::OnMRMLSceneNodeAdded(vtkMRMLNode* addedNode)
{
vtkMRMLMarkupsFiducialNode* fidNode =
vtkMRMLMarkupsFiducialNode::SafeDownCast(addedNode);
if (fidNode)
{
// here you write what you need to do when a
// fiducial node is added into the scene
}
}


{{documentation/{{documentation/version}}/module-footer}}

Documentation/4.3/Modules/Markups

2015-09-23T14:11:29Z

Fbudin: /* Adding Fiducials via Mouse Clicks */

<noinclude>{{documentation/versioncheck}}</noinclude>

{{documentation/{{documentation/version}}/module-header}}



{{documentation/{{documentation/version}}/module-section|Introduction and Acknowledgements}}
{{documentation/{{documentation/version}}/module-introduction-start|{{documentation/modulename}}}}
{{documentation/{{documentation/version}}/module-introduction-row}}
This work is part of the National Alliance for Medical Image Computing (NA-MIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Information on NA-MIC can be obtained from the [http://www.na-mic.org/ NA-MIC website]. 
Author: Nicole Aucoin, SPL, BWH 
Contact: Nicole Aucoin, <email>nicole@bwh.harvard.edu</email> 
{{documentation/{{documentation/version}}/module-introduction-row}}
{{documentation/{{documentation/version}}/module-introduction-logo-gallery
|{{collaborator|logo|spl}}|{{collaborator|longname|spl}}
}}
{{documentation/{{documentation/version}}/module-introduction-end}}


{{documentation/{{documentation/version}}/module-section|Module Description}}
This module is used to manage markups in Slicer.

It is based on the functionality in the Slicer 3.6 Fiducials module, with elements from the Slicer 4.2 Annotations module.

Currently, only fiducials are supported.

{{documentation/{{documentation/version}}/module-description}}

Development history can be found in the [[documentation/{{documentation/version}}/Modules/{{documentation/modulename}}#References|references]].


{{documentation/{{documentation/version}}/module-section|Use Cases}}

This module allows you to add new markups, edit markups in a list, delete markups and modify display properties of markups.

Markups can be passed to command line modules (CLIs) using the <pre>--point</pre> argument.

The Mouse mode tool bar can be used to place new markups by positioning the mouse and left clicking in the viewers. Once you are in Place mode and placing Markups fiducials, you can use the 'p' key to place a new fiducial while the Markups GUI is open. You can also use a right button click to stop placing fiducials when in persistent mode.

The Markups module can convert Annotation fiducials into Markups fiducials, and will offer the user the option of doing it automatically when the Markups GUI is entered. There is also a manual button under the Advanced tab.


{{documentation/{{documentation/version}}/module-section|Tutorials}}

N/A



== Panels ==

<gallery>
File:Markups-GUI-Collapsed.png | GUI
File:Markups-ModifyList.png | Select the active list, set visibility and lock flags, set uniform scale.
File:Markups-JumpSlices.png | Jump the 2D slice view windows to the coordinates of the highlighted markup.
File:Markups-ModifyMarkupsInList.png | Modify Markups in list: toggle visibility, selected, and lock flags, delete.
File:Markups-Table.png | Table showing the fiducials in the active Markups list
File:Markups-Advanced.png | Advanced panel: move markups up or down, add a markup, name format, convert annotation fiducials, display properties for the list of markups
File:Markups-DisplayProperties.png | Display properties, inside the Advaned panel, includes 2d projection settings.
File:Markups-MouseToolbar.png | Place Markup fiducials by setting the Mouse mode in the tool bar
</gallery>
{{documentation/{{documentation/version}}/module-section|Panels and their use}}

{{documentation/{{documentation/version}}/module-parametersdescription}}


{{documentation/{{documentation/version}}/module-section|Similar Modules}}

*[[Documentation/Nightly/Modules/Annotations | Annotations]] module is similar, and will be deprecated as the functionality is moved to the Markups module.
*[https://github.com/Slicer/Slicer/blob/master/Modules/Scripted/Endoscopy/Endoscopy.py#L303 Endoscopy module] uses fiducials


{{documentation/{{documentation/version}}/module-section|References}}

*[http://wiki.na-mic.org/Wiki/index.php/2013_Summer_Project_Week:MarkupsModuleSummer2013 Summer 2013 Project Week project page]
*[http://wiki.na-mic.org/Wiki/index.php/2013_Project_Week:MarkupsModule Winter 2013 Project Week project page]
*[http://wiki.na-mic.org/Wiki/index.php/2012_Summer_Project_Week:AnnotationModule Summer 2012 Project Week project page]


{{documentation/{{documentation/version}}/module-section|Information for Developers}}
{{documentation/{{documentation/version}}/module-developerinfo}}

== Python ==

=== Load From File ===

Markups fiducials can be loaded from file:

slicer.util.loadMarkupsFiducialList('/path/to/list/F.fcsv')

=== Adding Fiducials Programatically ===

Markups fiducials can be added to the currently active list from the python console by using the following module logic command:

slicer.modules.markups.logic().AddFiducial()

The command with no arguments will place a new fiducial at the origin. You can also pass it an initial location:

slicer.modules.markups.logic().AddFiducial(1.0, -2.0, 3.3)

=== Adding Fiducials via Mouse Clicks ===

You can also set the mouse mode into Markups fiducial placement by calling:

placeModePersistence = 1
slicer.modules.markups.logic().StartPlaceMode(placeModePersistence)

A lower level way to do this is via the selection and interaction nodes:
selectionNode = slicer.mrmlScene.GetNodeByID("vtkMRMLSelectionNodeSingleton")
selectionNode.SetReferenceActivePlaceNodeClassName("vtkMRMLMarkupsFiducialNode")
interactionNode = slicer.mrmlScene.GetNodeByID("vtkMRMLInteractionNodeSingleton")
placeModePersistence = 1
interactionNode.SetPlaceModePersistence(placeModePersistence)
# mode 1 is Place, can also be accessed via slicer.vtkMRMLInteractionNode().Place
interactionNode.SetCurrentInteractionMode(1)

If you want to interact with a specific fiducial list node, add the following line of code:
selectionNode.SetActivePlaceNodeID({your_node_ID})

=== Access to Fiducial Properties ===

Each vtkMRMLMarkupsFiducialNode has a vector of points in it which can be accessed from python:

fidNode = getNode("vtkMRMLMarkupsFiducialNode1")
n = fidNode.AddFiducial(4.0, 5.5, -6.0)
fidNode.SetNthFiducialLabel(n, "new label")
# each markup is given a unique id which can be accessed from the superclass level
id1 = fidNode.GetNthMarkupID(n)
# manually set the position
fidNode.SetNthFiducialPosition(n, 6.0, 7.0, 8.0)
# set the label
fidNode.SetNthFiducialLabel(n, "New label")
# set the selected flag, only selected = 1 fiducials will be passed to CLIs
fidNode.SetNthFiducialSelected(n, 1)
# set the visibility flag
fidNode.SetNthFiducialVisibility(n, 0)

You can also look at the sample code in the [https://github.com/Slicer/Slicer/blob/master/Modules/Scripted/Endoscopy/Endoscopy.py#L287 Endoscopy module] to see how python is used to access fiducials from a scripted module.

=== VTK Widget access ===

The Markups 3D fiducial displayable manager can be accessed from python allowing debugging of the vtkSeedWidget:

lm = slicer.app.layoutManager()
td = lm.threeDWidget(0)
ms = vtk.vtkCollection()
td.getDisplayableManagers(ms)
for i in range(ms.GetNumberOfItems()):
m = ms.GetItemAsObject(i)
if m.GetClassName() == "vtkMRMLMarkupsFiducialDisplayableManager3D":
print i, m.GetClassName()
h = m.GetHelper()
seedWidget = h.GetWidget(fidNode)
seedRepresentation = seedWidget.GetSeedRepresentation()
handleRep2 = seedRepresentation.GetHandleRepresentation(2)
print handleRep2.GetDisplayPosition()
print handleRep2.GetWorldPosition()

== C++ ==

===Selection and Interaction===

For the selection and interaction nodes, make sure that you access the singleton nodes already in the scene (rather than making your own) via (caveat: this call works on displayable managers, you may have to go a different route to get at the application logic):
vtkMRMLApplicationLogic *mrmlAppLogic = this->GetMRMLApplicationLogic();
vtkMRMLInteractionNode *inode = mrmlAppLogic->GetInteractionNode();
vtkMRMLSelectionNode *snode = mrmlAppLogic->GetSelectionNode();
If you can't get at the mrml application logic, you can get the nodes from the scene:
vtkMRMLInteractionNode *interactionNode = vtkMRMLInteractionNode::SafeDownCast(this->GetMRMLScene()->GetNodeByID("vtkMRMLInteractionNodeSingleton"));

You can then call methods on the nodes or add your own event observers as in
vtkSlicerMarkupsModuleLogic::ObserveMRMLScene
You can see vtkSlicerMarkupsModuleLogic::ProcessMRMLNodesEvents to see how to respond to interaction node changes.

Slicer4/Base/QTGUI/qSlicerMouseModeToolBar.cxx has a lot of the code you'll need as well, with a slightly different way of getting at the mrml app logic to access the nodes.

The calls you need to make to switch into placing fiducials with the mouse are:
selectionNode->SetReferenceActivePlaceNodeClassName("vtkMRMLMarkupsFiducialNode");
interactionNode->SetCurrentInteractionMode(vtkMRMLInteractionNode::Place);
If you don't set PlaceModePersistence on the interaction node to 1, the mouse mode/current interaction mode will automatically go back to view transform after one fiducial has been placed, and you just need to reset the current interaction mode for future placing (the active place node class name and ID are persistent).

=== Programmatic Access to Fiducials ===

This section explains how to access fiducial nodes added into the scene by the user.

In your module's Logic class, overwrite SetMRMLSceneInternal to observe the NodeAddedEvent of the scene:
void vtkSlicerMYMODULEModuleLogic::SetMRMLSceneInternal(vtkMRMLScene * newScene)
{
vtkIntArray *events = vtkIntArray::New();
events->InsertNextValue(vtkMRMLScene::NodeAddedEvent);
// Optionally you can add more events here,
// such as vtkMRMLScene::NodeRemovedEvent
this->SetAndObserveMRMLSceneEventsInternal(newScene, events);
events->Delete();
}
Via the set and observe mrml scene macro, anytime a node is added into the scene, it will trigger the base Logic class method
[http://slicer.org/doc/html/classvtkMRMLAbstractLogic.html#a51fdf00ecfc18c1a1465d4bccb789ef1 vtkMRMLAbstractLogic::ProcessMRMLNodesEvents] which calls the virtual method <code>vtkMRMLAbstractLogic::OnMRMLSceneNodeAdded(vtkMRMLNode* node)</code>
Reimplement that method in your logic class:
void vtkSlicerMYMODULEModuleLogic::OnMRMLSceneNodeAdded(vtkMRMLNode* addedNode)
{
vtkMRMLMarkupsFiducialNode* fidNode =
vtkMRMLMarkupsFiducialNode::SafeDownCast(addedNode);
if (fidNode)
{
// here you write what you need to do when a
// fiducial node is added into the scene
}
}


{{documentation/{{documentation/version}}/module-footer}}

Documentation/Labs/SlicerConfigAndUseSlicerTweaks

2015-09-06T23:24:06Z

Fbudin: /* Use-cases */

== Overview ==

This page describes possible improvements to the SlicerConfig.cmake and UseSlicer.cmake files. These files are used when calling:

<pre>
find_package(Slicer REQUIRED)
include(${Slicer_USE_FILE})
</pre>

The idea is to re-factor these files to avoid extension developers to implement clever work around and hacks for their use-cases, and facilitate overall maintenance.

== Use-cases ==

=== SPHARM-PDM ===

Extension: https://github.com/NIRALUser/SPHARM-PDM/blob/master/SuperBuild.cmake

The goal is to re-use only the Slicer packaging macros without having the external projects built by Slicer included in the extension.

The Slicer extension projects are not needed by the extension because it builds a static version of these projects.

Additional improvement: One may want to include some of the Slicer libraries (e.g. VTK) but may want to compile a specific version of other libraries that are provided by Slicer (e.g. ITK). Currently, it is complicated to do this operation: one needs to unset and reset variables (e.g. ITK_DIR) since Slicer requires that certain variables are set to certain values (to the value these variables have in the built tree of Slicer). One possible improvement would be to make optional the inclusion of the external libraries Slicer builds.

Documentation/Nightly/Developers/FAQ/Extensions

2015-08-11T19:04:40Z

Fbudin: /* How to package an extension ? */

<noinclude>{{documentation/versioncheck}}</noinclude>
<noinclude>__TOC__
={{#titleparts: {{PAGENAME}} | | -1 }}=</noinclude><includeonly>
='''Developer FAQ: {{{1}}}'''=
</includeonly>

{{:Documentation/{{documentation/version}}/FAQ/Extensions}}

== What is an extension description file ? ==

See [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|Description file description]]

== Can an extension contain different types of modules ? ==

Yes. Extensions are used to package together all types of Slicer modules.

See also [[Documentation/{{documentation/version}}/Developers/FAQ#What_is_an_extension_.3F|What_is_an_extension ?]]

== Should the name of the source repository match the name of the extension ? ==

Assuming your extension is named <code>AwesomeFilter</code>, generally, we suggest to name the extension repository either <code>SlicerAwesomeFilter</code>, <code>Slicer-AwesomeFilter</code>, <code>Slicer_AwesomeFilter</code>, <code>SlicerExtension-AwesomeFilter</code>, <code>SlicerExtension_AwesomeFilter</code>.

Doing so will minimize confusion by clearly stating that the code base is associated with Slicer.

== What is the Extensions Index ? ==

{{:Documentation/{{documentation/version}}/Developers/Extensions/Index}}

== What is an API Key ? ==

See http://en.wikipedia.org/wiki/Application_programming_interface_key

== How to obtain an API key to submit on the extension server ? ==
{{:Documentation/{{documentation/version}}/Developers/Tutorials/ObtainExtensionServerApiKey}}

== How to cache API credentials ? ==

There is now a new feature that allow you to "cache" your credential [1]. If you set the two environment variables, <code>MIDAS_PACKAGE_EMAIL</code> and <code>MIDAS_PACKAGE_API_KEY</code>, you would simply need to configure your extension using:

{{pre2|<nowiki>
cd MyExtension-build
cmake -DCMAKE_BUILD_TYPE:STRING=Release -DSlicer_DIR:PATH=/path/to/Slicer-Superbuild/Slicer-build ../MyExtension
make ExperimentalUpload
</nowiki>}}

[1] http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=22457

== Where can I find the extension templates ? ==

The module and extension templates are available in the Slicer source tree: https://github.com/Slicer/Slicer/tree/master/Utilities/Templates/

Using the [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|Extension Wizard]], you could easily create a new extension without having to copy, rename and update manually every files.

== How to build an extension ? ==

Assuming that the source code of your extension is located in folder <code>MyExtension</code>, this could be achieved doing:

{|width = "100%"
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Makefile
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Visual Studio
|-
| valign="top" |
{{pre2|<nowiki>
$ mkdir MyExtension-build
$ cd MyExtension-build
$ cmake -DCMAKE_BUILD_TYPE:STRING=Release -DSlicer_DIR:PATH=/path/to/Slicer-Superbuild/Slicer-build ../MyExtension
$ make</nowiki>
}}
| valign="top" |
<ol start="1" style="list-style-type: decimal;">
<li>Start CMake, select source and build directory</li>
<li>Add <code>Slicer_DIR</code> entry to the cache</li>
<li>Click on <code>Configure</code>, select generator, then click on <code>Generate</code> button.</li>
<li>Open <code>MyExtension.sln</code>, select <code>Release</code> configuration, then menu <code>Project -> Build Solution</code>.</li>
</ol>
|}

== How to package an extension ? ==

Assuming your extension has been built into folder <code>MyExtension-build</code>, this could be achieved doing:

{|width = "100%"
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Makefile
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Visual Studio
|-
| valign="top" |
{{pre2|<nowiki>
$ make package
</nowiki>
}}
| valign="top" |
<ol start="1" style="list-style-type: decimal;">
<li>Open <code>MyExtension.sln</code></li>
<li>Select <code>PACKAGES</code> project, then right click and select <code>Build</code></li>
</ol>
|}

== How are Superbuild extension packaged ? ==

Extensions using the Superbuild mechanism build projects in two steps:
* First, the project dependencies are built in an outer-build directory.
* Then, the project itself is built in an inner-build directory

Extensions can use the Superbuild mechanism. However, developers have to be careful that the packaging macros clean the project before reconfiguring it. This means that if ones uses the Slicer extension packaging macros inside the inner-build directory, when packaging and uploading the extension package, the project will be reconfigured, and variables passed from the outer-build directory will be lost. If the project only depends on libraries that Slicer builds, this is not an issue. If the project has specific dependencies that Slicer does not compile on its own, the developer should be careful to instantiate the Slicer extension packaging macros only in the outer-build directory. This only means that in the latter case, tests should be instantiated in the outer-build directory to allow the Slicer extension building process to test the extension before uploading the extension and the tests results.

== How to upload an extension ? ==

<ol style="list-style-type:none; border-left:thick solid red; padding-left:1em;">
<li>{{:Documentation/{{documentation/version}}/Developers/Tutorials/BuildTestPackageDistributeExtensions/ExperimentalFolderAccess}}</li>
</ol>

Assuming your extension has been built and packaged into folder <code>MyExtension-build</code>, this could be achieved by first re-configuring the project providing your [[#How_to_obtain_an_API_key_to_submit_on_the_extension_server_.3F|midas credentials]] and then building the <code>ExperimentalUploadOnly</code> target:

{|width = "100%"
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Makefile
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Visual Studio
|-
| valign="top" |
{{pre2|<nowiki>
$ cmake -DMIDAS_PACKAGE_EMAIL:STRING=<YOUR-MIDAS-LOGIN> -DMIDAS_PACKAGE_API_KEY:STRING=<YOUR-MIDAS-APIKEY> .
$ make ExperimentalUploadOnly
</nowiki>
}}
| valign="top" |
<ol start="1" style="list-style-type: decimal;">
<li>Start CMake, select source and build directory</li>
<li>Add <code>MIDAS_PACKAGE_EMAIL</code> and <code>MIDAS_PACKAGE_API_KEY</code> entries to the cache</li>
<li>Open <code>MyExtension.sln</code></li>
<li>Select <code>Release</code> configuration</li>
<li>Select <code>ExperimentalUploadOnly</code> project, then right click and select <code>Build</code></li>
</ol>
|}

== Can an extension depend on other extensions ? ==

Yes. An <code>ExtensionFoo</code> can depend on <code>ExtensionBar</code>

The dependency should be specified as a list by setting the variable <code>EXTENSION_DEPENDS</code> in the extension <code>CMakeLists.txt</code>.

For example, if you have <code>ModuleA</code>, <code>ModuleB</code> and <code>ModuleC</code> and <code>ModuleA</code> can be used as standalone one. You could create the following extensions:

* <code>Extension1</code> containing <code>ModuleA</code>
* <code>Extension2</code> containing <code>ModuleB</code> and <code>ModuleC</code>

and add the following variable to <code>Extension2/CMakeLists.txt</code>:
<pre>
set(EXTENSION_DEPENDS Extension1)
</pre>

'''User''':
* If user installs <code>Extension2</code>, <code>Extension1</code> will automatically be installed first.

'''Developer''':
* The generated extension description file have a <code>depends</code> field. See [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|here]] for details.
* The extension framework will build the extension in order. When building <code>Extension2</code>, it will pass the CMake option <code>-DExtension1_DIR:PATH=/path/to/Extension1-build</code>.

== What are the extension specific targets: ExperimentalUpload, ExperimentalUploadOnly, ... ? ==

Slicer extension build system provides the developer with a set of convenient targets allowing to build and upload extensions.

<table class="alternate">
<tr>
<th>Target name</th>
<th>Description</th>
</tr>
<tr>
<td><code>Experimental</code></td>
<td>Configure, build, test the extension and publish result on CDash.</td>
</tr>
<tr>
<td><code>ExperimentalUpload</code></td>
<td>Equivalent to Experimental target followed by packaging and upload of the extension on the extension server.</td>
</tr>
<tr>
<td><code>ExperimentalUploadOnly</code></td>
<td>Only proceed to the upload of the extension on the extension server.</td>
</tr>
<tr>
<td><code>test</code> or <code>BUILD_TESTS</code></td>
<td>Locally execute the test</td>
</tr>
<tr>
<td><code>package</code> or <code>PACKAGE</code></td>
<td>Locally package the extension</td>
</tr>
</table>

== Is --launch flag available for a MacOSX installed Slicer.app ?==

On MacOSx, running Slicer with the --help argument does NOT list the usual launcher related options.

$ ./Slicer.app/Contents/MacOS/Slicer --help
Usage
Slicer [options]

Options
--, --ignore-rest Ignores the rest of the labeled arguments following this flag. (default: false)
-h, --help Display available command line arguments.
[...]
--version Displays version information and exits.

To provide some background information, when generating the package that will be distributed, an application bundle <code>Slicer.app</code> is created. As explained [http://developer.apple.com/library/mac/#documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html here], a bundle is a directory with a standardized hierarchical structure that holds executable code and the resources used by that code. It means that since all libraries contained within a bundle are referenced relatively to the location of either the CLI or the Slicer executable, the use of launcher does NOT make sens.

To help fixing-up the libraries, executables and plugins so that they reference each other in a relative way, CMake provides us with the [http://www.cmake.org/cmake/help/v2.8.8/cmake.html#module:BundleUtilities BundleUtilities] module.

This module is used in two situations:
# Fixup of Slicer application itself. See [https://github.com/Slicer/Slicer/blob/master/CMake/SlicerCPack.cmake#L36-68 SlicerCPack.cmake#L36-68] and [https://github.com/Slicer/Slicer/blob/master/CMake/SlicerCPackBundleFixup.cmake.in SlicerCPackBundleFixup.cmake.in]
# Fixup of an extension package. See [https://github.com/Slicer/Slicer/blob/master/CMake/SlicerExtensionCPack.cmake#L126-143 SlicerExtensionCPack.cmake#L126-143] and [https://github.com/Slicer/Slicer/blob/master/CMake/SlicerExtensionCPackBundleFixup.cmake.in SlicerExtensionCPackBundleFixup.cmake.in]

== What is the difference between Documentation/Nightly/Modules and Documentation/Nightly/Extensions ? ==

As suggested by the namespace names:
* All module documentation pages should be located under <code>Documentation/Nightly/Modules</code>
* All extension documentation pages should be located under <code>Documentation/Nightly/Extensions</code>

For example, if an an extension named <code>DoSomethingGreat</code> bundles three modules <code>ModuleA</code>, <code>ModuleB</code> and <code>ModuleC</code>. The following pages should be created:
* <code>Documentation/Nightly/Extensions/DoSomethingGreat</code>
* <code>Documentation/Nightly/Modules/ModuleA</code>
* <code>Documentation/Nightly/Modules/ModuleB</code>
* <code>Documentation/Nightly/Modules/ModuleC</code>

In case your extension bundles only one module, the extension name is expected to match the module name. For example, if your extension is named <code>DoSomethingAwesome</code>, the associated module is expected to be named <code>DoSomethingAwesome</code>. The following pages will then be created:
* <code>Documentation/Nightly/Extensions/DoSomethingAwesome</code>
* <code>Documentation/Nightly/Modules/DoSomethingAwesome</code>
where page <code>Extensions/DoSomethingAwesome</code> redirect to page <code>Modules/DoSomethingAwesome</code>.

To setup a redirection, simply add the following text to page <code>Extensions/DoSomethingAwesome</code>:
<pre>
#REDIRECT [[Documentation/Nightly/Modules/DoSomethingAwesome]]
</pre>
For an example, see [http://www.slicer.org/slicerWiki/index.php?title=Documentation/Nightly/Extensions/SkullStripper&action=edit here]

More details about redirection are available here: http://www.mediawiki.org/wiki/Help:Redirects

== Which URL should be associated with EXTENSION_HOMEPAGE metadata ? ==

Extensions available through the Slicer Extensions Catalog are expected to have a page created under the <code>Nightly</code> documentation namespace. The corresponding URL should be associated with the <code>EXTENSION_HOMEPAGE</code> metadata.

For example:
* <code><nowiki>set(EXTENSION_HOMEPAGE "http://slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/DoSomethingGreat")</nowiki></code>
* <code><nowiki>set(EXTENSION_HOMEPAGE "http://slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/DoSomethingAwesome")</nowiki></code>

Note that this also apply for extension bundling only one module. Indeed, in this case the page will redirect to the appropriate module page. For example: http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/SkullStripper

== How to rename an extension to add new features ? ==

If you created an extension to perform Task1, but later on, your module is getting more generic and you add some other tasks, the name of your extension might change.
In order to rename, your extension, you should:
* Remove your old extension from the ExtensionsIndex
* Then, submit your extension again (including new features) with a new name
* Make also sure to add redirection from the "deprecated" module documentation to the "new" pages. On the Slicer wiki, this could be using the [http://www.mediawiki.org/wiki/Help:Redirects #REDIRECT] instruction.

== How to check if an extension is built by Slicer Extensions build system ? ==

Sometimes an extension could be built either as a standalone package or as a Slicer extension.

To differenciate the two cases, the developer could check for the value of:
<pre>
<ExtensionName>_BUILD_SLICER_EXTENSION
</pre>

This variable will be set to ON when the extension is built by the Slicer Extensions build system.

For details: https://github.com/Slicer/Slicer/blob/ff5f5a866d8afcaa0f2e6f615cc8f8cf07361741/Extensions/CMake/SlicerBlockBuildPackageAndUploadExtension.cmake#L95

== How often extensions are uploaded on the extensions server ? ==

Slicer extensions are built and uploaded on the [[Documentation/{{documentation/version}}/Developers/Extensions/Server|extensions server]] every day.

To be more specific, the frequency of extensions build and upload associated with:
* Slicer nightly package occurs '''every night''' and also '''continuously''' during the day.
* Slicer {{documentation/currentversion}} lastest stable release package occurs '''every night'''.

== Will an extension be uploaded if associated tests are failing ? ==

Independently of the extension test results, if the extension could be successfully packaged, it will be uploaded on the [[Documentation/{{documentation/version}}/Developers/Extensions/Server|extensions server]].

== How do I associate a remote with my local extension git source directory ? ==

1) Start a terminal (or Git Bash on Windows)

2) Get the associated SSH remote url. [https://help.github.com/articles/which-remote-url-should-i-use#cloning-with-ssh Need help ?]

3) Associate the remote URL with your local git source tree

<pre>
git remote add origin git://github.com/<username>/MyExtension
</pre>

== Which remote name is expected for extension git checkout ? ==

When packaging an extension and generating the associated [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|description file]], the system will look for a remote named <code>origin</code>.

In case you get the error reported below, you will have to either rename or add a remote. [http://git-scm.com/book/en/Git-Basics-Working-with-Remotes Need help ?]

<pre>
CMake Warning at /path/to/Slicer/CMake/FindGit.cmake:144 (message):
No remote origin set for git repository: /path/to/MyExtension
Call Stack (most recent call first):
/path/to/Slicer/CMake/SlicerMacroExtractRepositoryInfo.cmake:99 (GIT_WC_INFO)
/path/to/Slicer/CMake/SlicerExtensionCPack.cmake:55 (SlicerMacroExtractRepositoryInfo)
CMakeLists.txt:25 (include)
</pre>

== Why ExtensionWizard failed to describe extension: "script does not set 'EXTENSION_HOMEPAGE'" ? ==

The issue is that the your extension has a "non standard" layout and the wizard was now way of extracting the expected information.

Similar issue has been discussed and reported for the "SPHARM-PDM" or UKF extension.

First half of the solution would be to move the metadata from Common.cmake to CMakeLists.txt as it is done in [1]

Then, you could make sure there is a project() statement by following what is suggested in [2]

If you prefer not to re-organize your extension, you could still contribute extension description file. See [[Documentation/{{documentation/version}}/Developers/Tutorials/Contribute_Extension_Description_File|here]] for details.

[1] http://www.nitrc.org/plugins/scmsvn/viewcvs.php?view=rev&root=spharm-pdm&revision=228

[2] http://www.na-mic.org/Bug/view.php?id=3737#c12081

== Is project() statement allowed in extension CMakeLists.txt ? ==

Following Slicer [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=22038 r22038], the project statement is required.

== Is call to "if(NOT Slicer_SOURCE_DIR)" required to protect "find_package(Slicer)" in extension CMakeLists.txt ? ==

Following Slicer [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=22063 r22063], protecting call to <code>find_package(Slicer)</code> with <code>if(NOT Slicer_SOURCE_DIR)</code>
is optional and should be removed to keep code simpler and easier to maintain.

Before:

{{pre2|<nowiki>
cmake_minimum_required(VERSION 2.8.9)

if(NOT Slicer_SOURCE_DIR)
find_package(Slicer COMPONENTS ConfigurePrerequisites)
endif()

if(NOT Slicer_SOURCE_DIR)
set(EXTENSION_NAME EmptyExtensionTemplate)
set(EXTENSION_HOMEPAGE "http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/EmptyExtensionTemplate")
set(EXTENSION_CATEGORY "Examples")
set(EXTENSION_CONTRIBUTORS "Jean-Christophe Fillion-Robin (Kitware)")
set(EXTENSION_DESCRIPTION "This is an example of extension bundling N module(s)")
set(EXTENSION_ICONURL "http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Extensions/Testing/EmptyExtensionTemplate/EmptyExtensionTemplate.png?revision=21746&view=co")
set(EXTENSION_SCREENSHOTURLS "http://wiki.slicer.org/slicerWiki/images/4/42/Slicer-r19441-EmptyExtensionTemplate-screenshot.png")
endif()

if(NOT Slicer_SOURCE_DIR)
find_package(Slicer REQUIRED)
include(${Slicer_USE_FILE})
endif()

add_subdirectory(ModuleA)

if(NOT Slicer_SOURCE_DIR)
include(${Slicer_EXTENSION_CPACK})
endif()
</nowiki>}}

After:

{{pre2|<nowiki>
cmake_minimum_required(VERSION 2.8.9)

find_package(Slicer COMPONENTS ConfigurePrerequisites)

project(EmptyExtensionTemplate)

set(EXTENSION_HOMEPAGE "http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/EmptyExtensionTemplate")
set(EXTENSION_CATEGORY "Examples")
set(EXTENSION_CONTRIBUTORS "Jean-Christophe Fillion-Robin (Kitware)")
set(EXTENSION_DESCRIPTION "This is an example of empty extension")
set(EXTENSION_ICONURL "http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Extensions/Testing/EmptyExtensionTemplate/EmptyExtensionTemplate.png?revision=21746&view=co")
set(EXTENSION_SCREENSHOTURLS "http://wiki.slicer.org/slicerWiki/images/4/42/Slicer-r19441-EmptyExtensionTemplate-screenshot.png")

find_package(Slicer REQUIRED)
include(${Slicer_USE_FILE})

add_subdirectory(ModuleA)

include(${Slicer_EXTENSION_CPACK})
</nowiki>}}

== Why is the --contribute option is not available with the ExtensionWizard ? ==

Wizard contribute option is available only (1) if Slicer is built with OpenSSL support or (2) directly from the nightly.

To build Slicer with SSL support, you need to build (or download) Qt with SSL support and configure Slicer with <code>-DSlicer_USE_PYTHONQT_WITH_OPENSSL:BOOL=ON</code>

== How dependent extensions are configured and built ? ==

If an ExtensionB depends on an ExtensionA, ExtensionA should be listed as dependency in the metadata of ExtensionB.

This can be done setting <code>EXTENSION_DEPENDS</code> in the <code>CMakeLists.txt</code> or by specifying <code>depends</code> field in the [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|description file]].

Doing so will ensure that:
* (1) the extension build system configure the extensions in the right order
* (2) ExtensionB is configured with option <code>ExtensionA_DIR</code>.

Documentation/Nightly/FAQ/Extensions

2015-08-11T18:50:25Z

Documentation/Nightly/Extensions/ResampleDTIlogEuclidean

2015-06-12T16:26:40Z

Fbudin:

<noinclude>{{documentation/versioncheck}}</noinclude>

{{documentation/{{documentation/version}}/module-header}}



{{documentation/{{documentation/version}}/module-section|Introduction and Acknowledgements}}
{{documentation/{{documentation/version}}/module-introduction-start|{{documentation/modulename}}}}
{{documentation/{{documentation/version}}/module-introduction-row}}
Extension: [[Documentation/{{documentation/version}}/Extensions/ResampleDTIlogEuclidean|ResampleDTIlogEuclidean]] 
Acknowledgments:
This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. 
ResampleDTIlogEuclidean resamples Diffusion Tensor Images (DTI) in the log-euclidean framework. 
Author: Francois Budin ({{collaborator|name|niral}}) 
Contributor1: Sylvain Bouix ({{collaborator|name|pnl}}) 
Contact: Francois Budin, <email>fbudin@unc.edu</email> 
Website: https://github.com/NIRALUser/ResampleDTIlogEuclidean 
License: [http://www.apache.org/licenses/LICENSE-2.0 Apache License v2.0] 
{{documentation/{{documentation/version}}/module-introduction-row}}
{{documentation/{{documentation/version}}/module-introduction-logo-gallery
|{{collaborator|logo|niral}}|{{collaborator|longname|niral}}
|{{collaborator|logo|unc}}|{{collaborator|longname|unc}}
|{{collaborator|logo|namic}}|{{collaborator|longname|namic}}
}}

{{documentation/{{documentation/version}}/module-introduction-end}}


{{documentation/{{documentation/version}}/module-section|Module Description}}

ResampleDTIlogEuclidean resamples Diffusion Tensor Images (DTI) in the log-euclidean framework. It is an improved version of [[Documentation/{{documentation/version}}/Modules/ResampleDTIVolume|ResampleDTIVolume]] performing the resampling in the log-euclidean space [1]. The Diffusion Tensor images transformation classes are based on algorithms described by D.C. Alexander et al [2]. More information is available in the [http://www.insight-journal.org/browse/publication/742 Insight Journal]


{{documentation/{{documentation/version}}/module-section|Use Cases}}
{|
|[[Image:ResampleDTI-Slice extracted from a real Diffusion Tensor Image - No transformation.png|thumb|340px|Input Diffusion Tensor Image (DTI)]]
|[[Image:ResampleDTI-Real DTI transformed with a 45deg rotation - Linear interpolation.png|thumb|340px|Real DTI transformed with a 45 degrees rotation - Linear interpolation]]
|[[Image:ResampleDTI-Real DTI upscaled with a factor 2 - Linear interpolation.png|thumb|375px|Real DTI upscaled with a factor 2 - Linear interpolation]]
|}


{{documentation/{{documentation/version}}/module-section|Tutorials}}


{{documentation/{{documentation/version}}/module-section|Panels and their use}}

{|
|
|[[Image:ResampleDTIlogEuclidean-panel.png|thumb|280px|Module UI]]
|}

===Quick Tour of Features and Use===

* '''Input/Output:''' Defines input and output files.
** ''Input volume'' is the volume to resample,
** ''Reference Volume'' (optional) is the volume used to set the sampling parameters (origin, spacing, orientation and dimensions). If it is not set, the input volume will be taken for reference.
** ''Output volume'' is the name of the output.
* '''Deformation Field:''' Allows the user to transform the input image using a deformation field. The deformation field is applied last in the case other transforms are given.
** ''Displacement or H- field'' sets the type of deformation field. An H-field contains at each voxel the position in space of the transformed point. The displacement field contains at each voxel the displacement vector to apply to this point.
** ''Deformation Field Volume'' sets the deformation field. It should be a 3-Dimensional vector image. Vectors should be of dimension 3.
* '''Resampling Parameters:'''
** ''Number Of Threads'' sets the number of threads used to perform the resampling.
** ''Correction'' sets if a filter is applied on the resampled image to ensure that every tensor is positive definite symmetric. Three filters are available: set to zero the negative eigen values, take their absolute values or compute their closest positive definite symmetric matrix.
* '''Transform Parameters:'''
** ''Transform Node'' contains the transform(s) to apply to the image
** ''Transforms Order'' allows the user to tell the module in what order the transforms are stored in the node (or file). Transforms should be backward (from output space to input space). However, in Slicer3, the affine and rigid transform nodes are stored as forward transforms and are inverted when passed to the module.
Input Image <- Transform0 <- Transform1 <- ... <- Transform n <- Output Image (input-to-output)
Input Image <- Transform n <- Transform n-1 <- ... <- Transform0 <- Output Image (output-to-input)
* '''Manual Transform:''' if no tranform is set in previous panel, one can enter his own transform
** ''Transform Matrix:'' a 12-parameter affine transformation manually. The first 9 numbers represent a linear transformation matrix in column-major order (where the column index varies the fastest), the last 3 are a translation.
** ''Transform:'' forces the transform to be of rigid or affine type (affine is default)
** ''Space:'' It should normally not be modified when using this module directly in Slicer3 with a transform node. It does not specify whether the matrix is expressed in LPS or RAS coordinate space but rather if everything is expressed in the same coordinate space. LPS means that everything is in the same space and RAS means that it is not the case. This option can be set to RAS if the given transform is in RAS coordinate space (respectively LPS) and the input volume is in LPS coordinate space (respectively RAS). '''Be careful''': When passing manually the transform, the coordinate space modification is directly applied on the given transform. However, when passing the transform through a file or a transform node, it is the input volume coordinate space that is modified and the transform is left unchanged (so that any kind of transform supported by ITK is also supported by this module). If one sets the output volume parameters manually, one has to pay attention to the fact that in that case the given parameters are considered to be in the transform coordinate space!!!
* '''Rigid/Affine Parameters:'''
** ''Rotation Point:'' uses a fiducial to set a point around which the rotation defined in the transform needs to be performed.
** ''Centered Transform:'' sets the center of the transformation to the center of the image.
** ''Inverse ITK Transformation:'' inverses the transformation before applying it to the image. The transform given to the module is from the output image to the input one. If one wants to specify a transform from the input image to the output image, one should use this flag. This option can only be used if the transform is rigid or affine. Be careful: if the file containing the transform contains multiple transforms, only rigid and affine transforms will be inverted.
* '''Affine Transformation Type:''' Uses the Preservation of the Principal Direction (right image) to compute the affine transform. Otherwise, the Finite Strain Method (left image) is used [[#References|[1] ]].

{|
|[[Image:320px-Plan2dyz-skew-noppd-vertical.jpg|thumb|250px|Finite Strain]]
|[[Image:320px-Plan2dyz-skew-ppd-vertical.jpg|thumb|250px|Preservation Of Principal Direction]]
|}

* '''Interpolation Type:''' sets the type of interpolation kernel to either linear, nearest neighbor (nn), windowed sinc (ws), or b-spline (bs). The windowed sinc interpolator uses a constant boundary condition whereas the b-spline interpolator uses a mirror boundary condition.
* '''Windowed Sinc Interpolate Function Parameters:''' selects the type window function for the sinc interpolation h=hamming, c=cosine, w=welch, l=lanczos, b=blackman. '''This is only relevant if one selects ws as the interpolation type'''.
* '''BSpline Interpolate Function Parameters:''' The spline order (only relevant if the selected interpolator is bs).
* '''Output Parameters:''' One can overwrite the reference volume parameters by setting manually the ''spacing'', ''size'', ''origin'' (as a fiducial), and ''direction matrix'' (also known as space directions) in column-major order.


{{documentation/{{documentation/version}}/module-section|Similar Modules}}


{{documentation/{{documentation/version}}/module-section|References}}
* [1] Arsigny, V., Fillard, P., Pennec, X. and Ayache, N. (2006), Log-Euclidean metrics for fast and simple calculus on diffusion tensors. Magn Reson Med, 56: 411–421. doi: 10.1002/mrm.20965
* [2] D.C. Alexander, C. Pierpaoli, P.J. Basser, J.C. Gee. Spatial Transformations of Diffusion Tensor Magnetic Resonance Images, IEEE Transactions on medical imaging, vol. 20, No. 11, November 2001


{{documentation/{{documentation/version}}/module-section|Information for Developers}}
The source code of ResampleDTIlogEuclidean is available on [https://github.com/NIRALUser/ResampleDTIlogEuclidean GitHub]. It is published under an [http://www.apache.org/licenses/LICENSE-2.0 Apache License v2.0]. 
{|
|
|[[Image:ResampleDTIlogEuclidean-128x128-icon.png|thumb|128px|Extension Icon]]
|}

{{documentation/{{documentation/version}}/module-footer}}
[[Category:Documentation/{{documentation/version}}/Modules/Segmentation]]

Documentation/Nightly/Extensions/ResampleDTIlogEuclidean

2015-06-12T16:24:41Z

Fbudin:

<noinclude>{{documentation/versioncheck}}</noinclude>

{{documentation/{{documentation/version}}/module-header}}



{{documentation/{{documentation/version}}/module-section|Introduction and Acknowledgements}}
{{documentation/{{documentation/version}}/module-introduction-start|{{documentation/modulename}}}}
{{documentation/{{documentation/version}}/module-introduction-row}}
Extension: [[Documentation/{{documentation/version}}/Extensions/ResampleDTIlogEuclidean|ResampleDTIlogEuclidean]] 
Acknowledgments:
This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. 
ResampleDTIlogEuclidean resamples Diffusion Tensor Images (DTI) in the log-euclidean framework. 
Author: Francois Budin ({{collaborator|name|niral}}) 
Contributor1: Sylvain Bouix ({{collaborator|name|pnl}}) 
Contact: Francois Budin, <email>fbudin@unc.edu</email> 
Website: https://github.com/NIRALUser/ResampleDTIlogEuclidean 
License: [http://www.apache.org/licenses/LICENSE-2.0 Apache License v2.0] 
{{documentation/{{documentation/version}}/module-introduction-row}}
{{documentation/{{documentation/version}}/module-introduction-logo-gallery
|{{collaborator|logo|niral}}|{{collaborator|longname|niral}}
|{{collaborator|logo|unc}}|{{collaborator|longname|unc}}
|{{collaborator|logo|namic}}|{{collaborator|longname|namic}}
}}

{{documentation/{{documentation/version}}/module-introduction-end}}


{{documentation/{{documentation/version}}/module-section|Module Description}}

ResampleDTIlogEuclidean resamples Diffusion Tensor Images (DTI) in the log-euclidean framework. It is an improved version of [[Documentation/{{documentation/version}}/Modules/ResampleDTIVolume|ResampleDTIVolume]] performing the resampling in the log-euclidean space [1]. The Diffusion Tensor images transformation classes are based on algorithms described by D.C. Alexander et al [2]. More information is available in the [http://www.insight-journal.org/browse/publication/742 Insight Journal]


{{documentation/{{documentation/version}}/module-section|Use Cases}}
{|
|[[Image:ResampleDTI-Slice extracted from a real Diffusion Tensor Image - No transformation.png|thumb|340px|Input Diffusion Tensor Image (DTI)]]
|[[Image:ResampleDTI-Real DTI transformed with a 45deg rotation - Linear interpolation.png|thumb|340px|Real DTI transformed with a 45 degrees rotation - Linear interpolation]]
|[[Image:ResampleDTI-Real DTI upscaled with a factor 2 - Linear interpolation.png|thumb|375px|Real DTI upscaled with a factor 2 - Linear interpolation]]
|}


{{documentation/{{documentation/version}}/module-section|Tutorials}}


{{documentation/{{documentation/version}}/module-section|Panels and their use}}

{|
|
|[[Image:ResampleDTIlogEuclidean-panel.png|thumb|280px|Module UI]]
|}

===Quick Tour of Features and Use===

* '''Input/Output:''' Defines input and output files.
** ''Input volume'' is the volume to resample,
** ''Reference Volume'' (optional) is the volume used to set the sampling parameters (origin, spacing, orientation and dimensions). If it is not set, the input volume will be taken for reference.
** ''Output volume'' is the name of the output.
* '''Deformation Field:''' Allows the user to transform the input image using a deformation field. The deformation field is applied last in the case other transforms are given.
** ''Displacement or H- field'' sets the type of deformation field. An H-field contains at each voxel the position in space of the transformed point. The displacement field contains at each voxel the displacement vector to apply to this point.
** ''Deformation Field Volume'' sets the deformation field. It should be a 3-Dimensional vector image. Vectors should be of dimension 3.
* '''Resampling Parameters:'''
** ''Number Of Threads'' sets the number of threads used to perform the resampling.
** ''Correction'' sets if a filter is applied on the resampled image to ensure that every tensor is positive definite symmetric. Three filters are available: set to zero the negative eigen values, take their absolute values or compute their closest positive definite symmetric matrix.
* '''Transform Parameters:'''
** ''Transform Node'' contains the transform(s) to apply to the image
** ''Transforms Order'' allows the user to tell the module in what order the transforms are stored in the node (or file). Transforms should be backward (from output space to input space). However, in Slicer3, the affine and rigid transform nodes are stored as forward transforms and are inverted when passed to the module.
Input Image <- Transform0 <- Transform1 <- ... <- Transform n <- Output Image (input-to-output)
Input Image <- Transform n <- Transform n-1 <- ... <- Transform0 <- Output Image (output-to-input)
* '''Manual Transform:''' if no tranform is set in previous panel, one can enter his own transform
** ''Transform Matrix:'' a 12-parameter affine transformation manually. The first 9 numbers represent a linear transformation matrix in column-major order (where the column index varies the fastest), the last 3 are a translation.
** ''Transform:'' forces the transform to be of rigid or affine type (affine is default)
** ''Space:'' It should normally not be modified when using this module directly in Slicer3 with a transform node. It does not specify whether the matrix is expressed in LPS or RAS coordinate space but rather if everything is expressed in the same coordinate space. LPS means that everything is in the same space and RAS means that it is not the case. This option can be set to RAS if the given transform is in RAS coordinate space (respectively LPS) and the input volume is in LPS coordinate space (respectively RAS). '''Be careful''': When passing manually the transform, the coordinate space modification is directly applied on the given transform. However, when passing the transform through a file or a transform node, it is the input volume coordinate space that is modified and the transform is left unchanged (so that any kind of transform supported by ITK is also supported by this module). If one sets the output volume parameters manually, one has to pay attention to the fact that in that case the given parameters are considered to be in the transform coordinate space!!!
* '''Rigid/Affine Parameters:'''
** ''Rotation Point:'' uses a fiducial to set a point around which the rotation defined in the transform needs to be performed.
** ''Centered Transform:'' sets the center of the transformation to the center of the image.
** ''Inverse ITK Transformation:'' inverses the transformation before applying it to the image. The transform given to the module is from the output image to the input one. If one wants to specify a transform from the input image to the output image, one should use this flag. This option can only be used if the transform is rigid or affine. Be careful: if the file containing the transform contains multiple transforms, only rigid and affine transforms will be inverted.
* '''Affine Transformation Type:''' Uses the Preservation of the Principal Direction (right image) to compute the affine transform. Otherwise, the Finite Strain Method (left image) is used [[#References|[1] ]].

{|
|[[Image:320px-Plan2dyz-skew-noppd-vertical.jpg|thumb|250px|Finite Strain]]
|[[Image:320px-Plan2dyz-skew-ppd-vertical.jpg|thumb|250px|Preservation Of Principal Direction]]
|}

* '''Interpolation Type:''' sets the type of interpolation kernel to either linear, nearest neighbor (nn), windowed sinc (ws), or b-spline (bs). The windowed sinc interpolator uses a constant boundary condition whereas the b-spline interpolator uses a mirror boundary condition.
* '''Windowed Sinc Interpolate Function Parameters:''' selects the type window function for the sinc interpolation h=hamming, c=cosine, w=welch, l=lanczos, b=blackman. '''This is only relevant if one selects ws as the interpolation type'''.
* '''BSpline Interpolate Function Parameters:''' The spline order (only relevant if the selected interpolator is bs).
* '''Output Parameters:''' One can overwrite the reference volume parameters by setting manually the ''spacing'', ''size'', ''origin'' (as a fiducial), and ''direction matrix'' (also known as space directions) in column-major order.


{{documentation/{{documentation/version}}/module-section|Similar Modules}}


{{documentation/{{documentation/version}}/module-section|References}}
* [1] Arsigny, V., Fillard, P., Pennec, X. and Ayache, N. (2006), Log-Euclidean metrics for fast and simple calculus on diffusion tensors. Magn Reson Med, 56: 411–421. doi: 10.1002/mrm.20965
* [2] D.C. Alexander, C. Pierpaoli, P.J. Basser, J.C. Gee. Spatial Transformations of Diffusion Tensor Magnetic Resonance Images, IEEE Transactions on medical imaging, vol. 20, No. 11, November 2001


{{documentation/{{documentation/version}}/module-section|Information for Developers}}
The source code of ResampleDTIlogEuclidean is available on [https://github.com/NIRALUser/ResampleDTIlogEuclidean GitHub]. It is published under an [http://www.apache.org/licenses/LICENSE-2.0 Apache License v2.0]. 


{{documentation/{{documentation/version}}/module-footer}}
[[Category:Documentation/{{documentation/version}}/Modules/Segmentation]]