MITK Python Wrapping

MITK Python Wrapping

Introduction

This how-to will show you how to use MITK classes from a Python environment. The main purpose of wrapping MITK Code in Python is to accelerate algorithm development by using the interpreted Python environment and still have access to existing fast C++ algorithms. Besides that, there are many more scenarios in which these wrapper may proof to be useful. The creational workflow as well as the infrastructure was developed in the Diploma Thesis of Danial Saruji, completed in December 2010.

The wrapping process is very similar to ITK. CableSwig is used to generate the wrappers. Currently only Python wrappers can be generated for the core part of MITK. It is also possible to specify wrappers for other parts or own classes.

Finally, we have a very nice bundle intergrated in the MITK BlueBerry application which provides a Python console, a variable stack, a command history and a script editor. All in all, everything you need to access the running MITK application and all instantiated objects interactively through Python. You can easily drag and drop Data Nodes from the DataManager to the Python variable stack and vice versa. This way you can create DataNodes with Python Code and show them instantly in the MITK RenderWindows.

Contents

This document contains instructions on how to build MITK, ITK and VTK with Python support. Moreover, a description on how to build the Python plugin for the MITK BlueBerry Application is included. Last but not least, there are some troubleshooting paragraphs describing the fixes or workarounds that we needed when we encountered problems.

<<TableOfContents(2)>>

General Prerequisites

The document also describes how to enable Python Wrapping for other toolkits (ITK, VTK, OpenCV). Together with the MITK wrappers you will have the whole code base accessible through Python. In general you will need Python 2.6 or 2.7 installed on your computer. You can download it here. For the MITK wrapping process Python 3.x may not be used yet. Of course, you will need everything else to built the Toolkits if you would built them without Python support, especially CMake.

As an optional but useful software you may want to install IPython which is an enhanced interactive Python shell for Linux, Mac and Windows which we found to be very handy.

Python on Windows with Visual Studio in Debug configuration

There are some issues when building Python related modules in Debug mode on Windows with Visual Studio. The Python installer does not ship the debug library "python2x_d.lib", but the header file pyconfig.h enforces the use of it by using VS Macros:

...
#			ifdef _DEBUG
#				pragma comment(lib,"python27_d.lib")

We recommend using Python on Windows with Visual Studio only in release mode.

Build MITK with Python Wrapping

Prerequisites

• CableSwig, see Build CableSwig
• A VTK built with Python support, see Build VTK with Python Wrapping
• ITK with support (optional), see Build ITK with Python Wrapping
• OpenCV with support (optional), see Build OpenCV with Python Wrapping

Instructions :

• Follow the build instructions described here.
• In CMake set the view to advanced.
• Set the option WrapMITK_Python to ON.
• Press configure.
• Set the path to the CableSwig directory if not found.
• Adjust PYTHONPATH:
  • On Linux: $ export PYTHONPATH=<MITK-BUILD>/bin::$PYTHONPATH

Small python example for testing (start IPython console, then copy&paste the code below):

# load mitk python wrapper
import mitk

After generating the project files you can build the project _mitkCorePython. This will create a Python module called mitkCorePython which can be imported into any Python interpreter.

MITK Python Bundle

This bundle offers a Python console and a script editor.

Prerequisites

• The Common Toolkit (CTK) with Python console, see Build CTK with Python console

Activate the Bundle

1. Set the CMake option MITK_BUILD_org.mitk.gui.qt.python.console to ON
2. Set MITK_USE_CTK to ON
3. Press configure.
4. Set the path to the CTK directory if not found.

Set Python Path

In order that the Python interpreter finds the modules you have to set the Python path as an environment variable. You can use a batchfile as described in the build instructions.

• PYTHONPATH=<path to the modules>;...
• for MITK the path to the modules are:
  • Windows: <MITK_BINARY_PATH>/bin;<MITK_BINARY_PATH>/bin/<Debug|Release>;
  • Linux: <MITK_BINARY_PATH>/bin

Build Wrappers for your own module

1. Create a folder in <MITK_SOURCE_DIR>/Wrapping/CSwig

2. Add the name of the folder to the variable MITK_PYTHON_MODULES_DIRS located in the file <MITK_SOURCE_DIR>/Wrapping/CSwig/PythonMITKModules.cmake

