/[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 1076 by jongui, Wed Apr 4 06:40:33 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 - object is rendered on-screen with  approaches of rendering an object. (1) Online - object is rendered on-screen
11  interaction (i.e. zoom and rotate) capability, (2) Offline - object is rendered  with interaction (i.e. zoom and rotate) capability, (2) Offline - object is
12  off-screen with no interation capability and (3) Display - object is rendered  rendered off-screen (no window comes up) and (3) Display - object is rendered
13  on-screen but with no interaction capability (able to procude on-the-fly  on-screen but with no interaction capability (able to produce on-the-fly
14  animation). All three approaches has the option to save the rendered object as  animation). All three approaches have the option to save the rendered object
15  an image.  as an image.
16    
17  The following points outlines the general guidelines when using \pyvisi:  The following points outline the general guidelines when using \pyvisi:
18    
19  \begin{enumerate}  \begin{enumerate}
20  \item Create a \Scene instance, a window in which objects are to be rendered on.  \item Create a \Scene instance, a window in which objects are to be rendered on.
# Line 25  reads and loads the source data for visu Line 25  reads and loads the source data for visu
25  source data.  source data.
26  \item Create a \Camera or \Light instance, which controls the viewing angle and  \item Create a \Camera or \Light instance, which controls the viewing angle and
27  lighting effects.  lighting effects.
28  \item Lastly, render the object using either the Online, Offline or Display  \item Render the object using either the Online, Offline or Display approach.
 option.  
29  \end{enumerate}  \end{enumerate}
30  \begin{center}  \begin{center}
31  \begin{math}  \begin{math}
# Line 37  camera/light \rightarrow render Line 36  camera/light \rightarrow render
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, a data input instance must  to the dependencies among them. For example, a data input instance must
39  always be created BEFORE a data visualisation instance.  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 must to be specified before it can be  the program will throw an error. Similarly, a camera and light instance must
42  manipulated. Similarly, a camera and light instance must always be created  be created AFTER a data input instance because the camera and light instance
43  AFTER an input instance, otherwise the program will throw  calculates their position based on the source data. If the sequence is switched,
44  an error because the camera and light instance needs to calculates its  the programthe will throw an error .
 position 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,
# Line 305  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 314  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    
Legend:
Removed from v.1076  
changed lines
  Added in v.1078
  ViewVC Help
Powered by ViewVC 1.1.26