Difference between revisions of "Documentation/Nightly/Developers/ModuleWizard"

From Slicer Wiki
Jump to: navigation, search
 
(19 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
<noinclude>{{documentation/versioncheck}}</noinclude>
 +
 +
{{ambox
 +
| type  = warning
 +
| text  = '''Deprecated'''<p>This page describes a utility which has been deprecated. If you are using Slicer 4.4 or later, it is recommended to use the [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|Extension Wizard]] instead.</p>
 +
}}
 +
 +
<br/>
 +
 
== Background ==
 
== Background ==
  
Line 6: Line 15:
  
 
Also, it is not uncommon to want to use one module as the starting point for implementing similar functionality.
 
Also, it is not uncommon to want to use one module as the starting point for implementing similar functionality.
 +
 +
For development, we suggest starting with the structure of an Extension that can contains one or more modules.  The [[Documentation/{{documentation/version}}/Developers/Modules|modules]] can be of different types, such as python scripted module or pure C++ modules or a combination.
 +
 +
The ModuleWizard will do most of the copying and renaming for you, but you will also need to manually configure some steps (specifically, you need to edit the CMakeLists.txt file when you add a module to an extension).
  
 
== Terminology ==
 
== Terminology ==
Line 21: Line 34:
 
   --target default ./Modules/Loadable/<moduleName>
 
   --target default ./Modules/Loadable/<moduleName>
  
== Concepts ==
+
== Step by Step ==
  
 
The idea of the wizard is to create a new self-contained directory that is a working module from the slicer perspective.  This means that for C++ extensions, you only need to compile the extension and it will work with slicer.  For scripted (python) extensions, you don't even need to compile.
 
The idea of the wizard is to create a new self-contained directory that is a working module from the slicer perspective.  This means that for C++ extensions, you only need to compile the extension and it will work with slicer.  For scripted (python) extensions, you don't even need to compile.
  
 
Running this wizard will create the module in the specified target directory and will give it the name you specify on the command line.
 
Running this wizard will create the module in the specified target directory and will give it the name you specify on the command line.
 +
 +
On Windows, you can execute the wizard by running the command as a parameter of python:
 +
../Slicer-Superbuild/python-install/bin/python.exe ./Utilities/Scripts/ModuleWizard.py --template [...]
 +
 +
=== Creating an Extension ===
  
 
For example, running this command:
 
For example, running this command:
  
  ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate --target ../MyBorExtension MyBorExtension
+
  ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate --target ../MyExtension MyExtension
 +
 
 +
