<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Advanced Scripting with Mayavi — Mayavi2 v2.2.0 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '2.2.0',
COLLAPSE_MODINDEX: false,
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/interface.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="contents" title="Global table of contents" href="contents.html" />
<link rel="index" title="Global index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="Mayavi2 v2.2.0 documentation" href="index.html" />
<link rel="next" title="Creating data for Mayavi" href="data.html" />
<link rel="prev" title="Simple Scripting with mlab" href="mlab.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="data.html" title="Creating data for Mayavi"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="mlab.html" title="Simple Scripting with mlab"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Mayavi2 v2.2.0 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section">
<h1 id="id1"><span id="advanced-scripting-with-mayavi"></span>Advanced Scripting with Mayavi<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h1>
<p>As elaborated in the <a class="reference" href="overview.html#an-overview-of-mayavi"><em>An overview of Mayavi</em></a> section, mayavi can be
scripted from Python in order to visualize data. Mayavi2 was designed
from the ground up to be highly scriptable. Everything that can be done
from the user interface can be achieved using Python scripts.</p>
<p>If you are not looking to script mayavi itself but looking for quick
ways to get your visualization done with simple code you may want to
check out mayavi’s mlab module. This is described in more detail in
the <a class="reference" href="mlab.html#simple-scripting-with-mlab"><em>Simple Scripting with mlab</em></a> section.</p>
<p>To best understand how to script mayavi, a reasonable understanding of
the mayavi internals is necessary. The following sections provides an
overview of the basic design and objects in the mayavi pipeline.
Subsequent sections consider specific example scripts that are
included with the mayavi sources that illustrate the ideas.</p>
<p>Mayavi2 uses <a class="reference" href="https://svn.enthought.com/enthought/wiki/Traits">Traits</a> and <a class="reference" href="https://svn.enthought.com/enthought/wiki/TVTK">TVTK</a> internally. <a class="reference" href="https://svn.enthought.com/enthought/wiki/Traits">Traits</a> in many ways
changes the way we program. So it is important to have a good idea of
Traits in order to understand mayavi’s internals. If you are unsure
of traits it is a good idea to get a general idea about traits now.
Trust me, your efforts learning Traits will not be wasted!</p>
<div class="section">
<h2 id="design-overview">Design Overview<a class="headerlink" href="#design-overview" title="Permalink to this headline">¶</a></h2>
<p>This section provides a brief introduction to mayavi’s internal
architecture.</p>
<p>The “big picture” of a visualization in mayavi is that an <tt class="docutils literal"><span class="pre">Engine</span></tt>
(<tt class="docutils literal"><span class="pre">enthought.mayavi.engine.Engine</span></tt>) object manages the entire
visualization. The <tt class="docutils literal"><span class="pre">Engine</span></tt> manages a collection of <tt class="docutils literal"><span class="pre">Scene</span></tt>
(<tt class="docutils literal"><span class="pre">enthought.mayavi.core.scene.Scene</span></tt>) objects. In each <tt class="docutils literal"><span class="pre">Scene</span></tt>, a
user may have created any number of <tt class="docutils literal"><span class="pre">Source</span></tt>
(<tt class="docutils literal"><span class="pre">enthought.mayavi.core.source.Source</span></tt>) objects. A <tt class="docutils literal"><span class="pre">Source</span></tt>
object can further contain any number of <tt class="docutils literal"><span class="pre">Filters</span></tt>
(<tt class="docutils literal"><span class="pre">enthought.mayavi.core.filter.Filter</span></tt>) or <tt class="docutils literal"><span class="pre">ModuleManager</span></tt>
(<tt class="docutils literal"><span class="pre">enthought.mayavi.core.module_manager.ModuleManager</span></tt>) objects. A
<tt class="docutils literal"><span class="pre">Filter</span></tt> may contain either other filters or <tt class="docutils literal"><span class="pre">ModuleManagers</span></tt>. A
<tt class="docutils literal"><span class="pre">ModuleManager</span></tt> manages any number of <tt class="docutils literal"><span class="pre">Modules</span></tt>. The figure below
shows this hierarchy in a graphical form.</p>
<img alt="Illustration of the various objects in the mayavi pipeline." src="_images/m2_big_picture.png" />
<p><em>Illustration of the various objects in the mayavi pipeline.</em></p>
<p>This hierarchy is precisely what is seen in the Mayavi tree view on
the UI. The UI is therefore merely a graphical representation of this
internal world-view. A little more detail on these objects is given
below. For even more details please refer to the sources.</p>
<p>All objects in the mayavi pipeline feature <tt class="docutils literal"><span class="pre">start</span></tt> and <tt class="docutils literal"><span class="pre">stop</span></tt>
methods. The reasoning for this is that any object in mayavi is not
usable (i.e. it may not provide any outputs) unless it has been
started. Similarly the <tt class="docutils literal"><span class="pre">stop</span></tt> method “deactivates” the object.
This is done because mayavi is essentially driving VTK objects
underneath. These objects require inputs in order to do anything
useful. Thus, an object that is not connected to the pipeline cannot
be used. For example, consider an <tt class="docutils literal"><span class="pre">IsoSurface</span></tt> module. It requires
some data in order to contour anything. Thus, the module in isolation
is completely useless. It is usable only when it is added to the
mayavi pipeline. When an object is added to the pipeline, its inputs
are setup and its <tt class="docutils literal"><span class="pre">start</span></tt> method is called automatically. When the
object is removed from the pipeline its <tt class="docutils literal"><span class="pre">stop</span></tt> method is called
automatically.</p>
<p>Apart from the <tt class="docutils literal"><span class="pre">Engine</span></tt> object, all other objects in the mayavi
pipeline feature a <tt class="docutils literal"><span class="pre">scene</span></tt> trait which refers to the current
<tt class="docutils literal"><span class="pre">enthought.pyface.tvtk.tvtk_scene.TVTKScene</span></tt> instance that the
object is associated with. The objects also feature an <tt class="docutils literal"><span class="pre">add_child</span></tt>
method that lets one build up the pipeline by adding “children”
objects. The <tt class="docutils literal"><span class="pre">add_child</span></tt> method is “intelligent” and will try to
appropriately add the child in the right place.</p>
<p>Here is a brief description of the key objects in the mayavi pipeline.</p>
<blockquote>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">Engine</span></tt></dt>
<dd><p class="first">The Mayavi engine is defined in the <tt class="docutils literal"><span class="pre">enthought.mayavi.engine</span></tt>
module.</p>
<blockquote class="last">
<ul class="simple">
<li>It possesses a <tt class="docutils literal"><span class="pre">scenes</span></tt> trait which is a Trait <tt class="docutils literal"><span class="pre">List</span></tt> of
<tt class="docutils literal"><span class="pre">Scene</span></tt> objects.</li>
<li>Features several methods that let one add a
<tt class="docutils literal"><span class="pre">Filter/Source/Module</span></tt> instance to it. It allows one to
create new scenes and delete them. Also has methods to load
and save the entire visualization.</li>
<li>The <tt class="docutils literal"><span class="pre">EnvisageEngine</span></tt> defined in the
<tt class="docutils literal"><span class="pre">enthought.mayavi.envisage_engine</span></tt> module is a subclass of
<tt class="docutils literal"><span class="pre">Engine</span></tt> and is the one used in the <tt class="docutils literal"><span class="pre">mayavi2</span></tt> application.
The <tt class="docutils literal"><span class="pre">Engine</span></tt> object is not abstract and itself perfectly
usable. It is useful when users do not want to use <a class="reference" href="https://svn.enthought.com/enthought/wiki/Envisage">Envisage</a>
but still desire to use mayavi for visualization.</li>
</ul>
</blockquote>
</dd>
<dt><tt class="docutils literal"><span class="pre">Scene</span></tt></dt>
<dd><p class="first">Defined in the <tt class="docutils literal"><span class="pre">enthought.mayavi.core.scene</span></tt> module.</p>
<blockquote class="last">
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">scene</span></tt> attribute: manages a <tt class="docutils literal"><span class="pre">TVTKScene</span></tt>
(<tt class="docutils literal"><span class="pre">enthought.pyface.tvtk.tvtk_scene</span></tt>) object which is where
all the rendering occurs.</li>
<li>The <tt class="docutils literal"><span class="pre">children</span></tt> attribute is a <tt class="docutils literal"><span class="pre">List</span></tt> trait that manages a
list of <tt class="docutils literal"><span class="pre">Source</span></tt> objects.</li>
</ul>
</blockquote>
</dd>
<dt><tt class="docutils literal"><span class="pre">PipelineBase</span></tt></dt>
<dd><p class="first">Defined in the <tt class="docutils literal"><span class="pre">enthought.mayavi.core.pipeline_base</span></tt> module.
Derives from <tt class="docutils literal"><span class="pre">Base</span></tt> which merely abstracts out common
functionality. The <tt class="docutils literal"><span class="pre">PipelineBase</span></tt> is the base class for all
objects in the mayavi pipeline except the <tt class="docutils literal"><span class="pre">Scene</span></tt> and <tt class="docutils literal"><span class="pre">Engine</span></tt>
(which really isn’t <em>in</em> the pipeline but contains the pipeline).</p>
<blockquote class="last">
<ul>
<li><p class="first">This class is characterized by two events, <tt class="docutils literal"><span class="pre">pipeline_changed</span></tt>
and <tt class="docutils literal"><span class="pre">data_changed</span></tt>. These are <tt class="docutils literal"><span class="pre">Event</span></tt> traits. They
determine when the pipeline has been changed and when the data
has changed. Therefore, if one does:</p>
<div class="highlight"><pre><span class="nb">object</span><span class="o">.</span><span class="n">pipeline_changed</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
<p>then the <tt class="docutils literal"><span class="pre">pipeline_changed</span></tt> event is fired. Objects
downstream of <tt class="docutils literal"><span class="pre">object</span></tt> in the pipeline are automatically
setup to listen to events from an upstream object and will call
their <tt class="docutils literal"><span class="pre">update_pipeline</span></tt> method. Similarly, if the
<tt class="docutils literal"><span class="pre">data_changed</span></tt> event is fired then downstream objects will
automatically call their <tt class="docutils literal"><span class="pre">update_data</span></tt> methods.</p>
</li>
<li><p class="first">The <tt class="docutils literal"><span class="pre">outputs</span></tt> attribute is a trait <tt class="docutils literal"><span class="pre">List</span></tt> of outputs
produced by the object.</p>
</li>
</ul>
</blockquote>
</dd>
<dt><tt class="docutils literal"><span class="pre">Source</span></tt></dt>
<dd><p class="first">Defined in the <tt class="docutils literal"><span class="pre">enthought.mayavi.core.source</span></tt> module. All the
file readers, Parametric surface etc. are subclasses of the
<tt class="docutils literal"><span class="pre">Source</span></tt> class.</p>
<blockquote class="last">
<ul class="simple">
<li>Contains the rest of the pipeline via its <tt class="docutils literal"><span class="pre">children</span></tt> trait.
This is a <tt class="docutils literal"><span class="pre">List</span></tt> of either <tt class="docutils literal"><span class="pre">Modules</span></tt> or other <tt class="docutils literal"><span class="pre">Filters</span></tt>.</li>
<li>The <tt class="docutils literal"><span class="pre">outputs</span></tt> attribute is a trait <tt class="docutils literal"><span class="pre">List</span></tt> of outputs
produced by the source.</li>
</ul>
</blockquote>
</dd>
<dt><tt class="docutils literal"><span class="pre">Filter</span></tt></dt>
<dd><p class="first">Defined in the <tt class="docutils literal"><span class="pre">enthought.mayavi.core.filter</span></tt> module. All the
<tt class="docutils literal"><span class="pre">Filters</span></tt> described in the <a class="reference" href="application.html#filters"><em>Filters</em></a> section are subclasses of
this.</p>
<blockquote class="last">
<ul>
<li><p class="first">Contains the rest of the pipeline via its <tt class="docutils literal"><span class="pre">children</span></tt> trait.
This is a <tt class="docutils literal"><span class="pre">List</span></tt> of either <tt class="docutils literal"><span class="pre">Modules</span></tt> or other <tt class="docutils literal"><span class="pre">Filters</span></tt>.</p>
</li>
<li><p class="first">The <tt class="docutils literal"><span class="pre">inputs</span></tt> attribute is a trait <tt class="docutils literal"><span class="pre">List</span></tt> of input data
objects that feed into the filter.</p>
</li>
<li><p class="first">The <tt class="docutils literal"><span class="pre">outputs</span></tt> attribute is a trait <tt class="docutils literal"><span class="pre">List</span></tt> of outputs
produced by the filter.</p>
</li>
<li><p class="first">Also features the three methods:</p>
<ul>
<li><dl class="first docutils">
<dt><tt class="docutils literal"><span class="pre">setup_pipeline</span></tt>: used to create the underlying</dt>
<dd><p class="first last">TVTK pipeline objects if needed.</p>
</dd>
</dl>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">update_pipeline</span></tt>: a method that is called when the
upstream pipeline has been changed, i.e. an upstream object
fires a <tt class="docutils literal"><span class="pre">pipeline_changed</span></tt> event.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">update_data</span></tt>: a method that is called when the upstream
pipeline has <strong>not</strong> been changed but the data in the
pipeline has been changed. This happens when the upstream
object fires a <tt class="docutils literal"><span class="pre">data_changed</span></tt> event.</p>
</li>
</ul>
</li>
</ul>
</blockquote>
</dd>
<dt><tt class="docutils literal"><span class="pre">ModuleManager</span></tt></dt>
<dd><p class="first">Defined in the <tt class="docutils literal"><span class="pre">enthought.mayavi.core.module_manager</span></tt> module.
This object is the one called <em>Modules</em> in the tree view on the
UI. The main purpose of this object is to manage <tt class="docutils literal"><span class="pre">Modules</span></tt> and
share common data between them. All modules typically will use
the same lookup table (LUT) in order to produce a meaningful
visualization. This lookup table is managed by the module
manager.</p>
<blockquote class="last">
<ul class="simple">
<li>The <tt class="docutils literal"><span class="pre">source</span></tt> attribute is the <tt class="docutils literal"><span class="pre">Source</span></tt> or <tt class="docutils literal"><span class="pre">Filter</span></tt> object
that is the input of this object.</li>
<li>Contains a list of <tt class="docutils literal"><span class="pre">Modules</span></tt> in its <tt class="docutils literal"><span class="pre">children</span></tt> trait.</li>
<li>The <tt class="docutils literal"><span class="pre">scalar_lut_manager</span></tt> attribute is an instance of a
<tt class="docutils literal"><span class="pre">LUTManager</span></tt> which basically manages the color mapping from
scalar values to colors on the visualizations. This is
basically a mapping from scalars to colors.</li>
<li>The <tt class="docutils literal"><span class="pre">vector_lut_manager</span></tt> attribute is an instance of a
<tt class="docutils literal"><span class="pre">LUTManager</span></tt> which basically manages the color mapping from
vector values to colors on the visualizations.</li>
<li>The class also features a <tt class="docutils literal"><span class="pre">lut_data_mode</span></tt> attribute that
specifies the data type to use for the LUTs. This can be
changed between ‘auto’, ‘point data’ and ‘cell data’. Changing
this setting will change the data range and name of the lookup
table/legend bar. If set to ‘auto’ (the default), it
automatically looks for cell and point data with point data
being preferred over cell data and chooses the one available.
If set to ‘point data’ it uses the input point data for the LUT
and if set to ‘cell data’ it uses the input cell data.</li>
</ul>
</blockquote>
</dd>
<dt><tt class="docutils literal"><span class="pre">Module</span></tt></dt>
<dd><p class="first">Defined in the <tt class="docutils literal"><span class="pre">enthought.mayavi.core.module</span></tt> module.
These objects are the ones that typically produce a visualization
on the TVTK scene. All the modules defined in the <a class="reference" href="application.html#modules"><em>Modules</em></a>
section are subclasses of this.</p>
<blockquote class="last">
<ul>
<li><p class="first">The <tt class="docutils literal"><span class="pre">components</span></tt> attribute is a trait <tt class="docutils literal"><span class="pre">List</span></tt> of various
reusable components that are used by the module. These usually
are never used directly by the user. However, they are
extremely useful when creating new modules. A <tt class="docutils literal"><span class="pre">Component</span></tt> is
basically a reusable piece of code that is used by various
other objects. For example, almost every <tt class="docutils literal"><span class="pre">Module</span></tt> uses a
TVTK actor, mapper and property. These are all “componentized”
into a reusable <cite>Actor</cite> component that the modules use. Thus,
components are a means to promote reuse between mayavi pipeline
objects.</p>
</li>
<li><p class="first">The <tt class="docutils literal"><span class="pre">module_manager</span></tt> attribute specifies the
<tt class="docutils literal"><span class="pre">ModuleManager</span></tt> instance that it is attached to.</p>
</li>
<li><p class="first">Like the <tt class="docutils literal"><span class="pre">Filter</span></tt> modules also feature the three methods:</p>
<ul>
<li><dl class="first docutils">
<dt><tt class="docutils literal"><span class="pre">setup_pipeline</span></tt>: used to create the underlying</dt>
<dd><p class="first last">TVTK pipeline objects if needed.</p>
</dd>
</dl>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">update_pipeline</span></tt>: a method that is called when the
upstream pipeline has been changed, i.e. an upstream object
fires a <tt class="docutils literal"><span class="pre">pipeline_changed</span></tt> event.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">update_data</span></tt>: a method that is called when the upstream
pipeline has <strong>not</strong> been changed but the data in the
pipeline has been changed. This happens when the upstream
object fires a <tt class="docutils literal"><span class="pre">data_changed</span></tt> event.</p>
</li>
</ul>
</li>
</ul>
</blockquote>
</dd>
</dl>
</blockquote>
<p>The following figures show the class hierarchy of the various objects
involved.</p>
<img alt="The ``Engine`` object." src="_images/design2c.png" />
<p><em>The ``Engine`` object and its important attributes and methods.</em></p>
<img alt="Basic object hierarchy" src="_images/design2a.png" />
<p><em>This hierarchy depicts the ``Base`` object, the ``Scene``,
``PipelineBase`` and the ``ModuleManager``.</em></p>
<img alt="More object hierarchy" src="_images/design2b.png" />
<p><em>This hierarchy depicts the ``PipelineBase`` object, the ``Source``,
``Filter``, ``Module`` and the ``Component``.</em></p>
</div>
<div class="section">
<h2 id="scripting-the-mayavi2-application">Scripting the <tt class="docutils literal"><span class="pre">mayavi2</span></tt> application<a class="headerlink" href="#scripting-the-mayavi2-application" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">mayavi2</span></tt> application is implemented in the
<tt class="docutils literal"><span class="pre">enthought.mayavi.scripts.mayavi2</span></tt> module (look at the
<tt class="docutils literal"><span class="pre">mayavi2.py</span></tt> file and not the <tt class="docutils literal"><span class="pre">mayavi2</span></tt> script). This code
handles the command line argument parsing and runs the application.</p>
<p><tt class="docutils literal"><span class="pre">mayavi2</span></tt> is an <a class="reference" href="https://svn.enthought.com/enthought/wiki/Envisage">Envisage</a> application. It starts the Envisage
application in its <tt class="docutils literal"><span class="pre">main</span></tt> method. The code for this is in the
<tt class="docutils literal"><span class="pre">enthought.mayavi.app</span></tt> module. Mayavi uses several envisage plugins
to build up its functionality. These plugins are defined in the
<tt class="docutils literal"><span class="pre">enthought.mayavi.plugin_definitions</span></tt> module. In this module there
are two lists of plugins defined, <tt class="docutils literal"><span class="pre">PLUGIN_DEFINITIONS</span></tt> and the
<tt class="docutils literal"><span class="pre">NONGUI_PLUGIN_DEFINITIONS</span></tt>. The default application uses the
former which produces a GUI that the user can use. If one uses the
latter (<tt class="docutils literal"><span class="pre">NONGUI_PLUGIN_DEFINITIONS</span></tt>) then the mayavi tree view,
object editor and menu items will not be available when the
application is run. This allows a developer to create an application
that uses mayavi but does not show its user interface. An example of
how this may be done is provided in <tt class="docutils literal"><span class="pre">examples/nongui.py</span></tt>.</p>
<div class="section">
<h3 id="scripting-from-the-ui">Scripting from the UI<a class="headerlink" href="#scripting-from-the-ui" title="Permalink to this headline">¶</a></h3>
<p>When using the <tt class="docutils literal"><span class="pre">mayavi2</span></tt> application, it is possible to script from
the embedded Python interpreter on the UI. On the interpreter the
name <tt class="docutils literal"><span class="pre">mayavi</span></tt> is automatically bound to an
<tt class="docutils literal"><span class="pre">enthought.mayavi.script.Script</span></tt> instance that may be used to easily
script mayavi. This instance is a simple wrapper object that merely
provides some nice conveniences while scripting from the UI. It has
an <tt class="docutils literal"><span class="pre">engine</span></tt> trait that is a reference to the running mayavi engine.</p>
<p>As described in <a class="reference" href="application.html#the-embedded-python-interpreter"><em>The embedded Python interpreter</em></a> section, one can
always drag a mayavi object from the tree and drop it on the
interpreter to script it directly.</p>
<p>One may select the <cite>File->Open File...</cite> menu to open an existing
Python file in the text editor, or choose the <cite>File->New File</cite> menu to
create a new file. The text editor is Python-aware and one may write
a script assuming that the <tt class="docutils literal"><span class="pre">mayavi</span></tt> name is bound to the <tt class="docutils literal"><span class="pre">Script</span></tt>
instance as it is on the shell. To execute this script one can press
<tt class="docutils literal"><span class="pre">Control-r</span></tt> as described earlier. <tt class="docutils literal"><span class="pre">Control-s</span></tt> will save the
script.</p>
<p>The nice thing about this kind of scripting is that if one scripts
something on the interpreter or on the editor, one may save the
contents to a file, say <tt class="docutils literal"><span class="pre">script.py</span></tt> and then the next time mayavi
run it like so:</p>
<pre>$ mayavi2 -x script.py</pre>
<p>This will execute the script for automatically. The name <tt class="docutils literal"><span class="pre">mayavi</span></tt>
is available to the script and is bound to the <tt class="docutils literal"><span class="pre">Script</span></tt> instance.
This is very convenient. It is possible to have mayavi execute
multiple scripts. For example:</p>
<pre>$ mayavi2 -d foo.vtk -m IsoSurface -x setup_iso.py -x script2.py</pre>
<p>will load the <tt class="docutils literal"><span class="pre">foo.vtk</span></tt> file, create an <tt class="docutils literal"><span class="pre">IsoSurface</span></tt> module, then
run <tt class="docutils literal"><span class="pre">setup_iso.py</span></tt> and then run <tt class="docutils literal"><span class="pre">script2.py</span></tt>.</p>
<p>There are several scripts in the mayavi <tt class="docutils literal"><span class="pre">examples</span></tt> directory that
should show how this can be done. The <tt class="docutils literal"><span class="pre">examples/README.txt</span></tt>
contains some information on the recommended ways to script.</p>
</div>
<div class="section">
<h3 id="scripting-from-ipython">Scripting from IPython<a class="headerlink" href="#scripting-from-ipython" title="Permalink to this headline">¶</a></h3>
<p>It is possible to script Mayavi using <a class="reference" href="http://ipython.scipy.org">IPython</a>. IPython will have to
be invoked with the <tt class="docutils literal"><span class="pre">-wthread</span></tt> command line option in order to allow
one to interactively script the mayavi application:</p>
<pre>$ ipython -wthread</pre>
<p>To start a visualization do the following:</p>
<div class="highlight"><pre><span class="k">from</span> <span class="nn">enthought.mayavi.app</span> <span class="k">import</span> <span class="n">main</span>
<span class="c"># Note, this does not process any command line arguments.</span>
<span class="n">mayavi</span> <span class="o">=</span> <span class="n">main</span><span class="p">()</span>
<span class="c"># 'mayavi' is the mayavi Script instance.</span>
</pre></div>
<p>It is also possible to use mlab (see <a class="reference" href="mlab.html#simple-scripting-with-mlab"><em>Simple Scripting with mlab</em></a>) for
this purpose:</p>
<div class="highlight"><pre><span class="k">from</span> <span class="nn">enthought.mayavi.tools</span> <span class="k">import</span> <span class="n">mlab</span>
<span class="n">f</span> <span class="o">=</span> <span class="n">mlab</span><span class="o">.</span><span class="n">figure</span><span class="p">()</span> <span class="c"># Returns the current scene.</span>
<span class="n">mayavi</span> <span class="o">=</span> <span class="n">mlab</span><span class="o">.</span><span class="n">get_mayavi</span><span class="p">()</span> <span class="c"># Returns the Script instance.</span>
</pre></div>
<p>With this it should be possible to script mayavi just the way it is
done on the embedded interpreter or on the text editor.</p>
</div>
<div class="section">
<h3 id="an-example">An example<a class="headerlink" href="#an-example" title="Permalink to this headline">¶</a></h3>
<p>Here is an example script that illustrates various features of
scripting mayavi:</p>
<div class="highlight"><pre><span class="c"># Create a new mayavi scene.</span>
<span class="n">mayavi</span><span class="o">.</span><span class="n">new_scene</span><span class="p">()</span>
<span class="c"># Get the current active scene.</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">mayavi</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">current_scene</span>
<span class="c"># Read a data file.</span>
<span class="k">from</span> <span class="nn">enthought.mayavi.sources.api</span> <span class="k">import</span> <span class="n">VTKXMLFileReader</span>
<span class="n">d</span> <span class="o">=</span> <span class="n">VTKXMLFileReader</span><span class="p">()</span>
<span class="c"># You must specify the full path to the data here.</span>
<span class="n">d</span><span class="o">.</span><span class="n">initialize</span><span class="p">(</span><span class="s">'fire_ug.vtu'</span><span class="p">)</span>
<span class="n">mayavi</span><span class="o">.</span><span class="n">add_source</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>
<span class="c"># Import a few modules.</span>
<span class="k">from</span> <span class="nn">enthought.mayavi.modules.api</span> <span class="k">import</span> <span class="n">Outline</span><span class="p">,</span> <span class="n">IsoSurface</span><span class="p">,</span> <span class="n">Streamline</span>
<span class="c"># Show an outline.</span>
<span class="n">o</span> <span class="o">=</span> <span class="n">Outline</span><span class="p">()</span>
<span class="n">mayavi</span><span class="o">.</span><span class="n">add_module</span><span class="p">(</span><span class="n">o</span><span class="p">)</span>
<span class="n">o</span><span class="o">.</span><span class="n">actor</span><span class="o">.</span><span class="n">property</span><span class="o">.</span><span class="n">color</span> <span class="o">=</span> <span class="mf">1</span><span class="p">,</span> <span class="mf">0</span><span class="p">,</span> <span class="mf">0</span> <span class="c"># red color.</span>
<span class="c"># Make a few contours.</span>
<span class="n">iso</span> <span class="o">=</span> <span class="n">IsoSurface</span><span class="p">()</span>
<span class="n">mayavi</span><span class="o">.</span><span class="n">add_module</span><span class="p">(</span><span class="n">iso</span><span class="p">)</span>
<span class="n">iso</span><span class="o">.</span><span class="n">contour</span><span class="o">.</span><span class="n">contours</span> <span class="o">=</span> <span class="p">[</span><span class="mf">450</span><span class="p">,</span> <span class="mf">570</span><span class="p">]</span>
<span class="c"># Make them translucent.</span>
<span class="n">iso</span><span class="o">.</span><span class="n">actor</span><span class="o">.</span><span class="n">property</span><span class="o">.</span><span class="n">opacity</span> <span class="o">=</span> <span class="mf">0.4</span>
<span class="c"># Show the colormapping.</span>
<span class="n">iso</span><span class="o">.</span><span class="n">module_manager</span><span class="o">.</span><span class="n">scalar_lut_manager</span><span class="o">.</span><span class="n">show_scalar_bar</span> <span class="o">=</span> <span class="bp">True</span>
<span class="c"># A streamline.</span>
<span class="n">st</span> <span class="o">=</span> <span class="n">Streamline</span><span class="p">()</span>
<span class="n">mayavi</span><span class="o">.</span><span class="n">add_module</span><span class="p">(</span><span class="n">st</span><span class="p">)</span>
<span class="c"># Position the seed center.</span>
<span class="n">st</span><span class="o">.</span><span class="n">seed</span><span class="o">.</span><span class="n">widget</span><span class="o">.</span><span class="n">center</span> <span class="o">=</span> <span class="mf">3.5</span><span class="p">,</span> <span class="mf">0.625</span><span class="p">,</span> <span class="mf">1.25</span>
<span class="n">st</span><span class="o">.</span><span class="n">streamline_type</span> <span class="o">=</span> <span class="s">'tube'</span>
<span class="c"># Save the resulting image.</span>
<span class="n">s</span><span class="o">.</span><span class="n">scene</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="s">'test.png'</span><span class="p">)</span>
<span class="c"># Make an animation:</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mf">36</span><span class="p">):</span>
<span class="c"># Rotate the camera by 10 degrees.</span>
<span class="n">s</span><span class="o">.</span><span class="n">scene</span><span class="o">.</span><span class="n">camera</span><span class="o">.</span><span class="n">azimuth</span><span class="p">(</span><span class="mf">10</span><span class="p">)</span>
<span class="c"># Resets the camera clipping plane so everything fits and then</span>
<span class="c"># renders.</span>
<span class="n">s</span><span class="o">.</span><span class="n">scene</span><span class="o">.</span><span class="n">reset_zoom</span><span class="p">()</span>
<span class="c"># Save the scene.</span>
<span class="n">s</span><span class="o">.</span><span class="n">scene</span><span class="o">.</span><span class="n">save_png</span><span class="p">(</span><span class="s">'anim</span><span class="si">%d</span><span class="s">.png'</span><span class="o">%</span><span class="n">i</span><span class="p">)</span>
</pre></div>
<p>Sometimes, given a mayavi <tt class="docutils literal"><span class="pre">Script</span></tt> instance or <tt class="docutils literal"><span class="pre">Engine</span></tt>, it is
handy to be able to navigate to a particular module/object. In the
above this could be achieved as follows:</p>
<div class="highlight"><pre><span class="n">x</span> <span class="o">=</span> <span class="n">mayavi</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">scenes</span><span class="p">[</span><span class="mf">0</span><span class="p">]</span><span class="o">.</span><span class="n">children</span><span class="p">[</span><span class="mf">0</span><span class="p">]</span><span class="o">.</span><span class="n">children</span><span class="p">[</span><span class="mf">0</span><span class="p">]</span><span class="o">.</span><span class="n">children</span><span class="p">[</span><span class="o">-</span><span class="mf">1</span><span class="p">]</span>
<span class="k">print</span> <span class="n">x</span>
</pre></div>
<p>In this case <tt class="docutils literal"><span class="pre">x</span></tt> will be set to the <tt class="docutils literal"><span class="pre">Streamline</span></tt> instance that we
just created.</p>
<p>There are plenty of examples illustrating various things in the
<tt class="docutils literal"><span class="pre">examples</span></tt> directory. These are all fairly well documented.</p>
<p>In particular, the <tt class="docutils literal"><span class="pre">standalone.py</span></tt> example illustrates how one can
script mayavi without using the envisage application at all. The
<tt class="docutils literal"><span class="pre">offscreen.py</span></tt> example illustrates how this may be done using off
screen rendering (if supported by your particular build of VTK).</p>
<p><tt class="docutils literal"><span class="pre">examples/README.txt</span></tt> contains some information on the recommended
ways to script and some additional information.</p>
</div>
</div>
<div class="section">
<h2 id="using-the-mayavi-envisage-plugins">Using the mayavi envisage plugins<a class="headerlink" href="#using-the-mayavi-envisage-plugins" title="Permalink to this headline">¶</a></h2>
<p>The mayavi related plugin definitions to use are:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">mayavi_plugin_definition.py</span></tt></li>
<li><tt class="docutils literal"><span class="pre">mayavi_ui_plugin_definition.py</span></tt></li>
</ul>
</blockquote>
<p>These are in the <tt class="docutils literal"><span class="pre">enthought.mayavi</span></tt> package. To see an example of
how to use this see the <tt class="docutils literal"><span class="pre">enthought.mayavi.plugin_definitions</span></tt>
module and the <tt class="docutils literal"><span class="pre">enthought.mayavi.app</span></tt> module.</p>
<p>If you are writing Envisage plugins for an application and desire to
use the mayavi plugins from your plugins/applications then it is
important to note that mayavi creates three application objects for
your convenience. These are:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">enthought.mayavi.services.IMAYAVI</span></tt>: This is an
<tt class="docutils literal"><span class="pre">enthought.mayavi.script.Script</span></tt> instance that may be used to
easily script mayavi. It is a simple wrapper object that merely
provides some nice conveniences while scripting from the UI. It
has an <tt class="docutils literal"><span class="pre">engine</span></tt> trait that is a reference to the running mayavi
engine.</li>
<li><tt class="docutils literal"><span class="pre">enthought.mayavi.services.IMAYAVI_ENGINE</span></tt>: This is the running
mayavi engine instance.</li>
<li><tt class="docutils literal"><span class="pre">enthought.mayavi.services.IMAYAVI_ENGINE_VIEW</span></tt>: This is the
view of the engine and is only exposed if the
<tt class="docutils literal"><span class="pre">mayavi_ui_plugin_definition.py</span></tt> is used.</li>
</ul>
</blockquote>
<p>A simple example that demonstrates the use of the mayavi plugin in an
envisage application is included in the <tt class="docutils literal"><span class="pre">examples/explorer</span></tt>
directory. This may be studied to understand how you may do the same
in your envisage applications.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><img class="logo" src="_static/mayavi-logo.png" alt="Logo"/></p>
<h3>Table Of Contents</h3>
<ul>
<li><a class="reference" href="">Advanced Scripting with Mayavi</a><ul>
<li><a class="reference" href="#design-overview">Design Overview</a></li>
<li><a class="reference" href="#scripting-the-mayavi2-application">Scripting the <tt class="docutils literal"><span class="pre">mayavi2</span></tt> application</a><ul>
<li><a class="reference" href="#scripting-from-the-ui">Scripting from the UI</a></li>
<li><a class="reference" href="#scripting-from-ipython">Scripting from IPython</a></li>
<li><a class="reference" href="#an-example">An example</a></li>
</ul>
</li>
<li><a class="reference" href="#using-the-mayavi-envisage-plugins">Using the mayavi envisage plugins</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="mlab.html" title="previous chapter">Simple Scripting with <tt class="docutils literal"><span class="pre">mlab</span></tt></a></p>
<h4>Next topic</h4>
<p class="topless"><a href="data.html" title="next chapter">Creating data for Mayavi</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/advanced_scripting.txt">Show Source</a></li>
</ul>
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" /> <input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="data.html" title="Creating data for Mayavi"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="mlab.html" title="Simple Scripting with mlab"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Mayavi2 v2.2.0 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2008, Prabhu Ramachandran, Gaël Varoquaux.
Last updated on Jun 29, 2008.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
</body>
</html>
distrib
>
Mandriva
>
2008.1
>
x86_64
>
media
>
contrib-backports
>
by-pkgid
>
5a28ce08f20e322d24ac159a4334c346
>
files
>
2503
