/[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 1035 by jongui, Fri Mar 16 04:54:17 2007 UTC revision 1078 by jongui, Thu Apr 5 06:18:47 2007 UTC
# Line 6  Line 6 
6  \section{Introduction}  \section{Introduction}
7  \pyvisi is a Python module that is used to generate 2D and 3D visualization  \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  for escript and its PDE solvers: finley and bruce. This module provides
9  an easy to use interface to the \VTK library (\VTKUrl). There are three forms  an easy to use interface to the \VTK library (\VTKUrl). There are three
10  of rendering an object: (1) online: a single rendered object is displayed and    approaches of rendering an object. (1) Online - object is rendered on-screen
11  interaction (i.e. zoom and rotate) can occur, (2) offline: multiple rendered  with interaction (i.e. zoom and rotate) capability, (2) Offline - object is
12  objects are not displayed but are instead saved as a series of images. No  rendered off-screen (no window comes up) and (3) Display - object is rendered
13  interaction can occur and (3) animate: similar to offline except that multiple  on-screen but with no interaction capability (able to produce on-the-fly
14  rendered objects are displayed one after another (animated on-the-fly) and  animation). All three approaches have the option to save the rendered object
15  no images are saved.  No interaction can occur.  as an image.
16    
17  The general rule of thumb when using \pyvisi is to perform the following  The following points outline the general guidelines when using \pyvisi:
 in sequence:  
18    
19  \begin{enumerate}  \begin{enumerate}
20  \item Create a scene instance (i.e. \Scene), which is a window in which objects are to be  \item Create a \Scene instance, a window in which objects are to be rendered on.
21  rendered on.  \item Create a data input instance (i.e. \DataCollector or \ImageReader), which
22  \item Create an input instance (i.e. \DataCollector), which reads and loads  reads and loads the source data for visualization.
 the source data for visualization.  
23  \item Create a data visualization instance (i.e. \Map, \Velocity, \Ellipsoid,  \item Create a data visualization instance (i.e. \Map, \Velocity, \Ellipsoid,
24  \Contour and \Carpet), which proccesses and manipulates the source data.  \Contour, \Carpet, \StreamLine or \Image), which proccesses and manipulates the
25  \item Create a camera (i.e. \Camera) instance, which controls the viewing angle.  source data.
26  \item Lastly, render the object online, offline or animate.  \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}  \end{enumerate}
30  \begin{center}  \begin{center}
31  \begin{math}  \begin{math}
32  scene \rightarrow input \rightarrow visualization \rightarrow  scene \rightarrow data input \rightarrow data visualization \rightarrow
33  camera \rightarrow render  camera/light \rightarrow render
34  \end{math}  \end{math}
35  \end{center}  \end{center}
36    
37  The sequence in which instances are created is very important due to  The sequence in which instances are created is very important due to
38  to the dependencies among them. For example, an input instance must  to the dependencies among them. For example, a data input instance must
39  always be created BEFORE a data visualisation instance is created.  be created BEFORE a data visualization instance, because the source data must
40  If the sequence is switched, the program will throw an error because a  be specified before it can be manipulated. If the sequence is switched,
41  source data needs to be specified before the data can be  the program will throw an error. Similarly, a camera and light instance must
42  manipulated. Similarly, a camera instance must always be created  be created AFTER a data input instance because the camera and light instance
43  AFTER an input instance has been created. Otherwise, the program will throw  calculates their position based on the source data. If the sequence is switched,
44  an error because the camera instance needs to calculate its  the programthe will throw an error .
 default position (automatically carried out in the background) based on  
 the source data.  
