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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354

.. _using-the-mayavi-application:

使用Mayavi应用程序
=============================

.. topic:: 章节概要


    本章主要关注如何使用\ ``mayavi2``\ 应用程序。这里的一些内容也适用于在脚本中使用mayavi。我们建议新用户阅读此章以获得关于交互使用库程序的知识。

.. _general-layout-of-ui:

用户界面(UI)的通常布局
--------------------

当\ `mayavi2`\ 应用程序启动时，将出现一个如下图所示的用户界面。

.. image:: images/mayavi_ui_first.jpg
   :alt: Figure of Mayavi's initial UI window.

*Mayavi的初始用户界面窗口。\ *


此用户界面包括如下几部分。

  菜单
    使用菜单可以打开文件，载入模块，设置首选项等。

  Mayavi引擎树视图(engine tree view)
    这是mayavi管道的树视图。
      * 右键单击一个树节点可以可以重命名、删除、复制对象。

      * 左键单击一个节点，可以在树视图下面的对象编辑器中编辑其属性。

      * 可以在树视图上拖动节点。例如可以把一个模块从一组模块拖到另一组，或者把一个场景从一个可视化移到另一个可视化。

  对象编辑器(object editor)
    当单击mayavi管道中的一个对象时，在这里可以编辑其属性。

  TVTK场景(scene)
    这里显示数据可视化结果。可以使用鼠标和键盘与场景交互。更多细节在下面的章节中。

  Python解释器(interpreter)
    内置的Python解释器可以用来执行mayavi脚本和做其他事情。可以从mayavi的树视图内将节点拖到解释器内，然后对此节点所代表的对象编写脚本。

    如果你安装了高于0.9.1的\ IPython_\ ，Python解释器将使用IPython。

  日志(Logger)
    可以在此查看应用程序日志消息。

.. _IPython: http://ipython.scipy.org/

Mayavi的用户界面布局具有高可配置性：

 * 可以拖动各部分之间的线以改变相应视图的大小。

 * 大部分标签可以拖到程序内的任意地方。

 * 每个视图(mayavi引擎视图，对象编辑器，python解释器和日志)都可以在“View”菜单中打开和关闭。

每次改变mayavi的界面设置，都被保存下来，下一次启动应用程序会保持相同的设置。另外，也可以使用\ `View->Perspectives`\ 菜单项将不同的布局保存为不同的“perspectives”。

下面是一个特定配置的mayavi用户界面。这里各部分的大小都被改变了。 

.. image:: images/mayavi_ui_second.jpg
   :alt: Figure of Mayavi's UI after being configured by a user.

*\ 特定配置的mayavi用户界面\ *


可视化数据
----------------

在Mayavi中可视化数据可通过下列步骤实现：将数据载入为\ `数据源(data
sources)`\ ，将可视化模块应用于这些数据源以可视化数据，更多描述请参考\ :ref:`an-overview-of-mayavi`\ 和\ :ref:`learning-mayavi-by-example`\ 。  

在使用\ `模块`\ 或\ `过滤器`\ 之前，需要载入数据或进行类似的操作。Mayavi支持几种数据文件格式，最主要的是VTK数据文件格式。或者，\ :ref:`mlab
<simple-scripting-with-mlab>`\ 可用来从\ `numpy`\ 矩阵中载入数据。关于数据结构的更多信息，请参考\ 
:ref:`data-structures-used-by-mayavi`\ 。

数据被载入后，就可以使用各种过滤器\ :ref:`filters`\ 过滤或其他方法修改数据，然后使用几个模块\  :ref:`modules`\ 来可视化数据。 

这里列出所有的Mayavi\ `模块`\ 和\ `过滤器`\ 。此列表作为参考很有用\ :

.. toctree::

    modules.rst
    filters.rst


.. _interaction-with-the-scene:

与场景交互
--------------------------

在用户界面中的TVTK场景可以通过单击标签的“x”图标来关闭。每个场景有一个工具栏，包括各种功能：

  * 设置沿着X、Y和Z轴正负方向的等比例视图的按钮。

  * 打开平行投影代替默认的透视投影的按钮。查看二维图形时特别有用。

  * 显示xyz坐标轴的按钮。

  * 打开全屏视图的按钮。注意，进入全屏模式后，可以输入“q”或“e”回到正常窗口。

  * 将场景保存为各种图形格式的按钮。图形格式取决于文件后缀。

  * 打开场景配置界面的按钮。

