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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3279 - (show annotations)
Fri Oct 15 04:02:06 2010 UTC (9 years ago) by caltinay
File MIME type: application/x-tex
File size: 52122 byte(s)
Some corrections to 1.3 of user's guide and defined graphicspath globally.

1
2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %
4 % Copyright (c) 2003-2010 by University of Queensland
5 % Earth Systems Science Computational Center (ESSCC)
6 % http://www.uq.edu.au/esscc
7 %
8 % Primary Business: Queensland, Australia
9 % Licensed under the Open Software License version 3.0
10 % http://www.opensource.org/licenses/osl-3.0.php
11 %
12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13
14
15 \chapter{The Module \pyvisi}
16 \label{PYVISI CHAP}
17 \declaremodule{extension}{esys.pyvisi}
18 \modulesynopsis{Python Visualization Interface}
19
20 \begin{Large}\strong{Warning: The Module \pyvisi is no longer supported and will be removed from future releases.}\end{Large}
21
22
23 \strong{\begin{Large}Warning: The Module \pyvisi is not supported under MPI \end{Large}.}
24
25 \section{Introduction}
26 \pyvisi is a Python module that is used to generate 2D and 3D visualizations
27 for escript and its PDE solver finley. The module provides
28 an easy to use interface to the \VTK library (\VTKUrl) to render (generate)
29 surface maps and contours for scalar fields, arrows and streamlines for vector
30 fields, and ellipsoids for tensor fields. There are three approaches for
31 rendering an object. (1) Online - object is rendered on-screen with
32 interaction capability (i.e. zoom and rotate), (2) Offline - object is
33 rendered off-screen (no pop-up window) and (3) Display - object is rendered
34 on-screen but with no interaction capability (on-the-fly animation). All three
35 approaches have the option to save the rendered object as an image (e.g. jpeg)
36 and subsequently converting a series of images into a movie (mpeg).
37
38 The following outlines the general steps to use Pyvisi:
39
40 \begin{enumerate}
41 \item Create a \Scene instance - a window in which objects will be rendered on.
42 \item Create a data input instance (i.e. \DataCollector or \ImageReader) -
43 reads the source data for visualization.
44 \item Create a data visualization object (i.e. \Map, \Velocity, \Ellipsoid,
45 \Contour, \Carpet, \StreamLine, etc.) - creates a visual representation of
46 the source data.
47 \item Create a \Camera or \Light instance - controls the viewing angle and
48 lighting effects.
49 \item Render the object - using either the Online, Offline or Display approach.
50 \item Generate movie - converts a series of images into a movie. (optional)
51 \end{enumerate}
52 \begin{center}
53 \begin{math}
54 scene \rightarrow data \; input \rightarrow data \; visualization \rightarrow
55 camera \, / \, light \rightarrow render \rightarrow movie
56 \end{math}
57 \end{center}
58
59 \section{\pyvisi Classes}
60 The following subsections give a brief overview of the important classes
61 and some of their corresponding methods. Please refer to \ReferenceGuide for
62 full details.
63
64
65 %#############################################################################
66
67
68 \subsection{Scene Classes}
69 This section details the instances used to setup the viewing environment.
70
71 \subsubsection{\Scene class}
72
73 \begin{classdesc}{Scene}{renderer = Renderer.ONLINE, num_viewport = 1,
74 x_size = 1152, y_size = 864}
75 A scene is a window in which objects are to be rendered on. Only
76 one scene needs to be created. However, a scene may be divided into four
77 smaller windows called viewports (if needed). Each viewport in turn can
78 render a different object.
79 \end{classdesc}
80
81 The following are some of the methods available:
82 \begin{methoddesc}[Scene]{setBackground}{color}
83 Set the background color of the scene.
84 \end{methoddesc}
85
86 \begin{methoddesc}[Scene]{render}{image_name = None}
87 Render the object using either the Online, Offline or Display mode.
88 \end{methoddesc}
89
90 \subsubsection{\Camera class}
91
92 \begin{classdesc}{Camera}{scene, viewport = Viewport.SOUTH_WEST}
93 A camera controls the display angle of the rendered object and one is
94 usually created for a \Scene. However, if a \Scene has four viewports, then a
95 separate camera may be created for each viewport.
96 \end{classdesc}
97
98 The following are some of the methods available:
99 \begin{methoddesc}[Camera]{setFocalPoint}{position}
100 Set the focal point of the camera.
101 \end{methoddesc}
102
103 \begin{methoddesc}[Camera]{setPosition}{position}
104 Set the position of the camera.
105 \end{methoddesc}
106
107 \begin{methoddesc}[Camera]{azimuth}{angle}
108 Rotate the camera to the left and right. The angle parameter is in degrees.
109 \end{methoddesc}
110
111 \begin{methoddesc}[Camera]{elevation}{angle}
112 Rotate the camera up and down (angle must be between -90 and 90).
113 \end{methoddesc}
114
115 \begin{methoddesc}[Camera]{backView}{}
116 Rotate the camera to view the back of the rendered object.
117 \end{methoddesc}
118
119 \begin{methoddesc}[Camera]{topView}{}
120 Rotate the camera to view the top of the rendered object.
121 \end{methoddesc}
122
123 \begin{methoddesc}[Camera]{bottomView}{}
124 Rotate the camera to view the bottom of the rendered object.
125 \end{methoddesc}
126
127 \begin{methoddesc}[Camera]{leftView}{}
128 Rotate the camera to view the left side of the rendered object.
129 \end{methoddesc}
130
131 \begin{methoddesc}[Camera]{rightView}{}
132 Rotate the camera to view the right side of the rendered object.
133 \end{methoddesc}
134
135 \begin{methoddesc}[Camera]{isometricView}{}
136 Rotate the camera to view an isometric projection of the rendered object.
137 \end{methoddesc}
138
139 \begin{methoddesc}[Camera]{dolly}{distance}
140 Move the camera towards (greater than 1) the rendered object. However,
141 it is not possible to move the camera away from the rendered object with this
142 method.
143 \end{methoddesc}
144
145 \subsubsection{\Light class}
146
147 \begin{classdesc}{Light}{scene, viewport = Viewport.SOUTH_WEST}
148 A light controls the lighting effect for the rendered object and is set up in
149 a similar way to \Camera.
150 \end{classdesc}
151
152 The following are some of the methods available:
153 \begin{methoddesc}[Light]{setColor}{color}
154 Set the light color.
155 \end{methoddesc}
156
157 \begin{methoddesc}[Light]{setFocalPoint}{position}
158 Set the focal point of the light.
159 \end{methoddesc}
160
161 \begin{methoddesc}[Light]{setPosition}{position}
162 Set the position of the light.
163 \end{methoddesc}
164
165 \begin{methoddesc}[Light]{setAngle}{elevation = 0, azimuth = 0}
166 An alternative to set the position and focal point of the light by using
167 elevation and azimuth.
168 \end{methoddesc}
169
170
171 %##############################################################################
172
173
174 \subsection{Input Classes}
175 \label{INPUT SEC}
176 This subsection details the instances used to read and load the source data
177 for visualization.
178
179 \subsubsection{\DataCollector class}
180 \begin{classdesc}{DataCollector}{source = Source.XML}
181 A data collector is used to read data either from an XML file (using
182 \texttt{setFileName()}) or from an escript object directly (using
183 \texttt{setData()}). Writing XML files is expensive but has the advantage
184 that the results can be analyzed easily after the simulation has completed.
185 \end{classdesc}
186
187 The following are some of the methods available:
188 \begin{methoddesc}[DataCollector]{setFileName}{file_name}
189 Set the XML file name to read.
190 \end{methoddesc}
191
192 \begin{methoddesc}[DataCollector]{setData}{**args}
193 Create data using the \textless name\textgreater=\textless data\textgreater
194 pairing. The method assumes that the data is given in the appropriate format.
195 \end{methoddesc}
196
197 \begin{methoddesc}[DataCollector]{setActiveScalar}{scalar}
198 Specify the scalar field to load.
199 \end{methoddesc}
200
201 \begin{methoddesc}[DataCollector]{setActiveVector}{vector}
202 Specify the vector field to load.
203 \end{methoddesc}
204
205 \begin{methoddesc}[DataCollector]{setActiveTensor}{tensor}
206 Specify the tensor field to load.
207 \end{methoddesc}
208
209 \subsubsection{\ImageReader class}
210
211 \begin{classdesc}{ImageReader}{format}
212 An image reader is used to read data from an image in a variety of formats.
213 \end{classdesc}
214
215 The following is one of the methods available:
216 \begin{methoddesc}[ImageReader]{setImageName}{image_name}
217 Set the filename of the image to be loaded.
218 \end{methoddesc}
219
220 \subsubsection{\TextTwoD class}
221
222 \begin{classdesc}{Text2D}{scene, text, viewport = Viewport.SOUTH_WEST}
223 This class is used to insert two-dimensional text for annotations
224 (e.g. titles, authors and labels).
225 \end{classdesc}
226
227 The following are some of the methods available:
228 \begin{methoddesc}[Text2D]{setFontSize}{size}
229 Set the 2D text size.
230 \end{methoddesc}
231
232 \begin{methoddesc}[Text2D]{boldOn}{}
233 Use bold font style for the text.
234 \end{methoddesc}
235
236 \begin{methoddesc}[Text2D]{setColor}{color}
237 Set the color of the 2D text.
238 \end{methoddesc}
239
240 Including methods from \ActorTwoD.
241
242
243 %##############################################################################
244
245
246 \subsection{Data Visualization Classes}
247 \label{DATAVIS SEC}
248 This subsection details the instances used to process and manipulate the source
249 data. The typical usage of some of the classes is also shown. See \Sec{SAMPLEOUTPUT SEC} for sample images generated with these classes.
250
251 One point to note is that the source can either be point or cell data. If the
252 source is cell data, a conversion to point data may or may not be
253 required, in order for the object to be rendered correctly.
254 If a conversion is needed, the 'cell_to_point' flag (see below) must
255 be set to 'True', otherwise to 'False' (which is the default). On occasions, an
256 inaccurate object may be rendered from cell data even after conversion.
257
258 \subsubsection{\Map class}
259
260 \begin{classdesc}{Map}{scene, data_collector,
261 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
262 outline = True}
263 Class that shows a scalar field on a domain surface. The domain surface
264 can either be color or gray-scale, depending on the lookup table used.
265 \end{classdesc}
266
267 The following are some of the methods available:\\
268 Methods from \ActorThreeD and \DataSetMapper.
269
270 A typical usage of \Map is shown below.
271
272 \begin{python}
273 """
274 Author: John Ngui, john.ngui@uq.edu.au
275 """
276
277 # Import the necessary modules.
278 from esys.pyvisi import Scene, DataCollector, Map, Camera
279 from esys.pyvisi.constant import *
280 import os
281
282 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes"
283 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images"
284 X_SIZE = 800
285 Y_SIZE = 800
286
287 SCALAR_FIELD_POINT_DATA = "temperature"
288 SCALAR_FIELD_CELL_DATA = "temperature_cell"
289 FILE_3D = "interior_3D.xml"
290 IMAGE_NAME = "map.jpg"
291 JPG_RENDERER = Renderer.ONLINE_JPG
292
293 # Create a Scene with four viewports.
294 s = Scene(renderer = JPG_RENDERER, num_viewport = 4, x_size = X_SIZE,
295 y_size = Y_SIZE)
296
297 # Create a DataCollector reading from a XML file.
298 dc1 = DataCollector(source = Source.XML)
299 dc1.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, FILE_3D))
300 dc1.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA)
301
302 # Create a Map for the first viewport.
303 m1 = Map(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST,
304 lut = Lut.COLOR, cell_to_point = False, outline = True)
305 m1.setRepresentationToWireframe()
306
307 # Create a Camera for the first viewport
308 c1 = Camera(scene = s, viewport = Viewport.SOUTH_WEST)
309 c1.isometricView()
310
311 # Create a second DataCollector reading from the same XML file but specifying
312 # a different scalar field.
313 dc2 = DataCollector(source = Source.XML)
314 dc2.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, FILE_3D))
315 dc2.setActiveScalar(scalar = SCALAR_FIELD_CELL_DATA)
316
317 # Create a Map for the third viewport.
318 m2 = Map(scene = s, data_collector = dc2, viewport = Viewport.NORTH_EAST,
319 lut = Lut.COLOR, cell_to_point = True, outline = True)
320
321 # Create a Camera for the third viewport
322 c2 = Camera(scene = s, viewport = Viewport.NORTH_EAST)
323
324 # Render the object.
325 s.render(image_name = os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, IMAGE_NAME))
326 \end{python}
327
328 \subsubsection{\MapOnPlaneCut class}
329
330 \begin{classdesc}{MapOnPlaneCut}{scene, data_collector,
331 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
332 outline = True}
333 This class works in a similar way to \Map, except that the result is a slice of
334 the scalar field produced by cutting the map with a plane. The plane can be
335 translated and rotated to its desired position.
336 \end{classdesc}
337
338 The following are some of the methods available:\\
339 Methods from \ActorThreeD, \Transform and \DataSetMapper.
340
341 \subsubsection{\MapOnPlaneClip class}
342
343 \begin{classdesc}{MapOnPlaneClip}{scene, data_collector,
344 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
345 outline = True}
346 This class works in a similar way to \MapOnPlaneCut, except that the defined
347 plane is used to clip the scalar field.
348 \end{classdesc}
349
350 The following are some of the methods available:\\
351 Methods from \ActorThreeD, \Transform, \Clipper and \DataSetMapper.
352
353 \subsubsection{\MapOnScalarClip class}
354
355 \begin{classdesc}{MapOnScalarClip}{scene, data_collector,
356 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
357 outline = True}
358 This class works in a similar way to \Map, except that it only shows parts of
359 the scalar field matching a scalar value.
360 \end{classdesc}
361
362 The following are some of the methods available:\\
363 Methods from \ActorThreeD, \Clipper and \DataSetMapper.
364
365 \subsubsection{\MapOnScalarClipWithRotation class}
366
367 \begin{classdesc}{MapOnScalarClipWithRotation}{scene, data_collector,
368 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False}
369 This class works in a similar way to \Map except that it
370 shows a 2D scalar field clipped using a scalar value and subsequently
371 rotated around the z-axis to create a 3D looking effect. This class should
372 only be used with 2D data sets and NOT 3D.
373 \end{classdesc}
374
375 The following are some of the methods available:\\
376 Methods from \ActorThreeD, \Clipper, \Rotation and \DataSetMapper.
377
378 \subsubsection{\Velocity class}
379
380 \begin{classdesc}{Velocity}{scene, data_collector, arrow = Arrow.TWO_D,
381 color_mode = ColorMode.VECTOR, viewport = Viewport.SOUTH_WEST,
382 lut = Lut.COLOR, cell_to_point = False, outline = True}
383 This class is used to display a vector field using arrows. The arrows can
384 either be color or gray-scale, depending on the lookup table used. If the
385 arrows are colored, there are two possible coloring modes, either using vector
386 data or scalar data. Similarly, there are two possible types of arrows, either
387 two-dimensional or three-dimensional.
388 \end{classdesc}
389
390 The following are some of the methods available:\\
391 Methods from \ActorThreeD, \GlyphThreeD, \MaskPoints and \DataSetMapper.
392
393 \subsubsection{\VelocityOnPlaneCut class}
394
395 \begin{classdesc}{VelocityOnPlaneCut}{scene, data_collector,
396 arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,
397 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR,
398 cell_to_point = False, outline = True}
399 This class works in a similar way to \MapOnPlaneCut, except that it shows a
400 vector field using arrows cut using a plane.
401 \end{classdesc}
402
403 The following are some of the methods available:\\
404 Methods from \ActorThreeD, \GlyphThreeD, \Transform, \MaskPoints and
405 \DataSetMapper.
406
407 A typical usage of \VelocityOnPlaneCut is shown below.
408
409 \begin{python}
410 """
411 Author: John Ngui, john.ngui@uq.edu.au
412 """
413
414 # Import the necessary modules
415 from esys.pyvisi import Scene, DataCollector, VelocityOnPlaneCut, Camera
416 from esys.pyvisi.constant import *
417 import os
418
419 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes"
420 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images"
421 X_SIZE = 400
422 Y_SIZE = 400
423
424 VECTOR_FIELD_CELL_DATA = "velocity"
425 FILE_3D = "interior_3D.xml"
426 IMAGE_NAME = "velocity.jpg"
427 JPG_RENDERER = Renderer.ONLINE_JPG
428
429 # Create a Scene.
430 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
431 y_size = Y_SIZE)
432
433 # Create a DataCollector reading from a XML file.
434 dc1 = DataCollector(source = Source.XML)
435 dc1.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, FILE_3D))
436 dc1.setActiveVector(vector = VECTOR_FIELD_CELL_DATA)
437
438 # Create VelocityOnPlaneCut.
439 vopc1 = VelocityOnPlaneCut(scene = s, data_collector = dc1,
440 viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.VECTOR,
441 arrow = Arrow.THREE_D, lut = Lut.COLOR, cell_to_point = False,
442 outline = True)
443 vopc1.setScaleFactor(scale_factor = 0.5)
444 vopc1.setPlaneToXY(offset = 0.5)
445 vopc1.setRatio(2)
446 vopc1.randomOn()
447
448 # Create a Camera.
449 c1 = Camera(scene = s, viewport = Viewport.SOUTH_WEST)
450 c1.isometricView()
451 c1.elevation(angle = -20)
452
453 # Render the object.
454 s.render(image_name = os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, IMAGE_NAME))
455 \end{python}
456
457 \subsubsection{\VelocityOnPlaneClip class}
458
459 \begin{classdesc}{VelocityOnPlaneClip}{scene, data_collector,
460 arrow = Arrow.TWO_D, color_mode = ColorMode.VECTOR,
461 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR,
462 cell_to_point = False, online = True}
463 This class works in a similar way to \MapOnPlaneClip, except that it shows a
464 vector field using arrows clipped using a plane.
465 \end{classdesc}
466
467 The following are some of the methods available:\\
468 Methods from \ActorThreeD, \GlyphThreeD, \Transform, \Clipper,
469 \MaskPoints and \DataSetMapper.
470
471 \subsubsection{\Ellipsoid class}
472
473 \begin{classdesc}{Ellipsoid}{scene, data_collector,
474 viewport = Viewport = SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
475 outline = True}
476 Class that shows a tensor field using ellipsoids. The ellipsoids can either be
477 color or gray-scale, depending on the lookup table used.
478 \end{classdesc}
479
480 The following are some of the methods available:\\
481 Methods from \ActorThreeD, \Sphere, \TensorGlyph, \MaskPoints and
482 \DataSetMapper.
483
484 \subsubsection{\EllipsoidOnPlaneCut class}
485
486 \begin{classdesc}{EllipsoidOnPlaneCut}{scene, data_collector,
487 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
488 outline = True}
489 This class works in a similar way to \MapOnPlaneCut, except that it shows
490 a tensor field using ellipsoids cut using a plane.
491 \end{classdesc}
492
493 The following are some of the methods available:\\
494 Methods from \ActorThreeD, \Sphere, \TensorGlyph, \Transform,
495 \MaskPoints and \DataSetMapper.
496
497 \subsubsection{\EllipsoidOnPlaneClip class}
498
499 \begin{classdesc}{EllipsoidOnPlaneClip}{scene, data_collector,
500 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
501 outline = True}
502 This class works in a similar way to \MapOnPlaneClip, except that it shows a
503 tensor field using ellipsoids clipped using a plane.
504 \end{classdesc}
505
506 The following are some of the methods available:\\
507 Methods from \ActorThreeD, \Sphere, \TensorGlyph, \Transform, \Clipper,
508 \MaskPoints and \DataSetMapper.
509
510 A typical usage of \EllipsoidOnPlaneClip is shown below.
511
512 \begin{python}
513 """
514 Author: John Ngui, john.ngui@uq.edu.au
515 """
516
517 # Import the necessary modules
518 from esys.pyvisi import Scene, DataCollector, EllipsoidOnPlaneClip, Camera
519 from esys.pyvisi.constant import *
520 import os
521
522 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes"
523 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images"
524 X_SIZE = 400
525 Y_SIZE = 400
526
527 TENSOR_FIELD_CELL_DATA = "stress_cell"
528 FILE_3D = "interior_3D.xml"
529 IMAGE_NAME = "ellipsoid.jpg"
530 JPG_RENDERER = Renderer.ONLINE_JPG
531
532 # Create a Scene.
533 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
534 y_size = Y_SIZE)
535
536 # Create a DataCollector reading from a XML file.
537 dc1 = DataCollector(source = Source.XML)
538 dc1.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, FILE_3D))
539 dc1.setActiveTensor(tensor = TENSOR_FIELD_CELL_DATA)
540
541 # Create an EllipsoidOnPlaneClip.
542 eopc1 = EllipsoidOnPlaneClip(scene = s, data_collector = dc1,
543 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = True,
544 outline = True)
545 eopc1.setPlaneToXY()
546 eopc1.setScaleFactor(scale_factor = 0.2)
547 eopc1.rotateX(angle = 10)
548
549 # Create a Camera.
550 c1 = Camera(scene = s, viewport = Viewport.SOUTH_WEST)
551 c1.bottomView()
552 c1.azimuth(angle = -90)
553 c1.elevation(angle = 10)
554
555 # Render the object.
556 s.render(image_name = os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, IMAGE_NAME))
557 \end{python}
558
559 \subsubsection{\Contour class}
560
561 \begin{classdesc}{Contour}{scene, data_collector,
562 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
563 outline = True}
564 Class that shows a scalar field using contour surfaces. The contour surfaces
565 can either be color or gray-scale, depending on the lookup table used. This
566 class can also be used to generate isosurfaces.
567 \end{classdesc}
568
569 The following are some of the methods available:\\
570 Methods from \ActorThreeD, \ContourModule and \DataSetMapper.
571
572 A typical usage of \Contour is shown below.
573
574 \begin{python}
575 """
576 Author: John Ngui, john.ngui@uq.edu.au
577 """
578
579 # Import the necessary modules
580 from esys.pyvisi import Scene, DataCollector, Contour, Camera
581 from esys.pyvisi.constant import *
582 import os
583
584 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes"
585 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images"
586 X_SIZE = 400
587 Y_SIZE = 400
588
589 SCALAR_FIELD_POINT_DATA = "temperature"
590 FILE_3D = "interior_3D.xml"
591 IMAGE_NAME = "contour.jpg"
592 JPG_RENDERER = Renderer.ONLINE_JPG
593
594 # Create a Scene.
595 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
596 y_size = Y_SIZE)
597
598 # Create a DataCollector reading a XML file.
599 dc1 = DataCollector(source = Source.XML)
600 dc1.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, FILE_3D))
601 dc1.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA)
602
603 # Create three contours.
604 ctr1 = Contour(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST,
605 lut = Lut.COLOR, cell_to_point = False, outline = True)
606 ctr1.generateContours(contours = 3)
607
608 # Create a Camera.
609 cam1 = Camera(scene = s, viewport = Viewport.SOUTH_WEST)
610 cam1.elevation(angle = -40)
611
612 # Render the object.
613 s.render(image_name = os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, IMAGE_NAME))
614 \end{python}
615
616 \subsubsection{\ContourOnPlaneCut class}
617
618 \begin{classdesc}{ContourOnPlaneCut}{scene, data_collector,
619 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
620 outline = True}
621 This class works in a similar way to \MapOnPlaneCut, except that it shows a
622 scalar field using contour surfaces cut using a plane.
623 \end{classdesc}
624
625 The following are some of the methods available:\\
626 Methods from \ActorThreeD, \ContourModule, \Transform and \DataSetMapper.
627
628 \subsubsection{\ContourOnPlaneClip class}
629
630 \begin{classdesc}{ContourOnPlaneClip}{scene, data_collector,
631 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
632 outline = True}
633 This class works in a similar way to \MapOnPlaneClip, except that it shows a
634 scalar field using contour surfaces clipped using a plane.
635 \end{classdesc}
636
637 The following are some of the methods available:\\
638 Methods from \ActorThreeD, \ContourModule, \Transform, \Clipper and
639 \DataSetMapper.
640
641 \subsubsection{\StreamLine class}
642
643 \begin{classdesc}{StreamLine}{scene, data_collector,
644 viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.VECTOR, lut = Lut.COLOR,
645 cell_to_point = False, outline = True}
646 Class that shows the direction of particles of a vector field using streamlines.
647 The streamlines can either be color or gray-scale, depending on the lookup
648 table used. If the streamlines are colored, there are two possible coloring
649 modes, either using vector data or scalar data.
650 \end{classdesc}
651
652 The following are some of the methods available:\\
653 Methods from \ActorThreeD, \PointSource, \StreamLineModule, \Tube and
654 \DataSetMapper.
655
656 A typical usage of \StreamLine is shown below.
657
658 \begin{python}
659 """
660 Author: John Ngui, john.ngui@uq.edu.au
661 """
662
663 # Import the necessary modules.
664 from esys.pyvisi import Scene, DataCollector, StreamLine, Camera
665 from esys.pyvisi.constant import *
666 import os
667
668 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes"
669 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images"
670 X_SIZE = 400
671 Y_SIZE = 400
672
673 VECTOR_FIELD_CELL_DATA = "temperature"
674 FILE_3D = "interior_3D.xml"
675 IMAGE_NAME = "streamline.jpg"
676 JPG_RENDERER = Renderer.ONLINE_JPG
677
678 # Create a Scene.
679 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
680 y_size = Y_SIZE)
681
682 # Create a DataCollector reading from a XML file.
683 dc1 = DataCollector(source = Source.XML)
684 dc1.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, FILE_3D))
685
686 # Create streamlines.
687 sl1 = StreamLine(scene = s, data_collector = dc1,
688 viewport = Viewport.SOUTH_WEST, color_mode = ColorMode.SCALAR,
689 lut = Lut.COLOR, cell_to_point = False, outline = True)
690 sl1.setTubeRadius(radius = 0.02)
691 sl1.setTubeNumberOfSides(3)
692 sl1.setTubeRadiusToVaryByVector()
693 sl1.setPointSourceRadius(0.9)
694
695 # Create a Camera.
696 c1 = Camera(scene = s, viewport = Viewport.SOUTH_WEST)
697 c1.isometricView()
698
699 # Render the object.
700 s.render(image_name = os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, IMAGE_NAME))
701 \end{python}
702
703 \subsubsection{\Carpet class}
704
705 \begin{classdesc}{Carpet}{scene, data_collector,
706 viewport = Viewport.Viewport.SOUTH_WEST, warp_mode = WarpMode.SCALAR,
707 lut = Lut.COLOR, cell_to_point = False, outline = True}
708 This class works in a similar way to \MapOnPlaneCut, except that it shows a
709 scalar field cut on a plane and deformed (warped) along the normal. The
710 plane can either be color or gray-scale, depending on the lookup table used.
711 Similarly, the plane can be deformed either using scalar data or vector data.
712 \end{classdesc}
713
714 The following are some of the methods available:\\
715 Methods from \ActorThreeD, \Warp, \Transform and \DataSetMapper.
716
717 A typical usage of \Carpet is shown below.
718
719 \begin{python}
720 """
721 Author: John Ngui, john.ngui@uq.edu.au
722 """
723
724 # Import the necessary modules.
725 from esys.pyvisi import Scene, DataCollector, Carpet, Camera
726 from esys.pyvisi.constant import *
727 import os
728
729 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes"
730 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images"
731 X_SIZE = 400
732 Y_SIZE = 400
733
734 SCALAR_FIELD_CELL_DATA = "temperature_cell"
735 FILE_3D = "interior_3D.xml"
736 IMAGE_NAME = "carpet.jpg"
737 JPG_RENDERER = Renderer.ONLINE_JPG
738
739 # Create a Scene.
740 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
741 y_size = Y_SIZE)
742
743 # Create a DataCollector reading from a XML file.
744 dc1 = DataCollector(source = Source.XML)
745 dc1.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, FILE_3D))
746 dc1.setActiveScalar(scalar = SCALAR_FIELD_CELL_DATA)
747
748 # Create a Carpet.
749 cpt1 = Carpet(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST,
750 warp_mode = WarpMode.SCALAR, lut = Lut.COLOR, cell_to_point = True,
751 outline = True)
752 cpt1.setPlaneToXY(0.2)
753 cpt1.setScaleFactor(1.9)
754
755 # Create a Camera.
756 c1 = Camera(scene = s, viewport = Viewport.SOUTH_WEST)
757 c1.isometricView()
758
759 # Render the object.
760 s.render(image_name = os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, IMAGE_NAME))
761 \end{python}
762
763 \subsubsection{\Legend class}
764
765 \begin{classdesc}{Legend}{scene, data_collector,
766 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, legend = LegendType.SCALAR}
767 Class that shows a scalar field on a domain surface. The domain surface
768 can either be color or gray-scale, depending on the lookup table used
769 \end{classdesc}
770
771 The following are some of the methods available:\\
772 Methods from \ActorThreeD, \ScalarBar and \DataSetMapper.
773
774 \subsubsection{\Rectangle class}
775
776 \begin{classdesc}{Rectangle}{scene, viewport = Viewport.SOUTH_WEST}
777 Class that generates a rectangle box.
778 \end{classdesc}
779
780 The following are some of the methods available:\\
781 Methods from \ActorThreeD, \CubeSource and \DataSetMapper.
782
783 \subsubsection{\Image class}
784
785 \begin{classdesc}{Image}{scene, image_reader, viewport = Viewport.SOUTH_WEST}
786 Class that displays an image which can be scaled (upwards and downwards) and
787 has interaction capability. The image can also be translated and rotated along
788 the X, Y and Z axes. One of the most common use of this feature is pasting an
789 image on a surface map.
790 \end{classdesc}
791
792 The following are some of the methods available:\\
793 Methods from \ActorThreeD, \PlaneSource and \Transform.
794
795 A typical usage of \Image is shown below.
796
797 \begin{python}
798 """
799 Author: John Ngui, john.ngui@uq.edu.au
800 """
801
802 # Import the necessary modules.
803 from esys.pyvisi import Scene, DataCollector, Map, ImageReader, Image, Camera
804 from esys.pyvisi import GlobalPosition
805 from esys.pyvisi.constant import *
806 import os
807
808 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes"
809 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images"
810 X_SIZE = 400
811 Y_SIZE = 400
812
813 SCALAR_FIELD_POINT_DATA = "temperature"
814 FILE_3D = "interior_3D.xml"
815 LOAD_IMAGE_NAME = "flinders.jpg"
816 SAVE_IMAGE_NAME = "image.jpg"
817 JPG_RENDERER = Renderer.ONLINE_JPG
818
819 # Create a Scene.
820 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
821 y_size = Y_SIZE)
822
823 # Create a DataCollector reading from a XML file.
824 dc1 = DataCollector(source = Source.XML)
825 dc1.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, FILE_3D))
826
827 # Create a Map.
828 m1 = Map(scene = s, data_collector = dc1, viewport = Viewport.SOUTH_WEST,
829 lut = Lut.COLOR, cell_to_point = False, outline = True)
830 m1.setOpacity(0.3)
831
832 # Create an ImageReader (in place of DataCollector).
833 ir = ImageReader(ImageFormat.JPG)
834 ir.setImageName(image_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, \
835 LOAD_IMAGE_NAME))
836
837 # Create an Image.
838 i = Image(scene = s, image_reader = ir, viewport = Viewport.SOUTH_WEST)
839 i.setOpacity(opacity = 0.9)
840 i.translate(0,0,-1)
841 i.setPoint1(GlobalPosition(2,0,0))
842 i.setPoint2(GlobalPosition(0,2,0))
843
844 # Create a Camera.
845 c1 = Camera(scene = s, viewport = Viewport.SOUTH_WEST)
846
847 # Render the image.
848 s.render(image_name = os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, SAVE_IMAGE_NAME))
849 \end{python}
850
851 \subsubsection{\Logo class}
852
853 \begin{classdesc}{Logo}{scene, image_reader, viewport = Viewport.SOUTH_WEST}
854 Class that displays a static image, in particular a logo
855 (e.g. company symbol) and has NO interaction capability. The position and size
856 of the logo can be specified.
857 \end{classdesc}
858
859 The following are some of the methods available:\\
860 Methods from \ImageReslice and \ActorTwoD.
861
862 \subsubsection{\Movie class}
863
864 \begin{classdesc}{Movie}{parameter_file = "make_movie"}
865 This class is used to create movies out of a series of images. The parameter
866 specifies the name of a file that will contain the required information for the
867 'ppmtompeg' command which is used to generate the movie.
868 \end{classdesc}
869
870 The following are some of the methods available:\\
871 \begin{methoddesc}[Movie]{imageRange}{input_directory, first_image, last_image}
872 Use this method to specify that the movie is to be generated from image files
873 with filenames in a certain range (e.g. 'image000.jpg' to 'image050.jpg').
874 \end{methoddesc}
875
876 \begin{methoddesc}[Movie]{imageList}{input_directory, image_list}
877 Use this method to specify a list of arbitrary image filenames from which the
878 movie is to be generated.
879 \end{methoddesc}
880
881 \begin{methoddesc}[Movie]{makeMovie}{movie}
882 Generate the movie with the specified filename.
883 \end{methoddesc}
884
885 A typical usage of \Movie is shown below.
886
887 \begin{python}
888 """
889 Author: John Ngui, john.ngui@uq.edu.au
890 """
891
892 # Import the necessary modules.
893 from esys.pyvisi import Scene, DataCollector, Map, Camera, Velocity, Legend
894 from esys.pyvisi import Movie, LocalPosition
895 from esys.pyvisi.constant import *
896 import os
897
898 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes"
899 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images"
900 X_SIZE = 800
901 Y_SIZE = 800
902
903 SCALAR_FIELD_POINT_DATA = "temp"
904 FILE_2D = "tempvel-"
905 IMAGE_NAME = "movie"
906 JPG_RENDERER = Renderer.OFFLINE_JPG
907
908 # Create a Scene.
909 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
910 y_size = Y_SIZE)
911
912 # Create a DataCollector reading from a XML file.
913 dc1 = DataCollector(source = Source.XML)
914 dc1.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA)
915
916 # Create a Map.
917 m1 = Map(scene = s, data_collector = dc1,
918 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
919 outline = True)
920
921 # Create a Camera.
922 cam1 = Camera(scene = s, viewport = Viewport.SOUTH_WEST)
923
924 # Create a movie.
925 mov = Movie()
926 lst = []
927
928 # Read in one file one after another and render the object.
929 for i in range(938, 949):
930 dc1.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, \
931 FILE_2D + "%06d.vtu") % i)
932
933 s.render(image_name = os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, \
934 IMAGE_NAME + "%06d.jpg" % i))
935
936 lst.append(IMAGE_NAME + "%06d.jpg" % i)
937
938 # Images (first and last inclusive) from which the movie is to be generated.
939 mov.imageRange(input_directory = PYVISI_EXAMPLE_IMAGES_PATH,
940 first_image = IMAGE_NAME + "000938.jpg",
941 last_image = IMAGE_NAME + "000948.jpg")
942
943 # Alternatively, a list of images can be specified.
944 #mov.imageList(input_directory = PYVISI_EXAMPLE_IMAGES_PATH, image_list = lst)
945
946 # Generate the movie.
947 mov.makeMovie(os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, "movie.mpg"))
948 \end{python}
949
950
951 %##############################################################################
952
953
954 \subsection{Coordinate Classes}
955 This subsection details the instances used to position rendered objects.
956
957 \subsubsection{\LocalPosition class}
958
959 \begin{classdesc}{LocalPosition}{x_coor, y_coor}
960 Class that defines a position (X and Y) in the local 2D coordinate system.
961 \end{classdesc}
962
963 \subsubsection{\GlobalPosition class}
964
965 \begin{classdesc}{GlobalPosition}{x_coor, y_coor, z_coor}
966 Class that defines a position (X, Y and Z) in the global 3D coordinate system.
967 \end{classdesc}
968
969
970 %##############################################################################
971
972
973 \subsection{Supporting Classes}
974 This subsection details the supporting classes and their corresponding methods
975 inherited by the input (see \Sec{INPUT SEC}) and data
976 visualization classes (see \Sec{DATAVIS SEC}).
977
978 \subsubsection{\ActorThreeD class}
979 Class that defines a 3D actor. \\
980
981 The following are some of the methods available:
982
983 \begin{methoddesc}[Actor3D]{setOpacity}{opacity}
984 Set the opacity (transparency) of the 3D actor.
985 \end{methoddesc}
986
987 \begin{methoddesc}[Actor3D]{setColor}{color}
988 Set the color of the 3D actor.
989 \end{methoddesc}
990
991 \begin{methoddesc}[Actor3D]{setRepresentationToWireframe}{}
992 Set the representation of the 3D actor to wireframe.
993 \end{methoddesc}
994
995 \subsubsection{\ActorTwoD class}
996 Class that defines a 2D actor. \\
997
998 The following are some of the methods available:
999
1000 \begin{methoddesc}[Actor2D]{setPosition}{position}
1001 Set the position (XY) of the 2D actor. Default position is the lower left hand
1002 corner of the window / viewport.
1003 \end{methoddesc}
1004
1005 \subsubsection{\Clipper class}
1006 Class that defines a clipper. \\
1007
1008 The following are some of the methods available:
1009
1010 \begin{methoddesc}[Clipper]{setInsideOutOn}{}
1011 Clips one side of the rendered object.
1012 \end{methoddesc}
1013
1014 \begin{methoddesc}[Clipper]{setInsideOutOff}{}
1015 Clips the other side of the rendered object.
1016 \end{methoddesc}
1017
1018 \begin{methoddesc}[Clipper]{setClipValue}{value}
1019 Set the scalar clip value (instead of using a plane) for the clipper.
1020 \end{methoddesc}
1021
1022 \subsubsection{\ContourModule class}
1023 Class that defines the contour module. \\
1024
1025 The following are some of the methods available:
1026
1027 \begin{methoddesc}[ContourModule]{generateContours}{contours = None,
1028 lower_range = None, upper_range = None}
1029 Generate the specified number of contours within the specified range.
1030 In order to generate a single isosurface, the 'lower_range' and 'upper_range'
1031 must be set to the same value.
1032 \end{methoddesc}
1033
1034 \subsubsection{\GlyphThreeD class}
1035 Class that defines 3D glyphs. \\
1036
1037 The following are some of the methods available:
1038
1039 \begin{methoddesc}[Glyph3D]{setScaleModeByVector}{}
1040 Set the 3D glyph to scale according to the vector data.
1041 \end{methoddesc}
1042
1043 \begin{methoddesc}[Glyph3D]{setScaleModeByScalar}{}
1044 Set the 3D glyph to scale according to the scalar data.
1045 \end{methoddesc}
1046
1047 \begin{methoddesc}[Glyph3D]{setScaleFactor}{scale_factor}
1048 Set the 3D glyph scale factor.
1049 \end{methoddesc}
1050
1051 \subsubsection{\TensorGlyph class}
1052 Class that defines tensor glyphs. \\
1053
1054 The following are some of the methods available:
1055
1056 \begin{methoddesc}[TensorGlyph]{setScaleFactor}{scale_factor}
1057 Set the scale factor for the tensor glyph.
1058 \end{methoddesc}
1059
1060 \begin{methoddesc}[TensorGlyph]{setMaxScaleFactor}{max_scale_factor}
1061 Set the maximum allowable scale factor for the tensor glyph.
1062 \end{methoddesc}
1063
1064 \subsubsection{\PlaneSource class}
1065 Class that defines a plane source. A plane source is defined by an origin
1066 and two other points, which form the axes (X and Y). \\
1067
1068 The following are some of the methods available:
1069
1070 \begin{methoddesc}[PlaneSource]{setOrigin}{position}
1071 Set the origin of the plane source.
1072 \end{methoddesc}
1073
1074 \begin{methoddesc}[PlaneSource]{setPoint1}{position}
1075 Set the first point from the origin of the plane source.
1076 \end{methoddesc}
1077
1078 \begin{methoddesc}[PlaneSource]{setPoint2}{position}
1079 Set the second point from the origin of the plane source.
1080 \end{methoddesc}
1081
1082 \subsubsection{\PointSource class}
1083 Class that defines the source (location) to generate points. The points are
1084 generated within the radius of a sphere. \\
1085
1086 The following are some of the methods available:
1087
1088 \begin{methoddesc}[PointSource]{setPointSourceRadius}{radius}
1089 Set the radius of the sphere.
1090 \end{methoddesc}
1091
1092 \begin{methoddesc}[PointSource]{setPointSourceCenter}{center}
1093 Set the center of the sphere.
1094 \end{methoddesc}
1095
1096 \begin{methoddesc}[PointSource]{setPointSourceNumberOfPoints}{points}
1097 Set the number of points to generate within the sphere (the larger the
1098 number of points, the more streamlines are generated).
1099 \end{methoddesc}
1100
1101 \subsubsection{\Sphere class}
1102 Class that defines a sphere. \\
1103
1104 The following are some of the methods available:
1105
1106 \begin{methoddesc}[Sphere]{setThetaResolution}{resolution}
1107 Set the theta resolution of the sphere.
1108 \end{methoddesc}
1109
1110 \begin{methoddesc}[Sphere]{setPhiResolution}{resolution}
1111 Set the phi resolution of the sphere.
1112 \end{methoddesc}
1113
1114 \subsubsection{\StreamLineModule class}
1115 Class that defines the streamline module. \\
1116
1117 The following are some of the methods available:
1118
1119 \begin{methoddesc}[StreamLineModule]{setMaximumPropagationTime}{time}
1120 Set the maximum length of the streamline expressed in elapsed time.
1121 \end{methoddesc}
1122
1123 \begin{methoddesc}[StreamLineModule]{setIntegrationToBothDirections}{}
1124 Set the integration to occur both sides: forward (where the streamline
1125 goes) and backward (where the streamline came from).
1126 \end{methoddesc}
1127
1128 \subsubsection{\Transform class}
1129 Class that defines the orientation of planes. \\
1130
1131 The following are some of the methods available:
1132
1133 \begin{methoddesc}[Transform]{translate}{x_offset, y_offset, z_offset}
1134 Translate the rendered object along the x, y and z-axes.
1135 \end{methoddesc}
1136
1137 \begin{methoddesc}[Transform]{rotateX}{angle}
1138 Rotate the plane around the x-axis.
1139 \end{methoddesc}
1140
1141 \begin{methoddesc}[Transform]{rotateY}{angle}
1142 Rotate the plane around the y-axis.
1143 \end{methoddesc}
1144
1145 \begin{methoddesc}[Transform]{rotateZ}{angle}
1146 Rotate the plane around the z-axis.
1147 \end{methoddesc}
1148
1149 \begin{methoddesc}[Transform]{setPlaneToXY}{offset = 0}
1150 Set the plane orthogonal to the z-axis.
1151 \end{methoddesc}
1152
1153 \begin{methoddesc}[Transform]{setPlaneToYZ}{offset = 0}
1154 Set the plane orthogonal to the x-axis.
1155 \end{methoddesc}
1156
1157 \begin{methoddesc}[Transform]{setPlaneToXZ}{offset = 0}
1158 Set the plane orthogonal to the y-axis.
1159 \end{methoddesc}
1160
1161 \subsubsection{\Tube class}
1162 Class that defines the tube wrapped around the streamlines. \\
1163
1164 The following are some of the methods available:
1165
1166 \begin{methoddesc}[Tube]{setTubeRadius}{radius}
1167 Set the radius of the tube.
1168 \end{methoddesc}
1169
1170 \begin{methoddesc}[Tube]{setTubeRadiusToVaryByVector}{}
1171 Set the radius of the tube to vary by vector data.
1172 \end{methoddesc}
1173
1174 \begin{methoddesc}[Tube]{setTubeRadiusToVaryByScalar}{}
1175 Set the radius of the tube to vary by scalar data.
1176 \end{methoddesc}
1177
1178 \subsubsection{\Warp class}
1179 Class that defines the deformation of a scalar field. \\
1180
1181 The following are some of the methods available:
1182
1183 \begin{methoddesc}[Warp]{setScaleFactor}{scale_factor}
1184 Set the displacement scale factor.
1185 \end{methoddesc}
1186
1187 \subsubsection{\MaskPoints class}
1188 Class that defines masking of points. This is useful to prevent the
1189 rendered object from being cluttered with arrows or ellipsoids. \\
1190
1191 The following are some of the methods available:
1192
1193 \begin{methoddesc}[MaskPoints]{setRatio}{ratio}
1194 Mask every n'th point.
1195 \end{methoddesc}
1196
1197 \begin{methoddesc}[MaskPoints]{randomOn}{}
1198 Enables randomization of the points selected for masking.
1199 \end{methoddesc}
1200
1201 \subsubsection{\ScalarBar class}
1202 Class that defines a scalar bar. \\
1203
1204 The following are some of the methods available:
1205
1206 \begin{methoddesc}[ScalarBar]{setTitle}{title}
1207 Set the title of the scalar bar.
1208 \end{methoddesc}
1209
1210 \begin{methoddesc}[ScalarBar]{setPosition}{position}
1211 Set the local position of the scalar bar.
1212 \end{methoddesc}
1213
1214 \begin{methoddesc}[ScalarBar]{setOrientationToHorizontal}{}
1215 Set the orientation of the scalar bar to horizontal.
1216 \end{methoddesc}
1217
1218 \begin{methoddesc}[ScalarBar]{setOrientationToVertical}{}
1219 Set the orientation of the scalar bar to vertical.
1220 \end{methoddesc}
1221
1222 \begin{methoddesc}[ScalarBar]{setHeight}{height}
1223 Set the height of the scalar bar.
1224 \end{methoddesc}
1225
1226 \begin{methoddesc}[ScalarBar]{setWidth}{width}
1227 Set the width of the scalar bar.
1228 \end{methoddesc}
1229
1230 \begin{methoddesc}[ScalarBar]{setLabelColor}{color}
1231 Set the color of the scalar bar's label.
1232 \end{methoddesc}
1233
1234 \begin{methoddesc}[ScalarBar]{setTitleColor}{color}
1235 Set the color of the scalar bar's title.
1236 \end{methoddesc}
1237
1238 \subsubsection{\ImageReslice class}
1239 Class that defines an image reslice which is used to resize static
1240 (no interaction capability) images (i.e. logo). \\
1241
1242 The following are some of the methods available:
1243
1244 \begin{methoddesc}[ImageReslice]{setSize}{size}
1245 Set the size factor of the image. The value must be between 0 and 2.
1246 Size 1 (one) keeps the image in its original size (which is the default).
1247 \end{methoddesc}
1248
1249 \subsubsection{\DataSetMapper class}
1250 Class that defines a data set mapper. \\
1251
1252 The following are some of the methods available:
1253
1254 \begin{methoddesc}[DataSetMapper]{setScalarRange}{lower_range, upper_range}
1255 Set the minimum and maximum scalar range for the data set mapper. This
1256 method is called when the range has been specified by the user.
1257 Therefore, the scalar range read from the source will be ignored.
1258 \end{methoddesc}
1259
1260 \subsubsection{\CubeSource class}
1261 Class that defines a cube source. The center of the cube source defines
1262 the point from which the cube is to be generated and the X, Y
1263 and Z lengths define the length of the cube from the center point. If
1264 X length is 3, then the X length to the left and right of the center
1265 point is 1.5 respectively.\\
1266
1267 The following are some of the methods available:
1268
1269 \begin{methoddesc}[CubeSource]{setCenter}{center}
1270 Set the cube source center.
1271 \end{methoddesc}
1272
1273 \begin{methoddesc}[CubeSource]{setXLength}{length}
1274 Set the cube source length along the x-axis.
1275 \end{methoddesc}
1276
1277 \begin{methoddesc}[CubeSource]{setYLength}{length}
1278 Set the cube source length along the y-axis.
1279 \end{methoddesc}
1280
1281 \begin{methoddesc}[CubeSource]{setZLength}{length}
1282 Set the cube source length along the z-axis.
1283 \end{methoddesc}
1284
1285 \subsubsection{\Rotation class}
1286 Class that sweeps 2D data around the z-axis to create a 3D looking effect. \\
1287
1288 The following are some of the methods available:
1289
1290 \begin{methoddesc}[Rotation]{setResolution}{resolution}
1291 Set the resolution of the sweep for the rotation, which controls the
1292 number of intermediate points.
1293 \end{methoddesc}
1294
1295 \begin{methoddesc}[Rotation]{setAngle}{angle}
1296 Set the angle of rotation.
1297 \end{methoddesc}
1298
1299
1300 % #############################################################################
1301
1302
1303 \section{More Examples}
1304 This section provides examples for some common tasks.
1305
1306 \subsection{Reading a Series of Files}
1307 The following script shows how to generate images from a time series using
1308 two data sources.
1309
1310 \begin{python}
1311 """
1312 Author: John Ngui, john.ngui@uq.edu.au
1313 """
1314
1315 # Import the necessary modules.
1316 from esys.pyvisi import Scene, DataCollector, Contour, Camera
1317 from esys.pyvisi.constant import *
1318 import os
1319
1320 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes"
1321 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images"
1322 X_SIZE = 400
1323 Y_SIZE = 300
1324
1325 SCALAR_FIELD_POINT_DATA_1 = "lava"
1326 SCALAR_FIELD_POINT_DATA_2 = "talus"
1327 FILE_2D = "phi_talus_lava."
1328
1329 IMAGE_NAME = "seriesofreads"
1330 JPG_RENDERER = Renderer.ONLINE_JPG
1331
1332 # Create a Scene.
1333 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
1334 y_size = Y_SIZE)
1335
1336 # Create a DataCollector reading from an XML file.
1337 dc1 = DataCollector(source = Source.XML)
1338 dc1.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA_1)
1339
1340 # Create a Contour.
1341 mosc1 = Contour(scene = s, data_collector = dc1,
1342 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
1343 outline = True)
1344 mosc1.generateContours(0)
1345
1346 # Create a second DataCollector reading from the same XML file
1347 # but specifying a different scalar field.
1348 dc2 = DataCollector(source = Source.XML)
1349 dc2.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA_2)
1350
1351 # Create a second Contour.
1352 mosc2 = Contour(scene = s, data_collector = dc2,
1353 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
1354 outline = True)
1355 mosc2.generateContours(0)
1356
1357 # Create a Camera.
1358 cam1 = Camera(scene = s, viewport = Viewport.SOUTH_WEST)
1359
1360 # Read in one file after another and render the object.
1361 for i in range(99, 104):
1362 dc1.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, \
1363 FILE_2D + "%04d.vtu") % i)
1364 dc2.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, \
1365 FILE_2D + "%04d.vtu") % i)
1366
1367 s.render(image_name = os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, \
1368 IMAGE_NAME + "%04d.jpg") % i)
1369 \end{python}
1370
1371 \subsection{Creating Slices of a Data Source}
1372 The following script shows how to save a series of images that slice the
1373 data at different points by gradually translating the cut plane.
1374
1375 \begin{python}
1376 """
1377 Author: John Ngui, john.ngui@uq.edu.au
1378 """
1379
1380 # Import the necessary modules.
1381 from esys.pyvisi import Scene, DataCollector, MapOnPlaneCut, Camera
1382 from esys.pyvisi.constant import *
1383 import os
1384
1385 PYVISI_EXAMPLE_MESHES_PATH = "data_meshes"
1386 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images"
1387 X_SIZE = 400
1388 Y_SIZE = 400
1389
1390 SCALAR_FIELD_POINT_DATA = "temperature"
1391 FILE_3D = "interior_3D.xml"
1392 IMAGE_NAME = "seriesofcuts"
1393 JPG_RENDERER = Renderer.ONLINE_JPG
1394
1395 # Create a Scene.
1396 s = Scene(renderer = JPG_RENDERER, num_viewport = 1, x_size = X_SIZE,
1397 y_size = Y_SIZE)
1398
1399 # Create a DataCollector reading from an XML file.
1400 dc1 = DataCollector(source = Source.XML)
1401 dc1.setFileName(file_name = os.path.join(PYVISI_EXAMPLE_MESHES_PATH, FILE_3D))
1402 dc1.setActiveScalar(scalar = SCALAR_FIELD_POINT_DATA)
1403
1404 # Create a MapOnPlaneCut.
1405 mopc1 = MapOnPlaneCut(scene = s, data_collector = dc1,
1406 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, cell_to_point = False,
1407 outline = True)
1408 mopc1.setPlaneToYZ(offset = 0.1)
1409
1410 # Create a Camera.
1411 c1 = Camera(scene = s, viewport = Viewport.SOUTH_WEST)
1412 c1.isometricView()
1413
1414 # Render the object with multiple cuts using a series of translations.
1415 for i in range(0, 5):
1416 s.render(image_name = os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, IMAGE_NAME +
1417 "%02d.jpg") % i)
1418 mopc1.translate(0.6,0,0)
1419 \end{python}
1420
1421 \subsection{Reading Data Directly from escript Objects}
1422 The following script shows how to combine Pyvisi code with escript code to
1423 generate visualizations on the fly.
1424
1425 \begin{python}
1426 """
1427 Author: Lutz Gross, l.gross@uq.edu.au
1428 Author: John Ngui, john.ngui@uq.edu.au
1429 """
1430
1431 # Import the necessary modules.
1432 from esys.escript import *
1433 from esys.escript.linearPDEs import LinearPDE
1434 from esys.finley import Rectangle
1435 from esys.pyvisi import Scene, DataCollector, Map, Camera
1436 from esys.pyvisi.constant import *
1437 import os
1438
1439 PYVISI_EXAMPLE_IMAGES_PATH = "data_sample_images"
1440 X_SIZE = 400
1441 Y_SIZE = 400
1442 JPG_RENDERER = Renderer.ONLINE_JPG
1443
1444 #... set some parameters ...
1445 xc = [0.02,0.002]
1446 r = 0.001
1447 qc = 50.e6
1448 Tref = 0.
1449 rhocp = 2.6e6
1450 eta = 75.
1451 kappa = 240.
1452 tend = 5.
1453 # initialize time, time step size and counter ...
1454 t=0
1455 h=0.1
1456 i=0
1457
1458 # generate domain ...
1459 mydomain = Rectangle(l0=0.05, l1=0.01, n0=250, n1=50)
1460 # open PDE ...
1461 mypde = LinearPDE(mydomain)
1462 mypde.setSymmetryOn()
1463 mypde.setValue(A=kappa*kronecker(mydomain), D=rhocp/h, d=eta, y=eta*Tref)
1464 # set heat source: ...
1465 x = mydomain.getX()
1466 qH = qc*whereNegative(length(x-xc)-r)
1467
1468 # set initial temperature ....
1469 T=Tref
1470
1471 # Create a Scene.
1472 s = Scene(renderer = JPG_RENDERER, x_size = X_SIZE, y_size = Y_SIZE)
1473
1474 # Create a DataCollector reading directly from escript objects.
1475 dc = DataCollector(source = Source.ESCRIPT)
1476
1477 # Create a Map.
1478 m = Map(scene = s, data_collector = dc, \
1479 viewport = Viewport.SOUTH_WEST, lut = Lut.COLOR, \
1480 cell_to_point = False, outline = True)
1481
1482 # Create a Camera.
1483 c = Camera(scene = s, viewport = Viewport.SOUTH_WEST)
1484
1485 # start iteration
1486 while t < 0.4:
1487 i += 1
1488 t += h
1489 mypde.setValue(Y=qH+rhocp/h*T)
1490 T = mypde.getSolution()
1491
1492 dc.setData(temp = T)
1493
1494 # Render the object.
1495 s.render(image_name = os.path.join(PYVISI_EXAMPLE_IMAGES_PATH, \
1496 "diffusion%02d.jpg") % i)
1497 \end{python}
1498
1499 \newpage
1500
1501 \section{Useful Keys}
1502 This section lists keyboard shortcuts available when interacting with rendered
1503 objects using the Online approach.
1504
1505 \begin{table}[ht]
1506 \begin{center}
1507 \begin{tabular}{| c | p{12cm} |}
1508 \hline
1509 \textbf{Key} & \textbf{Description} \\ \hline
1510 Keypress 'c' / 'a' & Toggle between the camera ('c') and object ('a') mode. In
1511 camera mode, mouse events affect the camera position and focal point. In
1512 object mode, mouse events affect the rendered object's element (i.e.
1513 cut surface map, clipped velocity field, streamline, etc) that is under the
1514 mouse pointer.\\ \hline
1515 Mouse button 1 & Rotate the camera around its focal point (if in camera mode)
1516 or rotate the rendered object's element (if in object mode).\\ \hline
1517 Mouse button 2 & Pan the camera (if in camera mode) or translate the rendered
1518 object's element (if in object mode). \\ \hline
1519 Mouse button 3 & Zoom the camera (if in camera mode) or scale the rendered
1520 object's element (if in object mode). \\ \hline
1521 Keypress 3 & Toggle the render window in and out of stereo mode. By default,
1522 red-blue stereo pairs are created. \\ \hline
1523 Keypress 'e' / 'q' & Exit the application if only one file is to be read, or
1524 read and display the next file if multiple files are to be read. \\ \hline
1525 Keypress 's' & Modify the representation of the rendered object to surfaces.
1526 \\ \hline
1527 Keypress 'w' & Modify the representation of the rendered object to wireframe.
1528 \\ \hline
1529 Keypress 'r' & Reset the position of the rendered object to the center.
1530 \\ \hline
1531 \end{tabular}
1532 \caption{Useful keys in Online render mode}
1533 \end{center}
1534 \end{table}
1535
1536
1537 % ############################################################################
1538
1539
1540 \newpage
1541 \renewcommand{\textfraction}{0.06} % force first table to stay with the text
1542 \section{Sample Output}
1543 \label{SAMPLEOUTPUT SEC}
1544 This section shows sample images produced with the various classes of Pyvisi.
1545 The source code to produce these images is included in the Pyvisi distribution.
1546 %
1547 \begin{table}[hb]
1548 \begin{tabular}{c c c}
1549 \includegraphics[width=\thumbnailwidth]{Map} &
1550 \includegraphics[width=\thumbnailwidth]{MapOnPlaneCut} &
1551 \includegraphics[width=\thumbnailwidth]{MapOnPlaneClip} \\
1552 Map & MapOnPlaneCut & MapOnPlaneClip \\
1553 \includegraphics[width=\thumbnailwidth]{MapOnScalarClip} &
1554 \includegraphics[width=\thumbnailwidth]{MapOnScalarClipWithRotation} &
1555 \includegraphics[width=\thumbnailwidth]{StreamLine} \\
1556 MapOnScalarClip & MapOnScalarClipWithRotation & Streamline \\ \\ \\
1557 \includegraphics[width=\thumbnailwidth]{Velocity} &
1558 \includegraphics[width=\thumbnailwidth]{VelocityOnPlaneCut} &
1559 \includegraphics[width=\thumbnailwidth]{VelocityOnPlaneClip} \\
1560 Velocity & VelocityOnPlaneCut & VelocityOnPlaneClip \\ \\ \\
1561 \includegraphics[width=\thumbnailwidth]{Ellipsoid} &
1562 \includegraphics[width=\thumbnailwidth]{EllipsoidOnPlaneCut} &
1563 \includegraphics[width=\thumbnailwidth]{EllipsoidOnPlaneClip} \\
1564 Ellipsoid & EllipsoidOnPlaneCut & EllipsoidOnPlaneClip \\ \\
1565 \end{tabular}
1566 %\caption{Sample output}
1567 \end{table}
1568 %
1569 \newpage
1570 %
1571 \begin{table}[t]
1572 \begin{tabular}{c c c}
1573 \includegraphics[width=\thumbnailwidth]{Contour} &
1574 \includegraphics[width=\thumbnailwidth]{ContourOnPlaneCut} &
1575 \includegraphics[width=\thumbnailwidth]{ContourOnPlaneClip} \\
1576 Contour & ContourOnPlaneCut & ContourOnPlaneClip \\ \\ \\
1577 \includegraphics[width=\thumbnailwidth]{Carpet} &
1578 \includegraphics[width=\thumbnailwidth]{Rectangle} &
1579 \includegraphics[width=\thumbnailwidth]{Image} \\
1580 Carpet & Rectangle & Image \\ \\ \\ \\ \\
1581 \includegraphics[width=\thumbnailwidth]{Text} &
1582 \includegraphics[width=\thumbnailwidth]{Logo} &
1583 \includegraphics[width=\thumbnailwidth]{Legend} \\
1584 Text & Logo & Legend \\ \\
1585 \end{tabular}
1586 %\caption{Sample Output (continued)}
1587 \end{table}
1588
1589

  ViewVC Help
Powered by ViewVC 1.1.26