Warning: This documentation is outdated (see bug 19726).

Introduction

The application for manual segmentation in MITK (Segmentation view) comes with a tool class framework that is extensible with new tools (description at Technical design of QmitkSegmentation). The usual way to create new tools (since it is mostly used inside DKFZ) is to just add new files to the MITK source code tree. However, this requires to be familiar with the MITK build system and turnaround time during development might be long (recompiling parts of MITK again and again).

For external users who just want to use MITK as a library and application, there is a way to create new segmentation tools in an MITK external project, which will compile the new tools into a shared object (DLL). Such shared objects can be loaded via the ITK object factory and its autoload feature on application startup. This document describes how to build such external extensions.

Example files can be found in the MITK source code in the directory ${MITK_SOURCE_DIR}/QApplications/ToolExtensionsExample/.

What might be part of an extension

The extension concept assumes that you want to create one or several new interactive segmentation tools for Segmentation or another MITK functionality that uses the tools infrastructure. In the result you will create a shared object (DLL), which contains several tools and their GUI counterparts, plus optional code that your extension requires. The following sections shortly describe each of these parts.

Tool classes

A tool is basically any subclass of mitk::Tool. Tools are created at runtime through the ITK object factory (so they inherit from itk::Object). Tools should handle the interaction part of a segmentation method, i.e. create seed points, draw contours, etc., in order to parameterize segmentation algorithms. Simple algorithms can even be part of a tool. A tools is identified by icon (XPM format), name (short string) and optionally a group name (e.g. the group name for Segmentation is "default").

There is a naming convention: you should put a tool called mitk::ExternalTool into files called mitkExternalTool.h and mitkExternalTool.cpp. This is required if you use the convenience macros described below, because there need to be ITK factories, which names are directly derived from the file names of the tools. For the example of mitk::ExternalTool there would be a factory called mitk::ExternalToolFactory in a file named mitkExternalToolFactory.cpp.

GUI classes for tools

Tools are non-graphical classes that only implement interactions in renderwindows. However, some tools will need a means to allow the user to set some parameters – a graphical user interface, GUI. In the Qt3 case, tool GUIs inherit from QmitkToolGUI, which is a mixture of QWidget and itk::Object. Tool GUIs are also created through the ITK object factory.

Tools inform their GUIs about state changes by messages. Tool GUIs communicate with their associated tools via direct method calls (they know their tools). See mitk::BinaryThresholdTool for examples.

Again a naming convention: if the convenience macros for tool extension shared objects are used, you have to put a tool GUI called QmitkExternalToolGUI into a files named QmitkExternalToolGUI.cpp and QmitkExternalToolGUI.h. The convenience macro will create a factory called QmitkExternalToolGUIFactory into a file named QmitkExternalToolGUIFactory.cpp.

Additional files

If you are writing tools MITK externally, these tools might depend on additional files, e.g. segmentation algorithms. These can also be compiled into a tool extension shared object.

Writing a CMake file for a tool extension

Summing up the last section, an example tool extension could comprise the following files:

mitkExternalTool.h      \
mitkExternalTool.png     >--- implementing mitk::ExternalTool (header, icon, implementation)
mitkExternalTool.cpp    /

QmitkExternalToolGUI.h    ,-- implementing a GUI for mitk::ExternalTool
QmitkExternalToolGUI.cpp /

externalalgorithm.h         \
externalalgorithm.cpp        \
externalalgorithmsolver.h     >-- a couple of files (not related to MITK tools)
externalalgorithmsolver.cpp  /

This should all be compiled into one shared object. Just like ITK, VTK and MITK we will use CMake for this purpose (I assume you either know or are willing to learn about www.cmake.org) A CMake file for the above example would look like this:

project( ExternalTool )
find_package(ITK)
find_package(MITK)
find_package(Qt3)
add_definitions(${QT_DEFINITIONS})
set( TOOL_QT3GUI_FILES
     QmitkExternalToolGUI.cpp
   )
set( TOOL_FILES
     mitkExternalTool.cpp
   )
set( TOOL_ADDITIONAL_CPPS
     externalalgorithm.cpp
     externalalgorithmsolver.cpp
   )
set( TOOL_ADDITIONAL_MOC_H
)
MITK_GENERATE_TOOLS_LIBRARY(mitkExternalTools)

Basically, you only have to change the definitions of TOOL_FILES and, optionally, TOOL_QT3GUI_FILES, TOOL_ADDITIONAL_CPPS and TOOL_ADDITIONAL_MOC_H. For all .cpp files in TOOL_FILES and TOOL_QT3GUI_FILES there will be factories created assuming the naming conventions described in the sections above. Files listed in TOOL_ADDITIONAL_CPPS will just be compiled. Files listed in TOOL_ADDITIONAL_MOC_H will be run through Qts meta object compiler moc – this is neccessary for all objects that have the Q_OBJECT macro in their declaration. moc will create new files that will also be compiled into the library.

Compiling the extension

For compiling a tool extension, you will need a compiled version of MITK. We will assume MITK was compiled into /home/user/mitk/debug. You need to build MITK with BUILD_SHARED_CORE turned on!

You build the tool extension just like any other CMake based project:

know where your source code is (e.g. /home/user/mitk/tool-extension-src)
change into the directory, where you want to compile the shared object (e.g. /home/user/mitk/tool-extension-debug)
invoke cmake: ccmake /home/user/mitk/tool-extension-src
configure (press c or the "configure" button)
set the ITK_DIR variable to the directory, where you compiled ITK
set the MITK_DIR variable to the directory, where you compiled MITK: /home/user/mitk/debug
configure (press "c" or the "configure" button)
generate (press "g" or the "generate" button)

This should do it and leave you with a or project file or Makefile that you can compile (using make or VisualStudio).

Configuring ITK autoload

If the compile succeeds, you will get a library mitkExternalTools.dll or libmitkExternalTools.so. This library exports a symbol itkLoad which is expected by the ITK object factory.

On application startup the ITK object factory will search a list of directories from the environment variable ITK_AUTOLOAD_PATH. Set this environment variable to your binary directory (/home/user/mitk/tool-extension-debug).

The ITK object factory will load all shared objects that it finds in the specified directories and will test if they contain a symbol (function pointer) itkLoad, which is expected to return a pointer to a itk::ObjectFactoryBase instance. If such a symbol is found, the returned factory will be registered with the ITK object factory.

If you successfully followed all the steps above, MITK will find your mitk::ExternalTool on application startup, when the ITK object factory is asked to create all known instances of mitk::Tool. Furthermore, if your mitk::ExternalTool claims to be part of the "default" group, there will be a new icon in Segmentation, which activates your tool.

Have fun! (And Windows users: welcome to the world of DLLs)