/[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 1078 by jongui, Thu Apr 5 06:18:47 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
10          """  approaches of rendering an object. (1) Online - object is rendered on-screen
11          Loads image data from file.  with interaction (i.e. zoom and rotate) capability, (2) Offline - object is
12    rendered off-screen (no window comes up) and (3) Display - object is rendered
13          @param fname: The filename from which to load image data  on-screen but with no interaction capability (able to produce on-the-fly
14          @type fname: string  animation). All three approaches have the option to save the rendered object
15          """  as an image.
         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 following points outline the general guidelines when using \pyvisi:
         fileCheck(fname)  
18    
19          # this ability not handled by this renderer module  \begin{enumerate}
20          unsupportedError()  \item Create a \Scene instance, a window in which objects are to be rendered on.
21            \item Create a data input instance (i.e. \DataCollector or \ImageReader), which
22          return  reads and loads the source data for visualization.
23    \item Create a data visualization instance (i.e. \Map, \Velocity, \Ellipsoid,
24    \Contour, \Carpet, \StreamLine or \Image), which proccesses and manipulates the
25    source data.
26    \item Create a \Camera or \Light instance, which controls the viewing angle and
27    lighting effects.
28    \item Render the object using either the Online, Offline or Display approach.
29    \end{enumerate}
30    \begin{center}
31    \begin{math}
32    scene \rightarrow data input \rightarrow data visualization \rightarrow
33    camera/light \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, a data input instance must
39          Does PsImage object specific (pre)rendering stuff  be created BEFORE a data visualization instance, because the source data must
40          """  be specified before it can be manipulated. If the sequence is switched,
41          debugMsg("Called PsImage.render()")  the program will throw an error. Similarly, a camera and light instance must
42    be created AFTER a data input instance because the camera and light instance
43          return  calculates their position based on the source data. If the sequence is switched,
44    the programthe will throw an error .
45  class PdfImage(Image):  
46      """  \section{\pyvisi Classes}
47      Subclass of Image class to explicitly handle pdf images  The following subsections give a brief overview of the important classes
48      """  and some of their corresponding methods. Please refer to \ReferenceGuide for
49      def __init__(self, scene=None):  full details.
50          """  
51          Initialises the PdfImage class object  
52    %#############################################################################
53          This object is B{only} used for generating pdf output  
54    
55          @param scene: The Scene object to add to  \subsection{Scene Classes}
56          @type scene: Scene object  This subsection details the instances used to setup the viewing environment.
57          """  
58    \subsubsection{\Scene class}
59      def load(self, fname):  
60          """  \begin{classdesc}{Scene}{renderer = Renderer.ONLINE, num_viewport = 1,
61          Loads pdf image data from file.  x_size = 1152, y_size = 864}
62    A scene is a window in which objects are to be rendered on. Only
63          B{NOT} supported by this renderer module  one scene needs to be created. However, a scene may be divided into four
64    smaller windows called viewports (if needed). Each viewport can
65          @param fname: The filename from which to load pdf image data  render a different object.
66          @type fname: string  \end{classdesc}
67          """  
68    The following are some of the methods available:
69  class IsosurfacePlot(Plot):  \begin{methoddesc}[Scene]{setBackground}{color}
70      """  Set the background color of the scene.
71      Isosurface plot  \end{methoddesc}
72      """  
73      def __init__(self, scene):  \begin{methoddesc}[Scene]{render}{image_name = None}
74          """  Render the object using either the Online, Offline or Display mode.
75          Initialisation of the IsosurfacePlot class  \end{methoddesc}
76            
77          @param scene: The Scene to render the plot in  \subsubsection{\Camera class}
78          @type scene: Scene object  
79          """  \begin{classdesc}{Camera}{scene, data_collector, viewport = Viewport.SOUTH_WEST}
80      def setData(self, *dataList, **options):  A camera controls the display angle of the rendered object and one is
81          """  usually created for a \Scene. However, if a \Scene has four viewports, then a
82          Set data to the plot  separate camera may be created for each viewport.
83    \end{classdesc}
84          @param dataList: List of data to set to the plot  
85          @type dataList: tuple  The following are some of the methods available:
86    \begin{methoddesc}[Camera]{setFocalPoint}{position}
87          @param options: Dictionary of keyword options to the method  Set the focal point of the camera.
88          @type options: dict  \end{methoddesc}
89    
90      @param fname: the name of the input vtk file  \begin{methoddesc}[Camera]{setPosition}{position}
91      @type fname: string  Set the position of the camera.
92    \end{methoddesc}
93      @param format: the format of the input vtk file ('vtk' or 'vtk-xml')  
94      @type format: string  \begin{methoddesc}[Camera]{azimuth}{angle}
95    Rotate the camera to the left and right.
96      @param scalars: the name of the scalar data in the vtk file to use  \end{methoddesc}
97      @type scalars: string  
98          """  \begin{methoddesc}[Camera]{elevation}{angle}
99    Rotate the camera to the top and bottom (only between -90 and 90).
100  class LinePlot(Plot):  \end{methoddesc}
101      """  
102      Line plot  \begin{methoddesc}[Camera]{backView}{}
103      """  Rotate the camera to view the back of the rendered object.
104      def __init__(self, scene):  \end{methoddesc}
105          """  
106          Initialisation of the LinePlot class  \begin{methoddesc}[Camera]{topView}{}
107            Rotate the camera to view the top of the rendered object.
108          @param scene: The Scene to render the plot in  \end{methoddesc}
109          @type scene: Scene object  
110          """  \begin{methoddesc}[Camera]{bottomView}{}
111    Rotate the camera to view the bottom of the rendered object.
112      def setData(self, *dataList, **options):  \end{methoddesc}
113          """  
114          Set data to the plot  \begin{methoddesc}[Camera]{leftView}{}
115    Rotate the camera to view the left side of the rendered object.
116          @param dataList: List of data to set to the plot  \end{methoddesc}
117          @type dataList: tuple  
118    \begin{methoddesc}[Camera]{rightView}{}
119      @param options: Dictionary of extra options  Rotate the camera to view the right side of the rendered object.
120      @type options: dict  \end{methoddesc}
121    
122      @param offset: whether or not to offset the lines from one another  \begin{methoddesc}[Camera]{isometricView}{}
123      @type offset: boolean  Rotate the camera to view the isometric angle of the rendered object.
124    \end{methoddesc}
125      @param fname: Filename of the input vtk file  
126      @type fname: string  \begin{methoddesc}[Camera]{dolly}{distance}
127    Move the camera towards (greater than 1) and away (less than 1) from
128      @param format: format of the input vtk file ('vtk' or 'vtk-xml')  the rendered object.
129      @type format: string  \end{methoddesc}
130    
131      @param scalars: the name of the scalar data in the vtk file to use  \subsubsection{\Light class}
132      @type scalars: string  
133          """  \begin{classdesc}{Light}{scene, data_collector, viewport = Viewport.SOUTH_WEST}
134    A light controls the lighting for the rendered object and works in
135  class OffsetPlot(Plot):  a similar way to \Camera.
136      """  \end{classdesc}
137      Offset plot  
138      """  The following are some of the methods available:
139      def __init__(self, scene):  \begin{methoddesc}[Light]{setColor}{color}
140          """  Set the light color.
141          Initialisation of the OffsetPlot class  \end{methoddesc}
142            
143          @param scene: The Scene to render the plot in  \begin{methoddesc}[Light]{setFocalPoint}{position}
144          @type scene: Scene object  Set the focal point of the light.
145          """  \end{methoddesc}
146    
147      def setData(self, *dataList, **options):  \begin{methoddesc}[Light]{setPosition}{position}
148          """  Set the position of the light.
149          Set data to the plot  \end{methoddesc}
150    
151          @param dataList: List of data to set to the plot  \begin{methoddesc}[Light]{setAngle}{elevation = 0, azimuth = 0}
152          @type dataList: tuple  An alternative to set the position and focal point of the light by using the
153    elevation and azimuth.
154          @param options: Dictionary of extra options  \end{methoddesc}
155          @type options: dict  
156    
157      @param fname: Filename of the input vtk file  %##############################################################################
158      @type fname: string  
159    
160      @param format: Format of the input vtk file ('vtk' or 'vtk-xml')  \subsection{Input Classes}
161      @type format: string  This subsection details the instances used to read and load the source data
162    for visualization.
163      @param scalars: the name of the scalar data in the vtk file to use  
164      @type scalars: string  \subsubsection{\DataCollector class}
165          """  
166  class Plane(Item):  \begin{classdesc}{DataCollector}{source = Source.XML}
167      """  A data collector is used to read data from an XML file or from
168      Generic class for Plane objects  an escript object directly.
169      """  \end{classdesc}
170    
171      def __init__(self, scene):  The following are some of the methods available:
172          """  \begin{methoddesc}[DataCollector]{setFileName}{file_name}
173          Initialisation of the Plane object  Set the XML file name to read.
174          """  \end{methoddesc}
175    
176      def setOrigin(self, x, y, z):  \begin{methoddesc}[DataCollector]{setData}{**args}
177          """  Create data using the \textless name\textgreater=\textless data\textgreater
178          Set the origin of the plane  pairing. Assumption is made that the data will be given in the
179          """  appropriate format.
180    
181      def getOrigin(self):  BUG: Reading source data directly from an escript object is NOT
182          """  work properly. Therefore this method should NOT be used at this stage.
183          Get the current origin of the plane  \end{methoddesc}
184          """  
185    \begin{methoddesc}[DataCollector]{setActiveScalar}{scalar}
186      def setNormal(self, vx, vy, vz):  Specify the scalar field to load.
187          """  \end{methoddesc}
188          Set the normal vector to the plane  
189          """  \begin{methoddesc}[DataCollector]{setActiveVector}{vector}
190    Specify the vector field to load.
191      def getNormal(self):  \end{methoddesc}
192          """  
193          Get the current normal vector to the plane  \begin{methoddesc}[DataCollector]{setActiveTensor}{tensor}
194          """  Specify the tensor field to load.
195    \end{methoddesc}
196      def mapImageToPlane(self, image):  
197          # this really needs to go somewhere else!!!  \subsubsection{\ImageReader class}
198          """  
199          Maps an Image object onto a Plane object  \begin{classdesc}{ImageReader}{format}
200          """  An image reader is used to read data from an image in a variety of formats.
201    \end{classdesc}
202  class CutPlane(Plane):  
203      """  The following are some of the methods available:
204      Cut plane class: used to cut data sets with a plane  \begin{methoddesc}[ImageReader]{setImageName}{image_name}
205    Set the image name to be read.
206      Cut plane objects define a plane to cut a data set or plot by and return  \end{methoddesc}
207      the data along the intersection between the data set or plot with the  
208      defined plane.  \subsubsection{\TextTwoD class}
209      """  
210    \begin{classdesc}{Text2D}{scene, text, viewport = Viewport.SOUTH_WEST}
211      def __init__(self):  A two-dimensional text is used to annotate the rendered object
212          """  (i.e. adding titles, authors and labels).
213          Intialisation of the CutPlane object  \end{classdesc}
214          """  
215    The following are some of the methods available:
216    \begin{methoddesc}[Text2D]{setFontSize}{size}
217  class ClipPlane(Plane):  Set the 2D text size.
218      """  \end{methoddesc}
219      Class for planes used to clip datasets  
220      """  \begin{methoddesc}[Text2D]{boldOn}{}
221    Bold the 2D text.
222      def __init__(self):  \end{methoddesc}
223          """  
224          Intialisation of the ClipPlane object  \begin{methoddesc}[Text2D]{setColor}{color}
225          """  Set the color of the 2D text.
226    \end{methoddesc}
227      def setInsideOut(self, insideOut):  
228          """  Including methods from \ActorTwoD.
229          Set the inside out flag  
230          """  
231    %##############################################################################
232      def getInsideOut(self):  
233          """  
234          Get the current value of the inside out flag  \subsection{Data Visualization Classes}
235          """  This subsection details the instances used to process and manipulate the source
236    data.
237  class Plot(Item):  
238      """  One point to note is that the source can either be point or cell data. If the
239      Abstract plot class  source is cell data, a conversion to point data may or may not be
240      """  required, in order for the object to be rendered correctly.
241      def __init__(self, scene):  If a conversion is needed, the 'cell_to_point' flag (see below) must be set to
242          """  'True', otherwise 'False' (which is the default).
243          Initialisation of the abstract Plot class  
244            \subsubsection{\Map class}
245          @param scene: The Scene to render the plot in  
246          @type scene: Scene object  \begin{classdesc}{Map}{scene, data_collector,
247          """  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
248    outline = True}
249      def setData(self, *dataList, **options):  Class that shows a scalar field on a domain surface. The domain surface
250          """  can either be colored or grey-scaled, depending on the lookup table used.
251          Set data to the plot  \end{classdesc}
252    
253          @param dataList: List of data to set to the plot  The following are some of the methods available:\\
254          @type dataList: tuple  Methods from \ActorThreeD.
255    
256      @param options: Dictionary of extra options  \subsubsection{\MapOnPlaneCut class}
257      @type options: dict  
258          """  \begin{classdesc}{MapOnPlaneCut}{scene, data_collector,
259    viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
260      def setTitle(self, title):  outline = True}
261          """  This class works in a similar way to \Map, except that it shows a scalar
262          Set the plot title  field on a plane. The plane can be translated and rotated along the X, Y and
263    Z axes.
264          @param title: the string holding the title to the plot  \end{classdesc}
265          @type title: string  
266          """  The following are some of the methods available:\\
267          debugMsg("Called setTitle() in Plot()")  Methods from \ActorThreeD and \Transform.
268    
269    \subsubsection{\MapOnPlaneClip class}
270      def setXLabel(self, label):  
271          """  \begin{classdesc}{MapOnPlaneClip}{scene, data_collector,
272          Set the label of the x-axis  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
273    outline = True}
274          @param label: the string holding the label of the x-axis  This class works in a similar way to \MapOnPlaneCut, except that it shows a
275          @type label: string  scalar field clipped using a plane.
276          """  \end{classdesc}
277    
278      def setYLabel(self, label):  The following are some of the methods available:\\
279          """  Methods from \ActorThreeD, \Transform and \Clipper.
280          Set the label of the y-axis  
281    \subsubsection{\MapOnScalarClip class}
282          @param label: the string holding the label of the y-axis  
283          @type label: string  \begin{classdesc}{MapOnScalarClip}{scene, data_collector,
284          """  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
285    outline = True}
286      def setZLabel(self, label):  This class works in a similar way to \Map, except that it shows a scalar
287          """  field clipped using a scalar value.
288          Set the label of the z-axis  \end{classdesc}
289    
290          @param label: the string holding the label of the z-axis  The following are some of the methods available:\\
291          @type label: string  Methods from \ActorThreeD and \Clipper.
292          """  
293    \subsubsection{\Velocity class}
294      def setLabel(self, axis, label):  
295          """  \begin{classdesc}{Velocity}{scene, data_collector,
296          Set the label of a given axis  viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.VECTOR,
297    arrow = Arrow.TWO_D, lut = Lut.COLOR, cell_to_point = False, outline = True}
298          @param axis: string (Axis object maybe??) of the axis (e.g. x, y, z)  Class that shows a vector field using arrows. The arrows can either be
299          @type axis: string or Axis object  colored or grey-scaled, depending on the lookup table used. If the arrows
300    are colored, there are two possible coloring modes, either using vector data or
301          @param label: string of the label to set for the axis  scalar data. Similarly, there are two possible types of arrows, either
302          @type label: string  using two-dimensional or three-dimensional.
303          """  \end{classdesc}
304    
305  class Renderer(BaseRenderer):  The following are some of the methods available:\\
306      """  Methods from \ActorThreeD, \GlyphThreeD and \MaskPoints.
307      A generic object holding a renderer of a Scene().  
308      """  \subsubsection{\VelocityOnPlaneCut class}
309    
310      def __init__(self):  \begin{classdesc}{VelocityOnPlaneCut}{scene, data_collector,
311          """  arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,
312          Initialisation of Renderer() class  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR,
313          """  cell_to_point = False, outline = True}
314          debugMsg("Called Renderer.__init__()")  This class works in a similar way to \MapOnPlaneCut, except that
315          BaseRenderer.__init__(self)  it shows a vector field using arrows on a plane.
316    \end{classdesc}
317          # initialise some attributes  
318          self.renderWindowWidth = 640  The following are some of the methods available:\\
319          self.renderWindowHeight = 480  Methods from \ActorThreeD, \GlyphThreeD, \Transform and \MaskPoints.
320    
321          # what is the name of my renderer?  \subsubsection{\VelocityOnPlaneClip class}
322          self.name = _rendererName  
323    \begin{classdesc}{VelocityOnPlaneClip}{scene, data_collector,
324          # the namespace to run the exec code  arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,
325          self.renderDict = {}  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR,
326    cell_to_point = False, online = True}
327          # initialise the evalstack  This class works in a similar way to \MapOnPlaneClip, except that it shows a
328          self._evalStack = ""  vector field using arrows clipped using a plane.
329    \end{classdesc}
330          # keep the initial setup of the module for later reuse  
331          self._initStack = ""  The following are some of the methods available:\\
332    Methods from \ActorThreeD, \GlyphThreeD, \Transform, \Clipper and
333          # initialise the renderer module  \MaskPoints.
334          self.runString("# Renderer._initRendererModule")  
335          self.addToInitStack("import vtk")  \subsubsection{\Ellipsoid class}
336          self.addToInitStack("from numarray import *")  
337    \begin{classdesc}{Ellipsoid}{scene, data_collector,
338  __revision__ = '$Revision: 1.33 $'  viewport = Viewport = SOUTH_WEST, lut = Lut.COLOR, outline = True}
339    Class that shows a tensor field using ellipsoids. The ellipsoids can either be
340  class Scene(BaseScene):  colored or grey-scaled, depending on the lookup table used.
341      """  \end{classdesc}
342      The main object controlling the scene.  
343        The following are some of the methods available:\\
344      Scene object methods and classes overriding the BaseScene class.  Methods from \ActorThreeD, \Sphere, \TensorGlyph and \StructuredPoints.
345      """  
346    \subsubsection{\EllipsoidOnPlaneCut class}
347      def __init__(self):  
348          """  \begin{classdesc}{EllipsoidOnPlaneCut}{scene, data_collector,
349          The init function  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
350          """  This class works in a similar way to \MapOnPlaneCut, except that it shows
351    a tensor field using ellipsoids cut using a plane.
352      def add(self, obj):  \end{classdesc}
         """  
         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  
353    
354          @param pause: Flag to wait at end of script evaluation for user input  The following are some of the methods available:\\
355          @type pause: boolean  Methods from \ActorThreeD, \Sphere, \TensorGlyph, \Transform and
356    \StructuredPoints.
357    
358          @param interactive: Whether or not to have interactive use of the output  \subsubsection{\EllipsoidOnPlaneClip class}
359          @type interactive: boolean  
360          """  \begin{classdesc}{EllipsoidOnPlaneClip}{scene, data_collector,
361    viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}
362      def save(self, fname, format):  This class works in a similar way to \MapOnPlaneClip, except that it shows a
363          """  tensor field using ellipsoids clipped using a plane.
364          Save the scene to a file  \end{classdesc}
   
         Possible formats are:  
             - Postscript  
             - PNG  
             - 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  
365                    
366          @param scene: The Scene to render the plot in  The following are some of the methods available:\\
367          @type scene: Scene object  Methods from \ActorThreeD, \Sphere, \TensorGlyph, \Transform, \Clipper
368          """  and \StructuredPoints.
369    
370      def setData(self, *dataList, **options):  \subsubsection{\Contour class}
371          """  
372          Set data to the plot  \begin{classdesc}{Contour}{scene, data_collector,
373    viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
374          @param dataList: List of data to set to the plot  outline = True}
375          @type dataList: tuple  Class that shows a scalar field by contour surfaces. The contour surfaces can
376    either be colored or grey-scaled, depending on the lookup table used. This
377          @param options: Dictionary of extra options  class can also be used to generate iso surfaces.
378          @type options: dict  \end{classdesc}
379    
380          @param fname: the name of the input vtk file  The following are some of the methods available:\\
381          @type fname: string  Methods from \ActorThreeD and \ContourModule.
382    
383          @param format: the format of the input vtk file ('vtk' or 'vtk-xml')  \subsubsection{\ContourOnPlaneCut class}
384          @type format: string  
385    \begin{classdesc}{ContourOnPlaneCut}{scene, data_collector,
386          @param scalars: the scalar data in the vtk file to use  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
387          @type scalars: string  outline = True}
388          """  This class works in a similar way to \MapOnPlaneCut, except that it shows a
389    scalar field by contour surfaces on a plane.
390  class Text(Item):  \end{classdesc}
391      """  
392      Text  The following are some of the methods available:\\
393      """  Methods from \ActorThreeD, \ContourModule and \Transform.
394      def __init__(self, scene):  
395          """  \subsubsection{\ContourOnPlaneClip class}
396          Initialisation of the Text object  
397    \begin{classdesc}{ContourOnPlaneClip}{scene, data_collector,
398          @param scene: the scene with which to associate the Text object  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
399          @type scene: Scene object  outline = True}
400          """  This class works in a similar way to \MapOnPlaneClip, except that it shows a
401    scalar field by contour surfaces clipped using a plane.
402      def setFont(self, font):  \end{classdesc}
403          """  
404          Set the current font  The following are some of the methods available:\\
405    Methods from \ActorThreeD, \ContourModule, \Transform and \Clipper.
406          @param font: the font to set  
407          @type font: string  \subsubsection{\StreamLine class}
408          """  
409    \begin{classdesc}{StreamLine}{scene, data_collector,
410      def getFont(self):  viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.VECTOR, lut = Lut.COLOR,
411          """  outline = True}
412  \end{verbose}  Class that shows the direction of particles of a vector field using streamlines.
413    The streamlines can either be colored or grey-scaled, depending on the lookup
414    table used. If the streamlines are colored, there are two possible coloring
415    modes, either using vector data or scalar data.
416    \end{classdesc}
417    
418    The following are some of the methods available:\\
419    Methods from \ActorThreeD, \PointSource, \StreamLineModule and \Tube.
420    
421    \subsubsection{\Carpet class}
422    
423    \begin{classdesc}{Carpet}{scene, data_collector,
424    viewport = Viewport.Viewport.SOUTH_WEST, warp_mode = WarpMode.SCALAR,
425    lut = Lut.COLOR, outline = True}
426    This class works in a similar way to \MapOnPlaneCut, except that it shows a
427    scalar field on a plane deformated (warp) along the normal. The plane can
428    either be colored or grey-scaled, depending on the lookup table used.
429    Similarly, the plane can be deformated either using scalar data or vector data.
430    \end{classdesc}
431    
432    The following are some of the methods available:\\
433    Methods from \ActorThreeD, \Warp and \Transform.
434    
435    \subsubsection{\Image class}
436    
437    \begin{classdesc}{Image}{scene, image_reader, viewport = Viewport.SOUTH_WEST}
438    Class that displays an image which can be scaled (upwards and downwards). The
439    image can also be translated and rotated along the X, Y and Z axes.
440    \end{classdesc}
441    
442    The following are some of the methods available:\\
443    Methods from \ActorThreeD, \PlaneSource and \Transform.
444    
445    
446    %##############################################################################
447    
448    
449    \subsection{Coordinate Classes}
450    This subsection details the instances used to position the rendered object.
451    
452    \begin{classdesc}{LocalPosition}{x_coor, y_coor}
453    Class that defines the local positioning coordinate system (2D).
454    \end{classdesc}
455    
456    \begin{classdesc}{GlobalPosition}{x_coor, y_coor, z_coor}
457    Class that defines the global positioning coordinate system (3D).
458    \end{classdesc}
459    
460    
461    %##############################################################################
462    
463    
464    \subsection{Supporting Classes}
465    This subsection details the supporting classes inherited by the data
466    visualization classes. These supporting
467    
468    \subsubsection{\ActorThreeD class}
469    
470    The following are some of the methods available:
471    
472    \begin{methoddesc}[Actor3D]{setOpacity}{opacity}
473    Set the opacity (transparency) of the 3D actor.
474    \end{methoddesc}
475    
476    \begin{methoddesc}[Actor3D]{setColor}{color}
477    Set the color of the 3D actor.
478    \end{methoddesc}
479    
480    \begin{methoddesc}[Actor3D]{setRepresentationToWireframe}{}
481    Set the representation of the 3D actor to wireframe.
482    \end{methoddesc}
483    
484    \subsubsection{\ActorTwoD class}
485    
486    The following are some of the methods available:
487    
488    \begin{methoddesc}[Actor2D]{setPosition}{position}
489    Set the position (XY) of the 2D actor. Default position is the lower left hand
490    corner of the window / viewport.
491    \end{methoddesc}
492    
493    \subsubsection{\Clipper class}
494    
495    The following are some of the methods available:
496    
497    \begin{methoddesc}[Clipper]{setInsideOutOn}{}
498    Clips one side of the rendered object.
499    \end{methoddesc}
500    
501    \begin{methoddesc}[Clipper]{setInsideOutOff}{}
502    Clips the other side of the rendered object.
503    \end{methoddesc}
504    
505    \begin{methoddesc}[Clipper]{setClipValue}{value}
506    Set the scalar clip value.
507    \end{methoddesc}
508    
509    \subsubsection{\ContourModule class}
510    
511    The following are some of the methods available:
512    
513    \begin{methoddesc}[ContourModule]{generateContours}{contours,
514    lower_range = None, upper_range = None}
515    Generate the specified number of contours within the specified range.
516    \end{methoddesc}
517    
518    \subsubsection{\GlyphThreeD class}
519    
520    The following are some of the methods available:
521    
522    \begin{methoddesc}[Glyph3D]{setScaleModeByVector}{}
523    Set the 3D glyph to scale according to the vector data.
524    \end{methoddesc}
525    
526    \begin{methoddesc}[Glyph3D]{setScaleModeByScalar}{}
527    Set the 3D glyph to scale according to the scalar data.
528    \end{methoddesc}
529    
530    \begin{methoddesc}[Glyph3D]{setScaleFactor}{scale_factor}
531    Set the 3D glyph scale factor.
532    \end{methoddesc}
533    
534    \subsubsection{\TensorGlyph class}
535    
536    The following are some of the methods available:
537    
538    \begin{methoddesc}[TensorGlyph]{setScaleFactor}{scale_factor}
539    Set the scale factor for the tensor glyph.
540    \end{methoddesc}
541    
542    \subsubsection{\PlaneSource class}
543    
544    The following are some of the methods available:
545    
546    \begin{methoddesc}[PlaneSource]{setPoint1}{position}
547    Set the first point from the origin of the plane source.
548    \end{methoddesc}
549    
550    \begin{methoddesc}[PlaneSource]{setPoint2}{position}
551    Set the second point from the origin of the plane source.
552    \end{methoddesc}
553    
554    \subsubsection{\PointSource class}
555    
556    The following are some of the methods available:
557    
558    \begin{methoddesc}[PointSource]{setPointSourceRadius}{radius}
559    Set the radius of the sphere.
560    \end{methoddesc}
561    
562    \begin{methoddesc}[PointSource]{setPointSourceNumberOfPoints}{points}
563    Set the number of points to generate within the sphere (the larger the
564    number of points, the more streamlines are generated).
565    \end{methoddesc}
566    
567    \subsubsection{\StructuredPoints class}
568    
569    The following are some of the methods available:
570    
571    \begin{methoddesc}[StructuredPoints]{setDimension}{x, y, z}
572    Set the dimension on the x, y and z axes. The smaller the dimension,
573    the more points are populated.
574    \end{methoddesc}
575    
576    \subsubsection{\Sphere class}
577    
578    The following are some of the methods available:
579    
580    \begin{methoddesc}[Sphere]{setThetaResolution}{resolution}
581    Set the theta resolution of the sphere.
582    \end{methoddesc}
583    
584    \begin{methoddesc}[Sphere]{setPhiResolution}{resolution}
585    Set the phi resoluton of the sphere.
586    \end{methoddesc}
587    
588    \subsubsection{\StreamLineModule class}
589    
590    The following are some of the methods available:
591    
592    \begin{methoddesc}[StreamLineModule]{setMaximumPropagationTime}{time}
593    Set the maximum length of the streamline expressed in elapsed time.
594    \end{methoddesc}
595    
596    \begin{methoddesc}[StreamLineModule]{setIntegrationToBothDirections}{}
597    Set the integration to occur both sides: forward (where the streamline
598    goes) and backward (where the streamline came from).
599    \end{methoddesc}
600    
601    \subsubsection{\Transform class}
602    
603    \begin{methoddesc}[Transform]{translate}{x_offset, y_offset, z_offset}
604    Translate the rendered object along the x, y and z-axes.
605    \end{methoddesc}
606    
607    \begin{methoddesc}[Transform]{rotateX}{angle}
608    Rotate the plane along the x-axis.
609    \end{methoddesc}
610    
611    \begin{methoddesc}[Transform]{rotateY}{angle}
612    Rotate the plane along the y-axis.
613    \end{methoddesc}
614    
615    \begin{methoddesc}[Transform]{rotateZ}{angle}
616    Rotate the plane along the z-axis.
617    \end{methoddesc}
618    
619    \begin{methoddesc}[Transform]{setPlaneToXY}{offset = 0}
620    Set the plane orthogonal to the z-axis.
621    \end{methoddesc}
622    
623    \begin{methoddesc}[Transform]{setPlaneToYZ}{offset = 0}
624    Set the plane orthogonal to the x-axis.
625    \end{methoddesc}
626    
627    \begin{methoddesc}[Transform]{setPlaneToXZ}{offset = 0}
628    Set the plane orthogonal to the y-axis.
629    \end{methoddesc}
630    
631    \subsubsection{\Tube class}
632    
633    \begin{methoddesc}[Tube]{setTubeRadius}{radius}
634    Set the radius of the tube.
635    \end{methoddesc}
636    
637    \begin{methoddesc}[Tube]{setTubeRadiusToVaryByVector}{}
638    Set the radius of the tube to vary by vector data.
639    \end{methoddesc}
640    
641    \begin{methoddesc}[Tube]{setTubeRadiusToVaryByScalar}{}
642    Set the radius of the tube to vary by scalar data.
643    \end{methoddesc}
644    
645    \subsubsection{\Warp class}
646    
647    \begin{methoddesc}[Warp]{setScaleFactor}{scale_factor}
648    Set the displacement scale factor.
649    \end{methoddesc}
650    
651    
652    \section{Online Rendering Mechnism}
653    
654    
655    
656    same word on rendering, off-line, on-line, how to rotate, zoom, close the window, ...
657    
658    %==============================================
659    \section{How to Make a Movie}

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

  ViewVC Help
Powered by ViewVC 1.1.26