Location

All GUI plugins are contained in the folder

NifTK/MITK/Plugins

and the file Plugins.cmake controls which ones are on/off by default. In order to turn them on/off in a development environment, you must re-run CMake from the build folder, change the plugin's ON/OFF flag, and re-configure and re-build.

The MITK Plugin Generator

The basic structure of each plugin can be created automatically by using the MITK Plugin Generator. Once the whole NifTK code has been built once, in the main build folder, there will be a sub folder

<my-build>/MITK-build/MITK-build/bin

Within that MITK bin folder there is a program called MITKPluginGenerator.

From the NifTK-build sub-folder (i.e. not the top-level "Super Build" folder) a new plugin can be generated with a single command such as the following example for a plugin called "Affine Transform".

../MITK-build/MITK-build/bin/MITKPluginGenerator -o ../../NifTK/MITK/Plugins -l ~/build/NifTK/Documentation/TemplateCPlusPlus.txt -v "CMIC, Centre For Medical Image Computing, UCL." -vc AffineTransformView -vn "Affine Transform" -ps uk.ac.ucl.cmic.affinetransform -pn "Affine Transform"

In the above code, the -o options outputs the generated code directly to the NifTK source tree. The newly created files will need adding to version control manually. We also use a standard template text file to create the correct copyright headers.

You can then add the name of the plugin into

NifTK/MITK/Plugins/Plugins.cmake

and build. Please manually checking the following:

Find the Activator class within the plugin, and make sure it has a unique name, something pertaining specifically to your plugin.
If you use Qt resource files (.qrc), give them a unique name, again, something pertaining specifically to your plugin.
Edit files.cmake for the plugin accordingly to directly refer to any files that you just renamed manually.

As the version of MITK changes, the plugin generator may do this automatically.

Naming Conventions

For consistency sake, it is important to take care when naming plugins and providing various strings that appear in the front end of the application, and in the documentation. This set of instructions was written using the Affine Transform plugin as a template, and applied to all other plugins at the time of writing. Please make every effort to keep each plugin and its documentation up to date, and to keep the names of things consistent.

The following general rules must be applied to get nice user documentation. Again, lots of this will be automated by the MITK Plugin Generator, but it is worth checking and understanding what each feature is.

The top level directory structure must be in reverse domain name order, lower case, separated by dots. For example, uk.ac.uk.cmic.affinetransform.
For CMake purposes, each plugin is a 'project'. Within each plugin, there is a CMakeLists, and the first line contains the name of the project. The plugin name is in reverse domain name order, lower case, separated by underscores. For example, uk_ac_ucl_cmic_affinetransform.
Each plugin contains a manifest_headers.cmake file, which is used by MITK and CTK macros to generate the plugin. In other words, this file is not simply a nice-to-have text description that gets bundled inside the plugin. It is in fact used to generate the plugin, and generates things link include directives.
Within manifest_headers.cmake the Plugin-Name is used to generate the top level plugin name within the GUI help pages. Avoid unnecessary jargon in the plugin name, e.g. the term "Plugin" is non-informative for the clinical end-user.
Within plugin.xml the XML name tag is used to generate the name that goes on the GUI menu item. Use the same string as the plugin name in the previous point, so the names match. Try to avoid extra words like "The", or "Plugin", to keep it brief.
Within plugin.xml if you have a preferences page defined, again, use the same name as the view name.
Within <plugin>/documentation/UserManual there is a user manual doxygen file (file name doesn't matter). Please generate a FULL description of how to use that plugin. This doxygen page is the main page that the user will see when operating the plugin within the GUI. Use the full power of doxygen. Go crazy and write to your hearts content.

Under

<plugin>/documentation/doxygen

there is doxygen.dox and the following additional rules must be applied to get consistent code documentation. The doxygen.dox is used to generate the page within this Technical Manual. It is not seen within the GUI, and is for developers only. As mentioned above, use an example as a guideline, for example, go and look at the Affine Transform plugin.

The first line should read something like "\defgroup uk_ac_ucl_cmic_affinetransform uk.ac.ucl.cmic.affinetransform Plugin". So, its the tag "\defgroup", followed by the plugin project name, then the plugin directory name followed by the word "Plugin".
The group tag should be CMICPlugins.
A brief description should be placed using the "\brief" tag. This should be one sentence, fit on one line and succinctly capture what the plugin is for.
Please put a "Written by" line, containing email addresses of people to contact concerning the plugin.
Note that there are two doxygen sections. The first defines the external interface, and the second the internal interface. These correspond to the src folder (external) and the src/internal folder (internal).
Each class with the exception of the plugin activator in the src/internal folder should declare itself in the documentation as being part of the internal doxygen group, defined in doxygen.dox for that plugin.
Each class in the src folder should declare itself to be part of the same group as the plugin.

Managing Dependencies

For each plugin, the plugin's top-level CMakeLists.txt shows the library dependencies. For example in

NifTK/MITK/Plugins/uk.ac.ucl.cmic.midasgeneralsegmentor

we see

MODULE_DEPENDENCIES CTK QmitkExt niftkMitkExt niftkQmitkExt

)