should be done from within the slicer source directory, so that the <code>ModuleWizard.py</code> script is found, and so that the template path points to the correct spot.  This command relies on your machine having an installed python interpreter to run the wizard (any version of python should work, you don't need to use the one that gets built with slicer).
 +
 
 +
This command will create a new directory parallel to the Slicer source directory, in this case called MyExtension.
 +
 
 +
The resulting extension will include a sample module in a directory called "ScriptedLoadableModuleTemplate" -- ''you should delete this directory since we will replace it in the next step.''
 +
 
 +
Edit the MyExtension/CMakeLists.txt file to customize it for your work.  For example, list yourself and your colleagues as contributors and add the proper links to your project pages and icons.  You should also make a custom icon for extension, that will represent it in the ExtensionManager.
 +
 
 +
=== Adding a Module ===
 +
 
 +
Instead of the generic module, we'll want a new one with a custom name, you can use the ModuleWizard again to rename the file and the contents from the template:
 +
 
 +
./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate/ScriptedLoadableModuleTemplate --target ../MyExtension/MyScriptedModule MyScriptedModule
 +
 
 +
Now you will need to edit the ../MyExtension/CMakeLists.txt and change the following line:
 +
 
 +
add_subdirectory(ScriptedLoadableModuleTemplate)
 +
 
 +
to read:
  
should be done from within the slicer source directory, so that the ModuleWizard.py script is found, and so that the template path points to the correct spot. This command relies on your machine having an installed python interpreter to run the wizard (any version of python should work, you don't need to use the one that gets built with slicer).
+
  add_subdirectory(MyScriptedModule)
  
This command will create a new directory parallel to the Slicer source directory, in this case called MyBorExtension.
 
  
Since we used the ScriptedLoadableExtensionTemplate, the only thing we need to do is set the additional module path to point to the full path to MyBorExtension in the [[Documentation/{{documentation/version}}/SlicerApplication/ApplicationSettings|Application Settings]] dialog.  
+
Since we used the ScriptedLoadableExtensionTemplate, the only thing we need to do is set the additional module path to point to the full path to MyExtension/MyScriptedModule in the [[Documentation/{{documentation/version}}/SlicerApplication/ApplicationSettings|Application Settings]] dialog.  
  
 
Then when you restart slicer, you should select your module using in the [[Documentation/{{documentation/version}}/SlicerApplication/MainApplicationGUI#Module_Selection_.26_Navigation|Module Navigation]] interface.
 
Then when you restart slicer, you should select your module using in the [[Documentation/{{documentation/version}}/SlicerApplication/MainApplicationGUI#Module_Selection_.26_Navigation|Module Navigation]] interface.
  
== Examples ==
+
=== Adding More Modules ===
  
These can be run from the Slicer4 source directory.
+
Note that you can repeat the steps for adding modules so that your extension can contain many modules of different types.  Just run the ModuleWizard with the path to the appropriate template, and add the directory to the CMakeLists.txt.
  
 +
== Examples ==
  
 
To create a [[Documentation/{{documentation/version}}/Developers/Modules#Command_Line_Interface_.28CLI.29|CLI]] Extension:
 
To create a [[Documentation/{{documentation/version}}/Developers/Modules#Command_Line_Interface_.28CLI.29|CLI]] Extension:
  
   ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/CLIExtensionTemplate --target ../MyFooExtension MyFooExtension
+
   ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/CLIExtensionTemplate/CLIModuleTemplate --target ../MyExtension/MyCLIModule MyCLIModule
  
 
where <code>MyFooExtension</code> is the name of your extension
 
where <code>MyFooExtension</code> is the name of your extension
  
  
To create a [[Documentation/{{documentation/version}}/Developers/Tutorials/CreateLoadableModule|Loadable]] Extension:
+
To create a [[Documentation/{{documentation/version}}/Developers/Tutorials/CreateLoadableModule|Loadable]] Module:
  
   ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/LoadableExtensionTemplate --target ../MyBarExtension MyBarExtension
+
   ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/LoadableExtensionTemplate/LoadableModuleTemplate --target ../MyExtension/MyLoadableModule MyLoadableModule
  
where <code>MyBarExtension</code> is the name of your extension
 
  
 +
To create a [[Documentation/{{documentation/version}}/Developers/Modules#Scripted_Modules|Scripted Loadable]] Module:
  
To create a [[Documentation/{{documentation/version}}/Developers/Modules#Scripted_Modules|Scripted Loadable]] Extension:
+
  ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate/ScriptedLoadableModuleTemplate --target ../MyExtension/MyScriptedModule MyScriptedModule
  
  ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate --target ../MyBorExtension MyBorExtension
 
 
where <code>MyBorExtension</code> is the name of your extension
 
  
 +
To create an [[Documentation/{{documentation/version}}/Developers/EditorExtension|EditorEffect]] Extension
 +
  ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/EditorExtensionTemplate/EditorEffectTemplate --target ../MyExtension/MyEditorEffect MyEditorEffect
  
To create an [[Documentation/{{documentation/version}}/Developers/EditorExtension|EditorEffect]] Extension
 
  ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/EditorExtensionTemplate --target ../MyEditorEffect MyEditorEffect
 
  
where <code>MyEditorEffect</code> is the name of your extension
+
For reference, an extension directory that results from the steps above can be found [https://github.com/pieper/MyExtension in this git repository].
  
 
=== Creating and Testing a Loadable Module ===
 
=== Creating and Testing a Loadable Module ===
  
The following code can be run from the SuperBuild directory:
+
The following code can be run from the SuperBuild directory (mac and linux):
 
 
Linux:
 
  
 
<pre>
 
<pre>
Line 82: Line 115:
 
../Slicer/Utilities/Scripts/ModuleWizard.py --template ../Slicer/Extensions/Testing/LoadableExtensionTemplate --target /tmp/${NEWMODULE} ${NEWMODULE}
 
../Slicer/Utilities/Scripts/ModuleWizard.py --template ../Slicer/Extensions/Testing/LoadableExtensionTemplate --target /tmp/${NEWMODULE} ${NEWMODULE}
 
mkdir /tmp/${NEWMODULE}-build
 
mkdir /tmp/${NEWMODULE}-build
(cd /tmp/${NEWMODULE}-build; cmake /tmp/{NEWMODULE} -DSlicer_DIR:PATH=${SLICERSUPERBUILD}/Slicer-build; make)
+
(cd /tmp/${NEWMODULE}-build; cmake /tmp/${NEWMODULE} -DSlicer_DIR:PATH=${SLICERSUPERBUILD}/Slicer-build; make)
./Slicer-build/Slicer --additional-module-paths /tmp/NewModule-build/lib/Slicer-4.2/qt-loadable-modules
+
./Slicer-build/Slicer --additional-module-paths /tmp/${NEWMODULE}-build/lib/Slicer-4.2/qt-loadable-modules
  
 
</pre>
 
</pre>
  
  
Slicer will start, and you will find NewModule in the modules menu under Examples.  In the python interpreter, you can access the wrapped logic with:
+
After running this command, Slicer will start, and you will find the default LoadableModuleTempate in the modules menu under Examples.  In the python interpreter, you can access the wrapped logic with:
  
  logic = slicer.modules.newmodule.logic()
+
  logic = slicer.modules.loadablemoduletemplate.logic()
  
 
From here, you can add additional methods to the logic and develop the GUI.
 
From here, you can add additional methods to the logic and develop the GUI.
  
Note that as of mid-February 2013, mac builds may require /LibraryFrameworks to be specified explicitly as shown here:
+
''Note: use the latest version of CMake (2.8.11) on mac''
<pre>
 
NEWMODULE=NewModule
 
SLICERSUPERBUILD=`pwd`
 
 
 
../Slicer/Utilities/Scripts/ModuleWizard.py --template ../Slicer/Extensions/Testing/LoadableExtensionTemplate --target /tmp/${NEWMODULE} ${NEWMODULE}
 
mkdir /tmp/$NEWMODULE}-build
 
(cd /tmp/${NEWMODULE}-build; cmake /tmp/{NEWMODULE} -DSlicer_DIR:PATH=${SLICERSUPERBUILD}/Slicer-build -DCMAKE_SHARED_LINKER_FLAGS="-F /Library/Frameworks" -DCMAKE_EXE_LINKER_FLAGS="-F /Library/Frameworks" -DCMAKE_MODULE_LINKER_FLAGS="-F /Library/Frameworks"; make)
 
./Slicer-build/Slicer --additional-module-paths /tmp/NewModule-build/lib/Slicer-4.2/qt-loadable-modules
 
 
 
</pre>
 

Latest revision as of 20:49, 26 August 2014

Home < Documentation < Nightly < Developers < ModuleWizard


For the latest Slicer documentation, visit the read-the-docs.



Background

Slicer modules typically consist of several files of various types, such as CMake files, source files, and binary files.

In many cases, the names of the files and the names of text strings inside the files are related and need to be in sync in order for things to compile.

Also, it is not uncommon to want to use one module as the starting point for implementing similar functionality.

For development, we suggest starting with the structure of an Extension that can contains one or more modules. The modules can be of different types, such as python scripted module or pure C++ modules or a combination.

The ModuleWizard will do most of the copying and renaming for you, but you will also need to manually configure some steps (specifically, you need to edit the CMakeLists.txt file when you add a module to an extension).

Terminology

  • The template is a directory containing a slicer module
  • The templateKey is a text string, typically the name of the module, that is used in both filename and identifiers inside the module.
  • The target is a directory where you want the new module to be placed
  • The moduleName is the string that you want to use in place of the templateKey

Usage

ModuleWizard [--template <dir>] [--templateKey <key>] [--target <dir>] <moduleName>
 --template default ./Extensions/Testing/LoadableExtensionTemplate
 --templateKey default is dirname of template
 --target default ./Modules/Loadable/<moduleName>

Step by Step

The idea of the wizard is to create a new self-contained directory that is a working module from the slicer perspective. This means that for C++ extensions, you only need to compile the extension and it will work with slicer. For scripted (python) extensions, you don't even need to compile.

Running this wizard will create the module in the specified target directory and will give it the name you specify on the command line.

On Windows, you can execute the wizard by running the command as a parameter of python:

../Slicer-Superbuild/python-install/bin/python.exe ./Utilities/Scripts/ModuleWizard.py --template [...]

Creating an Extension

For example, running this command:

./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate --target ../MyExtension MyExtension 

should be done from within the slicer source directory, so that the ModuleWizard.py script is found, and so that the template path points to the correct spot. This command relies on your machine having an installed python interpreter to run the wizard (any version of python should work, you don't need to use the one that gets built with slicer).

This command will create a new directory parallel to the Slicer source directory, in this case called MyExtension.

The resulting extension will include a sample module in a directory called "ScriptedLoadableModuleTemplate" -- you should delete this directory since we will replace it in the next step.

Edit the MyExtension/CMakeLists.txt file to customize it for your work. For example, list yourself and your colleagues as contributors and add the proper links to your project pages and icons. You should also make a custom icon for extension, that will represent it in the ExtensionManager.

Adding a Module

Instead of the generic module, we'll want a new one with a custom name, you can use the ModuleWizard again to rename the file and the contents from the template:

./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate/ScriptedLoadableModuleTemplate --target ../MyExtension/MyScriptedModule MyScriptedModule 

Now you will need to edit the ../MyExtension/CMakeLists.txt and change the following line:

add_subdirectory(ScriptedLoadableModuleTemplate)

to read:

add_subdirectory(MyScriptedModule)


Since we used the ScriptedLoadableExtensionTemplate, the only thing we need to do is set the additional module path to point to the full path to MyExtension/MyScriptedModule in the Application Settings dialog.

Then when you restart slicer, you should select your module using in the Module Navigation interface.

Adding More Modules

Note that you can repeat the steps for adding modules so that your extension can contain many modules of different types. Just run the ModuleWizard with the path to the appropriate template, and add the directory to the CMakeLists.txt.

Examples

To create a CLI Extension:

 ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/CLIExtensionTemplate/CLIModuleTemplate --target ../MyExtension/MyCLIModule MyCLIModule

where MyFooExtension is the name of your extension


To create a Loadable Module:

 ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/LoadableExtensionTemplate/LoadableModuleTemplate --target ../MyExtension/MyLoadableModule MyLoadableModule


To create a Scripted Loadable Module:

 ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate/ScriptedLoadableModuleTemplate --target ../MyExtension/MyScriptedModule MyScriptedModule


To create an EditorEffect Extension

 ./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/EditorExtensionTemplate/EditorEffectTemplate --target ../MyExtension/MyEditorEffect MyEditorEffect


For reference, an extension directory that results from the steps above can be found in this git repository.

Creating and Testing a Loadable Module

The following code can be run from the SuperBuild directory (mac and linux):

NEWMODULE=NewModule
SLICERSUPERBUILD=`pwd`

../Slicer/Utilities/Scripts/ModuleWizard.py --template ../Slicer/Extensions/Testing/LoadableExtensionTemplate --target /tmp/${NEWMODULE} ${NEWMODULE}
mkdir /tmp/${NEWMODULE}-build
(cd /tmp/${NEWMODULE}-build; cmake /tmp/${NEWMODULE} -DSlicer_DIR:PATH=${SLICERSUPERBUILD}/Slicer-build; make)
./Slicer-build/Slicer --additional-module-paths /tmp/${NEWMODULE}-build/lib/Slicer-4.2/qt-loadable-modules


After running this command, Slicer will start, and you will find the default LoadableModuleTempate in the modules menu under Examples. In the python interpreter, you can access the wrapped logic with:

logic = slicer.modules.loadablemoduletemplate.logic()

From here, you can add additional methods to the logic and develop the GUI.

Note: use the latest version of CMake (2.8.11) on mac