与场景交互的主要方法是使用鼠标和键盘。


鼠标交互
~~~~~~~~~~~~~~~~~

有两种鼠标交互的模式。

  * 照相机模式：默认模式，使用鼠标操作照相机。输入“c”键可激活此模式。

  * 角色模式(Actor mode)：使用鼠标操作其所指向的角色。输入“a”键可激活此模式。

场景视图可以通过操作鼠标进行变换，通常是按住鼠标键然后拖动从而完成操作。

  * 按住鼠标左键并拖动将在移动的方向上旋转照相机/角色。

        - 同时按住“SHIFT”键将移动场景——正如按住鼠标中键并拖动一样。

        - 同时按住“CONTROL”将围绕照相机焦点旋转。

        - 同时按住“SHIFT”和“CONTROL”并向上拖动将放大，向下则缩小。这与右键相同。

  * 按住右键并向上拖动将放大(或增加角色比例)，向下拖动则缩小(或减小角色比例)。

  * 按住鼠标中键并拖动将移动场景或移动(translate)对象。

  * 向上滚动鼠标滚轮将放大，反之缩小。


键盘交互
~~~~~~~~~~~~~~~~~~~~

场景支持下列键盘命令：

 * '3': 打开/关闭立体渲染(stereo render)。如果“stereo”首选项没有设为True，此命令可能无效。

 * 'a': 将鼠标交互设为角色模式。

 * 'c': 将鼠标交互设为照相机模式。

 * 'e'/'q'/'Esc': 退出全屏模式。

 * 'f': 将照相机焦点移到鼠标所指位置。这将移动照相机焦点从而将视图中心移动至鼠标所指位置。

 * 'j': 将鼠标交互设为操纵杆模式。在操纵杆模式中，鼠标在一定程度上模拟操纵杆。例如，按住鼠标左键从中心移开将转动场景。

 * 'l': 配置场景的照明。这将打开一个弹出窗口以改变照明设置。

 * 'p': 获取鼠标位置处的数据。这将打开一个弹出窗口显示获取的数据。此界面允许用户改变获取数据的来源：单元(cell)，点(point)，或任意点(arbitrary point)。

 * 'r': 重置照相机焦点和位置。这是个很方便的命令。

 * 's': 将场景保存为图片。这将打开一个文件选择对话框，文件名后缀决定图片类型。

 * 't': 将鼠标交互设为轨迹球模式(trackball mode)，此为鼠标交互的默认模式。

 * '='/'+': 放大。

 * '-': 缩小。

 * '方向键': 按方向键可以转动照相机。同时按下"SHIFT"键，则移动照相机。

.. _the-embedded-python-interpreter:

内置的Python解释器
-------------------------------

内置的Python解释器为产生超强功能提供了可能性。此解释器具有命令补全、文档自动生成、工具提示和多行编辑等功能。另外，它还提供下列功能：

 * 名字\ ``mayavi``\ 自动地绑定到\ ``enthought.mayavi.script.Script``\ 实例，方便编写mayavi脚本。

 *  名字\``application``\ 绑定到envisage程序。

 * 如果通过\ ``File->Open File...``\ 菜单项打开Python文件，可以使用一个具有语法高亮功能的编辑器对其编辑。使用\ ``Control-r``\ 可以执行脚本，\ ``Control-s``\ 可保存文件，当编写简单mayavi脚本时很方便。也可以使用\ ``Control-n``\ 和\ ``Control-s``\ 增大和减少字体。

 * 正如上面提到的，可以从Mayavi引擎树视图中将节点拖入Python解释器，对象将被正常写入脚本语句。通常使用的模式如下\ ::

     >>> tvtk_scene_1
     <enthought.mayavi.core.scene.Scene object at 0x9f4cbe3c>
     >>> s = _

   在此例中，名称\ ``s``\ 被绑定到拖入的tvtk_scene对象。\ ``_``\ 变量保存了最后使用的表达式，这里即为拖入的对象。使用\ ``tvtk_scene_1``\ 也可以，但此变量名称是系统自动生成的，其中的数字没有具体含义(mouthful)。


.. _automatic-script-generation:

自动生成脚本
-----------------------------