which immediately reveals that the plugin is dependent on CTK and QmitkExt, and the NifTK modules niftkMitkExt and niftkQmitkExt which are MITK based modules within this project. In addition, the top level manifest_headers.cmake we see

set(Require-Plugin uk.ac.ucl.cmic.common )

Each plugin can define plugins that it depends on at both compile time and run time. So the above line is used when generating the plugin, and in this case will set up correct include paths for compilation.

So, with this in mind, it is important to keep the number of dependencies to a minimum. Don't include extra libraries in the CMakeLists.txt by just cutting and pasting and don't make your plugin's manifest_headers.cmake depend on too many other plugins. Also remember that plugin dependencies are transitive, so if A depends on B, which depends on C, then A also depends on C. So, try and make sure all NifTK plugins only depend on MITK plugins and our own Modules, and the list of dependencies is always minimal.

User Interface

There are two ways to generate a Qt GUI component for each plugin.

Use Qt Designer to draw it. This is good for standard layouts of standard widgets.
Write all the code, and layout programmatically. This is better for adding custom widgets, but layout can be tricky.

Lets look at the Snapshot plugin for a simple example of how to build a GUI, with code found here:

NifTK/MITK/Plugins/uk.ac.ucl.cmic.snapshot/src/internal

The steps required for this are:

Launch Qt Designer, and create a .ui file, and save it into src/internal folder for example.
Instantiate your GUI. For example, in SnapshotView.h we are creating a pointer to hold all the controls:
protected:

Ui::SnapshotViewControls *m_Controls;

and then in SnapshotView.cxx we have
void SnapshotView::CreateQtPartControl( QWidget *parent )

{

m_Parent = parent;

if (!m_Controls)

{

// create GUI widgets from the Qt Designer's .ui file

m_Controls = new Ui::SnapshotViewControls();

m_Controls->setupUi( parent );

// Connect Qt signals and slots programmatically.

connect(m_Controls->m_TakeSnapshotButton, SIGNAL(pressed()), this, SLOT(OnTakeSnapshotButtonPressed()));

}

}

so, you should aim to do similarly.

Add the files to CMakeLists, so refer to

NifTK/MITK/Plugins/uk.ac.ucl.cmic.snapshot/CMakeLists.txt

and compile.

The BlueBerry framework (part of MITK) creates the GUI at the appropriate time, so we do not put GUI construction code in the View components constructor. Also if Qt GUI components are registered with their parent in the layout then when the top level widget is destroyed, so will all registered children. For this reason, you will often not see class destructors trying to destroy Qt widgets.

The second option of writing all Qt code programmatically is very similar. Any widget could be created in the View class CreateQtPartControl and signals and slots connected to methods. Thus the View class is the main GUI starting point for each new plugin. There are now several examples in NifTK and many examples in MITK to inspire and to guide.

