Python库 | mayavi-4.4.4.tar.gz

===================================== An Introduction to Traited VTK (tvtk) ===================================== :Author: Prabhu Ramachandran :Contact: prabhu@enthought.com :Copyright: 2004-2012, Enthought, Inc. .. contents:: Introduction ============ The tvtk module (also called TVTK) provides a traits_ enabled version of VTK_. TVTK objects wrap around VTK objects but additionally support traits_, and provide a convenient Pythonic API. TVTK is implemented mostly in pure Python (except for a small extension module). Here is a list of current features. * All VTK classes are wrapped. * Classes are generated at install time on the installed platform. * Support for traits_. * Elementary pickle support. * Pythonic feel. * Handles numpy arrays/Python lists transparently. * Support for a pipeline browser, `ivtk` and a high-level `mlab` like module. * Envisage plugins for a tvtk scene and the pipeline browser. * tvtk is free software with a BSD style license. .. _traits: http://www.enthought.com/traits .. _VTK: http://www.vtk.org Requirements ============ The following is a list of requirements for you to be able to run tvtk. * Python-2.3 or greater. * Python should be built with zlib support and must support ZIP file imports. * VTK-5.x, VTK-4.4 or VTK-4.2. It is unlikely to work with VTK-3.x. * Traits, version 2. * numpy -- Any recent version should be fine. * To use `ivtk.py`, `mlab` you need to have `pyface` installed. * To use the plugins you need Envisage installed. Installation ============ TVTK is meant to be installed as part of the `enthought` package. The `setup_tvtk.py` file sets up TVTK. So installing the `enthought` package should also install tvtk for you. For an inplace build of the Enthought tool suite please read: `inplace build of the Enthought tool suite`_. This document only covers building and using TVTK from inside a checkout of the the enthought SVN_ repository. The tvtk module lives inside `tvtk`. To build the tvtk module and use them from inside the `enthought` sources do the following from the base of the enthought source tree (we assume here that this is in `/home/svn/enthought/src/lib/enthought`):: $ pwd /home/svn/enthought/src/lib/enthought $ cd tvtk $ python setup_tvtk.py build_ext --inplace The code generation will take a bit of time. On a PentiumIII machine at 450Mhz, generating the code takes about a minute. If the code generation was successful you should see a ZIP file called `tvtk_classes.zip` in the tvtk directory along with an extension module. This completes the installation. The build can be tested by running the tests in the `tests/` directory. This tests the built code:: $ pwd /home/svn/enthought/tvtk $ cd tests $ python test_tvtk.py [...] If the tests run fine, the build is good. There are other tests in the `tests` directory that can also be run. Documentation is available in the 'doc/' directory. The 'examples/' directory contains a few simple examples demonstrating tvtk in action. .. _SVN: http://subversion.tigris.org .. _inplace build of the Enthought tool suite: http://enthought.com/enthought/wiki/GrabbingAndBuilding Basic Usage =========== An example of how tvtk can be used follows:: >>> from tvtk.api import tvtk >>> cs = tvtk.ConeSource() >>> cs.resolution = 36 >>> m = tvtk.PolyDataMapper() >>> m.input = cs.output >>> a = tvtk.Actor() >>> a.mapper = m >>> p = a.property >>> p.representation = 'w' >>> print p.representation 'wireframe' Or equivalently:: >>> from tvtk.api import tvtk >>> cs = tvtk.ConeSource(resolution=36) >>> m = tvtk.PolyDataMapper(input=cs.output) >>> p = tvtk.Property(representation='w') >>> a = tvtk.Actor(mapper=m, property=p) Note that the properties of the object can be set during the instantiation. To import tvtk please use:: from tvtk.api import tvtk While this is perhaps a little inconvenient, note that tvtk provides access to all the VTK classes. This is the same way that the `vtk` package also behaves. If you are familiar with VTK-Python it is clear from the above example that tvtk "feels" like VTK but is more Pythonic. The most important differences are. 1. tvtk class names are essentially similar to VTK classes except there is no annoying 'vtk' at the front. The only difficulty is with classes that start with a digit. For example 'vtk3DSImporter' becomes '3DSImporter'. This is illegal in Python and therefore the class name used is 'ThreeDSImporter'. So, if the first character is a digit, it is replaced by an equivalent non-digit string. There are very few classes like this so this is not a big deal. 2. tvtk method names are `enthought` style names and not CamelCase. That is, if a VTK method is called `AddItem`, the equivalent tvtk name is `add_item`. This is done for the sake of consistency with names used in the `enthought` package. 3. Many VTK methods are replaced by handy properties. In the above example, we used `m.input = cs.output` and `p.representation = 'w'` instead of what would have been `m.SetInput(cs.GetOutput())` and `p.SetRepresentationToWireframe()` etc. Some of these properties are really traits_. 4. Unlike VTK objects, one can set the properties of a tvtk object when the object is initialized by passing the properties (traits) of the object as keyword arguments at the time of class instantiation. For example `cs = tvtk.ConeSource(radius=0.1, height=0.5)`. If you are used to VTK, this might take a little getting used to. However, these changes are consistent across all of tvtk. If they aren't, its a bug. Please let me know if you see inconsistencies. If the underlying VTK object returns another VTK object, this is suitably wrapped as a tvtk object. Similarly, all relevant parameters for a tvtk method should be tvtk objects, these are transparently converted to VTK objects. Advanced Usage ============== There are several important new features that tvtk provides in addition to the above. A tvtk object basically wraps around a VTK-Python object and provides a trait enabled API for the VTK object. Before we discuss these new features it is important to understand the notion of what we mean by the "basic state" or "state" of a tvtk object. This is defined and subsequently the new features are discussed in some detail. .. _state: Definition of the "basic state" of a tvtk object ------------------------------------------------ In tvtk the set of all properties of the VTK object that are represented as traits and have for their value a simple Python type (int/float/string) or a special value (like a tuple specifying color) define the state. In terms of the implementation of tvtk, any property of a VTK object that can be set by using methods having the form `<Property>On` or `<Property>Off`, `Set<Property>To<Value>` and `Set/Get<Property>` (where the return type is an int/float/string/tuple) are represented as traits. These properties are said to represent the "basic state" of the tvtk object. Note that the complete state of the underlying C++ object is impossible to represent in the Python world since this usually involves various pointers to other C++ objects. The wrapped VTK object ----------------------- The user should not ordinarily know this (or rely on this!) but it sometimes helps to know how to access the underlying VTK object that the tvtk object has wrapped. The recommended way to do this is by using the `to_vtk` function. For example:: >>> pd = tvtk.PolyData() >>> pd_vtk = tvtk.to_vtk(pd) The inverse process of creating a tvtk object from a VTK object is to use the `to_tvtk` function like so:: >>> pd1 = tvtk.to_tvtk(pd_vtk) >>> print pd1 == pd True Notice that `pd1 == pd`. TVTK maintains an internal cache of existing tvtk objects and when the `to_tvtk` meth