VTK/Python Wrapping FAQ

VTK Python Wrapping System

Big Picture

All the automated wrapping code generation relies on the consistent coding style followed in the VTK header files and the use of the convenience macros. Specific markers (in comments) in the header mark parts that are not to be parsed (BTX/ETX). Basically, a target language specific parser parses the header file figures out suitable wrapper functions in the desired target language and spits out the wrapper code that is used to generate the wrappings.

Organization

1. First look in VTK/Wrapping.  Go over the files there.  Specifically look at vtkWrapPython.c which actually does the code generation for Python.
2. When VTK is built, an executable called vtkWrapPython is built from this.
3. vtkWrapPython generates the Python wrappers for each wrappable VTK header and this is built to generate the Python wrapper.
4. The wrapper code makes use of Common/vtkPython.h Common/vtkPythonUtil.cxx  and Common/vtkPythonUtil.h for various things. Also note that Wrapping/hints is a mechanism for helping the wrapper code with, err, hints to help the wrapping process along.  To see what the individual codes represent see Wrapping/vtkParse.y and vtkParse.tab.c
5. The VTK module for the vtk Python package is all in Wrapping/Python/vtk.

Documentation

The VTK module for the vtk Python package is all in Wrapping/Python/vtk. There is a rambling README in Wrapping/Python that might be of some use. There is also a nice README_WRAP.txt in the same directory that is useful.

C++ that won't be wrapped

1. Templates

CMake's role

Big Picture

I think all CMake does is to build the parser and organize the building of the generated code, link it correctly (which can be a bloody pain) etc. I don't think it directly does anything regarding the wrapper generation process. Any useful CMake macros are best gleaned by looking at CMake files (at least thats how I used to do it).

CMake Macros

1. VTK_WRAP_PYTHON3(${NAME}Python KitPython_SRCS "${WRAP_LIST}")

Will wrap the c++ files in WRAP_LIST into python, outputting a list of transformed files into KitPython_SRCS.

2. ADD_LIBRARY(${NAME}PythonD ${KitPython_SRCS} ${Kit_PYTHON_EXTRA_SRCS})

Will take those outputs, and some optional additional ones, and create a library.

3. PYTHON_ADD_MODULE(${NAME}Python ${NAME}PythonInit.cxx)

Will produce a python module that links in the library so that the wrapped code is more easily callable via python.

That is what ParaView's WRAP_PLUGIN_FOR_PYTHON macro does anyway.

Excluding files from being wrapped

You can tell the wrapper to ignore certain files by using this in your CMakeLists.txt:

SET_SOURCE_FILES_PROPERTIES(

vtkMyUnwrappableClass.cxx
WRAP_EXCLUDE

)