Slicer3:Loadable Modules:HOWTO

In order to allow a module to be detected and loaded at runtime a number of changes are required. The first is within the module's GUI class. The vtkSlicerModuleGUI-derived class _must_ implement "void SetModuleLogic(vtkSlicerLogic*)". This allows the library loading methods to load the GUI without knowing the specific class type.

A text file named after the module must also be created.

Last, macros for module creation and handling must be added to the CMakeLists file.

For more information on these edits, plus some optional changes, see below.

vtkModuleNameGUI

vtkModuleNameGUI.h/cxx

Do not create this class if you want your module to be GUI-less

Required

For your vtkSlicerModuleGUI-derived class, declare and implement:

 virtual void SetModuleLogic(vtkSlicerLogic*)

This is necessary so that the Loadable module code does not need to cast the Logic pointer returned from the defined entry point.

Optional

To add module-specific MRML events to observe, declare and implement:

 virtual vtkIntArray* NewObservableEvents();

To add module-specific initialization code, declare and implement:

 virtual void Init();

This is useful to have your module register callbacks for Picking (See QdecModule).

vtkModuleNameLogic

vtkModuleNameLogic.h/cxx

Optional

To add module-specific MRML events to observe, declare and implement:

 virtual vtkIntArray* NewObservableEvents();

ModuleName.xml

ModuleName.xml

Create ModuleName.xml in the module's directory. ModuleName should follow the naming convention for the *GUI and *Logic classes.

For example, with two classes named vtkOpenIGTLinkLogic & vtkOpenIGTLinkGUI, create an XML file named OpenIGTLink.xml

This file contains naming directives, as well as lists dependencies. At a minimum, the module name & GUI name must be specified:

 <Name>Open IGT Link</Name>
 <GUIName>OpenIGT</GUIName>

When creating a GUI-less module, omit the GUIName directive.

Optionally, other attributes may be listed:

 <Description>This is a description of my module.</Description>
 <SourceLocation>https://use/the/source/luke</SourceLocation>
 <HomePage>http://my/module/homepage</HomePage>
 <Version>1.0</Version>
 <Dependency>Module One</Dependency>
 <Dependency>Module Two</Dependency>
 <Author>Karl Fardman</Author>
 <Acknowledgement>All the little people</Acknowledgement>

CMakeLists.txt

CMakeLists.txt

Most modules will be defined outside of the main Slicer3 build tree. To enable your module to be loaded dynamically, a couple entries in CMakeLists.txt are required.

Near the top of the file, include the directives that will locate the Slicer 3 build tree:

 if(NOT Slicer3_SOURCE_DIR)
   find_package(Slicer3 REQUIRED)
   include(${Slicer3_USE_FILE})
   slicer3_set_default_install_prefix_for_external_projects()
 endif(NOT Slicer3_SOURCE_DIR)

Next, tell CMake to generate the supporting files for Loadable Module:

 generatelm(OpenIGTLink_SRCS OpenIGTLink.txt)

NOTE: The macro should be placed after TCL wrapping is done, as it adds to the source variable. For more details, check the NeuroNav module CMakeLists.txt file, as it provides a good starting point.

Finally, direct CMake to copy the binary files to the Slicer3 library location. This should be the last entry in your CMakeLists file:

 install(TARGETS ${lib_name}
   RUNTIME DESTINATION ${Slicer3_INSTALL_MODULES_BIN_DIR} COMPONENT RuntimeLibraries 
   LIBRARY DESTINATION ${Slicer3_INSTALL_MODULES_LIB_DIR} COMPONENT RuntimeLibraries
   ARCHIVE DESTINATION ${Slicer3_INSTALL_MODULES_LIB_DIR} COMPONENT Development
   )

Slicer3 Extension Description

In order to add the module to the extension server, a Slicer3 Extension file needs to be added to /Slicer3/Extensions:

 scm       svn
 svnpath   https://www.nitrc.org/svn/slicer3examples/trunk/Slicer3ExampleModules/Loadable
 svnusername slicerbot
 svnpassword slicer
 
 depends
 
 homepage  http://www.nitrc.org/projects/slicer3examples/
 
 category  Examples
 
 status    Beta
 
 description An example of a loadable module using Slicer3 GUI and Logic classes, plus a MRML node.

Adding logo to your module

To add logo to a C++ loadable module, you can use KWConvertImageToHeader tool, which is compiled in Slicer3-lib/KWWidgets-build/bin to convert an image to C++ header file. Once you include this file, you can initialize the logo vtkKWIcon as follows:

  // Logo setup. To prepare the header file with the logo information, use
  // KWConvertImageToHeader tool supplied with KWWidgets, with --zlib option.
  vtkKWIcon* logo = vtkKWIcon::New();
  logo->SetImage(image_bsf_logo,
                 image_bsf_logo_width, image_bsf_logo_height,
                 image_bsf_logo_pixel_size, image_bsf_logo_length,
                 0);
  this->Logo = logo;
  logo->Delete();

Next, you can insert logo into the logo frame in the BuildGUI() method:

  this->BuildHelpAndAboutFrame(module_page, help_text, ack_text);

  // Show the logo
  if (this->GetLogo())
  {
    vtkKWLabel *logoLabel = vtkKWLabel::New();
    logoLabel->SetParent( this->GetLogoFrame() );
    logoLabel->Create();
    logoLabel->SetImageToIcon( this->GetLogo() );
    app->Script("pack %s", logoLabel->GetWidgetName() );
    logoLabel->Delete();
  }

Examples

Loadable Module

Loadable GUI-less Module

Building and testing a loadable module locally

1) check out the example and make a build directory

svn checkout https://www.nitrc.org/svn/slicer3examples/trunk/Slicer3ExampleModules/Loadable
mkdir Loadable-build
cd Loadable-build/

2) run the version of cmake that you built with slicer (it's the latest version and may not be installed on your machine)

/csail/vision-polina2/pieper/slicer3/latest/Slicer3-lib/CMake-build/bin/ccmake ../Loadable

(in cmake, confirm that Slicer3_DIR points to your build of slicer's Slicer3-build directory. Press 'c' twice then 'g').

3) make the module

make

4) run your locally built version of slicer

/csail/vision-polina2/pieper/slicer3/latest/Slicer3-build/Slicer3

in the View->Application Settings->Module Settings add the path to the built loadable module (it will be something like /csail/vision-polina2/pieper/slicer3/latest/examples/Loadable-build/lib/Slicer3/Modules)

5) restart slicer and you should see "ExampleLM" in the modules menu.

From here you can edit/modify the example loadable module to make it do what you need to do.