SCM

Use CamiTK in Python

From Forge Wiki

Jump to: navigation, search

CamiTK SDK API is exposed to Python. This allows you to use CamiTK extensions through Python scripts, for applying a pipeline of CamiTK actions on a bunch of data for instance ...



To use CamiTK in python, you will need to launch CamiTK python package into your python shell. Then manipulate CamiTK API's objects within a Python script.

In this page you will learn how to configure and build the CamiTK python package. Indeed, at the moment, no binary built package is provided. Then, you will see how to load the CamiTK package in a Python shell / through a python script.

Note, at the moment, the building process of the Python package of CamiTK has been done only on Linux Debian platforms. We have not tested it yet under MacOS and Windows systems. Also note that the binding of CamiTK concerns only the SDK, neither the IMAGING nor the MODELING CEP are yet exposed to Python

Contents

Prerequisites

First of all, remember that we only support Linux Debian operating system to build the CamiTK python module. You may try on your own with another operating system.

CamiTK API python module compilation requires:

  • The Python library installed on your computer (minimum version 2.7)
  • PySide
  • Shiboken

Here are some information about the PySide and Shiboken library / application. PySide is the binding of the Qt framework in Python. Thus PySide is composed of the different Qt packages, provided as Python packages. Shiboken is the binding tool, which had been developped to bind C++ libraries into Python. This a generic tool which can create, from a C++ library, its python version (a python package). Shiboken allows you to create a CPython extension for each C++ library you give it as an input.

A little bit of history and technical stuffs

To correctly bind your code, Shiboken requires that your API's methods manipulated objects are available in C++ and Python AND you have some rules to convert your object from the C++ world to Python and vice versa. This is how the exposition to Python works (global concept, even using other tool than Shiboken).

PySide provides both the Qt API in the Python language AND the conversion rules C++ Qt objects <-> Python Qt objects. VTK, which is available in C++ and Python has no such rules (some are available using another binding tool other than Shiboken). As you know, CamiTK SDK requires two (big) libraries : Qt and VTK. Thus, when we decided to expose CamITK SDK to Python, we had to provide our binding tool (Shiboken) the correct C++ <-> Python binding rules. What was the biggest : Qt or VTK ? Qt won easily the match in CamiTK API. This made us decide to choose Shiboken with PySide.

At the moment, we have not provided yet C++ <-> Python conversion rules, for the VTK libraries. This as a consequence that all API methods using C++ VTK objects are NOT exposed to Python. But, FYI, more than 90% of the CamiTK SDK API's methods are already exposed to Python.

The CamiTK SDK API's methods containing C++ VTK objects in their signature are not available in the Python world. Thus, you won't be able to call these methods within the CamiTK SDK python module.

Prepare CamiTK applications for Python exposition

A particular attention should be given to C++ applications, which you'd like to expose to the Python world. In fact, using Shiboken, only libraries can be wrapped for Python exposition. Thus, if you wish to use your own C++ application in Python, you will have to convert it into a library. Don't worry, this is done simply. The concept is to keep all your C++ classes in the library and call all your application functions, initially in the main.cpp file from the Python world.

To do so, simply modify the CMake type of your application into a CamiTK component. For instance, for the IMP application, modify its CMakeLists.txt file this way :

replace its content:

camitk_application( ADDITIONAL_SOURCES CommandLineOptions.cxx CommandLineOptions.hxx CommandLineOptions.ixx
                    CEP_NAME SDK
                    DESCRIPTION "All-in-one application to load actions and component and interact with them"
)

with:

camitk_extension(   COMPONENT_EXTENSION
                    EXTERNAL_SOURCES CommandLineOptions.cxx CommandLineOptions.hxx CommandLineOptions.ixx
                    CEP_NAME SDK
                    DESCRIPTION "All-in-one application to load actions and component and interact with them"
)

If you don't change the CMakeLists.txt files of the CamiTK SDK applications you want to use, they won't be available in Python.

Once this is done, make a local installation of CamiTK (you may have selected the Imaging and Modeling CEPs):

make sdk_local_install

As you have certainly transformed some application into components from the last CMakeLists.txt file modifications, just remove the corresponding binaries:

cd ~/.config/CamiTK/lib/camitk-3.3/components

and then remove each of them (here an example for the IMP application):

rm libimp*

Indeed, you need the IMP application AS a libray (here a component) for the python package. Once you will launched it from the Python world, it will automatically try to load all the extension of your ~/.config/CamiTK folder (local installation folder).

Configure CamiTK source code to build the CamiTK python modules