Mayavi具有非常便利和强大的脚本记录功能，可用于下列方面：

 - 将所有操作记录为\ *\ 易于阅读\ *\ 的Python脚本，可以用来重新生成可视化结果。

 - 易于学习Mayavi的编码基础和如何编辑脚本。

.. _recording-python-script:

录制mayavi操作为脚本
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

这里是使用此功能的方法：

 1. 当启动\ ``mayavi2``\ 程序时，引擎视图(树视图)的工具栏有一个红色的记录图标，在问号图标旁边，单击此图标。此操作也可以在独立的mlab会话中进行。

 2. 将弹出一个窗口，其中有一些样本代码行，可以独立运行或使用下列方式运行：\ ``mayavi2 -x script.py``\ 或者\ ``python script.py``\ 。

 3. 在UI内进行想做的操作，此时可以看到执行这些操作所需的代码。例如，产生一个新数据源(通过增加节点对话框，文件菜单或右键单击任意选项)，然后增加一个模块/过滤器等等。在树视图中编辑对象。

 4. 移动UI中的照相机，旋转，放大，缩小。所有这些操作将产生相应的代码。对于照相机，只有最终位置被存下来(否则将产生无数无用的代码行)。对于场景的主要键盘操作将被记录(除了\  'c'/'t'/'j'/'a')。这意味着程序将记录方向键和\ '+'/'-'\ 键等。

    进行操作的同时代码被更新，这是学习mayavi API的好方式。 

 5. 完成操作后，再次单击记录图标，程序将询问保存文件的名称，例如\ ``script.py``\ 。如果只对代码感兴趣而不愿保存文件，单击\ 'cancel'\ 。

 6. 关闭记录窗口，退出Mayavi(如果你愿意)。

 7. 现在从解释器输入\ ::

      $  mayavi2 -x script.py

    或\ ::

      $ python script.py

    这样将运行所有代码，回到你上次离开时的状态。你可以自由地修改此脚本--事实上这正是自动代码生成的意义所在！

也可以对现有的Mayavi会话进行编程，理解这一点很重要。所以，如果启动mayavi后，你做了一些操作，或运行一个mayavi脚本，接着想记录以后的操作，这是可以完成的。按照以前一样的流程进行即可。这里需要记住的一点是脚本记录器不创建你在此会话中已经建立的对象。

.. note::

    也可以删除或拖动mayavi树视图中的对象。然而这可能不是你想在自动记录的脚本中所进行的操作。

正如前面所谈到的，脚本记录在\ ``mlab``\ 会话中或其他使用mayavi的地方都有效。任何\ ``mlab``\ 专用代码不会被记录，只有使用OO Mayavi API的代码才会被记录下来。

.. _recording-limitations:

限制
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

脚本记录器将记录大多数重要的操作。但不支持下列操作：

  - 在场景中，“c”/“t”/“j”/“a”/“p”\ 按键操作不能正确地记录。原因在于其实现非常复杂，对于基本的脚本编写没有必要。

  - 对界面的任意的脚本显然不会正常工作。

  - 只有改变特性(trait)和执行的特定方法(call)能被记录在代码中。所以执行任意对象的任意方法通常不会被记录下来，只有mayavi引擎的特定方法可以被记录下来。

.. _command-line-arguments:

命令行参数
----------------------

下面的章节将介绍几个``mayavi2``\ 应用程序的命令行参数。这些介绍也可以在\ ``mayavi2``\ 的用户手册中找到。 

完整的管道可以通过命令行建立起来，所以Mayavi可以集成在shell脚本中提供可视化功能。

可以如下运行Mayavi::

       mayavi2 [options] [args]

这里的\ ``arg1``\ ，\ ``arg2``\ 等等是可选的文件名，对应于已经保存的Mayavi2可视化(``filename.mv2``)，Mayavi2脚本(``filename.py``)或任何Mayavi支持的数据文件。如果没有提供参数或选项，mayavi将以默认的空白场景启动。

这些选项如下：

-h
      打印所有命令行选项然后退出。与\ ``--help``\ 相同。

-V
      打印Mayavi版本然后退出。与\ ``--version``\ 相同。

-z file_name
      载入之前保存的Mayavi2可视化。与\ ``--viz file_name``\ 及\ ``--visualization file_name``\ 相同。

