/[escript]/trunk/doc/user/pyvisi.tex
ViewVC logotype

Diff of /trunk/doc/user/pyvisi.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 606 by gross, Mon Mar 20 23:34:00 2006 UTC revision 1035 by jongui, Fri Mar 16 04:54:17 2007 UTC
# Line 1  Line 1 
1  \chapter{The module \pyvisi}  \chapter{The module \pyvisi}
2                                                                                                                                                                                                        \label{PYVISI CHAP}
3  \declaremodule{extension}{pyvisi}  \declaremodule{extension}{esys.pyvisi}
4  \modulesynopsis{visualization interface}  \modulesynopsis{Python Visualization Interface}
   
 The idea behind is to provide an easy to use interface and unified to a variety of  
 visualization tools like \VTK, \OpenDX and \GnuPlot.  
   
 The following script illustartes the usage of \pyvisi together with the  
 \VTK library:  
 \begin{python}  
 from esys.pyvisi import *                # base level visualisation stuff  
 from esys.pyvisi.renderers.vtk import *  # vtk renderer module  
 from esys.escript import *  
 from esys.finley import Brick  
 # now make some data of some kind  
 domain = Brick(3,5,7)  # a Finley domain  
 vectorData = domain.getX()  # get vector data from the domain nodes  
 # define the scene object  
 scene = Scene()  
 # create an ArrowPlot object  
 plot = ArrowPlot(scene)  
 # add the plot to the scene  
 scene.add(plot)  
 # assign some data to the plot  
 plot.setData(vectorData)  
 # render the scene  
 scene.render()  
 # saving a scene  
 scene.save(file="example.jpg", format="jpeg")  
 \begin{python}  
 A \Scene is a container for all of the kinds of things you want to put into your plot,  
 for instance, images, domaines, arrow plots, contour plots, spheres etc.  
 The renderer is specified in the scene initialisation. In fact the  
 \code{from esys.pyvisi.renderers.vtk import *} provides the specific implementation for  
 \VTK  
   
   
 \begin{verbose}  
 class ArrowPlot3D(Plot):  
     """  
     Arrow field plot in three dimensions  
     """  
     def __init__(self, scene):  
         """  
         Initialisation of the ArrowPlot3D class  
           
         @param scene: The Scene to render the plot in  
         @type scene: Scene object  
     def setData(self, *dataList, **options):  
         """  
         Set data to the plot  
   
         @param dataList: List of data to set to the plot  
         @type dataList: tuple  
   
         @param options: Dictionary of extra options  
         @type options: dict  
   
         @param fname: Filename of the input vtk file  
         @type fname: string  
   
         @param format: Format of the input vtk file ('vtk' or 'vtk-xml')  
         @type format: string  
   
     @param vectors: the name of the vector data in the vtk file to use  
     @type vectors: string  
         """  
 class ArrowPlot(Plot):  
     """  
     Arrow field plot  
     """  
     def __init__(self, scene):  
         """  
         Initialisation of the ArrowPlot class  
           
         @param scene: The Scene to render the plot in  
         @type scene: Scene object  
         """  
     def setData(self, *dataList, **options):  
         """  
         Set data to the plot  
   
         @param dataList: List of data to set to the plot  
         @type dataList: tuple  
   
     @param options: Dictionary of extra options  
     @type options: dict  
   
     @param fname: the name of the input vtk file  
     @type fname: string  
   
     @param format: the format of the input vtk file ('vtk' or 'vtk-xml')  
     @type format: string  
   
     @param vectors: the name of the vector data in the vtk file to use  
     @type vectors: string  
         """  
 class Axes(Plot):  
     """  
     Axes class  
     """  
     def __init__(self):  
         """  
         Initialisation of Axes object  
         """  
         debugMsg("Called Axes.__init__()")  
         Plot.__init__(self)  
   
 class BallPlot(Plot):  
     """  
     Ball plot  
     """  
     def __init__(self, scene):  
   
     def setData(self, points=None,  
             fname=None, format=None,  
             radii=None, colors=None, tags=None):  
         """  
         Set data to the plot  
         @param points: the array to use for the points of the sphere  
         locations in space  
         @type points: float array  
   
         @param fname: the name of the input vtk file  
         @type fname: string  
   
         @param format: the format of the input vtk file ('vtk' or 'vtk-xml')  
         @type format: string  
   
         @param radii: the name of the scalar array in the vtk unstructured  
         grid to use as the radii of the balls  
         @type radii: float array  
   
         @param colors: the name of the scalar array in the vtk unstructured  
         grid to use as the colour tags of the balls  
         @type colors: string  
   
         @param tags: the name of the scalar array in the vtk unstructured  
         grid to use as the colour of the tags of the balls  
         @type tags: integer array  
         """  
   
 class Box(Item):  
     """  
     Generic class for Box objects  
   
     To define a box one specify one of three groups of things:  
       - The bounds of the box: xmin, xmax, ymin, ymax, zmin, zmax  
       - The dimensions and origin: width, height, depth and origin  
       - The bottom left front and top right back corners: blf, trb  
     """  
   
     def __init__(self):  
         """  
         Initialisation of the Box object  
         """  
         debugMsg("Called Box.__init__()")  
         Item.__init__(self)  
   
         # define a box in many ways, either by its centre and width, height  
         # and depth, or by its bounds, xmin, xmax, ymin, ymax, zmin, zmax,  
         # or by its bottom left front and top right back points.  
   
         # set the default bounds  
         self.xmin = -0.5  
         self.xmax = 0.5  
         self.ymin = -0.5  
         self.ymax = 0.5  
         self.zmin = -0.5  
         self.zmax = 0.5  
   
         # set the default origin (the centre of the box)  
         self.origin = ((self.xmin + self.xmax)/2.0,  
                 (self.ymin + self.ymax)/2.0,  
                 (self.zmin + self.zmax)/2.0)  
   
         # set the default dimensions  
         self.width = self.xmax - self.xmin  
         self.height = self.ymax - self.ymin  
         self.depth = self.zmax - self.zmin  
   
         # set the default blf and trb points  
         self.blf = (self.xmin, self.ymin, self.zmin)  
         self.trb = (self.xmax, self.ymax, self.zmax)  
   
         # tolerance for calculated variables checking purposes  
         self.tolerance = 1e-8  
   
     def setBounds(self, xmin, xmax, ymin, ymax, zmin, zmax):  
         """  
         Set the bounds of the box  
         """  
     def getBounds(self):  
         """  
         Get the current bounds of the box  
         """  
   
     def setOrigin(self, xo, yo, zo):  
         """  
         Set the origin of the box  
         """  
     def getOrigin(self):  
         """  
         Get the current origin of the box  
         """  
         debugMsg("Called Box.getOrigin()")  
         return self.origin  
   
     def setWidth(self, width):  
         """  
         Set the width of the box  
         """  
     def getWidth(self):  
         """  
         Get the current box width  
         """  
         debugMsg("Called Box.getWidth()")  
         return self.width  
   
     def setHeight(self, height):  
         """  
         Set the box height  
         """  
   
     def getHeight(self):  
         """  
         Get the current box height  
         """  
         debugMsg("Called Box.getHeight()")  
         return self.height  
   
     def setDepth(self, depth):  
         """  
         Set the box depth  
         """  
   
     def getDepth(self):  
         """  
         Get the current box depth  
         """  
         debugMsg("Called Box.getDepth()")  
         return self.depth  
   
     def setBLF(self, bottom, left, front):  
         """  
         Set the position of the bottom, left, front corner  
         """  
   
     def getBLF(self):  
         """  
         Get the current position of the bottom, left, front corner  
         """  
         debugMsg("Called Box.getBLF()")  
         return self.blf  
   
     def setTRB(self, top, right, back):  
         """  
         Set the position of the top, right, back corner  
         """  
   
     def getTRB(self):  
         """  
         Get the current position of the top, right, back corner  
         """  
         debugMsg("Called Box.getTRB()")  
         return self.trb  
   
   
 class ClipBox(Box):  
     """  
     Clip box class: used to clip data sets with a box  
   
     A box in this sense means three planes at right angles to one another  
     """  
   
     def __init__(self, plot):  
         """  
         Intialisation of the ClipBox object  
         """  
   
     def setInsideOut(self, insideOut):  
         """  
         Set the inside out flag  
         """  
   
     def getInsideOut(self):  
         """  
         Get the current value of the inside out flag  
         """  
   
 class Camera(Item):  
     """  
     Camera class  
     """  
     def __init__(self, scene):  
         """  
         Initialisation of the Camera object  
   
         @param scene: The Scene object to add the Camera object to  
         @type scene: Scene object  
         """  
     def setPosition(self, *pos):  
         """  
         Set position of camera within scene  
   
         @param pos: Position to set camera in terms of x,y,z coordinates  
         @type pos: tuple  
         """  
   
     def getPosition(self):  
         """  
         Get the position of Camera within Scene  
   
         Returns the position in a tuple of form (xPos, yPos, zPos)  
         """  
         debugMsg("Called Camera.getPosition()")  
   
         return (self.xPos, self.yPos, self.zPos)  
   
     def setFocalPoint(self, *pos):  
         """  
         Sets the focal point of the Camera with the Scene  
   
         @param pos: Position to set the focal point  
         @type pos: tuple  
         """  
   
     def getFocalPoint(self):  
         """  
         Get the position of the focal point of the Camera  
   
         Returns the position of the focal point in a tuple of form  
         (xPos, yPos, zPos)  
         """  
   
     def setElevation(self, elevation):  
         """  
         Set the elevation angle (in degrees) of the Camera  
   
         @param elevation: The elevation angle (in degrees) of the Camera  
         @type elevation: float  
         """  
   
         return  
   
     def getElevation(self):  
         """  
         Gets the elevation angle (in degrees) of the Camera  
         """  
   
     def setAzimuth(self, azimuth):  
         """  
         Set the azimuthal angle (in degrees) of the Camera  
   
         @param azimuth: The azimuthal angle (in degrees) of the Camera  
         @type azimuth: float  
         """  
   
     def getAzimuth(self):  
         """  
         Get the azimuthal angle (in degrees) of the Camera  
         """  
 class ContourPlot(Plot):  
     """  
     Contour plot  
     """  
     def __init__(self, scene):  
         """  
         Initialisation of the ContourPlot class  
           
         @param scene: The Scene to render the plot in  
         @type scene: Scene object  
         """  
     def setData(self, *dataList, **options):  
         """  
         Set data to the plot  
   
         @param dataList: List of data to set to the plot  
         @type dataList: tuple  
   
         @param options: Dictionary of extra options  
         @type options: dict  
   
         @param fname: the name of the input vtk file  
         @type fname: string  
   
         @param format: the format of the input vtk file ('vtk' or 'vtk-xml')  
         @type format: string  
   
         @param scalars: the scalar data in the vtk file to use  
         @type scalars: string  
         """  
   
 class EllipsoidPlot(Plot):  
     """  
     Ellipsoid plot  
     """  
     def __init__(self, scene):  
         """  
         Initialisation of the EllipsoidPlot class  
   
         @param scene: The Scene to render the plot in  
         @type scene: Scene object  
         """  
         debugMsg("Called EllipsoidPlot.__init__()")  
         Plot.__init__(self, scene)  
   
         self.renderer = scene.renderer  
         self.renderer.addToInitStack("# EllipsoidPlot.__init__()")  
   
         # labels and stuff  
         self.title = None  
         self.xlabel = None  
         self.ylabel = None  
         self.zlabel = None  
           
         # default values for fname, format and tensors  
         self.fname = None  
         self.format = None  
     self.tensors = None  
   
     # default values for shared info  
     self.escriptData = False  
     self.otherData = False  
   
         # add the plot to the scene  
         scene.add(self)  
   
     def setData(self, *dataList, **options):  
         """  
         Set data to the plot  
   
         @param dataList: List of data to set to the plot  
         @type dataList: tuple  
   
         @param options: Dictionary of keyword options to the method  
         @type options: dict  
   
     @param fname: the name of the input vtk file  
     @type fname: string  
   
     @param format: the format of the input vtk file ('vtk' or 'vtk-xml')  
     @type format: string  
   
     @param tensors: the name of the tensor data in the vtk file to use  
     @type tensors: string  
         """  
   
 class Image(Item):  
     """  
     Image class.  Generic class to handle image data.  
     """  
     def __init__(self, scene=None):  
         """  
         Initialises the Image class object  
           
         @param scene: The Scene object to add to  
         @type scene: Scene object  
         """  
         debugMsg("Called Image.__init__()")  
         Item.__init__(self)  
5    
6          if scene is not None:  \section{Introduction}
7              self.renderer = scene.renderer  \pyvisi is a Python module that is used to generate 2D and 3D visualization
8            for escript and its PDE solvers: finley and bruce. This module provides
9      def load(self, fname):  an easy to use interface to the \VTK library (\VTKUrl). There are three forms
10          """  of rendering an object: (1) online: a single rendered object is displayed and  
11          Loads image data from file.  interaction (i.e. zoom and rotate) can occur, (2) offline: multiple rendered
12    objects are not displayed but are instead saved as a series of images. No
13          @param fname: The filename from which to load image data  interaction can occur and (3) animate: similar to offline except that multiple
14          @type fname: string  rendered objects are displayed one after another (animated on-the-fly) and
15          """  no images are saved.  No interaction can occur.
         debugMsg("Called Image.load()")  
   
         fileCheck(fname)  
   
         return  
   
 class JpegImage(Image):  
     """  
     Subclass of Image class to explicitly handle jpeg images  
     """  
     def __init__(self, scene=None):  
         """  
         Initialises the JpegImage class object  
   
         @param scene: The Scene object to add to  
         @type scene: Scene object  
         """  
   
     def load(self, fname):  
         """  
         Loads jpeg image data from file.  
   
         @param fname: The filename from which to load jpeg image data  
         @type fname: string  
         """  
   
 class PngImage(Image):  
     """  
     Subclass of Image class to explicitly handle png images  
     """  
     def __init__(self, scene=None):  
         """  
         Initialises the PngImage class object  
   
         @param scene: The Scene object to add to  
         @type scene: Scene object  
         """  
   
     def load(self, fname):  
         """  
         Loads png image data from file.  
   
         @param fname: The filename from which to load png image data  
         @type fname: string  
         """  
 class BmpImage(Image):  
     """  
     Subclass of Image class to explicitly handle bmp images  
     """  
     def __init__(self, scene=None):  
         """  
         Initialises the BmpImage class object  
   
         @param scene: The Scene object to add to  
         @type scene: Scene object  
         """  
     def load(self, fname):  
         """  
         Loads bmp image data from file.  
   
         @param fname: The filename from which to load bmp image data  
         @type fname: string  
         """  
   
 class TiffImage(Image):  
     """  
     Subclass of Image class to explicitly handle tiff images  
     """  
     def __init__(self, scene=None):  
         """  
         Initialises the TiffImage class object  
   
         @param scene: The Scene object to add to  
         @type scene: Scene object  
         """  
     def load(self, fname):  
         """  
         Loads tiff image data from file.  
   
         @param fname: The filename from which to load tiff image data  
         @type fname: string  
         """  
 class PnmImage(Image):  
     """  
     Subclass of Image class to explicitly handle pnm (ppm, pgm, pbm) images  
     """  
     def __init__(self, scene=None):  
         """  
         Initialises the PnmImage class object  
   
         @param scene: The Scene object to add to  
         @type scene: Scene object  
         """  
           
     def load(self, fname):  
         """  
         Loads pnm (ppm, pgm, pbm) image data from file.  
   
         @param fname: The filename from which to load pnm image data  
         @type fname: string  
         """  
   
 class PsImage(Image):  
     """  
     Subclass of Image class to explicitly handle ps images  
     """  
     def __init__(self, scene=None):  
         """  
         Initialises the PsImage class object  
   
         This object is B{only} used for generating postscript output  
   
         @param scene: The Scene object to add to  
         @type scene: Scene object  
         """  
   
     def load(self, fname):  
         """  
         Loads ps image data from file.  
   
         B{NOT} supported by this renderer module  
   
         @param fname: The filename from which to load ps image data  
         @type fname: string  
         """  
         debugMsg("Called PsImage.load()")  
16    
17          # need to check if the file exists  The general rule of thumb when using \pyvisi is to perform the following
18          fileCheck(fname)  in sequence:
19    
20          # this ability not handled by this renderer module  \begin{enumerate}
21          unsupportedError()  \item Create a scene instance (i.e. \Scene), which is a window in which objects are to be
22            rendered on.
23          return  \item Create an input instance (i.e. \DataCollector), which reads and loads
24    the source data for visualization.
25    \item Create a data visualization instance (i.e. \Map, \Velocity, \Ellipsoid,
26    \Contour and \Carpet), which proccesses and manipulates the source data.
27    \item Create a camera (i.e. \Camera) instance, which controls the viewing angle.
28    \item Lastly, render the object online, offline or animate.
29    \end{enumerate}
30    \begin{center}
31    \begin{math}
32    scene \rightarrow input \rightarrow visualization \rightarrow
33    camera \rightarrow render
34    \end{math}
35    \end{center}
36    
37      def render(self):  The sequence in which instances are created is very important due to
38          """  to the dependencies among them. For example, an input instance must
39          Does PsImage object specific (pre)rendering stuff  always be created BEFORE a data visualisation instance is created.
40          """  If the sequence is switched, the program will throw an error because a
41          debugMsg("Called PsImage.render()")  source data needs to be specified before the data can be
42    manipulated. Similarly, a camera instance must always be created
43          return  AFTER an input instance has been created. Otherwise, the program will throw
44    an error because the camera instance needs to calculate its
45  class PdfImage(Image):  default position (automatically carried out in the background) based on
46      """  the source data.
47      Subclass of Image class to explicitly handle pdf images  
48      """  \section{\pyvisi Classes}
49      def __init__(self, scene=None):  The following subsections give a brief overview of the important classes
50          """  and some of their corresponding methods. Please refer to \ReferenceGuide for
51          Initialises the PdfImage class object  full details.
52    
53          This object is B{only} used for generating pdf output  
54    %#############################################################################
55          @param scene: The Scene object to add to  
56          @type scene: Scene object  
57          """  \subsection{Scene Classes}
58    This subsection details the instances used to setup the viewing environment.
59      def load(self, fname):  
60          """  \subsubsection{\Scene class}
61          Loads pdf image data from file.  
62    \begin{classdesc}{Scene}{renderer = Renderer.ONLINE, num_viewport = 1,
63          B{NOT} supported by this renderer module  x_size = 1152, y_size = 864}
64    A scene is a window in which objects are to be rendered on. Only
65          @param fname: The filename from which to load pdf image data  one scene needs to be created and can display data from one source. However,
66          @type fname: string  a scene may be divided into four smaller windows called viewports (if needed).
67          """  The four viewports in turn can display data from four different sources.
68    \end{classdesc}
69  class IsosurfacePlot(Plot):  
70      """  The following are some of the methods available:
71      Isosurface plot  \begin{methoddesc}[Scene]{setBackground}{color}
72      """  Set the background color of the scene.
73      def __init__(self, scene):  \end{methoddesc}
74          """  
75          Initialisation of the IsosurfacePlot class  \begin{methoddesc}[Scene]{saveImage}{image_name}
76            Save the rendered object as an image offline. No interaction can occur.
77          @param scene: The Scene to render the plot in  \end{methoddesc}
78          @type scene: Scene object  
79          """  \begin{methoddesc}[Scene]{animate}{}
80      def setData(self, *dataList, **options):  Animate the rendered object on-the-fly. No interaction can occur.
81          """  \end{methoddesc}
82          Set data to the plot  
83    \begin{methoddesc}[Scene]{render}{}
84          @param dataList: List of data to set to the plot  Render the object online. Interaction can occur.
85          @type dataList: tuple  \end{methoddesc}
86    
87          @param options: Dictionary of keyword options to the method  \subsubsection{\Camera class}
88          @type options: dict  
89    \begin{classdesc}{Camera}{scene, data_collector, viewport = Viewport.SOUTH_WEST}
90      @param fname: the name of the input vtk file  A camera controls the display angle of the rendered object and one is
91      @type fname: string  usually created for a \Scene. However, if a \Scene has four viewports, then a
92    separate camera may be created for each viewport.
93      @param format: the format of the input vtk file ('vtk' or 'vtk-xml')  \end{classdesc}
94      @type format: string  
95    The following are some of the methods available:
96      @param scalars: the name of the scalar data in the vtk file to use  \begin{methoddesc}[Camera]{setFocalPoint}{position}
97      @type scalars: string  Set the focal point of the camera.
98          """  \end{methoddesc}
99    
100  class LinePlot(Plot):  \begin{methoddesc}[Camera]{setPosition}{position}
101      """  Set the position of the camera.
102      Line plot  \end{methoddesc}
103      """  
104      def __init__(self, scene):  \begin{methoddesc}[Camera]{setClippingRange}{near_clipping, far_clipping}
105          """  Set the near and far clipping plane of the camera.
106          Initialisation of the LinePlot class  \end{methoddesc}
107            
108          @param scene: The Scene to render the plot in  \begin{methoddesc}[Camera]{setViewUp}{position}
109          @type scene: Scene object  Set the view up direction of the camera.
110          """  \end{methoddesc}
111    
112      def setData(self, *dataList, **options):  \begin{methoddesc}[Camera]{azimuth}{angle}
113          """  Rotate the camera to the left and right.
114          Set data to the plot  \end{methoddesc}
115    
116          @param dataList: List of data to set to the plot  \begin{methoddesc}[Camera]{elevation}{angle}
117          @type dataList: tuple  Rotate the camera to the top and bottom (only between -90 and 90).
118    \end{methoddesc}
119      @param options: Dictionary of extra options  
120      @type options: dict  \begin{methoddesc}[Camera]{backView}{}
121    Rotate the camera to view the back of the rendered object.
122      @param offset: whether or not to offset the lines from one another  \end{methoddesc}
123      @type offset: boolean  
124    \begin{methoddesc}[Camera]{topView}{}
125      @param fname: Filename of the input vtk file  Rotate the camera to view the top of the rendered object.
126      @type fname: string  \end{methoddesc}
127    
128      @param format: format of the input vtk file ('vtk' or 'vtk-xml')  \begin{methoddesc}[Camera]{bottomView}{}
129      @type format: string  Rotate the camera to view the bottom of the rendered object.
130    \end{methoddesc}
131      @param scalars: the name of the scalar data in the vtk file to use  
132      @type scalars: string  \begin{methoddesc}[Camera]{leftView}{}
133          """  Rotate the camera to view the left side of the rendered object.
134    \end{methoddesc}
135  class OffsetPlot(Plot):  
136      """  \begin{methoddesc}[Camera]{rightView}{position}
137      Offset plot  Rotate the camera to view the right side of the rendered object.
138      """  \end{methoddesc}
139      def __init__(self, scene):  
140          """  \begin{methoddesc}[Camera]{isometricView}{position}
141          Initialisation of the OffsetPlot class  Rotate the camera to view the isometric angle of the rendered object.
142            \end{methoddesc}
143          @param scene: The Scene to render the plot in  
144          @type scene: Scene object  \begin{methoddesc}[Camera]{dolly}{distance}
145          """  Move the camera towards (greater than 1) and away (less than 1) from
146    the rendered object.
147      def setData(self, *dataList, **options):  \end{methoddesc}
148          """  
149          Set data to the plot  \subsubsection{\Light class}
150    
151          @param dataList: List of data to set to the plot  \begin{classdesc}{Light}{scene, data_collector, viewport = Viewport.SOUTH_WEST}
152          @type dataList: tuple  A light controls the source of light for the rendered object and works in
153    a similar way to \Camera.
154          @param options: Dictionary of extra options  \end{classdesc}
155          @type options: dict  
156    The following are some of the methods available:
157      @param fname: Filename of the input vtk file  \begin{methoddesc}[Light]{setColor}{color}
158      @type fname: string  Set the light color.
159    \end{methoddesc}
160      @param format: Format of the input vtk file ('vtk' or 'vtk-xml')  
161      @type format: string  \begin{methoddesc}[Light]{setFocalPoint}{position}
162    Set the focal point of the light.
163      @param scalars: the name of the scalar data in the vtk file to use  \end{methoddesc}
164      @type scalars: string  
165          """  \begin{methoddesc}[Light]{setPosition}{position}
166  class Plane(Item):  Set the position of the camera.
167      """  \end{methoddesc}
168      Generic class for Plane objects  
169      """  \begin{methoddesc}[Light]{setAngle}{elevation = 0, azimuth = 0}
170    An alternative to set the position and focal point of the light using the
171      def __init__(self, scene):  elevation and azimuth degrees.
172          """  \end{methoddesc}
173          Initialisation of the Plane object  
174          """  
175    %##############################################################################
176      def setOrigin(self, x, y, z):  
177          """  
178          Set the origin of the plane  \subsection{Input Classes}
179          """  This subsection details the instances used to read and load the source data
180    for visualization.
181      def getOrigin(self):  
182          """  \subsubsection{\DataCollector class}
183          Get the current origin of the plane  
184          """  \begin{classdesc}{DataCollector}{source = Source.XML}
185    % need to say something about the escript object not just d xml file.
186      def setNormal(self, vx, vy, vz):  A data collector is used to read data from an XML file or from
187          """  an escript object directly. Please note that a separate data collector needs
188          Set the normal vector to the plane  to be created when two or more attributes of the same type from
189          """  the same file needs to be specified (i.e.two scalar attributes from a file).
190    \end{classdesc}
191      def getNormal(self):  
192          """  The following are some of the methods available:
193          Get the current normal vector to the plane  \begin{methoddesc}[DataCollector]{setFileName}{file_name}
194          """  Set the XML source file name to be read.
195    \end{methoddesc}
196      def mapImageToPlane(self, image):  
197          # this really needs to go somewhere else!!!  \begin{methoddesc}[DataCollector]{setData}{**args}
198          """  Create data using the \textless name\textgreater=\textless data\textgreater
199          Maps an Image object onto a Plane object  pairing. Assumption is made that the data will be given in the
200          """  appropriate format.
201    \end{methoddesc}
202  class CutPlane(Plane):  
203      """  \begin{methoddesc}[DataCollector]{setActiveScalar}{scalar}
204      Cut plane class: used to cut data sets with a plane  Specify the scalar field to load.
205    \end{methoddesc}
206      Cut plane objects define a plane to cut a data set or plot by and return  
207      the data along the intersection between the data set or plot with the  \begin{methoddesc}[DataCollector]{setActiveVector}{vector}
208      defined plane.  Specify the vector field to load.
209      """  \end{methoddesc}
210    
211      def __init__(self):  \begin{methoddesc}[DataCollector]{setActiveTensor}{tensor}
212          """  Specify the tensor field to load.
213          Intialisation of the CutPlane object  \end{methoddesc}
214          """  
215    \subsubsection{\ImageReader class}
216    
217  class ClipPlane(Plane):  \begin{classdesc}{ImageReader}{format}
218      """  An image reader is used to read data from an image in a variety of formats.
219      Class for planes used to clip datasets  \end{classdesc}
220      """  
221    The following are some of the methods available:
222      def __init__(self):  \begin{methoddesc}[ImageReader]{setImageName}{image_name}
223          """  Set the image name to be read.
224          Intialisation of the ClipPlane object  \end{methoddesc}
225          """  
226    \subsubsection{\TextTwoD class}
227      def setInsideOut(self, insideOut):  
228          """  \begin{classdesc}{Text2D}{scene, text, viewport = Viewport.SOUTH_WEST}
229          Set the inside out flag  2D text is used to annotate the rendered object (i.e. adding titles, authors
230          """  and labels).
231    \end{classdesc}
232      def getInsideOut(self):  
233          """  The following are some of the methods available:
234          Get the current value of the inside out flag  \begin{methoddesc}[Text2D]{setFontSize}{size}
235          """  Set the 2D text size.
236    \end{methoddesc}
237  class Plot(Item):  
238      """  \begin{methoddesc}[Text2D]{boldOn}{}
239      Abstract plot class  Bold the 2D text.
240      """  \end{methoddesc}
241      def __init__(self, scene):  
242          """  \begin{methoddesc}[Text2D]{setColor}{color}
243          Initialisation of the abstract Plot class  Set the color of the 2D text.
244            \end{methoddesc}
245          @param scene: The Scene to render the plot in  
246          @type scene: Scene object  Including methods from \ActorTwoD.
247          """  
248    
249      def setData(self, *dataList, **options):  %##############################################################################
250          """  
251          Set data to the plot  
252    \subsection{Data Visualization Classes}
253          @param dataList: List of data to set to the plot  This subsection details the instances used to process and manipulate the source
254          @type dataList: tuple  data.
255    \subsubsection{\Map class}
256      @param options: Dictionary of extra options  
257      @type options: dict  \begin{classdesc}{Map}{scene, data_collector,
258          """  viewport = Viewport.Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
259    Class that shows a scalar field on a domain surface. The domain surface
260      def setTitle(self, title):  can either be colored or grey-scaled, depending on the lookup table used.
261          """  \end{classdesc}
262          Set the plot title  
263    The following are some of the methods available:\\
264          @param title: the string holding the title to the plot  Methods from \ActorThreeD.
265          @type title: string  
266          """  \subsubsection{\MapOnPlaneCut class}
267          debugMsg("Called setTitle() in Plot()")  
268    \begin{classdesc}{MapOnPlaneCut}{scene, data_collector,
269    viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
270      def setXLabel(self, label):  This class works in a similar way to \Map, except that it shows a scalar
271          """  field on a plane. The plane can be translated and rotated along the X, Y and
272          Set the label of the x-axis  Z axes.
273    \end{classdesc}
274          @param label: the string holding the label of the x-axis  
275          @type label: string  The following are some of the methods available:\\
276          """  Methods from \ActorThreeD and \Transform.
277    
278      def setYLabel(self, label):  \subsubsection{\MapOnPlaneClip class}
279          """  
280          Set the label of the y-axis  \begin{classdesc}{MapOnPlaneClip}{scene, data_collector,
281    viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
282          @param label: the string holding the label of the y-axis  This class works in a similar way to \MapOnPlaneCut, except that it shows a
283          @type label: string  scalar field clipped using a plane.
284          """  \end{classdesc}
285    
286      def setZLabel(self, label):  The following are some of the methods available:\\
287          """  Methods from \ActorThreeD, \Transform and \Clipper.
288          Set the label of the z-axis  
289    \subsubsection{\MapOnScalarClip class}
290          @param label: the string holding the label of the z-axis  
291          @type label: string  \begin{classdesc}{MapOnScalarClip}{scene, data_collector,
292          """  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
293    This class works in a similar way to \Map, except that it shows a scalar
294      def setLabel(self, axis, label):  field clipped using a scalar value.
295          """  \end{classdesc}
296          Set the label of a given axis  
297    The following are some of the methods available:\\
298          @param axis: string (Axis object maybe??) of the axis (e.g. x, y, z)  Methods from \ActorThreeD and \Clipper.
299          @type axis: string or Axis object  
300    \subsubsection{\Velocity class}
301          @param label: string of the label to set for the axis  
302          @type label: string  \begin{classdesc}{Velocity}{scene, data_collector,
303          """  viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.VECTOR,
304    arrow = Arrow.TWO_D, lut = Lut.COLOR, outline = True}
305  class Renderer(BaseRenderer):  Class that shows a vector field using arrows. The arrows can either be
306      """  colored or grey-scaled, depending on the lookup table used. If the arrows
307      A generic object holding a renderer of a Scene().  are colored, there are two possible coloring modes, either using vector data or
308      """  scalar data. Similarly, there are two possible types of arrows, either
309    using two-dimensional or three-dimensional.
310      def __init__(self):  \end{classdesc}
311          """  
312          Initialisation of Renderer() class  The following are some of the methods available:\\
313          """  Methods from \ActorThreeD, \GlyphThreeD and \StructuredPoints.
314          debugMsg("Called Renderer.__init__()")  
315          BaseRenderer.__init__(self)  \subsubsection{\VelocityOnPlaneCut class}
316    
317          # initialise some attributes  \begin{classdesc}{VelocityOnPlaneCut}{scene, data_collector,
318          self.renderWindowWidth = 640  arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,
319          self.renderWindowHeight = 480  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
320    This class works in a similar way to \MapOnPlaneCut, except that
321          # what is the name of my renderer?  it shows a vector field using arrows on a plane.
322          self.name = _rendererName  \end{classdesc}
323    
324          # the namespace to run the exec code  The following are some of the methods available:\\
325          self.renderDict = {}  Methods from \ActorThreeD, \GlyphThreeD, \Transform and \StructuredPoints.
326    
327          # initialise the evalstack  \subsubsection{\VelocityOnPlaneClip class}
328          self._evalStack = ""  
329    \begin{classdesc}{VelocityOnPlaneClip}{scene, data_collector,
330          # keep the initial setup of the module for later reuse  arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,
331          self._initStack = ""  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, online = True}
332    This class works in a similar way to \MapOnPlaneClip, except that it shows a
333          # initialise the renderer module  vector field using arrows clipped using a plane.
334          self.runString("# Renderer._initRendererModule")  \end{classdesc}
335          self.addToInitStack("import vtk")  
336          self.addToInitStack("from numarray import *")  The following are some of the methods available:\\
337    Methods from \ActorThreeD, \GlyphThreeD, \Transform, \Clipper and
338  __revision__ = '$Revision: 1.33 $'  \StructuredPoints.
339    
340  class Scene(BaseScene):  \subsubsection{\Ellipsoid class}
341      """  
342      The main object controlling the scene.  \begin{classdesc}{Ellipsoid}{scene, data_collector,
343        viewport = Viewport = SOUTH_WEST, lut = Lut.COLOR, outline = True}
344      Scene object methods and classes overriding the BaseScene class.  Class that shows a tensor field using ellipsoids. The ellipsoids can either be
345      """  colored or grey-scaled, depending on the lookup table used.
346    \end{classdesc}
347      def __init__(self):  
348          """  The following are some of the methods available:\\
349          The init function  Methods from \ActorThreeD, \Sphere, \TensorGlyph and \StructuredPoints.
350          """  
351    \subsubsection{\EllipsoidOnPlaneCut class}
     def add(self, obj):  
         """  
         Add a new item to the scene  
   
         @param obj: The object to add to the scene  
         @type obj: object  
         """  
   
     def place(self, obj):  
         """  
         Place an object within a scene  
   
         @param obj: The object to place within the scene  
         @type obj: object  
         """  
   
     def render(self, pause=False, interactive=False):  
         """  
         Render (or re-render) the scene  
           
         Render the scene, either to screen, or to a buffer waiting for a save  
352    
353          @param pause: Flag to wait at end of script evaluation for user input  \begin{classdesc}{EllipsoidOnPlaneCut}{scene, data_collector,
354          @type pause: boolean  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
355    This class works in a similar way to \MapOnPlaneCut, except that it shows
356    a tensor field using ellipsoids cut using a plane.
357    \end{classdesc}
358    
359          @param interactive: Whether or not to have interactive use of the output  The following are some of the methods available:\\
360          @type interactive: boolean  Methods from \ActorThreeD, \Sphere, \TensorGlyph, \Transform and
361          """  \StructuredPoints.
362    
363      def save(self, fname, format):  \subsubsection{\EllipsoidOnPlaneClip class}
364          """  
365          Save the scene to a file  \begin{classdesc}{EllipsoidOnPlaneClip}{scene, data_collector,
366    viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
367          Possible formats are:  This class works in a similar way to \MapOnPlaneClip, except that it shows a
368              - Postscript  tensor field using ellipsoids clipped using a plane.
369              - PNG  \end{classdesc}
             - JPEG  
             - TIFF  
             - BMP  
             - PNM  
   
         @param fname: Name of output file  
         @type fname: string  
   
         @param format: Graphics format of output file  
         @type format: Image object or string  
         """  
   
     def setBackgroundColor(self, *color):  
         """  
         Sets the background color of the Scene  
   
         @param color: The color to set the background to.  Can be RGB or CMYK  
         @type color: tuple  
         """  
   
     def getBackgroundColor(self):  
         """  
         Gets the current background color setting of the Scene  
         """  
   
     def setSize(self, xSize, ySize):  
         """  
         Sets the size of the scene.  
   
         This size is effectively the renderer window size.  
   
         @param xSize: the size to set the x dimension  
         @type xSize: float  
   
         @param ySize: the size to set the y dimension  
         @type ySize: float  
         """  
   
     def getSize(self):  
         """  
         Gets the current size of the scene  
   
         This size is effectively the renderer window size.  Returns a tuple  
         of the x and y dimensions respectively, in pixel units(??).  
         """  
 class SurfacePlot(Plot):  
     """  
     Surface plot  
     """  
     def __init__(self, scene):  
         """  
         Initialisation of the SurfacePlot class  
370                    
371          @param scene: The Scene to render the plot in  The following are some of the methods available:\\
372          @type scene: Scene object  Methods from \ActorThreeD, \Sphere, \TensorGlyph, \Transform, \Clipper
373          """  and \StructuredPoints.
374    
375      def setData(self, *dataList, **options):  \subsubsection{\Contour class}
376          """  
377          Set data to the plot  \begin{classdesc}{Contour}{scene, data_collector,
378    viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
379          @param dataList: List of data to set to the plot  Class that shows a scalar field by contour surfaces. The contour surfaces can
380          @type dataList: tuple  either be colored or grey-scaled, depending on the lookup table used. This
381    class can also be used to generate iso surfaces.
382          @param options: Dictionary of extra options  \end{classdesc}
383          @type options: dict  
384    The following are some of the methods available:\\
385          @param fname: the name of the input vtk file  Methods from \ActorThreeD and \ContourModule.
386          @type fname: string  
387    \subsubsection{\ContourOnPlaneCut class}
388          @param format: the format of the input vtk file ('vtk' or 'vtk-xml')  
389          @type format: string  \begin{classdesc}{ContourOnPlaneCut}{scene, data_collector,
390    viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
391          @param scalars: the scalar data in the vtk file to use  This class works in a similar way to \MapOnPlaneCut, except that it shows a
392          @type scalars: string  scalar field by contour surfaces on a plane.
393          """  \end{classdesc}
394    
395  class Text(Item):  The following are some of the methods available:\\
396      """  Methods from \ActorThreeD, \ContourModule and \Transform.
397      Text  
398      """  \subsubsection{\ContourOnPlaneClip class}
399      def __init__(self, scene):  
400          """  \begin{classdesc}{ContourOnPlaneClip}{scene, data_collector,
401          Initialisation of the Text object  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
402    This class works in a similar way to \MapOnPlaneClip, except that it shows a
403          @param scene: the scene with which to associate the Text object  scalar field by contour surfaces clipped using a plane.
404          @type scene: Scene object  \end{classdesc}
405          """  
406    The following are some of the methods available:\\
407      def setFont(self, font):  Methods from \ActorThreeD, \ContourModule, \Transform and \Clipper.
408          """  
409          Set the current font  \subsubsection{\StreamLine class}
410    
411          @param font: the font to set  \begin{classdesc}{StreamLine}{scene, data_collector,
412          @type font: string  viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.VECTOR, lut = Lut.COLOR,
413          """  outline = True}
414    Class that shows the direction of particles of a vector field using streamlines.
415      def getFont(self):  The streamlines can either be colored or grey-scaled, depending on the lookup
416          """  table used. If the streamlines are colored, there are two possible coloring
417  \end{verbose}  modes, either using vector data or scalar data.
418    \end{classdesc}
419    
420    The following are some of the methods available:\\
421    Methods from \ActorThreeD, \PointSource, \StreamLineModule and \Tube.
422    
423    \subsubsection{\Carpet class}
424    
425    \begin{classdesc}{Carpet}{scene, data_collector,
426    viewport = Viewport.Viewport.SOUTH_WEST, warp_mode = WarpMode.SCALAR,
427    lut = Lut.COLOR, outline = True}
428    This class works in a similar way to \MapOnPlaneCut, except that it shows a
429    scalar field on a plane deformated (warp) along the normal. The plane can
430    either be colored or grey-scaled, depending on the lookup table used.
431    Similarly, the plane can be deformated either using scalar data or vector data.
432    \end{classdesc}
433    
434    The following are some of the methods available:\\
435    Methods from \ActorThreeD, \Warp and \Transform.
436    
437    \subsubsection{\Image class}
438    
439    \begin{classdesc}{Image}{scene, image_reader, viewport = Viewport.SOUTH_WEST}
440    Class that displays an image which can be scaled (upwards and downwards). The
441    image can also be translated and rotated along the X, Y and Z axes.
442    \end{classdesc}
443    
444    The following are some of the methods available:\\
445    Methods from \ActorThreeD, \PlaneSource and \Transform.
446    
447    
448    %##############################################################################
449    
450    
451    \subsection{Coordiante Classes}
452    This subsection details the instances used to position the rendered object.
453    
454    \begin{classdesc}{LocalPosition}{x_coor, y_coor}
455    Class that defines the local positioning coordinate system (2D).
456    \end{classdesc}
457    
458    \begin{classdesc}{GlobalPosition}{x_coor, y_coor, z_coor}
459    Class that defines the global positioning coordinate system (3D).
460    \end{classdesc}
461    
462    
463    %##############################################################################
464    
465    
466    \subsection{Supporting Classes}
467    This subsection details the supporting classes inherited by the data
468    visualization classes. These supporting
469    
470    \subsubsection{\ActorThreeD class}
471    
472    The following are some of the methods available:
473    
474    \begin{methoddesc}[Actor3D]{setOpacity}{opacity}
475    Set the opacity (transparency) of the 3D actor.
476    \end{methoddesc}
477    
478    \begin{methoddesc}[Actor3D]{setColor}{color}
479    Set the color of the 3D actor.
480    \end{methoddesc}
481    
482    \begin{methoddesc}[Actor3D]{setRepresentationToWireframe}{}
483    Set the representation of the 3D actor to wireframe.
484    \end{methoddesc}
485    
486    \subsubsection{\ActorTwoD class}
487    
488    The following are some of the methods available:
489    
490    \begin{methoddesc}[Actor2D]{setPosition}{position}
491    Set the position (XY) of the 2D actor. Default position is the lower left hand
492    corner of the window / viewport.
493    \end{methoddesc}
494    
495    \subsubsection{\Clipper class}
496    
497    The following are some of the methods available:
498    
499    \begin{methoddesc}[Clipper]{setInsideOutOn}{}
500    Clips one side of the rendered object.
501    \end{methoddesc}
502    
503    \begin{methoddesc}[Clipper]{setInsideOutOff}{}
504    Clips the other side of the rendered object.
505    \end{methoddesc}
506    
507    \begin{methoddesc}[Clipper]{setClipValue}{value}
508    Set the scalar clip value.
509    \end{methoddesc}
510    
511    \subsubsection{\ContourModule class}
512    
513    The following are some of the methods available:
514    
515    \begin{methoddesc}[ContourModule]{generateContours}{contours,
516    lower_range = None, upper_range = None}
517    Generate the specified number of contours within the specified range.
518    \end{methoddesc}
519    
520    \subsubsection{\GlyphThreeD class}
521    
522    The following are some of the methods available:
523    
524    \begin{methoddesc}[Glyph3D]{setScaleModeByVector}{}
525    Set the 3D glyph to scale according to the vector data.
526    \end{methoddesc}
527    
528    \begin{methoddesc}[Glyph3D]{setScaleModeByScalar}{}
529    Set the 3D glyph to scale according to the scalar data.
530    \end{methoddesc}
531    
532    \begin{methoddesc}[Glyph3D]{setScaleFactor}{scale_factor}
533    Set the 3D glyph scale factor.
534    \end{methoddesc}
535    
536    \subsubsection{\TensorGlyph class}
537    
538    The following are some of the methods available:
539    
540    \begin{methoddesc}[TensorGlyph]{setScaleFactor}{scale_factor}
541    Set the scale factor for the tensor glyph.
542    \end{methoddesc}
543    
544    \subsubsection{\PlaneSource class}
545    
546    The following are some of the methods available:
547    
548    \begin{methoddesc}[PlaneSource]{setPoint1}{position}
549    Set the first point from the origin of the plane source.
550    \end{methoddesc}
551    
552    \begin{methoddesc}[PlaneSource]{setPoint2}{position}
553    Set the second point from the origin of the plane source.
554    \end{methoddesc}
555    
556    \subsubsection{\PointSource class}
557    
558    The following are some of the methods available:
559    
560    \begin{methoddesc}[PointSource]{setPointSourceRadius}{radius}
561    Set the radius of the sphere.
562    \end{methoddesc}
563    
564    \begin{methoddesc}[PointSource]{setPointSourceNumberOfPoints}{points}
565    Set the number of points to generate within the sphere (the larger the
566    number of points, the more streamlines are generated).
567    \end{methoddesc}
568    
569    \subsubsection{\StructuredPoints class}
570    
571    The following are some of the methods available:
572    
573    \begin{methoddesc}[StructuredPoints]{setDimension}{x, y, z}
574    Set the dimension on the x, y and z axes. The smaller the dimension,
575    the more points are populated.
576    \end{methoddesc}
577    
578    \subsubsection{\Sphere class}
579    
580    The following are some of the methods available:
581    
582    \begin{methoddesc}[Sphere]{setThetaResolution}{resolution}
583    Set the theta resolution of the sphere.
584    \end{methoddesc}
585    
586    \begin{methoddesc}[Sphere]{setPhiResolution}{resolution}
587    Set the phi resoluton of the sphere.
588    \end{methoddesc}
589    
590    \subsubsection{\StreamLineModule class}
591    
592    The following are some of the methods available:
593    
594    \begin{methoddesc}[StreamLineModule]{setMaximumPropagationTime}{time}
595    Set the maximum length of the streamline expressed in elapsed time.
596    \end{methoddesc}
597    
598    \begin{methoddesc}[StreamLineModule]{setIntegrationToBothDirections}{}
599    Set the integration to occur both sides: forward (where the streamline
600    goes) and backward (where the streamline came from).
601    \end{methoddesc}
602    
603    \subsubsection{\Transform class}
604    
605    \begin{methoddesc}[Transform]{translate}{x_offset, y_offset, z_offset}
606    Translate the rendered object along the x, y and z-axes.
607    \end{methoddesc}
608    
609    \begin{methoddesc}[Transform]{rotateX}{angle}
610    Rotate the plane along the x-axis.
611    \end{methoddesc}
612    
613    \begin{methoddesc}[Transform]{rotateY}{angle}
614    Rotate the plane along the y-axis.
615    \end{methoddesc}
616    
617    \begin{methoddesc}[Transform]{rotateZ}{angle}
618    Rotate the plane along the z-axis.
619    \end{methoddesc}
620    
621    \begin{methoddesc}[Transform]{setPlaneToXY}{offset = 0}
622    Set the plane orthogonal to the z-axis.
623    \end{methoddesc}
624    
625    \begin{methoddesc}[Transform]{setPlaneToYZ}{offset = 0}
626    Set the plane orthogonal to the x-axis.
627    \end{methoddesc}
628    
629    \begin{methoddesc}[Transform]{setPlaneToXZ}{offset = 0}
630    Set the plane orthogonal to the y-axis.
631    \end{methoddesc}
632    
633    \subsubsection{\Tube class}
634    
635    \begin{methoddesc}[Tube]{setTubeRadius}{radius}
636    Set the radius of the tube.
637    \end{methoddesc}
638    
639    \begin{methoddesc}[Tube]{setTubeRadiusToVaryByVector}{}
640    Set the radius of the tube to vary by vector data.
641    \end{methoddesc}
642    
643    \begin{methoddesc}[Tube]{setTubeRadiusToVaryByScalar}{}
644    Set the radius of the tube to vary by scalar data.
645    \end{methoddesc}
646    
647    \subsubsection{\Warp class}
648    
649    \begin{methoddesc}[Warp]{setScaleFactor}{scale_factor}
650    Set the displacement scale factor.
651    \end{methoddesc}
652    
653    
654    \section{Online Rendering Mechnism}
655    
656    
657    
658    same word on rendering, off-line, on-line, how to rotate, zoom, close the window, ...
659    
660    %==============================================
661    \section{How to Make a Movie}

Legend:
Removed from v.606  
changed lines
  Added in v.1035

  ViewVC Help
Powered by ViewVC 1.1.26