3. Create a CMakeLists.txt file in this folder:

SET(MASTER_INDEX_FILES "${CMAKE_CURRENT_BINARY_DIR}/${NAME_OF_MODULES_MDX_FILE}.mdx")

MITK_WRAP_LIBRARY("${WRAP_SOURCES}" "${LIBRARY_NAME}" "${NAME_OF_THE_FOLDER}" "${DEPEND_LIBRARIES}" "${EXTRA_SOURCES}" "${LINK_LIBRARIES}")

• MASTER_INDEX_FILES: The Master Index Files contain the index files which are generated during the wrapping process
• NAME_OF_MODULES_MDX_FILE: Name/s for the MDX file/s have to be maintained. Only a custom name has to be set the rest will be done automatically.
• WRAP_SOURCES: Specifies which Cable Configuration Files should be included into the module
• LIBRARY_NAME: The name of the Python module to be generated.
• NAME_OF_THE_FOLDER: The name of the folder created in step 1
• DEPEND_LIBRARIES: Libraries on which the module depends
• EXTRA_SOURCES: Extra source files which should be included
• LINK_LIBRARIES: Libraries which should be linked to the module

4. Create CABLE Configuration Files for the classes which should be wrapped:

• A description of how to write a CABLE Configuration File can be found here
• Note: The mitkCSwigMacros.h (located <MITK_SOURCE_DIR>/Wrapping/CSwig) has some usefull macros for typedefs

5. It can be necessary to modify the wrapping process in some cases. For this please have a look at the SWIG Users Manual. E.g. Typemaps

Build CableSwig

• Download the latest source from the ITK download site
• Create a binary directory and run a first "Configure" with CMake
• At the moment (Jan 2011) the default configuration is acceptable
• Run "Configure" again and click "Generate"
• Build CableSwig with your compiler

Modify CableSwig to enable Windows Debug builds to be built

Currently it is only possible to use the MITK Python Bundle in release mode on Windows. This is because CTK uses the Python Release Library in debug mode, whereas the MITK Core Python module is linked to the Python Debug Library in debug mode. There are two workarounds to enable the build on Windows in debug mode:

• CableSwig:
  • Modify python.swg located <CABLESWIG_SOURCE_PATH>/SWIG/Lib/python:

Change:

%insert(runtime) %{
#include "Python.h"
%}

to:

%insert(runtime) %{
# ifdef _DEBUG
#   undef _DEBUG
#   if defined(_MSC_VER) && _MSC_VER >= 1400
#     define _CRT_NOFORCE_MANIFEST 1
#  endif
#   include <Python.h>
#  define _DEBUG
# else
#   include <Python.h>
# endif
%}

• ITK:
  • Instead of setting the path to the Python Debug Library set the path to the Python Release Library in CMake
• VTK:
  • Use the normal wrapping without the CMake variable VTK_WINDOWS_PYTHON_DEBUGGABLE or set it to OFF
• MITK:
  • Instead of setting the path to the Python Debug Library set the path to the Python Release Library in CMake

Build ITK with Python Wrapping

• Download the latest source (current: 3.20.0, Jan 2011) from the ITK download site
• Create a binary directory and run a first "Configure" with CMake
• Make all your personal configuration settings that do not concern ITK Python wrapping
• Set USE_WRAP_ITK to ON. There is another option ITK_CSWIG_PYTHON which you should not use since this will build the old fashioned ITK Python Wrapping
• At the moment you also have to set ITK_USE_REVIEW and BUILD_SHARED_LIBS to ON in order to build WrapITK (the warnings that ITK_USE_REVIEW is used may be ignored)
• Run configure
• Set the CableSwig_DIR to the path containing your previously built CableSwig
• Run configure
• A lot of WRAP_* variables will appear, they are pretty self explaining. E.g., they determine which basic types for images (char, long, etc.) will be built. Adjust this to your needs
• Make sure that WRAP_ITK_JAVA is deactivated in order to reduce the compile time
• Run configure and generate
• Build ITK with your compiler (Compilation will take much longer depending on how many basic types were chosen to be wrapped)
• Examples and a bit more documentation can be found here
• Adjust PYTHONPATH:
  • On Linux: $ export PYTHONPATH=<ITK-BUILD>/bin:<ITK-BUILD>/Wrapping/WrapITK/Python:$PYTHONPATH

