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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1099 - (show annotations)
Tue Apr 17 01:45:08 2007 UTC (12 years, 5 months ago) by jongui
File MIME type: application/x-tex
File size: 38408 byte(s)
Upated some examples.
1 \chapter{The module \pyvisi}
2 \label{PYVISI CHAP}
3 \declaremodule{extension}{esys.pyvisi}
4 \modulesynopsis{Python Visualization Interface}
5
6 \section{Introduction}
7 \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 an easy to use interface to the \VTK library (\VTKUrl). There are three
10 approaches of rendering an object. (1) Online - object is rendered on-screen
11 with interaction (i.e. zoom and rotate) capability, (2) Offline - object is
12 rendered off-screen (no window comes up) and (3) Display - object is rendered
13 on-screen but with no interaction capability (able to produce on-the-fly
14 animation). All three approaches have the option to save the rendered object
15 as an image.
16
17 The following points outline the general guidelines when using \pyvisi:
18
19 \begin{enumerate}
20 \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 reads and loads the source data for visualization.
23 \item Create a data visualization instance (i.e. \Map, \Velocity, \Ellipsoid,
24 \Contour, \Carpet, \StreamLine or \Image), which proccesses and manipulates the
25 source data.
26 \item Create a \Camera or \Light instance, which controls the viewing angle and
27 lighting effects.
28 \item Render the object using either the Online, Offline or Display approach.
29 \end{enumerate}
30 \begin{center}
31 \begin{math}
32 scene \rightarrow data \; input \rightarrow data \; visualization \rightarrow
33 camer \, / \, light \rightarrow render
34 \end{math}
35 \end{center}
36
37 The sequence in which instances are created is very important due to
38 to the dependencies among them. For example, a data input instance must
39 be created BEFORE a data visualization instance, because the source data must
40 be specified before it can be manipulated. If the sequence is switched,
41 the program will throw an error. Similarly, a camera and light instance must
42 be created AFTER a data input instance because the camera and light instance
43 calculates their position based on the source data. If the sequence is switched,
44 the programthe will throw an error .
45
46 \section{\pyvisi Classes}
47 The following subsections give a brief overview of the important classes
48 and some of their corresponding methods. Please refer to \ReferenceGuide for
49 full details.
50
51
52 %#############################################################################
53
54
55 \subsection{Scene Classes}
56 This subsection details the instances used to setup the viewing environment.
57
58 \subsubsection{\Scene class}
59
60 \begin{classdesc}{Scene}{renderer = Renderer.ONLINE, num_viewport = 1,
61 x_size = 1152, y_size = 864}
62 A scene is a window in which objects are to be rendered on. Only
63 one scene needs to be created. However, a scene may be divided into four
64 smaller windows called viewports (if needed). Each viewport can
65 render a different object.
66 \end{classdesc}
67
68 The following are some of the methods available:
69 \begin{methoddesc}[Scene]{setBackground}{color}
70 Set the background color of the scene.
71 \end{methoddesc}
72
73 \begin{methoddesc}[Scene]{render}{image_name = None}
74 Render the object using either the Online, Offline or Display mode.
75 \end{methoddesc}
76
77 \subsubsection{\Camera class}
78
79 \begin{classdesc}{Camera}{scene, data_collector, viewport = Viewport.SOUTH_WEST}
80 A camera controls the display angle of the rendered object and one is
81 usually created for a \Scene. However, if a \Scene has four viewports, then a
82 separate camera may be created for each viewport.
83 \end{classdesc}
84
85 The following are some of the methods available:
86 \begin{methoddesc}[Camera]{setFocalPoint}{position}
87 Set the focal point of the camera.
88 \end{methoddesc}
89
90 \begin{methoddesc}[Camera]{setPosition}{position}
91 Set the position of the camera.
92 \end{methoddesc}
93
94 \begin{methoddesc}[Camera]{azimuth}{angle}
95 Rotate the camera to the left and right.
96 \end{methoddesc}
97
98 \begin{methoddesc}[Camera]{elevation}{angle}
99 Rotate the camera to the top and bottom (only between -90 and 90).
100 \end{methoddesc}
101
102 \begin{methoddesc}[Camera]{backView}{}
103 Rotate the camera to view the back of the rendered object.
104 \end{methoddesc}
105
106 \begin{methoddesc}[Camera]{topView}{}
107 Rotate the camera to view the top of the rendered object.
108 \end{methoddesc}
109
110 \begin{methoddesc}[Camera]{bottomView}{}
111 Rotate the camera to view the bottom of the rendered object.
112 \end{methoddesc}
113
114 \begin{methoddesc}[Camera]{leftView}{}
115 Rotate the camera to view the left side of the rendered object.
116 \end{methoddesc}
117
118 \begin{methoddesc}[Camera]{rightView}{}
119 Rotate the camera to view the right side of the rendered object.
120 \end{methoddesc}
121
122 \begin{methoddesc}[Camera]{isometricView}{}
123 Rotate the camera to view the isometric angle of the rendered object.
124 \end{methoddesc}
125
126 \begin{methoddesc}[Camera]{dolly}{distance}
127 Move the camera towards (greater than 1) and away (less than 1) from
128 the rendered object.
129 \end{methoddesc}
130
131 \subsubsection{\Light class}
132
133 \begin{classdesc}{Light}{scene, data_collector, viewport = Viewport.SOUTH_WEST}
134 A light controls the lighting for the rendered object and works in
135 a similar way to \Camera.
136 \end{classdesc}
137
138 The following are some of the methods available:
139 \begin{methoddesc}[Light]{setColor}{color}
140 Set the light color.
141 \end{methoddesc}
142
143 \begin{methoddesc}[Light]{setFocalPoint}{position}
144 Set the focal point of the light.
145 \end{methoddesc}
146
147 \begin{methoddesc}[Light]{setPosition}{position}
148 Set the position of the light.
149 \end{methoddesc}
150
151 \begin{methoddesc}[Light]{setAngle}{elevation = 0, azimuth = 0}
152 An alternative to set the position and focal point of the light by using the
153 elevation and azimuth.
154 \end{methoddesc}
155
156
157 %##############################################################################
158
159
160 \subsection{Input Classes}
161 This subsection details the instances used to read and load the source data
162 for visualization.
163
164 \subsubsection{\DataCollector class}
165
166 \begin{classdesc}{DataCollector}{source = Source.XML}
167 A data collector is used to read data from an XML file or from
168 an escript object directly.
169 \end{classdesc}
170
171 The following are some of the methods available:
172 \begin{methoddesc}[DataCollector]{setFileName}{file_name}
173 Set the XML file name to read.
174 \end{methoddesc}
175
176 \begin{methoddesc}[DataCollector]{setData}{**args}
177 Create data using the \textless name\textgreater=\textless data\textgreater
178 pairing. Assumption is made that the data will be given in the
179 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}
184
185 \begin{methoddesc}[DataCollector]{setActiveScalar}{scalar}
186 Specify the scalar field to load.
187 \end{methoddesc}
188
189 \begin{methoddesc}[DataCollector]{setActiveVector}{vector}
190 Specify the vector field to load.
191 \end{methoddesc}
192
193 \begin{methoddesc}[DataCollector]{setActiveTensor}{tensor}
194 Specify the tensor field to load.
195 \end{methoddesc}
196
197 \subsubsection{\ImageReader class}
198
199 \begin{classdesc}{ImageReader}{format}
200 An image reader is used to read data from an image in a variety of formats.
201 \end{classdesc}
202
203 The following are some of the methods available:
204 \begin{methoddesc}[ImageReader]{setImageName}{image_name}
205 Set the image name to be read.
206 \end{methoddesc}
207
208 \subsubsection{\TextTwoD class}
209
210 \begin{classdesc}{Text2D}{scene, text, viewport = Viewport.SOUTH_WEST}
211 A two-dimensional text is used to annotate the rendered object
212 (i.e. adding titles, authors and labels).
213 \end{classdesc}
214
215 The following are some of the methods available:
216 \begin{methoddesc}[Text2D]{setFontSize}{size}
217 Set the 2D text size.
218 \end{methoddesc}
219
220 \begin{methoddesc}[Text2D]{boldOn}{}
221 Bold the 2D text.
222 \end{methoddesc}
223
224 \begin{methoddesc}[Text2D]{setColor}{color}
225 Set the color of the 2D text.
226 \end{methoddesc}
227
228 Including methods from \ActorTwoD.
229
230
231 %##############################################################################
232
233
234 \subsection{Data Visualization Classes}
235 This subsection details the instances used to process and manipulate the source
236 data. The typical usage of the classes is also shown.
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}
245
246 \begin{classdesc}{Map}{scene, data_collector,
247 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
250 can either be colored or grey-scaled, depending on the lookup table used.
251 \end{classdesc}
252
253 The following are some of the methods available:\\
254 Methods from \ActorThreeD.
255
256 A typical usage of \Map is shown below.
257
258 \begin{python}
259 # Import the necessary modules.
260 from esys.pyvisi import Scene, DataCollector, Map, Camera
261 from esys.pyvisi.constant import *
262
263 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes/"
264 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images/"
265 X_SIZE = 800
266 Y_SIZE = 800
267
268 SCALAR_FIELD_POINT_DATA = "temperature"
269 SCALAR_FIELD_CELL_DATA = "temperature_cell"
270 FILE_3D = "interior_3D.xml"
271 IMAGE_NAME = "map.jpg"
272 JPG_RENDERER = Renderer.ONLINE_JPG
273
274
275 # Create a Scene with four viewports.
276 s = Scene(renderer = JPG_RENDERER, num_viewport = 4, x_size = X_SIZE,
277 y_size = Y_SIZE)
278
279 # Create a DataCollector reading from a XML file.
280 dc1 = DataCollector(source = Source.XML)
281 dc1.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FILE_3D)
282 dc1.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA)
283
284 # Create a Map for the first viewport.
285 m1 = Map(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST,
286 lut = Lut.COLOR, cell_to_point = False, outline = True)
287 m1.setRepresentationToWireframe()
288
289 # Create a Camera for the first viewport
290 c1 = Camera(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST)
291 c1.isometricView()
292
293 # Create a second DataCollector reading from the same XML file but specifying
294 # a different scalar field.
295 dc2 = DataCollector(source = Source.XML)
296 dc2.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FILE_3D)
297 dc2.setActiveScalar(scalar = SCALAR_FIELD_CELL_DATA)
298
299 # Create a Map for the third viewport.
300 m2 = Map(scene = s, data_collector = dc2, viewport = Viewport.NORTH_EAST,
301 lut = Lut.COLOR, cell_to_point = True, outline = True)
302
303 # Render the object.
304 s.render(PYVISI_EXAMPLE_IMAGES_PATH + IMAGE_NAME)
305 \end{python}
306
307 \subsubsection{\MapOnPlaneCut class}
308
309 \begin{classdesc}{MapOnPlaneCut}{scene, data_collector,
310 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
311 outline = True}
312 This class works in a similar way to \Map, except that it shows a scalar
313 field cut using a plane. The plane can be translated and rotated along the
314 X, Y and Z axes.
315 \end{classdesc}
316
317 The following are some of the methods available:\\
318 Methods from \ActorThreeD and \Transform.
319
320 \subsubsection{\MapOnPlaneClip class}
321
322 \begin{classdesc}{MapOnPlaneClip}{scene, data_collector,
323 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
324 outline = True}
325 This class works in a similar way to \MapOnPlaneCut, except that it shows a
326 scalar field clipped using a plane.
327 \end{classdesc}
328
329 The following are some of the methods available:\\
330 Methods from \ActorThreeD, \Transform and \Clipper.
331
332 \subsubsection{\MapOnScalarClip class}
333
334 \begin{classdesc}{MapOnScalarClip}{scene, data_collector,
335 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
336 outline = True}
337 This class works in a similar way to \Map, except that it shows a scalar
338 field clipped using a scalar value.
339 \end{classdesc}
340
341 The following are some of the methods available:\\
342 Methods from \ActorThreeD and \Clipper.
343
344 \subsubsection{\Velocity class}
345
346 \begin{classdesc}{Velocity}{scene, data_collector,
347 viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.VECTOR,
348 arrow = Arrow.TWO_D, lut = Lut.COLOR, cell_to_point = False, outline = True}
349 Class that shows a vector field using arrows. The arrows can either be
350 colored or grey-scaled, depending on the lookup table used. If the arrows
351 are colored, there are two possible coloring modes, either using vector data or
352 scalar data. Similarly, there are two possible types of arrows, either
353 using two-dimensional or three-dimensional.
354 \end{classdesc}
355
356 The following are some of the methods available:\\
357 Methods from \ActorThreeD, \GlyphThreeD and \MaskPoints.
358
359 \subsubsection{\VelocityOnPlaneCut class}
360
361 \begin{classdesc}{VelocityOnPlaneCut}{scene, data_collector,
362 arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,
363 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR,
364 cell_to_point = False, outline = True}
365 This class works in a similar way to \MapOnPlaneCut, except that
366 it shows a vector field using arrows cut using a plane.
367 \end{classdesc}
368
369 The following are some of the methods available:\\
370 Methods from \ActorThreeD, \GlyphThreeD, \Transform and \MaskPoints.
371
372 A typical usage of \VelocityOnPlaneCut is shown below.
373
374 \begin{python}
375 # Import the necessary modules
376 from esys.pyvisi import Scene, DataCollector, VelocityOnPlaneCut, Camera
377 from esys.pyvisi.constant import *
378
379 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes/"
380 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images/"
381 X_SIZE = 400
382 Y_SIZE = 400
383
384 VECTOR_FIELD_CELL_DATA = "velocity"
385 FILE_3D = "interior_3D.xml"
386 IMAGE_NAME = "velocity.jpg"
387 JPG_RENDERER = Renderer.ONLINE_JPG
388
389
390 # Create a Scene with four viewports
391 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
392 y_size = Y_SIZE)
393
394 # Create a DataCollector reading from a XML file.
395 dc1 = DataCollector(source = Source.XML)
396 dc1.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FILE_3D)
397 dc1.setActiveVector(vector = VECTOR_FIELD_CELL_DATA)
398
399 # Create VelocityOnPlaneCut.
400 vopc1 = VelocityOnPlaneCut(scene = s, data_collector = dc1,
401 viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.VECTOR,
402 arrow = Arrow.THREE_D, lut = Lut.COLOR, cell_to_point = False,
403 outline = True)
404 vopc1.setScaleFactor(scale_factor = 0.5)
405 vopc1.setPlaneToXY(offset = 0.5)
406 vopc1.setRatio(2)
407 vopc1.randomOn()
408
409 # Create a Camera.
410 c1 = Camera(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST)
411 c1.isometricView()
412 c1.elevation(angle = -20)
413
414 # Render the object.
415 s.render(PYVISI_EXAMPLE_IMAGES_PATH + IMAGE_NAME)
416 \end{python}
417
418 \subsubsection{\VelocityOnPlaneClip class}
419
420 \begin{classdesc}{VelocityOnPlaneClip}{scene, data_collector,
421 arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,
422 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR,
423 cell_to_point = False, online = True}
424 This class works in a similar way to \MapOnPlaneClip, except that it shows a
425 vector field using arrows clipped using a plane.
426 \end{classdesc}
427
428 The following are some of the methods available:\\
429 Methods from \ActorThreeD, \GlyphThreeD, \Transform, \Clipper and
430 \MaskPoints.
431
432 \subsubsection{\Ellipsoid class}
433
434 \begin{classdesc}{Ellipsoid}{scene, data_collector,
435 viewport = Viewport = SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
436 outline = True}
437 Class that shows a tensor field using ellipsoids. The ellipsoids can either be
438 colored or grey-scaled, depending on the lookup table used.
439 \end{classdesc}
440
441 The following are some of the methods available:\\
442 Methods from \ActorThreeD, \Sphere, \TensorGlyph and \MaskPoints.
443
444 \subsubsection{\EllipsoidOnPlaneCut class}
445
446 \begin{classdesc}{EllipsoidOnPlaneCut}{scene, data_collector,
447 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
448 outline = True}
449 This class works in a similar way to \MapOnPlaneCut, except that it shows
450 a tensor field using ellipsoids cut using a plane.
451 \end{classdesc}
452
453 The following are some of the methods available:\\
454 Methods from \ActorThreeD, \Sphere, \TensorGlyph, \Transform and
455 \MaskPoints.
456
457 \subsubsection{\EllipsoidOnPlaneClip class}
458
459 \begin{classdesc}{EllipsoidOnPlaneClip}{scene, data_collector,
460 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
461 outline = True}
462 This class works in a similar way to \MapOnPlaneClip, except that it shows a
463 tensor field using ellipsoids clipped using a plane.
464 \end{classdesc}
465
466 The following are some of the methods available:\\
467 Methods from \ActorThreeD, \Sphere, \TensorGlyph, \Transform, \Clipper
468 and \MaskPoints.
469
470 A typical usage of \EllipsoidOnPlaneClip is shown below.
471
472 \begin{python}
473 # Import the necessary modules
474 from esys.pyvisi import Scene, DataCollector, EllipsoidOnPlaneClip, Camera
475 from esys.pyvisi.constant import *
476
477 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes/"
478 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images/"
479 X_SIZE = 400
480 Y_SIZE = 400
481
482 TENSOR_FIELD_CELL_DATA = "stress_cell"
483 FILE_3D = "interior_3D.xml"
484 IMAGE_NAME = "ellipsoid.jpg"
485 JPG_RENDERER = Renderer.ONLINE_JPG
486
487 # Create a Scene.
488 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
489 y_size = Y_SIZE)
490
491 # Create a DataCollector reading from a XML file.
492 dc1 = DataCollector(source = Source.XML)
493 dc1.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FILE_3D)
494 dc1.setActiveTensor(tensor = TENSOR_FIELD_CELL_DATA)
495
496 # Create a EllipsoidOnPlaneClip.
497 eopc1 = EllipsoidOnPlaneClip(scene = s, data_collector = dc1,
498 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = True,
499 outline = True)
500 eopc1.setPlaneToXY()
501 eopc1.setScaleFactor(scale_factor = 0.2)
502 eopc1.rotateX(angle = 10)
503
504 # Create a camera.
505 c1 = Camera(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST)
506 c1.bottomView()
507 c1.azimuth(angle = -90)
508 c1.elevation(angle = 10)
509
510 # Render the object.
511 s.render(PYVISI_EXAMPLE_IMAGES_PATH + IMAGE_NAME)
512 \end{python}
513
514 \subsubsection{\Contour class}
515
516 \begin{classdesc}{Contour}{scene, data_collector,
517 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
518 outline = True}
519 Class that shows a scalar field using contour surfaces. The contour surfaces can
520 either be colored or grey-scaled, depending on the lookup table used. This
521 class can also be used to generate iso surfaces.
522 \end{classdesc}
523
524 The following are some of the methods available:\\
525 Methods from \ActorThreeD and \ContourModule.
526
527 A typical usage of \Contour is shown below.
528
529 \begin{python}
530 # Import the necessary modules
531 from esys.pyvisi import Scene, DataCollector, Contour, Camera
532 from esys.pyvisi.constant import *
533
534 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes/"
535 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images/"
536 X_SIZE = 400
537 Y_SIZE = 400
538
539 SCALAR_FIELD_POINT_DATA = "temperature"
540 FILE_3D = "interior_3D.xml"
541 IMAGE_NAME = "contour.jpg"
542 JPG_RENDERER = Renderer.ONLINE_JPG
543
544
545 # Create a Scene.
546 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
547 y_size = Y_SIZE)
548
549 # Create a DataCollector reading a XML file.
550 dc1 = DataCollector(source = Source.XML)
551 dc1.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FILE_3D)
552 dc1.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA)
553
554 # Create a Contour.
555 ctr1 = Contour(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST,
556 lut = Lut.COLOR, cell_to_point = False, outline = True)
557 ctr1.generateContours(contours = 3)
558
559 # Create a Camera.
560 cam1 = Camera(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST)
561 cam1.elevation(angle = -40)
562
563 # Render the object.
564 s.render(PYVISI_EXAMPLE_IMAGES_PATH + IMAGE_NAME)
565 \end{python}
566
567 \subsubsection{\ContourOnPlaneCut class}
568
569 \begin{classdesc}{ContourOnPlaneCut}{scene, data_collector,
570 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
571 outline = True}
572 This class works in a similar way to \MapOnPlaneCut, except that it shows a
573 scalar field using contour surfaces cut using a plane.
574 \end{classdesc}
575
576 The following are some of the methods available:\\
577 Methods from \ActorThreeD, \ContourModule and \Transform.
578
579 \subsubsection{\ContourOnPlaneClip class}
580
581 \begin{classdesc}{ContourOnPlaneClip}{scene, data_collector,
582 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
583 outline = True}
584 This class works in a similar way to \MapOnPlaneClip, except that it shows a
585 scalar field using contour surfaces clipped using a plane.
586 \end{classdesc}
587
588 The following are some of the methods available:\\
589 Methods from \ActorThreeD, \ContourModule, \Transform and \Clipper.
590
591 \subsubsection{\StreamLine class}
592
593 \begin{classdesc}{StreamLine}{scene, data_collector,
594 viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.VECTOR, lut = Lut.COLOR,
595 outline = True}
596 Class that shows the direction of particles of a vector field using streamlines.
597 The streamlines can either be colored or grey-scaled, depending on the lookup
598 table used. If the streamlines are colored, there are two possible coloring
599 modes, either using vector data or scalar data.
600 \end{classdesc}
601
602 The following are some of the methods available:\\
603 Methods from \ActorThreeD, \PointSource, \StreamLineModule and \Tube.
604
605 A typical usage of \StreamLine is shown below.
606
607 \begin{python}
608 # Import the necessary modules.
609 from esys.pyvisi import Scene, DataCollector, StreamLine, Camera
610 from esys.pyvisi.constant import *
611
612 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes/"
613 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images/"
614 X_SIZE = 400
615 Y_SIZE = 400
616
617 VECTOR_FIELD_CELL_DATA = "temperature"
618 FILE_3D = "interior_3D.xml"
619 IMAGE_NAME = "streamline.jpg"
620 JPG_RENDERER = Renderer.ONLINE_JPG
621
622
623 # Create a Scene.
624 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
625 y_size = Y_SIZE)
626
627 # Create a DataCollector reading from a XML file.
628 dc1 = DataCollector(source = Source.XML)
629 dc1.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FILE_3D)
630
631 # Create a Streamline.
632 sl1 = StreamLine(scene = s, data_collector = dc1,
633 viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.SCALAR,
634 lut = Lut.COLOR, cell_to_point = False, outline = True)
635 sl1.setTubeRadius(radius = 0.02)
636
637 # Create a Camera.
638 c1 = Camera(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST)
639 c1.isometricView()
640
641 # Render the object.
642 s.render(PYVISI_EXAMPLE_IMAGES_PATH + IMAGE_NAME)
643 \end{python}
644
645 \subsubsection{\Carpet class}
646
647 \begin{classdesc}{Carpet}{scene, data_collector,
648 viewport = Viewport.Viewport.SOUTH_WEST, warp_mode = WarpMode.SCALAR,
649 lut = Lut.COLOR, outline = True}
650 This class works in a similar way to \MapOnPlaneCut, except that it shows a
651 scalar field cut on a plane and deformated (warp) along the normal. The
652 plane can either be colored or grey-scaled, depending on the lookup table used.
653 Similarly, the plane can be deformated either using scalar data or vector data.
654 \end{classdesc}
655
656 The following are some of the methods available:\\
657 Methods from \ActorThreeD, \Warp and \Transform.
658
659 A typical usage of \Carpet is shown below.
660
661 \begin{python}
662 # Import the necessary modules.
663 from esys.pyvisi import Scene, DataCollector, Carpet, Camera
664 from esys.pyvisi.constant import *
665
666 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes/"
667 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images/"
668 X_SIZE = 400
669 Y_SIZE = 400
670
671 SCALAR_FIELD_CELL_DATA = "temperature_cell"
672 FILE_3D = "interior_3D.xml"
673 IMAGE_NAME = "carpet.jpg"
674 JPG_RENDERER = Renderer.ONLINE_JPG
675
676 # Create a Scene.
677 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
678 y_size = Y_SIZE)
679
680 # Create a DataCollector reading from a XML file.
681 dc1 = DataCollector(source = Source.XML)
682 dc1.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FILE_3D)
683 dc1.setActiveScalar(scalar = SCALAR_FIELD_CELL_DATA)
684
685 # Create a Carpet.
686 cpt1 = Carpet(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST,
687 warp_mode = WarpMode.SCALAR, lut = Lut.COLOR, cell_to_point = True,
688 outline = True)
689 cpt1.setPlaneToXY(0.2)
690 cpt1.setScaleFactor(1.9)
691
692 # Create a Camera.
693 c1 = Camera(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST)
694 c1.isometricView()
695
696 # Render the object.
697 s.render(PYVISI_EXAMPLE_IMAGES_PATH + IMAGE_NAME)
698 \end{python}
699
700 \subsubsection{\Image class}
701
702 \begin{classdesc}{Image}{scene, image_reader, viewport = Viewport.SOUTH_WEST}
703 Class that displays an image which can be scaled (upwards and downwards). The
704 image can also be translated and rotated along the X, Y and Z axes. One of
705 the most common use of this feature is pasting an image on a surface map.
706 \end{classdesc}
707
708 The following are some of the methods available:\\
709 Methods from \ActorThreeD, \PlaneSource and \Transform.
710
711 A typical usage of \Image is shown below.
712
713 \begin{python}
714 # Import the necessary modules.
715 from esys.pyvisi import Scene, DataCollector, StreamLine, Camera
716 from esys.pyvisi.constant import *
717
718 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes/"
719 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images/"
720 X_SIZE = 400
721 Y_SIZE = 400
722
723 VECTOR_FIELD_CELL_DATA = "temperature"
724 FILE_3D = "interior_3D.xml"
725 IMAGE_NAME = "streamline.jpg"
726 JPG_RENDERER = Renderer.ONLINE_JPG
727
728
729 # Create a Scene.
730 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
731 y_size = Y_SIZE)
732
733 # Create a DataCollector reading from a XML file.
734 dc1 = DataCollector(source = Source.XML)
735 dc1.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FILE_3D)
736
737 # Create a Streamline.
738 sl1 = StreamLine(scene = s, data_collector = dc1,
739 viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.SCALAR,
740 lut = Lut.COLOR, cell_to_point = False, outline = True)
741 sl1.setTubeRadius(radius = 0.02)
742
743 # Create a Camera.
744 c1 = Camera(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST)
745 c1.isometricView()
746
747 # Render the object.
748 s.render(PYVISI_EXAMPLE_IMAGES_PATH + IMAGE_NAME)
749 \end{python}
750
751
752 %##############################################################################
753
754
755 \subsection{Coordinate Classes}
756 This subsection details the instances used to position the rendered object.
757
758 \begin{classdesc}{LocalPosition}{x_coor, y_coor}
759 Class that defines the local positioning coordinate system (2D).
760 \end{classdesc}
761
762 \begin{classdesc}{GlobalPosition}{x_coor, y_coor, z_coor}
763 Class that defines the global positioning coordinate system (3D).
764 \end{classdesc}
765
766
767 %##############################################################################
768
769
770 \subsection{Supporting Classes}
771 This subsection details the supporting classes inherited by the data
772 visualization classes and their available methods.
773
774 \subsubsection{\ActorThreeD class}
775
776 The following are some of the methods available:
777
778 \begin{methoddesc}[Actor3D]{setOpacity}{opacity}
779 Set the opacity (transparency) of the 3D actor.
780 \end{methoddesc}
781
782 \begin{methoddesc}[Actor3D]{setColor}{color}
783 Set the color of the 3D actor.
784 \end{methoddesc}
785
786 \begin{methoddesc}[Actor3D]{setRepresentationToWireframe}{}
787 Set the representation of the 3D actor to wireframe.
788 \end{methoddesc}
789
790 \subsubsection{\ActorTwoD class}
791
792 The following are some of the methods available:
793
794 \begin{methoddesc}[Actor2D]{setPosition}{position}
795 Set the position (XY) of the 2D actor. Default position is the lower left hand
796 corner of the window / viewport.
797 \end{methoddesc}
798
799 \subsubsection{\Clipper class}
800
801 The following are some of the methods available:
802
803 \begin{methoddesc}[Clipper]{setInsideOutOn}{}
804 Clips one side of the rendered object.
805 \end{methoddesc}
806
807 \begin{methoddesc}[Clipper]{setInsideOutOff}{}
808 Clips the other side of the rendered object.
809 \end{methoddesc}
810
811 \begin{methoddesc}[Clipper]{setClipValue}{value}
812 Set the scalar clip value (instead of using a plane) for the clipper.
813 \end{methoddesc}
814
815 \subsubsection{\ContourModule class}
816
817 The following are some of the methods available:
818
819 \begin{methoddesc}[ContourModule]{generateContours}{contours,
820 lower_range = None, upper_range = None}
821 Generate the specified number of contours within the specified range.
822 In order to generate an iso surface, the 'lower_range' and 'upper_range'
823 must be equal.
824 \end{methoddesc}
825
826 \subsubsection{\GlyphThreeD class}
827
828 The following are some of the methods available:
829
830 \begin{methoddesc}[Glyph3D]{setScaleModeByVector}{}
831 Set the 3D glyph to scale according to the vector data.
832 \end{methoddesc}
833
834 \begin{methoddesc}[Glyph3D]{setScaleModeByScalar}{}
835 Set the 3D glyph to scale according to the scalar data.
836 \end{methoddesc}
837
838 \begin{methoddesc}[Glyph3D]{setScaleFactor}{scale_factor}
839 Set the 3D glyph scale factor.
840 \end{methoddesc}
841
842 \subsubsection{\TensorGlyph class}
843
844 The following are some of the methods available:
845
846 \begin{methoddesc}[TensorGlyph]{setScaleFactor}{scale_factor}
847 Set the scale factor for the tensor glyph.
848 \end{methoddesc}
849
850 \begin{methoddesc}[TensorGlyph]{setMaxScaleFactor}{max_scale_factor}
851 Set the maximum allowable scale factor for the tensor glyph.
852 \end{methoddesc}
853
854 \subsubsection{\PlaneSource class}
855
856 The following are some of the methods available:
857
858 \begin{methoddesc}[PlaneSource]{setPoint1}{position}
859 Set the first point from the origin of the plane source.
860 \end{methoddesc}
861
862 \begin{methoddesc}[PlaneSource]{setPoint2}{position}
863 Set the second point from the origin of the plane source.
864 \end{methoddesc}
865
866 \subsubsection{\PointSource class}
867
868 The following are some of the methods available:
869
870 \begin{methoddesc}[PointSource]{setPointSourceRadius}{radius}
871 Set the radius of the sphere.
872 \end{methoddesc}
873
874 \begin{methoddesc}[PointSource]{setPointSourceCenter}{position}
875 Set the center of the sphere.
876 \end{methoddesc}
877
878 \begin{methoddesc}[PointSource]{setPointSourceNumberOfPoints}{points}
879 Set the number of points to generate within the sphere (the larger the
880 number of points, the more streamlines are generated).
881 \end{methoddesc}
882
883 \subsubsection{\Sphere class}
884
885 The following are some of the methods available:
886
887 \begin{methoddesc}[Sphere]{setThetaResolution}{resolution}
888 Set the theta resolution of the sphere.
889 \end{methoddesc}
890
891 \begin{methoddesc}[Sphere]{setPhiResolution}{resolution}
892 Set the phi resoluton of the sphere.
893 \end{methoddesc}
894
895 \subsubsection{\StreamLineModule class}
896
897 The following are some of the methods available:
898
899 \begin{methoddesc}[StreamLineModule]{setMaximumPropagationTime}{time}
900 Set the maximum length of the streamline expressed in elapsed time.
901 \end{methoddesc}
902
903 \begin{methoddesc}[StreamLineModule]{setIntegrationToBothDirections}{}
904 Set the integration to occur both sides: forward (where the streamline
905 goes) and backward (where the streamline came from).
906 \end{methoddesc}
907
908 \subsubsection{\Transform class}
909
910 \begin{methoddesc}[Transform]{translate}{x_offset, y_offset, z_offset}
911 Translate the rendered object along the x, y and z-axes.
912 \end{methoddesc}
913
914 \begin{methoddesc}[Transform]{rotateX}{angle}
915 Rotate the plane along the x-axis.
916 \end{methoddesc}
917
918 \begin{methoddesc}[Transform]{rotateY}{angle}
919 Rotate the plane along the y-axis.
920 \end{methoddesc}
921
922 \begin{methoddesc}[Transform]{rotateZ}{angle}
923 Rotate the plane along the z-axis.
924 \end{methoddesc}
925
926 \begin{methoddesc}[Transform]{setPlaneToXY}{offset = 0}
927 Set the plane orthogonal to the z-axis.
928 \end{methoddesc}
929
930 \begin{methoddesc}[Transform]{setPlaneToYZ}{offset = 0}
931 Set the plane orthogonal to the x-axis.
932 \end{methoddesc}
933
934 \begin{methoddesc}[Transform]{setPlaneToXZ}{offset = 0}
935 Set the plane orthogonal to the y-axis.
936 \end{methoddesc}
937
938 \subsubsection{\Tube class}
939
940 \begin{methoddesc}[Tube]{setTubeRadius}{radius}
941 Set the radius of the tube.
942 \end{methoddesc}
943
944 \begin{methoddesc}[Tube]{setTubeRadiusToVaryByVector}{}
945 Set the radius of the tube to vary by vector data.
946 \end{methoddesc}
947
948 \begin{methoddesc}[Tube]{setTubeRadiusToVaryByScalar}{}
949 Set the radius of the tube to vary by scalar data.
950 \end{methoddesc}
951
952 \subsubsection{\Warp class}
953
954 \begin{methoddesc}[Warp]{setScaleFactor}{scale_factor}
955 Set the displacement scale factor.
956 \end{methoddesc}
957
958 \subsubsection{\MaskPoints class}
959
960 \begin{methoddesc}[MaskPoints]{setRatio}{ratio}
961 Mask every nth point.
962 \end{methoddesc}
963
964 \begin{methoddesc}[MaskPoints]{randomOn}{}
965 Enables the randomization of the points selected for masking.
966 \end{methoddesc}
967
968
969 % #############################################################################
970
971
972 \section{More Examples}
973 This section shows more examples.
974
975 \textsf{Reading A Series of Files}
976
977 \begin{python}
978 # Import the necessary modules.
979 from esys.pyvisi import Scene, DataCollector, Contour, Camera
980 from esys.pyvisi.constant import *
981
982 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes/"
983 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images/"
984 X_SIZE = 400
985 Y_SIZE = 300
986
987 SCALAR_FIELD_POINT_DATA_1 = "lava"
988 SCALAR_FIELD_POINT_DATA_2 = "talus"
989 FILE_2D = "phi_talus_lava."
990 FIRST_FILE_NAME = "phi_talus_lava.0099.vtu"
991
992 IMAGE_NAME = "seriesofreads"
993 JPG_RENDERER = Renderer.ONLINE_JPG
994
995
996 # Create a Scene.
997 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
998 y_size = Y_SIZE)
999
1000 # Create a DataCollector reading from a XML file. An initial file must always
1001 # be assigned when the DataCollector is created, although the same file is
1002 # read again in the for-loop.
1003 dc1 = DataCollector(source = Source.XML)
1004 dc1.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FIRST_FILE_NAME)
1005 dc1.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA_1)
1006
1007 # Create a Contour.
1008 mosc1 = Contour(scene = s, data_collector = dc1,
1009 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
1010 outline = True)
1011 mosc1.generateContours(0)
1012
1013 # Create a second DataCollector reading from the same XML file. An initial
1014 # file must always be assigned when the DataCollector is created,
1015 # although the same file is read again in the for-loop.
1016 dc2 = DataCollector(source = Source.XML)
1017 dc2.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FIRST_FILE_NAME)
1018 dc2.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA_2)
1019
1020 # Create a second Contour.
1021 mosc2 = Contour(scene = s, data_collector = dc2,
1022 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
1023 outline = True)
1024 mosc2.generateContours(0)
1025
1026 # Read in one file one after another and render the object.
1027 for i in range(99, 104):
1028 dc1.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FILE_2D +
1029 "%04d.vtu" % i)
1030 dc1.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA_1)
1031 dc2.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FILE_2D +
1032 "%04d.vtu" % i)
1033 dc2.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA_2)
1034
1035 s.render(PYVISI_EXAMPLE_IMAGES_PATH + IMAGE_NAME + "%04d.jpg" % i)
1036 \end{python}
1037
1038 \textsf{Manipulating A Single File with A Series of Translation}
1039
1040 \begin{python}
1041 # Import the necessary modules.
1042 from esys.pyvisi import Scene, DataCollector, MapOnPlaneCut, Camera
1043 from esys.pyvisi.constant import *
1044
1045 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes/"
1046 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images/"
1047 X_SIZE = 400
1048 Y_SIZE = 400
1049
1050 SCALAR_FIELD_POINT_DATA = "temperature"
1051 FILE_3D = "interior_3D.xml"
1052 IMAGE_NAME = "seriesofcuts"
1053 JPG_RENDERER = Renderer.ONLINE_JPG
1054
1055
1056 # Create a Scene.
1057 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
1058 y_size = Y_SIZE)
1059
1060 # Create a DataCollector reading from a XML file.
1061 dc1 = DataCollector(source = Source.XML)
1062 dc1.setFileName(file_name = PYVISI_EXAMPLE_MESHES_PATH + FILE_3D)
1063 dc1.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA)
1064
1065 # Create a MapOnPlaneCut.
1066 mopc1 = MapOnPlaneCut(scene = s, data_collector = dc1,
1067 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
1068 outline = True)
1069 mopc1.setPlaneToYZ(offset = 0.1)
1070
1071 # Create a Camera.
1072 c1 = Camera(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST)
1073 c1.isometricView()
1074
1075 # Render the object with multiple cuts from a series of translation.
1076 for i in range(0, 5):
1077 s.render(PYVISI_EXAMPLE_IMAGES_PATH + IMAGE_NAME + "%02d.jpg" % i)
1078 mopc1.translate(0.6,0,0)
1079 \end{python}
1080
1081 \section{Useful Keys}
1082 This section shows some of the useful keys when interacting with the rendered
1083 object.
1084
1085 \begin{table}
1086 \begin{center}
1087 \begin{tabular}{| c | p{13cm} |}
1088 \hline
1089 \textbf{Key} & \textbf{Description} \\ \hline
1090 Keypress 'c' / 'a' & Toggle between the camera ('c') and object ('a') mode. In
1091 camera mode, mouse events affect the camera position and focal point. In
1092 object mode, mouse events affect the rendered object's element (i.e.
1093 cut surface map, clipped velocity field, streamline, etc) that is under the
1094 mouse pointer.\\ \hline
1095 Mouse button 1 & Rotate the camera around its focal point (if in camera mode)
1096 or rotate the rendered object's element (if in object mode).\\ \hline
1097 Mourse button 2 & Pan the camera (if in camera mode) or translate the rendered
1098 object's element (if in object mode). \\ \hline
1099 Mouse button 3 & Zoom the camera (if in camera mode) or scale the rendered
1100 object's element (if in object mode). \\ \hline
1101 Keypress 3 & Toggle the render window in and out of stereo mode. By default,
1102 red-blue stereo pairs are created. \\ \hline
1103 Keypress 'e' / 'q' & Exit the application if only one file is to be read or
1104 read and display the next file if multiple files are to be read. \\ \hline
1105 Keypress 's' & Modify the representation of the rendered object to surfaces.
1106 \\ \hline
1107 Keypress 'w' & Modify the representation of the rendered object to wireframe.
1108 \\ \hline
1109 \end{tabular}
1110 \end{center}
1111 \end{table}
1112
1113
1114 % ############################################################################
1115
1116
1117 \section{Sample Output}
1118 The following section displays a list of sample outputs.
1119
1120 \begin{table}[h]
1121 \begin{tabular}{c c c}
1122 \includegraphics[width=\thumbnailwidth]{figures/Map} &
1123 \includegraphics[width=\thumbnailwidth]{figures/MapOnPlaneCut} &
1124 \includegraphics[width=\thumbnailwidth]{figures/MapOnPlaneClip} \\
1125 Map & MapOnPlaneCut & MapOnPlaneClip \\
1126 \includegraphics[width=\thumbnailwidth]{figures/MapOnScalarClip} &
1127 \includegraphics[width=\thumbnailwidth]{figures/Velocity} &
1128 \includegraphics[width=\thumbnailwidth]{figures/VelocityOnPlaneCut} \\
1129 MapOnScalarClip & Velocity & VelocityOnPlaneCut \\
1130 \includegraphics[width=\thumbnailwidth]{figures/VelocityOnPlaneClip} &
1131 \includegraphics[width=\thumbnailwidth]{figures/Ellipsoid} &
1132 \includegraphics[width=\thumbnailwidth]{figures/EllipsoidOnPlaneCut} \\
1133 VelocityOnPlaneClip & Ellipsoid & EllipsoidOnPlaneCut \\
1134 \includegraphics[width=\thumbnailwidth]{figures/EllipsoidOnPlaneClip} &
1135 \includegraphics[width=\thumbnailwidth]{figures/Contour} &
1136 \includegraphics[width=\thumbnailwidth]{figures/ContourOnPlaneCut} \\
1137 EllipsoidOnPlaneClip & Contour & ContourOnPlaneCut \\
1138 \includegraphics[width=\thumbnailwidth]{figures/ContourOnPlaneClip} &
1139 \includegraphics[width=\thumbnailwidth]{figures/StreamLine} &
1140 \includegraphics[width=\thumbnailwidth]{figures/Carpet} \\
1141 ContourOnPlaneClip & StreamLine & Carpet \\
1142 \end{tabular}
1143 \caption{Sample output}
1144 \end{table}
1145
1146
1147

  ViewVC Help
Powered by ViewVC 1.1.26