Configuring CamiTK source code for building on your platform is done thanks to the Cmake tool, which allows CamiTK to be cross-platforms.

When configuring CamiTK using CMake, you will see at first step of the configuration the unchecked CAMITK_BINDING_PYTHON option. Please check it, in order to consider building the CamiTK python package.

CMake will then look for your installation of Python, PySide and Shiboken. If CMake fails to find one of these library, please check you have correctly installed them on your computer and added them to your system PATH (or CMake won't find them).

Once you have correctly configured CamiTK SDK for Python exposition, you will see two new build targets in your favourite IDE:

  • sdk_wrap_to_python
  • sdk_package_to_python

You will use them to build the CamiTK SDK python package.

Build the CamiTK python module

Wrap the CamiTK C++ classes to expose to Python

First of all, Shiboken will decorate the C++ classes to expose to Python. By decorating, we mean, adding C++ methods that will interface the existing ones in the C++ input class to be callable from the Python world and vice versa. To create those decorated classes, build the sdk_wrap_to_python target.

Shiboken may output many warnings, ignore them.

The output classes are located within the python_sdk/camitk_sdk of your build directory.

Create the python package

Once you have decorated each class of the CamiTK SDK API, build the target sdk_package_to_python. This target will compile each decorated classe generated by the previous target and link it with the original camitk sdk library.

Use CamiTK python package in a python script

Once you have built the sdk_package_to_python target, you will obtain a camitk_sdk.so library in your build directory. This library contains nearly 90% of the CamiTK SDK API, in Python. This library is a Cython extension, which explain why it is built as a .so file. Don't worry, this file can be imported in any Python script.

General concept

To use CamiTK SDK API objects in your Python script, simply import it:

import camitk_sdk
from camitk_sdk import camitk


The CamiTK SDK contains only one namespace (as imported in the previous line): camitk. The namespace from the C++ classes description are kept the same in the Python libraries.

To know what classes and methods are available from the camitk_sdk.sp Python package, you may consult the API Documentation.

Simple processing example

Here are two simple python examples:

IMP in Python

This Python script simply instanciates the IMP application. Note that this is the generic way to instanciate CamiTK applications in Python. It is inspired from the main entry point of the C++ CamiTK IMP application, located in the main.cpp file.

import sys
 
import camitk_sdk
from camitk_sdk import camitk
from camitk_sdk import ImpMainWindow
 
app = camitk.Application("imp-python", sys.argv, True, False)
mw = ImpMainWindow()
app.setMainWindow(mw)
sys.exit(app.exec_())


Simple mesh processing example

This script instanciates the IMP application, open a mesh file (Mesh.off) which is relatively located in the script at the same place as the script itself. Then apply a decimation filter on it (75%) and display it in the 3D viewer. All this is done through CamiTK SDK actions.

import sys
 
import camitk_sdk
from camitk_sdk import camitk
from camitk_sdk import *
 
app = camitk.Application("python-app", sys.argv, True, False) 
mw = ImpMainWindow()
app.setMainWindow(mw)
 
# Open the mesh image in memory
image = camitk.Application.open("./Mesh.off")
showAllViewerAction = camitk.Application.getAction("Show All Viewers")
show3DViewerAction = camitk.Application.getAction("Show 3D Viewer")
showAllViewerAction.apply()
 
# Select the component opened
selectLastInstanciatedComponentAction = camitk.Application.getAction("Select Last Instanciated Top Level Component")
selectLastInstanciatedComponentAction.apply()
 
# Select the corresponding parameter of the decimation and launch it
meshDecimationAction = camitk.Application.getAction("Decimation")
meshDecimationAction.setInputComponent(image)
meshDecimationAction.setProperty("percentageOfReduction", 75)
meshDecimationAction.apply()
 
camitk.Application.getAction("Select Last Instanciated Top Level Component").apply()
 
sys.exit(app.exec_())

Known bugs

Compiling camitk_sdk.so

You may encounter the error below:

make[2]: Circular python_sdk/camitk_sdk.so <- python_sdk/camitk_sdk.so dependency dropped.

From your build folder, go to the python_sdk subfolder and clean it

cd python_sdk
make clean

Then try to compile it again.

Instanciating CamiTK application in Python

Nearly 50% of the time, you will encounter a segfault at instanciating your application in Python. This bug comes from how Shiboken transforms the Python argc, argv input arguments to the application constructor in the CPython extension of the application. We are working on solving this bug soon, and sorry for the inconvenience. Please, at the moment, launch your script again.

Powered By FusionForge