VTK/Python Wrapping FAQ: Difference between revisions
From KitwarePublic
< VTK
Jump to navigationJump to search
(Added example code to mix VTK Python wrappers with Boost.Python wrapped code, which uses VTK objects) |
|||
| (19 intermediate revisions by 4 users not shown) | |||
| Line 2: | Line 2: | ||
=== Big Picture === | === 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 | 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. 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 === | === Python Versions === | ||
The VTK master branch is regularly tested with Python 2.7 and 3.4, and VTK 7 should work with 2.5, 2.6, 2.7, and 3.2+. Versions of VTK prior to 7.0 will only work with Python 2. | |||
=== Organization === | === Organization === | ||
| Line 23: | Line 21: | ||
=== Documentation === | === Documentation === | ||
The VTK module for the vtk Python package is all in Wrapping/Python/vtk. | |||
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 === | === C++ that won't be wrapped === | ||
Information about what kinds of VTK class methods can or cannot be wrapped is provided by the [https://gitlab.kitware.com/vtk/vtk/blob/master/Wrapping/Python/README.md README] file in the VTK/Wrapping/Python directory. Recent progress on the wrappers is described on the [[VTK/Python_Wrapper_Enhancement |python wrapper enhancements]] page. | |||
== CMake's role == | == CMake's role == | ||
| Line 59: | Line 33: | ||
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). | 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 === | === CMake Macros (only valid for VTK 6 and VTK 7) === | ||
1. | 1. vtk_wrap_python3(${NAME}Python KitPython_SRCS "${WRAP_LIST}") | ||
Will wrap the c++ files in WRAP_LIST into python, outputting a list of | Will wrap the c++ files in WRAP_LIST into python, outputting a list of | ||
transformed files into KitPython_SRCS. | transformed files into KitPython_SRCS. | ||
2. | 2. add_library(${NAME}PythonD ${KitPython_SRCS} ${Kit_PYTHON_EXTRA_SRCS}) | ||
Will take those outputs, and some optional additional ones, and create | Will take those outputs, and some optional additional ones, and create | ||
a library. | a library. | ||
3. | 3. python_add_module(${NAME}Python ${NAME}PythonInit.cxx) | ||
Will produce a python module that links in the library so that the | Will produce a python module that links in the library so that the | ||
wrapped code is more easily callable via python. | wrapped code is more easily callable via python. | ||
| Line 75: | Line 49: | ||
=== Excluding files from being wrapped === | === Excluding files from being wrapped === | ||
For VTK 7 onwards, you can tell the wrapper to ignore certain files by using this in your CMakeLists.txt: | |||
set_source_files_properties( | |||
vtkMyUnwrappableClass.cxx | |||
WRAP_EXCLUDE_PYTHON | |||
) | |||
For earlier versions of VTK, you exclude a class globally from wrapping with WRAP_EXCLUDE (which also excludes it from Java and Tcl wrapping). Or, to wrap a class only in Python but not Java or Tcl, you would mark it as WRAP_EXCLUDE and also as WRAP_SPECIAL. (The WRAP_SPECIAL property is deprecated from VTK 7 onwards). | |||
set_source_files_properties( | |||
vtkMyClassWrappableInPython.cxx | |||
WRAP_EXCLUDE | |||
) | |||
set_source_files_properties( | |||
vtkMyClassWrappableInPython.cxx | |||
PROPERTIES WRAP_SPECIAL 1 | |||
) | |||
Latest revision as of 23:21, 17 December 2019
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. 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
The VTK master branch is regularly tested with Python 2.7 and 3.4, and VTK 7 should work with 2.5, 2.6, 2.7, and 3.2+. Versions of VTK prior to 7.0 will only work with Python 2.
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 file in the VTK/Wrapping/Python directory. Recent progress on the wrappers is described on the python 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 (only valid for VTK 6 and VTK 7)
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
For VTK 7 onwards, you can tell the wrapper to ignore certain files by using this in your CMakeLists.txt:
set_source_files_properties( vtkMyUnwrappableClass.cxx WRAP_EXCLUDE_PYTHON )
For earlier versions of VTK, you exclude a class globally from wrapping with WRAP_EXCLUDE (which also excludes it from Java and Tcl wrapping). Or, to wrap a class only in Python but not Java or Tcl, you would mark it as WRAP_EXCLUDE and also as WRAP_SPECIAL. (The WRAP_SPECIAL property is deprecated from VTK 7 onwards).
set_source_files_properties( vtkMyClassWrappableInPython.cxx WRAP_EXCLUDE ) set_source_files_properties( vtkMyClassWrappableInPython.cxx PROPERTIES WRAP_SPECIAL 1 )