Small python example for testing (start IPython console, then copy&paste the code below):

# load ITK extensions
import itk
# print version (e.g. "3.20.0")
print itk.Version.GetITKVersion()

Build VTK with Python Wrapping

• Download the latest source (current: 5.6, Jan 2011) from the VTK download site
• Create a binary directory and run a first "Configure" with CMake
• Make all your personal configuration settings that do not concern VTK Python wrapping
• Set VTK_WRAP_PYTHON to ON
• A lot of PYTHON_* variables will come up. Again, they are pretty self explaining and responsible for which modules are wrapped by Python (less will reduce compile time)
• Run configure and generate
• Build VTK with your compiler
• A nice VTK Python Wrapping FAQ can be found here
• Adjust PYTHONPATH (${LIBRARY_OUTPUT_PATH} is the path containing the VTK shared libraries):
  • On Linux: $ export PYTHONPATH=$VTK_ROOT/Wrapping/Python:${LIBRARY_OUTPUT_PATH}:$PYTHONPATH
• Adjust LD_LIBRARY_PATH on linux or the PATH environment variable on windows:
  • On Linux: $ export LD_LIBRARY_PATH=$LIBRARY_OUTPUT_PATH:$LD_LIBRARY_PATH

Small python example for testing (start IPython console, then copy&paste the code below):

# load VTK extensions
import vtk

# create a rendering window and renderer
ren = vtk.vtkRenderer()
renWin = vtk.vtkRenderWindow()
renWin.AddRenderer(ren)
renWin.SetSize(300,300)

iren = vtk.vtkRenderWindowInteractor()
iren.SetRenderWindow(renWin)

# create an actor and give it cone geometry
cone = vtk.vtkConeSource()
cone.SetResolution(8)
coneMapper = vtk.vtkPolyDataMapper()
coneMapper.SetInput(cone.GetOutput())
coneActor = vtk.vtkActor()
coneActor.SetMapper(coneMapper)

# assign our actor to the renderer
ren.AddActor(coneActor)

# enable user interface interactor
iren.Initialize()
iren.Start()

Build OpenCV with Python Wrapping

• Download the latest source (current: 2.2, Jan 2011) from the OpenCV download site
• Create a binary directory and run a first "Configure" with CMake
• Make all your personal configuration settings that do not concern OpenCV Python wrapping
• Set BUILD_NEW_PYTHON_SUPPORT to ON
• Run configure and generate
• Build OpenCV with your compiler
• The OpenCV Python documentation can be found here
• Adjust PYTHONPATH to point to the directory containing your OpenCV shared libraries
  • On Linux: export PYTHON_LIBRARY_PATH=~/projects/opencv/release/lib:$PYTHON_LIBRARY_PATH
  • On Windows: set PYTHONPATH=<OpenCV-BinaryDirectory>\lib\<Debug|Release>;%PYTHONPATH%
• Adjust PATH on Windows to point to the directory containing your OpenCV DLLs:
  • set PATH=<OpenCV-BinaryDirectory>\bin\<Debug|Release>;%PATH%

Small python example for testing (start IPython console, then copy&paste the code below):

# create black image and show it
import cv
im = cv.CreateImage( (300,300), 8, 1 )
cv.Set(im, cv.Scalar(0,0,0))
cv.ShowImage("Output", im)
cv.WaitKey(0)

Build CTK with Python console

The MITK Python console is build upon the CTK python console. You can access the current source code repository with git: git clone https://github.com/commontk/CTK.git will checkout the current state.

Please note: For the command history to work we needed a little workaround in the CTK source code. This workaround is included in a branch of the CTK repository: https://github.com/saruji/CTK.git. At the moment (January, 2011), you will have to checkout this branch. The changes will however be included soon in the master CTK repository.

Instructions :

• Checkout the CTK source code with git: git clone https://github.com/saruji/CTK.git
• Create a binary directory and run a first "Configure" with CMake
• Make all your personal configuration settings that do not concern CTK Python wrapping
• Set CTK_LIB_Scripting/Python/Core to ON
• Run configure
• Set CTK_APP_ctkSimplePythonShell to ON
• Run configure and generate
• Build CTK with your compiler