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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3293 - (show annotations)
Thu Oct 21 23:18:32 2010 UTC (9 years, 8 months ago) by caltinay
File MIME type: application/x-tex
File size: 51984 byte(s)
user's guide builds again with new class file. The cleanup can commence...

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

  ViewVC Help
Powered by ViewVC 1.1.26