1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
#############################################################
## ##
## Copyright (c) 2003-2011 by The University of Queensland ##
## Earth Systems Science Computational Centre (ESSCC) ##
## http://www.uq.edu.au/esscc ##
## ##
## Primary Business: Brisbane, Queensland, Australia ##
## Licensed under the Open Software License version 3.0 ##
## http://www.opensource.org/licenses/osl-3.0.php ##
## ##
#############################################################
__docformat__ = "restructuredtext en"
import esys.lsm.doc.Util
from esys.lsm.vis.core import Scene, Camera, Sphere, GlyphData
from esys.lsm.geometry import SimpleSphere, SimpleBlock, CubicBlock
from esys.lsm.geometry import HexagBlock, RandomBoxPacker, ParticleCollection
from esys.lsm.geometry import RandomSpherePacker
__visualisationTutSection = \
"""
Tutorial 3: Visualisation
=========================
The `esys.lsm.vis` package provides sub-packages and modules for
rendering data to screen and/or image files. This tutorial covers
the fundamentals of the API.
POV-Ray and VTK Renderers
-------------------------
The `esys.lsm.vis` package provides a Python API which
delegates calls to 3rd-party *render* software.
Currently, there are two *renderer* modules, ``esys.lsm.vis.povray``,
which delegates calls to POV-ray_ ray-tracing software, and
``esys.lsm.vis.vtk`` which delegates calls to Kitwares VTK_ scientific
visualisation library.
.. _POV-Ray: http://www.povray.org
.. _VTK: http://www.vtk.org
The main reason for the existence of the ``esys.lsm.vis`` package
is to allow the same Python code to be executed to produce images
using either VTK or POV-Ray as the *render engine*.
The ``esys.lsm.vis`` API also hopefully simplifies visualisation
tasks with a minimal loss in flexibility.
Scenes, Cameras and Objects
---------------------------
There are four basic steps when creating a visualisation of a data-set:
(1) Creating a `Scene` object
(2) Adding objects to the Scene
(3) Positioning the `Camera` to view the objects
(4) Rendering the ``Scene`` to produce an image
Here is an example script which renders two spheres::
import esys.lsm.vis.povray
import esys.lsm.vis.vtk
renpkg = esys.lsm.vis.povray
scene = renpkg.Scene()
scene.add(renpkg.Sphere(center=[0.0, 0.0, 0.0], radius=1.0))
scene.add(renpkg.Sphere(center=[2.0, 0.0, 0.0], radius=0.75))
scene.getCamera().setPosn([0.0, 0.0, -4.0])
scene.getCamera().setLookAt([1.0, 0.0, 0.0])
scene.render(size=[512,384], offScreen=False, interactive=True)
As usual, the script begins with ``import`` statements to load
packages and define classes/functions. Here, the
``esys.lsm.vis.povray`` and ``esys.lsm.vis.vtk``
modules are both imported into the script. Next, the
``esys.lsm.vis.povray`` package is assigned to the ``renpkg``
variable and the classes from this package will be
used to construct the scene and generate an image.
An object of class ``renpkg.Scene`` is created and
assigned to the ``scene`` variable. ``Scene`` objects
are containers for objects appearing in a visualisation.
Two calls to the `Scene.add` method are then used to add two
`Sphere` objects to the scene. The camera is then
positioned at coordinate ``(0,0,-4)`` with a call
to the `Camera.getPosn` method and the camera is *pointed at*
the coordinate ``(1,0,0)`` which is situated between the
two spheres. Lastly, the scene is rendered as an image
with the call to the `Scene.render` method. The call to
the ``render`` method is passed three arguments:
``size``
A pair of ``int`` values specifying the size of the image.
In the above example, the image size is 512 pixels wide and
384 pixels high.
``offScreen``
A ``bool`` indicating whether a window is displayed to screen.
In the above example, this argument is set to ``False``
so that a window is displayed on-screen.
``interactive``
A ``bool`` indicating whether the displayed window allows
interaction. Typically, this means that the ``render`` method
will *pause* until the user exits the window (by typing the
letter ``q``). The ``esys.lsm.vis.vtk.Scene`` renderer window
allows the user to manipulate the camera (zoom, translate and rotate)
with the mouse. The ``interactive`` argument only has effect if
``offScreen`` is set to ``True``.
The ``Scene.render`` method also accepts ``fileName`` and ``imageType``
arguments for saving an image to file, see `Scene.render` documentation
for details.
Simple Animations
-----------------
Here, the camera is rotated about the look-at point
to generate a simple animation::
import esys.lsm.vis.povray
import esys.lsm.vis.vtk
import math
renpkg = esys.lsm.vis.vtk
scene = renpkg.Scene()
scene.add(renpkg.Sphere(center=[-3.5, 0.0, 0.0], radius=1.75))
scene.add(renpkg.Cube(minPt=[-1.0, 0.0, 0.0], sideLength=2.75))
scene.getCamera().setPosn([2.0, 6.0, -6.0])
scene.getCamera().setLookAt([0.0, 0.0, 0.0])
numFrames = 300
deltaRadians = 2.0*math.pi/numFrames
for i in xrange(0,numFrames):
scene.getCamera().rotatePosn(
axis = [0, deltaRadians, 0],
axisPt = scene.getCamera().getLookAt()
)
scene.render(size=[512,384], offScreen=False, interactive=False)
scene.render(size=[512,384], offScreen=False, interactive=True)
After the imports, VTK is chosen as the renderer package
(that is, ``esys.lsm.vis.vtk`` assigned to ``renpkg``),
and two objects are added to the scene: a sphere and a cube.
The initial position and look-at position of the camera is set
before entering the ``for`` loop to generate the frames. The
`Camera.rotatePosn` method is used to incrementally rotate the
camera position about a *y*-vector which passes through the camera
look-at coordinate. The scene is rendered on-screen in each step of
the ``for`` loop with the ``interactive`` parameter set to ``False``.
At completion of the ``for`` loop, the final frame is rendered once
again, but this time with ``interactive=True`` so that the script
pauses until the render window is exited.
Visualising a Data-Set Using GlyphData
--------------------------------------
An alternative to creating individual objects within a scene
as was done with the ``scene.add(Sphere(centre=(0,0,0), radius=1.0))``
statements is to use a `GlyphData` object. ``GlyphData`` objects
are used to generate multiple *glyphs* (spheres, arrows, cylinders,
disks,...) of the same type for a given set of data. The following
example script uses a ``GlyphData`` object to display disks with
orientation information from a table of values::
import esys.lsm.vis.povray
import esys.lsm.vis.vtk
#
# Create table of data
#
#
table = [
# x, y, z, radius, degrees
[ 0, 0, 0, 0.20, 10.0]
[ 1, 0, 0, 0.30, 40.0]
[ 1, 1, 0, 0.40, 60.0]
[ 0, 1, 0, 0.50, 80.0]
[ 2, 0, 0, 0.40, 100.0]
[ 2, 1, 0, 0.30, 120.0]
[ 2, 2, 0, 0.30, 140.0]
]
numRows = len(table)
renpkg = esys.lsm.vis.povray
diskExtractor = \\
renpkg.DiskExtractor(
radiusMap = lambda idx: table[idx][3],
centerMap = lambda idx: table[idx][0:3],
radiusScale = 1.0
)
disks = renpkg.GlyphData(xrange(0, numRows), diskExtractor)
arrowExtractor = \\
renpkg.ArrowExtractor(
tailPtMap = lambda idx: table[idx][0:3]
vecMap = lambda idx: getVector(table[idx][3], table[idx][0:3], table[idx][4])
)
arrows = renpkg.GlyphData(xrange(0, numRows), arrowExtractor)
scene = renpgk.Scene()
scene.add(disks)
scene.add(arrows)
scene.getCamera().setPosn((1,1,-5))
scene.getCamera().setLookAt((1,1,0))
scene.render(offScreen=False, interactive=True, size=[512,512])
"""
__doc__ = \
esys.lsm.doc.Util.setSectionDoc("VisualisationSection",__visualisationTutSection) \
+ "\n:summary: Visualising data tutorial.\n"
|