45    
46  \section{\pyvisi Classes}  \section{\pyvisi Classes}
47  The following subsections give a brief overview of the important classes  The following subsections give a brief overview of the important classes
# Line 62  This subsection details the instances us Line 60  This subsection details the instances us
60  \begin{classdesc}{Scene}{renderer = Renderer.ONLINE, num_viewport = 1,  \begin{classdesc}{Scene}{renderer = Renderer.ONLINE, num_viewport = 1,
61  x_size = 1152, y_size = 864}  x_size = 1152, y_size = 864}
62  A scene is a window in which objects are to be rendered on. Only  A scene is a window in which objects are to be rendered on. Only
63  one scene needs to be created and can display data from one source. However,  one scene needs to be created. However, a scene may be divided into four
64  a scene may be divided into four smaller windows called viewports (if needed).  smaller windows called viewports (if needed). Each viewport can
65  The four viewports in turn can display data from four different sources.  render a different object.
66  \end{classdesc}  \end{classdesc}
67    
68  The following are some of the methods available:  The following are some of the methods available:
# Line 72  The following are some of the methods av Line 70  The following are some of the methods av
70  Set the background color of the scene.  Set the background color of the scene.
71  \end{methoddesc}  \end{methoddesc}
72    
73  \begin{methoddesc}[Scene]{saveImage}{image_name}  \begin{methoddesc}[Scene]{render}{image_name = None}
74  Save the rendered object as an image offline. No interaction can occur.  Render the object using either the Online, Offline or Display mode.
 \end{methoddesc}  
   
 \begin{methoddesc}[Scene]{animate}{}  
 Animate the rendered object on-the-fly. No interaction can occur.  
 \end{methoddesc}  
   
 \begin{methoddesc}[Scene]{render}{}  
 Render the object online. Interaction can occur.  
75  \end{methoddesc}  \end{methoddesc}
76    
77  \subsubsection{\Camera class}  \subsubsection{\Camera class}
# Line 101  Set the focal point of the camera. Line 91  Set the focal point of the camera.
91  Set the position of the camera.  Set the position of the camera.
92  \end{methoddesc}  \end{methoddesc}
93    
 \begin{methoddesc}[Camera]{setClippingRange}{near_clipping, far_clipping}  
 Set the near and far clipping plane of the camera.  
 \end{methoddesc}  
   
 \begin{methoddesc}[Camera]{setViewUp}{position}  
 Set the view up direction of the camera.  
 \end{methoddesc}  
   
94  \begin{methoddesc}[Camera]{azimuth}{angle}  \begin{methoddesc}[Camera]{azimuth}{angle}
95  Rotate the camera to the left and right.  Rotate the camera to the left and right.
96  \end{methoddesc}  \end{methoddesc}
# Line 133  Rotate the camera to view the bottom of Line 115  Rotate the camera to view the bottom of
115  Rotate the camera to view the left side of the rendered object.  Rotate the camera to view the left side of the rendered object.
116  \end{methoddesc}  \end{methoddesc}
117    
118  \begin{methoddesc}[Camera]{rightView}{position}  \begin{methoddesc}[Camera]{rightView}{}
119  Rotate the camera to view the right side of the rendered object.  Rotate the camera to view the right side of the rendered object.
120  \end{methoddesc}  \end{methoddesc}
121    
122  \begin{methoddesc}[Camera]{isometricView}{position}  \begin{methoddesc}[Camera]{isometricView}{}
123  Rotate the camera to view the isometric angle of the rendered object.  Rotate the camera to view the isometric angle of the rendered object.
124  \end{methoddesc}  \end{methoddesc}
125    
# Line 149  the rendered object. Line 131  the rendered object.
131  \subsubsection{\Light class}  \subsubsection{\Light class}
132    
133  \begin{classdesc}{Light}{scene, data_collector, viewport = Viewport.SOUTH_WEST}  \begin{classdesc}{Light}{scene, data_collector, viewport = Viewport.SOUTH_WEST}
134  A light controls the source of light for the rendered object and works in  A light controls the lighting for the rendered object and works in
135  a similar way to \Camera.  a similar way to \Camera.
136  \end{classdesc}  \end{classdesc}
137    
# Line 163  Set the focal point of the light. Line 145  Set the focal point of the light.
145  \end{methoddesc}  \end{methoddesc}
146    
147  \begin{methoddesc}[Light]{setPosition}{position}  \begin{methoddesc}[Light]{setPosition}{position}
148  Set the position of the camera.  Set the position of the light.
149  \end{methoddesc}  \end{methoddesc}
150    
151  \begin{methoddesc}[Light]{setAngle}{elevation = 0, azimuth = 0}  \begin{methoddesc}[Light]{setAngle}{elevation = 0, azimuth = 0}
152  An alternative to set the position and focal point of the light using the  An alternative to set the position and focal point of the light by using the
153  elevation and azimuth degrees.  elevation and azimuth.
154  \end{methoddesc}  \end{methoddesc}
155    
156    
# Line 182  for visualization. Line 164  for visualization.
164  \subsubsection{\DataCollector class}  \subsubsection{\DataCollector class}
165    
166  \begin{classdesc}{DataCollector}{source = Source.XML}  \begin{classdesc}{DataCollector}{source = Source.XML}
 % need to say something about the escript object not just d xml file.  
167  A data collector is used to read data from an XML file or from  A data collector is used to read data from an XML file or from
168  an escript object directly. Please note that a separate data collector needs  an escript object directly.
 to be created when two or more attributes of the same type from  
 the same file needs to be specified (i.e.two scalar attributes from a file).  
169  \end{classdesc}  \end{classdesc}
170    
171  The following are some of the methods available:  The following are some of the methods available:
172  \begin{methoddesc}[DataCollector]{setFileName}{file_name}  \begin{methoddesc}[DataCollector]{setFileName}{file_name}
173  Set the XML source file name to be read.  Set the XML file name to read.
174  \end{methoddesc}  \end{methoddesc}
175    
176  \begin{methoddesc}[DataCollector]{setData}{**args}  \begin{methoddesc}[DataCollector]{setData}{**args}
177  Create data using the \textless name\textgreater=\textless data\textgreater  Create data using the \textless name\textgreater=\textless data\textgreater
178  pairing. Assumption is made that the data will be given in the  pairing. Assumption is made that the data will be given in the
179  appropriate format.  appropriate format.
180    
181    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  \end{methoddesc}  \end{methoddesc}
184    
185  \begin{methoddesc}[DataCollector]{setActiveScalar}{scalar}  \begin{methoddesc}[DataCollector]{setActiveScalar}{scalar}
# Line 226  Set the image name to be read. Line 208  Set the image name to be read.
208  \subsubsection{\TextTwoD class}  \subsubsection{\TextTwoD class}
209    
210  \begin{classdesc}{Text2D}{scene, text, viewport = Viewport.SOUTH_WEST}  \begin{classdesc}{Text2D}{scene, text, viewport = Viewport.SOUTH_WEST}
211  2D text is used to annotate the rendered object (i.e. adding titles, authors  A two-dimensional text is used to annotate the rendered object
212  and labels).  (i.e. adding titles, authors and labels).
213  \end{classdesc}  \end{classdesc}
214    
215  The following are some of the methods available:  The following are some of the methods available:
# Line 252  Including methods from \ActorTwoD. Line 234  Including methods from \ActorTwoD.
234  \subsection{Data Visualization Classes}  \subsection{Data Visualization Classes}
235  This subsection details the instances used to process and manipulate the source  This subsection details the instances used to process and manipulate the source
236  data.  data.
237    
238    One point to note is that the source can either be point or cell data. If the
239    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    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    
244  \subsubsection{\Map class}  \subsubsection{\Map class}
245    
246  \begin{classdesc}{Map}{scene, data_collector,  \begin{classdesc}{Map}{scene, data_collector,
247  viewport = Viewport.Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
248    outline = True}
249  Class that shows a scalar field on a domain surface. The domain surface  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.  can either be colored or grey-scaled, depending on the lookup table used.
251  \end{classdesc}  \end{classdesc}
# Line 266  Methods from \ActorThreeD. Line 256  Methods from \ActorThreeD.
256  \subsubsection{\MapOnPlaneCut class}  \subsubsection{\MapOnPlaneCut class}
257    
258  \begin{classdesc}{MapOnPlaneCut}{scene, data_collector,  \begin{classdesc}{MapOnPlaneCut}{scene, data_collector,
259  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
260    outline = True}
261  This class works in a similar way to \Map, except that it shows a scalar  This class works in a similar way to \Map, except that it shows a scalar
262  field on a plane. The plane can be translated and rotated along the X, Y and  field on a plane. The plane can be translated and rotated along the X, Y and
263  Z axes.  Z axes.
# Line 278  Methods from \ActorThreeD and \Transform Line 269  Methods from \ActorThreeD and \Transform
269  \subsubsection{\MapOnPlaneClip class}  \subsubsection{\MapOnPlaneClip class}
270    
271  \begin{classdesc}{MapOnPlaneClip}{scene, data_collector,  \begin{classdesc}{MapOnPlaneClip}{scene, data_collector,
272  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
273    outline = True}
274  This class works in a similar way to \MapOnPlaneCut, except that it shows a  This class works in a similar way to \MapOnPlaneCut, except that it shows a
275  scalar field clipped using a plane.  scalar field clipped using a plane.
276  \end{classdesc}  \end{classdesc}
# Line 289  Methods from \ActorThreeD, \Transform an Line 281  Methods from \ActorThreeD, \Transform an
281  \subsubsection{\MapOnScalarClip class}  \subsubsection{\MapOnScalarClip class}
282    
283  \begin{classdesc}{MapOnScalarClip}{scene, data_collector,  \begin{classdesc}{MapOnScalarClip}{scene, data_collector,
284  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
285    outline = True}
286  This class works in a similar way to \Map, except that it shows a scalar  This class works in a similar way to \Map, except that it shows a scalar
287  field clipped using a scalar value.  field clipped using a scalar value.
288  \end{classdesc}  \end{classdesc}
# Line 301  Methods from \ActorThreeD and \Clipper. Line 294  Methods from \ActorThreeD and \Clipper.
294    
295  \begin{classdesc}{Velocity}{scene, data_collector,  \begin{classdesc}{Velocity}{scene, data_collector,
296  viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.VECTOR,  viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.VECTOR,
297  arrow = Arrow.TWO_D, lut = Lut.COLOR, outline = True}  arrow = Arrow.TWO_D, lut = Lut.COLOR, cell_to_point = False, outline = True}
298  Class that shows a vector field using arrows. The arrows can either be  Class that shows a vector field using arrows. The arrows can either be
299  colored or grey-scaled, depending on the lookup table used. If the arrows  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  are colored, there are two possible coloring modes, either using vector data or
# Line 310  using two-dimensional or three-dimension Line 303  using two-dimensional or three-dimension
303  \end{classdesc}  \end{classdesc}
304    
305  The following are some of the methods available:\\  The following are some of the methods available:\\
306  Methods from \ActorThreeD, \GlyphThreeD and \StructuredPoints.  Methods from \ActorThreeD, \GlyphThreeD and \MaskPoints.
307    
308  \subsubsection{\VelocityOnPlaneCut class}  \subsubsection{\VelocityOnPlaneCut class}
309    
310  \begin{classdesc}{VelocityOnPlaneCut}{scene, data_collector,  \begin{classdesc}{VelocityOnPlaneCut}{scene, data_collector,
311  arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,  arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,
312  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR,
313    cell_to_point = False, outline = True}
314  This class works in a similar way to \MapOnPlaneCut, except that  This class works in a similar way to \MapOnPlaneCut, except that
315  it shows a vector field using arrows on a plane.  it shows a vector field using arrows on a plane.
316  \end{classdesc}  \end{classdesc}
317    
318  The following are some of the methods available:\\  The following are some of the methods available:\\
319  Methods from \ActorThreeD, \GlyphThreeD, \Transform and \StructuredPoints.  Methods from \ActorThreeD, \GlyphThreeD, \Transform and \MaskPoints.
320    
321  \subsubsection{\VelocityOnPlaneClip class}  \subsubsection{\VelocityOnPlaneClip class}
322    
323  \begin{classdesc}{VelocityOnPlaneClip}{scene, data_collector,  \begin{classdesc}{VelocityOnPlaneClip}{scene, data_collector,
324  arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,  arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,
325  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, online = True}  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR,
326    cell_to_point = False, online = True}
327  This class works in a similar way to \MapOnPlaneClip, except that it shows a  This class works in a similar way to \MapOnPlaneClip, except that it shows a
328  vector field using arrows clipped using a plane.  vector field using arrows clipped using a plane.
329  \end{classdesc}  \end{classdesc}
330    
331  The following are some of the methods available:\\  The following are some of the methods available:\\
332  Methods from \ActorThreeD, \GlyphThreeD, \Transform, \Clipper and  Methods from \ActorThreeD, \GlyphThreeD, \Transform, \Clipper and
333  \StructuredPoints.  \MaskPoints.
334    
335  \subsubsection{\Ellipsoid class}  \subsubsection{\Ellipsoid class}
336    
# Line 375  and \StructuredPoints. Line 370  and \StructuredPoints.
370  \subsubsection{\Contour class}  \subsubsection{\Contour class}
371    
372  \begin{classdesc}{Contour}{scene, data_collector,  \begin{classdesc}{Contour}{scene, data_collector,
373  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
374    outline = True}
375  Class that shows a scalar field by contour surfaces. The contour surfaces can  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  either be colored or grey-scaled, depending on the lookup table used. This
377  class can also be used to generate iso surfaces.  class can also be used to generate iso surfaces.
# Line 387  Methods from \ActorThreeD and \ContourMo Line 383  Methods from \ActorThreeD and \ContourMo
383  \subsubsection{\ContourOnPlaneCut class}  \subsubsection{\ContourOnPlaneCut class}
384    
385  \begin{classdesc}{ContourOnPlaneCut}{scene, data_collector,  \begin{classdesc}{ContourOnPlaneCut}{scene, data_collector,
386  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
387    outline = True}
388  This class works in a similar way to \MapOnPlaneCut, except that it shows a  This class works in a similar way to \MapOnPlaneCut, except that it shows a
389  scalar field by contour surfaces on a plane.  scalar field by contour surfaces on a plane.
390  \end{classdesc}  \end{classdesc}
# Line 398  Methods from \ActorThreeD, \ContourModul Line 395  Methods from \ActorThreeD, \ContourModul
395  \subsubsection{\ContourOnPlaneClip class}  \subsubsection{\ContourOnPlaneClip class}
396    
397  \begin{classdesc}{ContourOnPlaneClip}{scene, data_collector,  \begin{classdesc}{ContourOnPlaneClip}{scene, data_collector,
398  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, outline = True}  viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
399    outline = True}
400  This class works in a similar way to \MapOnPlaneClip, except that it shows a  This class works in a similar way to \MapOnPlaneClip, except that it shows a
401  scalar field by contour surfaces clipped using a plane.  scalar field by contour surfaces clipped using a plane.
402  \end{classdesc}  \end{classdesc}
# Line 448  Methods from \ActorThreeD, \PlaneSource Line 446  Methods from \ActorThreeD, \PlaneSource
446  %##############################################################################  %##############################################################################
447    
448    
449  \subsection{Coordiante Classes}  \subsection{Coordinate Classes}
450  This subsection details the instances used to position the rendered object.  This subsection details the instances used to position the rendered object.
451    
452  \begin{classdesc}{LocalPosition}{x_coor, y_coor}  \begin{classdesc}{LocalPosition}{x_coor, y_coor}

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

  ViewVC Help
Powered by ViewVC 1.1.26