Within the project, Qt widgets can be stored in a number of places, depending on how general purpose the Qt widget is. The following guidelines may help.

General purpose widgets can be placed in
```
NifTK/Libraries/QtWidgets
```
Notice that the TARGET_LINK_LIBRARIES only depends on default Qt libraries. So, widgets here, know NOTHING about the application they will be used for.
Under
```
NifTK/MITK/Modules
```
we have Modules called niftkMitkExt and niftkQmitkExt. These folder names simply refer to the fact that they are NifTK specifc extensions to the MITK libraries called MitkExt and QmitkExt. Qt widgets can be placed in niftkQmitkExt and NOT niftkMitkExt. Widgets in this folder are somewhat specific to NiftyView.
Each plugin can have its own widgets as appropriate. The can be created within the
```
<plugin-name>/src/internal
```
folder.

In order to become proficient at writing Qt widgets please refer to:

The CTK website contains a lot of well written widgets, developed for Slicer 4. These can be used as model widgets to inspire your coding, or used directly by including CTK within the MODULE_DEPENDENCIES of your plugin.
A selection of Qt books such as this and this.
Practice, Practice, Practice.

Functionality

The actual functionality of a plugin can obviously vary immensely depending on user requirements. The View class is the starting point for methods. Here are some guiding principals, and hopefully this list can be extended over time.

Your view class should extend from the MITK QmitkAbstractView. Get to know this class.
Remember the Model-View-Controller pattern. The central data storage is shared, and lots of things listen to updates. This is the model, plugins are controllers that take user input, and update the model.
Try to keep a clear focus on the purpose of the plugin, prefering to do a small number of things in a well defined manner.
Data storage can be retrieved simply by (in ThumbnailView.cxx)
mitk::DataStorage::Pointer dataStorage = service->GetDefaultDataStorage()->GetDataStorage();
Preference Pages can be created for each plugin. Again, preferences should be specific to the actual functionality of that plugin. For example, the MIDAS Morphological Editor has a preference page MIDASMorphologicalSegmentorViewPreferencePage defined in
```
NifTK/MITK/Plugins/uk.ac.ucl.cmic.midasmorphologicalsegmentor/src/MIDASMorphologicalSegmentorViewPreferencePage.h/.cxx.
```
and this page is added to files.cmake to compile it, plugin.xml to run it at run-time and registered with the framework in MIDASMorphologicalSegmentorViewActivator.
When the user hits "OK" in the Preferences dialog page, the preferences are broadcast to all plugins. For a simple example, see how ThumbnailView implements ThumbnailView::OnPreferencesChanged to update itself.

Documentation

The GUI is constructed from all the plugins. So, each plugin must provide its own documentation page, written using Doxygen. For example look in:

NifTK/MITK/Plugins/uk.ac.ucl.cmic.imagelookuptables/documentation/UserManual

The Doxygen manual is here.

Testing

Unit testing a plugin can be difficult. For this reason the NifTK project structure has been set up so that as much as possible, all the functionality is provided in libraries/modules and the plugin should be a small wrapper bringing it all together. So the initial focus should be on unit testing each class outside of a plugin.

For example

All ITK code should be placed under NifTK/Libraries/ITK and hence unit tested under NifTK/Libraries/ITK/Testing
Similarly for VTK
MITK based code should be placed under NifTK/MITK/Modules/niftkMitkExt and unit tested under NifTK/MITK/Modules/niftkMitkExt/Testing using mitkITKRegionParametersDataNodeProperty as an example.

Further examples are available throughout ITK, VTK and MITK. CTK has a Qt testing framework. It may be possible to leverage that, or provide good widgets back to CTK so they are unit tested as part of that project.

Also, keep an eye on the project dashboards to see how the project is currently compiling on different platforms.

Conclusion

Writing a plugin is easy in principal. In practice it may take a few attempts to get the user interaction to work nicely, but this is a small price to pay for having a nice GUI application.