Setup a MITK-based project

This page describes how to create your own project based on MITK. Instead of downloading and building MITK yourself, you usually choose between the two options below to bootstrap your project:

1. Use the MITK Plugin Generator, a command line tool used to generate a customized MITK project and/or MITK plug-ins (available for download here).

2. Use the MITK project template as an example project.

Both options will provide you with a project which contains a "superbuild" mechanism to automatically download, configure, and build MITK as a dependency of your own project.

The MITK Plugin Generator generates code using the supplied command line arguments, whereas the MITK project template needs immediate modifications to customize it to your naming schemes. However, the project template will potentially contain more code demonstrating features of MITK.

Using the MITK Plugin Generator is recommended for beginners.

Prerequisites

What ever option you choose, a MITK-based project needs essentially the same prerequisites as MITK itself. Please see the MITK Build Instructions for details.

MITK Plugin Generator

Please have a look at How to create a new MITK Plug-in for details about the Plugin Generator.

MITK Project Template

This tutorial is for Windows, but the steps are basically the same for Linux.

We will use the MITK project template and its build-in support for automatically building MITK itself (aka Superbuild). Please read also the provided README.

1. Get the project template as a zipball and extract it in a directory, e.g. in D:\AwesomeProject.

2. Search for the string "awesome" in the template and replace it with your project name.

3. If you installed any previous version of Qt make sure to remove the path from your PATH-environment variable. Otherwise you might get errors during configuration.

4. Start "cmake-gui" and enter your source (e.g. D:\AwesomeProject) and binary directory (e.g. D:\AwesomeProject-superbuild).

5. Press "Configure" until no new variables appear and then "Generate". Now all project files have been generated into your binary directory.

6. Close CMake and open "D:\AwesomeProject-superbuild\AwesomeProject-superbuild.sln" (replace the path accordingly). Your Visual Studio should appear and by pressing F7 you start the compilation. This will clone the MITK source code, build it, and then start building your own project.

7. After the superbuild compilation has finished, close the solution file and start the batch file "D:\AwesomeProject-superbuild\AwesomeProject-build\StartVS_debug.bat" (or _release.bat if you built in Release mode) which opens the "D:\AwesomeProject-superbuild\AweseomeProject-build\AwesomeProject.sln" solution.

8. Set the "AwesomeApp" project as start-up project (right click > "Set as StartUp Project") and press "F5" to start your MITK AwesomeApp.

=> Just opening AwesomeProject.sln from your explorer by double-cliking won`t allow you to start or debug your application because the required environment variables would be missing. Use the supplied batch files or set your PATH variable accordingly.

Customize MITK

The CMake scripts from the Plugin Generator of the project template provide some handy options which allow you to customize the MITK build used in your project. You can either inject an already build MITK to be used by your project or configure some MITK options directly in your project's superbuild configuration if MITK is going to be build inside your project.

Inject a MITK build

By setting the EXTERNAL_MITK_DIR variable in your project's superbuild CMake configuration to a MITK build directory (containing the MITKConfig.cmake) you can skip the MITK build process.

If MITK is the only external project in your project, you might want to disable the superbuild of your project completely (set <your-proj-name>_USE_SUPERBUILD to OFF or edit your CMakeLists.txt file to set it to OFF by default) and set the MITK_DIR CMake variable to your MITK build directory.

Configure the MITK superbuild

If MITK is being build inside your project's superbuild process, you can enable the use of certain third-party libraries inside of MITK. The following variables control the MITK configuration:

• MITK_USE_BLUEBERRY Enable the use of the BlueBerry application framework

• MITK_USE_Boost Download and use Boost in MITK

• MITK_USE_CTK Download, compile, and use CTK in MITK

• MITK_USE_DCMTK Download, compile, and use DCMTK in MITK

• MITK_USE_OpenCV Download, compile, and use OpenCV in MITK

• MITK_USE_Python Download and compile 1CableSwig and enable Python wrapping in ITK, VTK, OpenCV, and MITK

• MITK_USE_QT Use the Qt framework in MITK

You can also inject already build third-party libraries from inside your project's superbuild in the MITK superbuild by using any of the following CMake variables:

• MITK_CTK_DIR Reuse a CTK build directory in MITK.

• MITK_CableSwig_DIR Reuse a 1CableSwig build directory in MITK.

• MITK_DCMTK_DIR Reuse a DCMKT build directory in MITK.

• MITK_GDCM_DIR Reuse a GDCM build directory in MITK.

• MITK_ITK_DIR Reuse a ITK build directory in MITK.

• MITK_OpenCV_DIR Reuse a OpenCV build directory in MITK.

• MITK_VTK_DIR Reuse a VTK build directory in MITK.

If the corresponding MITK_USE_<proj> option is set to on, the MITK superbuild will use the provided build directory instead of building the project itself.

You can also control the source code location for MITK in your project's superbuild configuration by using the following CMake variables:

• MITK_SOURCE_DIR The path to the MITK source directory. If the value for this variable is non-empty, the variables below are ignored.

• MITK_GIT_REPOSITORY The Git repository containing the MITK source code.

• MITK_GIT_TAG The hash id, tag or branch name used for a checkout from MITK_GIT_REPOSITORY.

Project Structure

If you are using the superbuild feature of the generated project (the default), you might want to familiarise yourself with the layout of your build tree. The top-level build directory which you specified in CMake when configuring your project will contain all the required dependencies.

Suppose we call our project MyProject and the build directory is C:\MyProject-superbuild. Then the layout looks something like this:

The top-level directory contains the source code and the build directories from the dependencies of your project. In the current case, the only dependency of MyProject is MITK, which in turn has downloaded and built its own dependencies (CTK, DCMTK, ITK, etc.). The "real" build tree for your project is located in MyProject-superbuild/MyProject-build, so point the CMake-GUI to this build directory if you want to change the set of enabled plug-ins for example.

Further, you should open the MyProject.sln solution file (for Visual Studio) or execute "make" in the MyProject-superbuild/MyProject-build/ directory. Only for the very first time or if you want to update and newly build the project's dependencies should you use the project files in the MyProject-superbuild directory directly.

The same applies for the MyProject-superbuild/MITK-superbuild directory. This directory contains the MITK superbuild, nested inside your project's superbuild. If you want to change CMake options for MITK, use the MyProject-superbuild/MITK-superbuild/MITK-build build directory.

Packaging

The project template and the generated projects by the Plugin Generator come with full packaging support. You can create deployable packages of your project for all supported operating systems my building the PACKAGE target. On Linux, this will create a tarball, on MacOS a .dmg file, and on Windows a zipball and an NSIS installer (if NSIS is installed and found).

You can read more about deployment here.