Notes on the Python Wrappers for VTK

Latest Revision: Dec 8, 2000
Refers to VTK version 3.2


Introduction:
============

All of the classes derived from vtkObject are available from python
via the vtkpython module.  The vtkpython module built if --with-python
is specified when VTK is built under UNIX.  The vtkpython module also
comes as part of the Windows (TM) install of VTK.

The vtkpython module defines two new vtk types: a vtkclass type and 
a vtkobject type.  These correspond, respectively, to C++ classes
derived from vtkObject and to instances of those classes.


Special vtkobject attributes:
============

 o.__class__     the vtkclass that this object is an instance of
 o.__doc__       a description of the class (obtained from C++ header file)
 o.__methods__   list of all methods of this object
 o.__members__   list of all attributes of this object
 o.__this__      a string containing the address of the VTK object


Special method attributes:
============

 m.__doc__       a description of the method (obtained from C++ header file)


Special vtkclass attributes:
============

 c.__bases__     a tuple of base classes for this class (empty for vtkObject)
 c.__doc__       a description of the class (obtained from C++ header file)
 c.__methods__   methods of this class (not including inherited methods)
 c.__members__   list of all attributes of this class
 c.__name__      the name of the class, same as returned by GetClassName()

When you call a class method, you must provide an instance of that class
as the first argument unless the method is declared static in C++:

 static method:   vtkMath.Dot((1,2,3),(3,4,5))
 non-static:      vtkObject.GetMTime(obj)

Note that the concept of 'static' does not exist in Python, so special
treatment of static methods might have to be removed if vtkclass objects
are eventually made to be compatible with Python class objects.

When you instantiate a class, you can provide a hexidecimal string
containing the address of an existing vtk object, e.g.
   t = vtkTransform('_1010e068_vtkTransform_p')
The string follows SWIG mangling conventions.  If a wrapper for the
specified object already exists, then that wrapper will be used rather
than a new wrapper being created.  If you want to use this feature
of vtkpython, please think twice.


Differences between VTK in C++ and Python:
============

For the most part, using VTK from Python is the same as using VTK from
C++, except that objects are created using the syntax

    o = vtkObject()     rather than          vtkObject *o = vtkObject::New()

and access of methods is done using

    o.Method()           rather than         o->Method()

Some other important differences are that Python tuples are converted
to C++ const arrays e.g.

    (float,float,float)   is equivalent to   const float[3]

and (almost vice-versa) if and only if an entry for a method appears in
the vtk/wrap/hints file or if the method is defined via a vtkGetArray
macro then a returned C++ pointer is converted to a Python tuple:

    (float,float,float)   is equivalent to   float * (plus hint)

The python None is equivalent to the C++ NULL, i.e. if a VTK C++ method
returns a NULL vtkObject * or a NULL char *, then the pointer will be
converted to None: 

    None                  is equivalent to   NULL

Perhaps one of the most pleasant features of Python is that all 
type-checking is performed at run time, and type casts are therefore
never necessary.

Finally, a C++ method that requires a void * can be passed a Python
string.  No check is done to ensure that the string is the correct
size, and the string's reference count is not incremented.  Extreme
caution should be applied when using this feature.


Unavailable methods
============

A C++ method is not available from Python if
1) its parameter list contains a pointer/reference that is not a 
   pointer/reference to a vtkObject
2) its parameter list contains an array that is not 'const'
3) it returns a pointer/reference that is not a pointer/reference
   to a vtkObject and there is no entry in the file vtk/wrap/hints
4) it is an operator method


Unavailable classes
============

All classes that are not derived from vtkObject are not available
from python.  This includes vtkTimeStamp, vtkIndent, and some others.


Viewing VTK documentation within Python
============

Obtaining VTK documentation during an interactive Python session is easy.

    print vtkobject.__doc__             documentation for the class

    print vtkobject.method.__doc__      documentation for a method

The documentation might be truncated if it is very long (longer than
around 1000 characters).   You can obtain exactly the same documentation
from either a vtkclass, or from a vtkobject that was instantiated from
that class.

You can also use the .__methods__ attribute to get all methods of a
vtkobject or a vtkclass.  


Printing VTK objects 
============

Printing a vtk object will provide the same information as provided
by the vtkObject::Print() method (i.e. the values of all instance variables)
The same information is provided by calling str(obj).  A more compact
representation of the object is available by calling repr(obj)

  repr(obj)  ->  '<vtkclass libVTKCommonPython.vtkObject at 100c8d48>'

(under Windows (TM), 'libVTKCommonPython' is replaced by 'vtkpython').


Deriving python classes from VTK classes
============

The short answer is that this is not possible with this version of VTK.
However, you can do something that is nearly equivalent by using the
special method __gettattr__ as demonstrated below, and then defining
any methods that you want to override.

class vtkMyImageReader:

    def __init__(self):
        pass 

    def __getattr__(self,attr):
        # get methods from the vtkobject
        try:
            vtkobject = self.__dict__['__vtkobject__']
        except KeyError:
            vtkobject = vtkImageReader()
            self.__dict__['__vtkobject__'] = vtkobject
        if attr == '__vtk__':
            return lambda t=vtkobject: t
        return getattr(vtkobject,attr)

    def SetFileName(self,filename):
        # override SetFileName method
        f = open(filename,'r+')

        # add code here to read the file header, and
        # set up the vtkImageReader parameters

        f.close()

        # call method from parent class, if necessary
        vtkImageReader.SetFileName(self,filename)

This isn't quite the same a deriving from a vtk class because virtual
methods are not properly honored.  Note that __vtk__() is a special
method that allows a python object to be converted to a vtkobject.


A few examples
============

Each of the graphics, imaging, and contrib directories in the vtk source
package contain an examplesPython directory with several examples.  These
examples are not tested very often, so not all of them are guaranteed to
work.  They do, however, cover most of VTK's functionality.

There are also examples in the python directory.  The most important of
these are vtkRenderWidget.py, which demonstrates how to use Tkinter with
VTK.


END OF FILE

