VTK/Python Wrapping FAQ: Difference between revisions

From KitwarePublic
< VTK
Jump to navigationJump to search
Line 26: Line 26:
The VTK module for the vtk Python package is all in Wrapping/Python/vtk.  Individual classes can be inspected with the python "help()" function, e.g. help(vtk.vtkObject).
The VTK module for the vtk Python package is all in Wrapping/Python/vtk.  Individual classes can be inspected with the python "help()" function, e.g. help(vtk.vtkObject).


=== C++ that won't be wrapped <span style="color:#aa0000">(Obsolete Information)</span> ===
=== C++ that won't be wrapped ===
Note: this list refers to VTK releases 5.6 and earlier.  For the development version of VTK, see the page on [[VTK/Python_Wrapper_Enhancement |python wrapper enhancements]].


* Templates
Information about what kinds of VTK class methods can or cannot be wrapped is provided by the [http://vtk.org/gitweb?p=VTK.git;a=blob;f=Wrapping/Python/README_WRAP.txt README_WRAP.txt] file in the VTK/Wrapping/Python directoryRecent progress on the wrappers is described on the[[VTK/Python_Wrapper_Enhancement |python wrapper enhancements]] page.
 
* Abstract classes - these are wrapped, and their static methods can be used, but they cannot be instantiated
 
Because they can't be directly instantiated. Abstract classes are identified as such by putting them in a named list in cmakelist.txt.
 
* Anything marked as wrap exclude
This is also done via a named list in cmakelist.txt.
 
* Anything put between //BTX and //ETX in the header file
 
* Methods that take or return unbounded pointers
 
Methods like "GetTupleValue(int i, double *tuple)" aren't wrapped in
python unless they have a signature like GetTupleValue(int i, double
tuple[3]) so that the wrappers know how large the array is.
 
Likewise, methods like "double *GetTuple(int i)" aren't wrapped
unless there is a hint so that the wrappers know how many values will
be returned.
 
The wrappers don't do anything fancy like check how many components an
array has in order to find out what size of tuple to use.  The
wrapping of a method is determined only by the method signature and
the hints in VTK/Wrapping/hints.


== CMake's role ==
== CMake's role ==

Revision as of 02:33, 4 September 2014

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.

Python Versions

Currently (Aug 2010), VTK is regularly tested with Python 2.5 and Python 2.6, and it should work with all Python 2.x versions. Python 1.x is no longer supported, the wrappers might compile but the examples will definitely not run under Python 1.x.

Python 3 support is planned, but there is no date set. This version of Python has introduced two very significant changes to the Python-C API that will require changes to the VTK wrapper code. Fortunately the Python 3 API is similar enough to the Python 2 API that it will be possible to support both at the same time (just as numpy does). The hardest part will be to make sure that all the tests and examples run under both Python 2 and Python 3, as the Python language itself has changed more significantly than its C API.

Organization

  • First look in VTK/Wrapping. Go over the files there. Specifically look at vtkWrapPython.c which actually does the code generation for Python.
  • When VTK is built, an executable called vtkWrapPython is built from this.
  • vtkWrapPython generates the Python wrappers for each wrappable VTK header and this is built to generate the Python wrapper.
  • The wrapper code makes use of Wrapping/Python/vtkPythonUtil.h and several other C and C++ files in Wrapping/Python 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
  • 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. Individual classes can be inspected with the python "help()" function, e.g. help(vtk.vtkObject).

C++ that won't be wrapped

Information about what kinds of VTK class methods can or cannot be wrapped is provided by the README_WRAP.txt file in the VTK/Wrapping/Python directory. Recent progress on the wrappers is described on thepython wrapper enhancements page.

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
)

Other Topics

Using VTK objects in code wrapped with Boost.Python

Example from and to python converters