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