Useful Python Modules

Useful Python Modules
Prev	Chapter 4. Using MayaVi from Python	Next

This section describes some other useful modules that are released as part of MayaVi but are not necessarily part of the core MayaVi module/application. The module ivtk is described in the next section. The MayaVi package also contains a sub-package called tools. This directory contains miscellaneous but useful tools that use or are related to MayaVi. This is described subsequently.

The Interactive VTK module

It is very nice to be able to use and experiment with VTK from the Python interpreter. In order to make this easier I've written a simple module that uses some of the MayaVi classes. This makes using VTK from Python very pleasant. The module is called ivtk which stands for interactive VTK. ivtk provides the following features.

An easy to use VTK actor viewer that has menus to save the scene, change background, show a help browser, show a pipeline browser etc.
A simple class documentation search tool/browser that lets you search for arbitrary strings in the VTK class documentation and lets you browse the VTK class documentation.
An easy to use GUI to configure VTK objects using the vtkPipeline.ConfigVtkObj module.
An integrated picker that can be activated by pressing the p or P keys. This picker functions the same way as the MayaVi picker.
An integrated light configuration kit that can be activated by pressing the l or L keys. This light configuration functions the same way as the MayaVi light kit.

The help browser allows one to search for arbitrary strings in the VTK class documentation. 'and' and 'or' keywords are supported and this makes searching for specific things easier. If a search is successful a list of matching classes is returned. Clicking on a class will pop up a window with the particular class documentation. It is also possible to search for a particular class name. All classes matching the searched name will be shown. The searching is case insensitive.

Here is a sample session that illustrates how ivtk can be used. A simple cone example is shown.

>>> from mayavi import ivtk
>>> from vtk import *
>>> c = vtkConeSource()
>>> m = vtkPolyDataMapper()
>>> m.SetInput(c.GetOutput())
>>> a = vtkActor()
>>> a.SetMapper(m)
>>> v = ivtk.create_viewer() # or ivtk.viewer()
# this creates the easy to use render window that can be used from
# the interpreter.  It has several useful menus.

>>> v.AddActors(a)    # add actor(s) to viewer
>>> v.config(c)       # pops up a GUI configuration for object.
>>> v.doc(c)          # pops up class documentation for object.
>>> v.help_browser()  # pops up a help browser where you can search!
>>> v.RemoveActors(a) # remove actor(s) from viewer.

The AddActors/RemoveActors method can be passed a list/tuple or a single actor. All of the passed actors will be added/removed to the vtkRenderWindow . The config method provides an easy to use GUI to configure the passed VTK object. The viewer also provides menus to save the rendered scene and also provides a menu to open a VTK Pipeline browser that can be used to browse the VTK pipeline and configure objects in it.

Even without creating the actor viewer it is possible to use the help browser and the configure code as shown below.

>>> from mayavi import ivtk
>>> d = ivtk.doc_browser()
# pops up a standalone searcheable VTK class help browser.
>>> from vtk import *
>>> c = vtkConeSource()
>>> ivtk.doc(c)            # pops up class documentation for c
>>> ivtk.doc('vtkObject')  # class documentation for vtkObject.
>>> ivtk.config(c)         # configure object with GUI.

The module is fairly well documented and one should look at the module for more information. However, the above information should suffice if one wants to start using the module.

The MayaVi `tools` sub-package

MayaVi has a tools sub-package that contains useful modules that use or are related to MayaVi. The following modules are present currently.

The `imv` package

The imv module provides Matlab-like one liners that make it easy to visualize data from the Python interpreter. It currently provides three useful functions. These are partially described below. A simple example is also provided below that. The imv module is well documented so please read the documentation strings in the module for more details.

surf(x, y, f): This samples the function or 2D array f along x and y and plots a 3D surface.
view(arr): Views 2D arrays as a structured points dataset. The view is set to the way we usually think of matrices with (0,0) at the top left of the screen.
viewi(arr): Views 2D arrays as a structured points dataset. The data is viewed as an image. This function is meant to be used with large arrays. For smaller arrays one should use the more powerful view() function. The implementation of this function is a bit of a hack and many of MayaVi's features cannot be used. For instance you cannot change the lookup table color and expect the color of the image to change.
sampler(xa, ya, func): Samples a function (func) at an array of ordered points (with equal spacing) and returns an array of scalars as per VTK's requirements for a structured points data set, i.e. x varying fastest and y varying next.

Here is a simple example of what can be done with the imv module.

>>> from Numeric import *
>>> from mayavi.tools import imv

>>> # surf example.
>>> def f(x, y):
...   return sin(x*y)/(x*y)
>>> x = arange(-5., 5.05, 0.05)
>>> y = arange(-5., 5.05, 0.05)
>>> v = imv.surf(x, y, f)

>>> # view/viewi example.
>>> z1 = fromfunction(lambda i,j:i+j, (128,256))
>>> v1 = imv.view(z1)

>>> z2 = fromfunction(lambda i,j:i+j, (512, 512))
>>> v2 = imv.viewi(z2)