1
.. _learning-mayavi-by-example:
3
Learning Mayavi by example
4
==========================
6
To get acquainted with mayavi you may start up ``mayavi2`` like so::
10
On Windows you can double click on the installed ``mayavi2.exe``
11
executable (usually in the ``Python2X\Scripts`` directory).
13
Once mayavi starts, you may resize the various panes of the user
14
interface to get a comfortable layout. These settings will become the
15
default "perspective" of the mayavi application. More details on the
16
UI are available in the :ref:`general-layout-of-ui` section.
18
Before proceeding on the quick tour, it is important to locate some data
19
to experiment with. The mayavi sources ship with several useful data
20
files for the examples and testing. These may be found in the
21
``examples/data`` directory inside the root of the mayavi source tree.
22
If these are not installed, the sources may be downloaded from here:
23
http://code.enthought.com/enstaller/eggs/source/
25
If for some reason the sample data files are not available or there is
26
no Internet access to download them, one can always create some
27
interesting looking surfaces using the `File->Load data->Create Parametric
28
surface source` menu item. This will let us create very pretty
29
looking surfaces without reference to any external data. This is
30
described in the `Parametric surfaces example`_ section below.
33
Parametric surfaces example
34
---------------------------
36
Parametric surfaces are particularly handy if you are unable to find
37
any data to play with right away. Parametric surfaces are surfaces
38
parametrized typically by 2 variables, u and v. VTK has a bunch of
39
classes that let users explore Parametric surfaces. This
40
functionality is also available in Mayavi. The data basically is a 2D
41
surface embedded in 3D. Scalar data is also available on the surface.
42
More details on parametric surfaces in VTK may be obtained from Andrew
43
Maclean's `Parametric Surfaces`_ document.
45
1. After starting mayavi2, create a simple Parametric surface source
46
by selecting `File->Open->Create Parametric Surface source`.
47
Once you create the data, you will see a new node on the Mayavi
48
tree view on the left that says `ParametricSurface`. Note that
49
you **will not** see anything visualized on the TVTK scene yet.
51
You can modify the nature of the parametric surface by clicking
52
on the node for the `ParametricSurface` source object.
54
2. To see an outline (a box) of the data, navigate to the
55
`Visualize->Modules` menu item and select the `Outline` module.
56
You will immediately see a white box on the TVTK scene. You
57
should also see two new nodes on the tree view, one called
58
`Modules` and one underneath that called `Outline`.
60
3. You can change properties of the outline displayed by clicking on
61
the `Outline` node on the left. This will create an object editor
62
window on left bottom of the window (the object editor tab) below
63
the tree view. Play with the settings here and look at the
64
results. If you double-click a node on the left it will pop up an
65
editor dialog rather than show it in the embedded object editor.
67
4. To navigate the scene look at the section on
68
:ref:`interaction-with-the-scene` section for more details. Experiment
71
5. To view the actual surface create a `Surface` module by selecting
72
`Visualize->Modules->Surface`. You can show contours of the
73
scalar data on this surface by clicking on the `Surface` node on
74
the left and switching on the `Enable contours` check-box.
76
6. To view the color legend (used to map scalar values to colors),
77
click on the `Modules` node on the tree view and on the object
78
editor activate the `Show scalar bar` check-box. This will show
79
you a legend on the TVTK scene. The legend can be moved around on
80
the scene by clicking on it and dragging it. It can also be
81
resized by clicking and dragging on its edges. You can change the
82
nature of the color-mapping by choosing among different lookup
83
tables on the object editor.
85
7. You can add as many modules as you like. Not all modules make
86
sense for all data. Mayavi does not yet grey out (or disable) menu
87
items and options if they are invalid for the particular data
88
chosen. This will be implemented in the future. However making a
89
mistake should not in general be disastrous, so go ahead and
92
8. You may add as many data sources as you like. It is possible to
93
view two different parametric surfaces on the same scene.
94
Whether this makes sense or not is up to the user. You may also
95
create as many scenes you want to and view anything in those.
96
You can cut/paste/copy sources and modules between any nodes on
97
the tree view using the right click options.
99
9. To delete the `Outline` module say, right click on the `Outline`
100
node and select the Delete option. You may also want to
101
experiment with the other options.
103
10. You can save the rendered visualization to a variety of file
104
formats using the `File->Save Scene As` menu.
106
11. The visualization may itself be saved out to a file via the
107
`File->Save Visualization` menu and reloaded using the `Load
110
Shown below is an example visualization made using the parametric
111
source. Note that the positioning of the different surfaces was
112
effected by moving the actors on screen using the actor mode of the
113
scene via the 'a' key. For more details on this see the section on
114
:ref:`interaction-with-the-scene`.
116
.. image:: images/param.png
117
:alt: Sample visualization using parametric surfaces.
119
The examples detailed above should provide a good general idea of how
120
to visualize data with Mayavi2 and also an idea of its features and
124
.. _Parametric Surfaces: http://www.vtk.org/pdf/ParametricSurfaces.pdf
127
``heart.vtk`` example
128
---------------------
130
This section describes a simple example with the ``heart.vtk`` file.
131
This is a simple volume of 3D data (32 x 32 x 12 points) with scalars
132
at each point (the points are equally spaced). The data is a
133
structured dataset (an `ImageData` in fact), we'll read more about
134
these later but you can think of it as a cube of points regularly
135
spaced with some scalar data associated with each point. The data
136
apparently represents a CT scan of a heart. I have no idea whose
137
heart! The file is a readable text file, look at it in a text editor
140
1. With ``mayavi2`` started, we start by opening the data file. Go
141
to the `File->Open->VTK File` menu item and then in the file
142
dialog, navigate to the directory that contains the sample data.
143
There select the ``heart.vtk`` file.
145
Once you choose the data, you will see a new node on the Mayavi
146
tree view on the left that says `VTK file (heart.vtk)`. Note
147
that you **will not** see anything visualized on the TVTK scene
150
2. To see an outline (a box) of the data, navigate to the
151
`Visualize->Modules` menu item and select the `Outline` module.
152
You will immediately see a white box on the TVTK scene. You
153
should also see two new nodes on the tree view, one called
154
`Modules` and one underneath that called `Outline`.
156
3. You can change properties of the outline displayed by clicking on
157
the `Outline` node on the left. This will create an object editor
158
window on left bottom of the window (the object editor tab) below
159
the tree view. Play with the settings here and look at the
160
results. If you double-click a node on the tree view it will pop
161
up an editor dialog rather than show it in the embedded object
164
Note that in general, the editor window for a `Module` will have
165
a section for the `Actor`, one for the `Mapper` and one for
166
`Property`. These refer to TVTK/VTK terminology. You may think
167
of Properties as those related to the color, representation
168
(surface, wireframe, etc.), line size etc. Things grouped under
169
`Actor` are related to the object that is rendered on screen and
170
typically the editor will let you toggle its visibility. In VTK
171
parlance, the word `Mapper` refers to an object that converts the
172
data to graphics primitives. Properties related to it will be
173
grouped under the `Mapper` head.
175
4. To interact with the TVTK scene window, look at the section on
176
:ref:`interaction-with-the-scene` for more details. Experiment with
177
these options till you are comfortable.
179
5. Now create an iso-surface by selecting the
180
`Visualize->Modules->IsoSurface` menu item. You will see a new
181
`IsoSurface` node on the left and an iso-contour of the scalar
182
data on the scene. The iso-surface is colored as per the
183
particular iso-value chosen. Experiment with the settings of
186
6. To produce meaningful visualizations you need to know what each
187
color represents. To display this legend on the scene, click on the
188
`Modules` node on the tree view and on the object editor activate
189
the `Show scalar bar` check-box. This will show you a legend on
190
the TVTK scene. The legend can be moved around on the scene by
191
clicking on it and dragging on it. It can also be resized by
192
clicking and dragging on its edges. You can change the nature of
193
the color-mapping by choosing various options on the object
196
7. Create a simple "grid plane" to obtain an idea of the actual
197
points on the grid. This can be done using the `GridPlane`
198
module, and created via the `Visualize->Modules->GridPlane` menu
201
8. You can delete a particular module by right clicking on it and
202
choosing delete. Try this on the `GridPlane` module. Try the
203
other right click menu options as well.
205
9. Experiment with the `ContourGridPlane` module and also the
206
`ScalarCutPlane` module a little.
208
The `ScalarCutPlane` module features a very powerful feature
209
called *3D widgets*. On the TVTK scene window you will see a cut
210
plane that slices through your data showing you colors
211
representing your data. This cut plane will have a red outline
212
and an arrow sticking out of it. You can click directly on the
213
cut plane and move it by dragging it. Click on the arrow head to
214
rotate the plane. You can also reset its position by using the
215
editor window for the scalar cut plane.
217
10. You can save the visualization to an image produced by clicking
218
on the little save icon on the TVTK scene or via any of the
219
options on the `File->Save Scene As` menu.
221
You should have a visualization that looks something like the one
224
.. image:: images/heart.png
225
:alt: Sample visualization of the ``heart.vtk`` dataset.
227
The nice thing about mayavi is that although in this case all of the
228
above was done using the user interface, all of it can be done using
229
pure Python scripts as well. More details on this are available in
230
the :ref:`advanced-scripting-with-mayavi` section.
232
Opening data files and starting up modules can also be done from the
233
command line. For example we could simply have done::
235
$ mayavi2 -d /path/to/heart.vtk -m Outline -m IsoSurface \
236
> -m GridPlane -m ScalarCutPlane
238
More details are available in the :ref:`command-line-arguments` section.
241
``fire_ug.vtu`` example
242
-----------------------
244
Like ``heart.vtk``, the ``fire_ug.vtu`` example dataset is available
245
in the ``examples/data`` directory. This dataset is an unstructured
246
grid stored in a VTK XML file. It represents a room with a fire in
247
one corner. A simulation of the fluid flow generated by this fire was
248
performed and the resulting data at a particular instant of time is
249
stored in the file. The dataset was provided by Dr. Philip Rubini,
250
who at the time was at Cranfield University. A VRML file
251
(``room_vis.wrl``) is also provided to show the context of the room in
252
which the fire is taking place.
254
1. With mayavi2 started, select `File->Open->VTK XML file` to load the
255
data. Again, you will see a node on the tree view on the left but
256
nothing on the TVTK scene. This dataset contains different scalars
257
and vectors in the same data file. If you select the `VTK XML file
258
...` node on the left the reader may be configured in the object
259
editor pane of the UI. On this, you will see a drop list of all
260
the scalars, vectors etc. in this data file. Select any that you
263
2. Create an outline of the data as described earlier using an
264
`Outline` module. View an iso-surface of the data by creating an
265
`IsoSurface` module. Also experiment with the `ScalarCutPlane`
268
3. Show the scalar bar that represents the color mapping (via a Look
269
up table that maps scalar values to colors) by clicking on the
270
`Modules` and enabling the `Show scalar bar`. Experiment with
271
the different color maps provided by default.
273
4. Now click on the `VTK XML file ...` and select different scalar
274
values to see how the data has changed. Your legend should
275
automatically update when the scalar value is changed.
277
5. This data also features vectors. The scalar data has `u`, `v`
278
and `w` but not the magnitude of the velocity. Lets say we'd
279
like to be able to view iso-contours of the magnitude of the
280
velocity. To do this lets use the `ExtractVectorNorm` filter.
281
This is created by choosing the `Visualize->Filters->Extract
284
6. If you now create a `ScalarCutPlane`, you will see a new
285
`Modules` node under the `ExtractVectorNorm` node. This scalar
286
cut plane is displaying colors for the velocity magnitude that
287
the filter has created. You can drag the iso-surface module from
288
the other `Modules` node and drop it on this `Modules` node so
289
that the IsoSurface generated is for the velocity magnitude and
290
not for the scalars chosen in the data.
292
Note that the view on the left represents a pipeline of the flow
293
of the data from `source -> filter -> modules`. Essentially the
294
data flows from the parent node down to the children nodes below
297
Now if you want to visualize something on a different "branch" of
298
the pipeline, lets say you want to view iso-surfaces of the
299
temperature data you must first click on the modules or the
300
source object (the `VTK XML File ...` node) itself and then
301
select the menu item. When you select an item on the tree, it
302
makes that item the *current object* and menu selections made
303
after that will in general create new modules/filters below the
306
7. You can filter "filtered data". So select the
307
`ExtractVectorNorm` node to make it the active object. Now
308
create a Threshold filter by selecting
309
`Visualize->Filters->Threshold`. Now set the upper and lower
310
thresholds on the object editor for the Threshold to something
311
like 0.5 and 3.0. If you create a `VectorCutPlane` module at
312
this point and move the cut plane you should see arrows but only
313
arrows that are between the threshold values you have selected.
314
Thus, you can create pretty complicated visualization pipelines
317
8. There are several vector modules. `VectorCutPlane`, `Vectors`,
318
`WarpVectorCutPlane` and `Streamlines`. If you view streamlines
319
then mayavi will generate streamlines of vector data in your
320
dataset. To view streamlines of the original dataset you can
321
click on the original `Outline` module (or the source) and then
322
choose the `Streamline` menu item. The streamline lets you move
323
different type of seeds on screen using 3D widgets. Seed points
324
originating from these positions are used to trace out the
325
streamlines. Sphere, line and plane sources may be used here to
326
initialize the streamline seeds.
328
9. You can view the room in which the fire is taking place by
329
opening the VRML file by the `File->Open->VRML2 file` menu item
330
and selecting the ``room_vis.wrl`` file included with the data.
332
10. Once you setup a complex visualization pipeline and want to save
333
it for later experimentation you may save the entire
334
visualization via the `File->Save Visualization` menu. A saved
335
file can be loaded later using the `File->Load Visualization`
336
menu item. This option is not 100% robust and is still
337
experimental. Future versions will improve this feature.
338
However, it does work and can be used for the time being.
340
Once again, the visualization in this case was created by using the
341
user interface. It is possible to script this entirely using Python
342
scripts. A simple script demonstrating several of the above modules
343
is available in ``examples/streamline.py``. This file may be studied.
344
It can be run either like so::
347
$ python streamline.py
351
$ mayavi2 -x streamline.py
353
As can be seen from the example, it is quite easy to script mayavi to
354
visualize data. An image of a resulting visualization generated from
355
this script is shown below.
357
.. image:: images/streamline.png
358
:alt: Sample visualization of the ``fire_ug.vtu`` dataset.
added
removed
enthought.mayavi/enthought/mayavi/html/_sources/examples.txt