-d data_file
      打开所支持格式的数据文件或非文件的数据源对象，包括VTK文件格式(*.vtk, *.xml, *.vt[i,p,r,s,u], *.pvt[i,p,r,s,u])，VRML2 (*.wrl)，3D Studio (*.3ds)，PLOT3D (*.xyz)和其他所支持的格式。

      ``data_file``也可以是非文件的数据源，例如\ ``ParametricSurface``\ 或\ ``PointLoad``\ 将载入对应的数据源。本选项与\ ``--data``\ 相同。

-m module-name
      模块是事际上对数据进行可视化的对象。给定的\ ``module-name``\ 将被载入当前\ ``ModuleManager``\ 。模块名字必须有效，否则将得到出错信息。

      如果模块像这样给出：\ ``package.sub.module.SomeModule``\ ，那么模块(``SomeModule``)将从``package.sub.module``中导入。\ ``mayavi2``\ 的标准模块不需要完整路径，例如\ ::

         mayavi2 -d data.vtk -m Outline -m user_modules.AModule

      在此例中，\ ``Outline``\ 是标准模块，\ ``user_modules.AModule``\ 是某个用户自定义模块。本选项与\ ``--module``\ 相同。

-f filter-name
      过滤器是以某种方式过滤数据的对象。\ ``filter-name``\ 将载入并对应于当前的源对象或过滤器对象。过滤器必须有效，否则将得到出错信息。

      如果过滤器像这样给出：\ ``package.sub.filter.SomeFilter``\ ，那么过滤器(``SomeFilter``)将从\ ``package.sub.filter``\ 导入。\ ``mayavi2``\ 的标准过滤器不需要完整路径。例如\ ::

         mayavi2 -d data.vtk -f ExtractVectorNorm -f user_filters.AFilter

      在此例中，\ ``ExtractVectorNorm``\ 是一个标准过滤器，\ ``user_filters.AFilter``\ 是某个用户定义的过滤器。本选项与\ ``--filter``\ 相同。

-M
      在Mayavi管道中启动一个新模块管理器。与\ ``--module-mgr``\ 相同。

-n
      建立一个新窗口或场景。在此之后的选项将作用于新创建的场景。与\ ``--new-window``\ 相同。

-o
      在offscreen模式下运行Mayavi，没有任何图形用户界面。此模式在需要后台渲染图片(例如动画)时非常有用，避免弹出扰人的用户界面。Mayavi脚本(通过\ ``-x``\ 选项运行)应该在此模式下工作得很好。与\ ``--offscreen``\ 相同。

-x script-file
      运行给定的脚本，同时确保名字空间中的“mayavi”是Mayavi的脚本实例 --就像在内置的Python解释器内一样。与\ ``--exec``\ 相同.

-s python-expression
      对最后建立的对象执行Python命令。假设前一个对象是个模块，如果要设置其颜色并保存场景，可以这样做\ ::

       $ mayavi2 [...] -m Outline -s"actor.property.color = (1,0,0)" \
        -s "scene.save('test.png', size=(800, 800))"

      应在命令前后使用引号。本选项与\ ``--set``\ 相同。

.. warning::
 ``-x``\ 或\ ``--exec``\ 使用\ `execfile`\ ，如果脚本做不合适的操作将很危险。类似的，\ ``-s``\ 或\ ``--set``\ 使用\ `exec`\ ，如不适当使用也很危险。

还有很重要的一点，mayavi的\ **命令行参数是按照给出顺序依次处理的\ **\ 。由此用户可以实现一些有趣的操作。

下面是一些命令行参数的例子\ ::

  $ mayavi2 -d ParametricSurface -s "function='dini'" -m Surface \
    -s "module_manager.scalar_lut_manager.show_scalar_bar = True" \
    -s "scene.isometric_view()" -s "scene.save('snapshot.png')"

  $ mayavi2 -d heart.vtk -m Axes -m Outline -m GridPlane \
    -m ContourGridPlane -m IsoSurface

  $ mayavi2 -d fire_ug.vtu -m Axes -m Outline -m VectorCutPlane \
    -f MaskPoints -m Glyph

在上面的例子中，\ ``heart.vtk``\ 和\ ``fire_ug.vtu``\ 等VTK文件可以在源文件目录的\ ``examples/data``\ 中找到。它们是否安装到你的电脑取决于你的操作系统。



..
   Local Variables:
   mode: rst
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: