Tips and Tricks¶
Below are a few tips and tricks that you may find useful when you use Mayavi2.
Using Mayavi in Jupyter notebooks¶
Mayavi can display either images or X3D elements on the notebook. The images are static and one cannot interact with them. The X3D output produces a fully interactive 3D scene. For information on how to interact with the scene, see here: http://www.x3dom.org/documentation/interaction/
$ jupyter nbextension install --py mayavi --user
To view Mayavi visualizations on the notebook one should first do:
from mayavi import mlab mlab.init_notebook()
Subequently, one may simply do:
s = mlab.test_plot3d() s
init_notebook method is called it configures the Mayavi
objects so they can be rendered on the Jupyter notebook.
One can call
init_notebook multiple times if one wishes to
change the backend between
x3d for some reason.
There are several optional arguments to
init_notebook, the first
is the backend which defaults to
'x3d', it can also be set to
'png'. One can set the width and height of the figure to create
(as integers). The last keyword argument
local defaults to
distributed along with Mayavi otherwise will require an internet
connection to use the x3dom files online. If for some reason the
installation of the jupyter nbextension is not working, using
local=False with an internet connection should work on a modern
browser that supports WebGL.
The X3D data is embedded in the notebook and can be shared but if the scenes have a lot of polygons, these files can be large. With the PNG backend, the PNG’s are also embedded and these are smaller files. The PNG backend relies on offscreen rendering working correctly on your platform.
Off screen rendering¶
Avoiding the rendering window¶
Often you write Mayavi scripts to render a whole batch of images to make an animation or so and find that each time you save an image, Mayavi “raises” the window to make it the active window thus disrupting your work. This is needed since VTK internally grabs the window to make a picture. Occluding the window will also produce either blank or incorrect images.
If you already have a Python script, say
script.py that sets up your
visualization that you run likes so:
$ mayavi2 -x script.py
Then it is very easy to have this script run offscreen. Simply run it like so:
$ mayavi2 -x script.py -o
This will run the script in an offscreen, standalone window. On Linux,
this works best with VTK-5.2 and above. For more details on the command
line arguments supported by the
mayavi2 application, see the
Command line arguments section.
mlab you will want to do this:
mlab.options.offscreen = True
before you create a figure and it will use an offscreen window for the rendering.
Another option for offscreen rendering would be to click on the scene and set the “Off screen rendering” option on. Or from a script:
mayavi.engine.current_scene.scene.off_screen_rendering = True
This will stop raising the window. However, this may not be enough. Please see below on the situation on different platforms.
Windows: If you are using win32 then off screen rendering should work well out of the box. All you will need to do is what is given above.
Linux and the Mac: there are several options to get this working correctly and some major issues to consider:
If you have VTK-5.2 the offscreen rendering option should let you generate the pictures without worrying about occluding the window. However, you will need VTK-5.2 to get this working properly. There are also situations when this does not always work – try it and if you get blank windows, you have a problem. For example:
from mayavi import mlab mlab.options.offscreen = True mlab.test_contour3d() mlab.savefig('example.png')
If this produces a clean image (even if you switch desktops or cover any windows produced), you should be golden. If not you should consider either using a virtual framebuffer or building VTK with Mesa + OSMesa to give you a pure software rendering approach.
Rendering using the virtual framebuffer¶
VTK uses openGL for all its rendering. Under any conventional Unix (including Linux), you need an Xserver running to open a GL context (especially if you want hardware acceleration). This might be a problem when rendering on a headless server. As mentioned in the above paragraph, on a desktop, using the default server may also be a problem as it interferes with your ongoing work.
A good workaround is to use the virtual framebuffer X server for X11 like so:
Make sure you have the
Xvfbpackage installed. For example under Debian and derivatives this is called the
Create the virtual framebuffer X server like so:Xvfb :1 -screen 0 1280x1024x24 -auth localhost
This creates the display ”:1” and creates a screen of size 1280x1024 with 24 bpp (the 24bpp is important). For more options check your
Export display to :1 like so (on bash):$ export DISPLAY=:1
Now run your Mayavi script. It should run uninterrupted on this X server and produce your saved images.
This probably will have to be fine tuned to suit your taste.
Many Linux systems (including Ubuntu and Debian) ship with a helper script xvfb-run for running headless. The following command can run a Python script with Mayavi2 visualizations headless:
xvfb-run --server-args="-screen 0 1024x768x24" python my_script.py
Beware that you shouldn’t call mlab.show or start the mainloop in the script, elsewhere the script will run endlessly, waiting for interaction in a hidden window.
If you want to use Mayavi without the envisage UI or even a traits UI (i.e. with a pure TVTK window) and do off screen rendering with Python scripts you may be interested in the examples_offscreen. This simple example shows how you can use Mayavi without using Envisage or the Mayavi envisage application and still do off screen rendering.
If you are using mlab, outside of the Mayavi2 application, simply set:
mlab.options.offscreen = True
Using VTK with Mesa for pure software rendering¶
Sometimes you might want to run Mayavi/VTK completely headless on a machine with no X server at all and are interested in pure offscreen rendering (for example for usage on the Sage notebook interface). In these cases one could use Mesa’s OSMesa library to render offscreen. The downside is that you will not get any hardware acceleration in this case. Here are brief instructions on how to build VTK to do this.
Build a recent version of mesa. 7.0.4 (as of this time) should work as would 7.2. We assume you download MesaLib-7.0.4.tar.bz2.
Untar, and change directory to the new directory created. We call this directory
make configs/linux-x86, change file as per your configuration. Run
maketo see list of options. Note: 7.2 has a
./configurescript that you can run.
Get VTK-5.2 or later (CVS will also work)..
Now select advanced options ‘t’.
Configure: press ‘c’
Similarly set the
ONif you want offscreen all the time, this will never produce an actual mapped VTK window since the default value of the render window’s offscreen rendering ivar will be set to True in this case.
Any other settings like
Configure again (press ‘c’) and then generate ‘g’.
Note that if you do not want to use
ccmakeand would like to do this from the command line you may also do (for example):cmake \ -DVTK_OPENGL_HAS_OSMESA=ON \ -DVTK_USE_OFFSCREEN=ON \ -DCMAKE_INSTALL_PREFIX=/path/to/vtk-offscreen \ -DVTK_WRAP_PYTHON=ON \ -DPYTHON_EXECUTABLE=/usr/bin/python2.5 \ -DPYTHON_LIBRARY=/usr/lib/libpython2.5.so \ -DBUILD_SHARED_LIBS=ON \ -DVTK_USE_GL2PS=ON \ -DOSMESA_INCLUDE_DIR=/path/to/Mesa-7.2/include/ \ -DOSMESA_LIBRARY=/home/path/to/Mesa-7.2/lib64/libOSMesa.so \ -DOPENGL_INCLUDE_DIR=/path/to/Mesa-7.2/include \ -DOPENGL_gl_LIBRARY=/path/to/Mesa-7.2/lib64/libGL.so \ -DOPENGL_glu_LIBRARY=/path/to/Mesa-7.2/lib64/libGLU.so \ path/to/VTK/
makeand wait till VTK has built. Let us say the build is in
Now install VTK or set the
LD_LIBRARY_PATHsuitably. Also ensure that
$MESA/lib(if the mesa libs are not installed on the system) this ensures that VTK links to the right GL libs. For example:$ export PYTHONPATH=$VTK_BUILD/bin:$VTK_BUILD/Wrapping/Python`` $ export LD_LIBRARY_PATH=$VTK_BUILD/bin:$MESA/lib
Now, you should be all set.
Once this is done you should be able to run mlab examples offscreen. This will work without an X display even.
With such a VTK built and running, one could simply build and install
mayavi2. To use it in a Sage notebook for example you’d want to set
ETS_TOOLKIT='null' and set
mlab.options.offscreen = True. Thats
it. Everything should now work offscreen.
Note that if you set
ON then you’ll by
default only get offscreen contexts. If you do want a UI you will want
to explicitly set the render window’s
off_screen_rendering ivar to
False to force a mapped window. For this reason if you might need
to popup a full UI, it might be better to not set
Extending Mayavi with customizations¶
A developer may wish to customize Mayavi by adding new sources, filters
or modules. These can be done by writing the respective filters and
exposing them via a
user_mayavi.py or a
described in Customizing Mayavi2. A more flexible and
reusable mechanism for doing this is to create a full fledged Mayavi
contrib package in the following manner.
Create a Python package, let’s call it
mv_iitb(for IIT Bombay specific extensions/customizations). The directory structure of this package can be something like so:mv_iitb/ __init__.py user_mayavi.py sources/ ... filters/ ... modules/ ... docs/ ...
The two key points to note in the above are the fact that
mv_iitbis a proper Python package (notice the
__init__.py) and the
user_mayavi.pyis the file that adds whatever new sources/filters/modules etc. to Mayavi. The other part of the structure is really up to the developer. At the moment these packages can add new sources, filters, modules and contribute any Envisage plugins that the
mayavi2application will load.
This package should then be installed somewhere on
sys.path. Once this is done, users can find these packages and enable them from the Tools->Preferences (the UI will automatically detect the package). The
user_mayavi.pyof each selected package will then be imported next time Mayavi is started, note that this will be usable even from
Any number of such packages may be created and distributed. If they are
installed, users can choose to enable them. Internally, the list of
selected packages is stored as the
preference option. The following code shows how this may be accessed
from a Python script:
>>> from mayavi.preferences.api import preference_manager >>> print preference_manager.root.contrib_packages  >>> preference_manager.configure_traits() # Pop up a UI.
For more details on how best to write
user_mayavi.py files and what
you can do in them, please refer to the
examples/mayavi/user_mayavi.py example. Please pay particular
attention to the warnings in that file. It is a very good idea to
ensure that the
user_mayavi.py does not implement any
sources/modules/filters and only registers the metadata. This will
avoid issues with circular imports.
There are three ways a user can customize Mayavi:
- Via Mayavi contributions installed on the system. This may be done by enabling any found contributions from the Tools->Preferences menu on the Mayavi component, look for the “contribution settings”. Any selected contributions will be imported the next time Mayavi starts. For more details see the Extending Mayavi with customizations section.
- At a global, system wide level via a
site_mayavi.py. This file is to be placed anywhere on
- At a local, user level. This is achieved by placing a
user_mayavi.pyin the users
~/.mayavi2/directory. If a
~/.mayavi2/user_mayavi.pyis found, the directory is placed in
The files are similar in their content. Two things may be done in this file:
- Registering new sources, modules or filters in the Mayavi registry (
mayavi.core.registry.registry). This is done by registering metadata for the new class in the registry. See
examples/mayavi/user_mayavi.pyto see an example.
- Adding additional envisage plugins to the mayavi2 application. This is done by defining a function called
get_plugins()that returns a list of plugins that you wish to add to the mayavi2 application.
examples/mayavi/user_mayavi.py example documents and shows how
this can be done. To see it, copy the file to the
directory. If you are unsure where
~ is on your platform, just run
the example and it should print out the directory.
site_mayavi.py, avoid Mayavi imports
from mayavi.modules.outline import Outline etc.
This is because
user_mayavi is imported at a time when many of the
imports are not complete and this will cause hard-to-debug circular
import problems. The
registry is given only metadata mostly in the
form of strings and this will cause no problem. Therefore to define
new modules, we strongly recommend that the modules be defined in
another module or be defined in a factory function as done in the
Scripting Mayavi without using Envisage¶
The Standalone example demonstrates how one can use the core Mayavi API without using Envisage. This is useful when you want to minimize dependencies. Offscreen example demonstrates how to use Mayavi without the envisage UI or even a traits UI (i.e. with a pure TVTK window) and do off screen rendering.
Computing in a thread¶
Compute in thread example demonstrates how to visualize a 2D numpy array and visualize it as image data using a few modules. It also shows how one can do a computation in another thread and update the Mayavi pipeline once the computation is done. This allows a user to interact with the user interface when the computation is performed in another thread.
Polling a file and auto-updating Mayavi¶
Sometimes you have a separate computational process that generates data
suitable for visualization. You’d like Mayavi to visualize the data but
automatically update the data when the data file is updated by the
computation. This is easily achieved by polling the data file and
checking if it has been modified. The Poll file example
demonstrates this. To see it in action will require that you edit the
scalar data in the
examples/data/heart.vtk data file.
Serving Mayavi on the network¶
Say you have a little visualization script and you’d like to run some kind of server where you can script the running Mayavi UI from a TCP/UDP connection. It turns out there is a simple way to do this if you have Twisted installed. Here is a trivial example:
from mayavi import mlab from mayavi.tools import server mlab.test_plot3d() server.serve_tcp()
There is no need to call
mlab.show() in the above. The TCP server
will listen on port 8007 by default in the above (this can be changed
with suitable arguments to
serve_tcp()). Any data sent to the server
is simply exec’d, meaning you can do pretty much anything you want. The
mlab are all available
and can be scripted with Python code. For example after running the
above you can do this:
$ telnet localhost 8007 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. scene.camera.azimuth(45) mlab.clf() mlab.test_contour3d() scene.camera.zoom(1.5)
The nice thing about this is that you do not loose any interactivity of
the application and can continue to use its UI as before, any network
commands will be simply run on top of this. To serve on a UDP port use
serve_udp() function. For more details on the
please look at the source code – it is thoroughly documented.
While this is very powerful it is also a huge security hole since the remote user can do pretty much anything they want once connected to the server.
TCP server: the serve_tcp function¶
UDP server: the serve_udp function¶
Animating a timeseries¶
If a file that mayavi can load has the form
then it is treated as part of a timeseries. For example let us say
you have the following files:
$ ls data_01.vti data_02.vti ... data_10.vti
If one loads the file using Mayavi, a slider will show up on the file reader object which can be used to choose an appropriate timestep. There are also buttons to automatically change the timestep. To do this, select the play checkbox. This can also be done programmatically as follows:
from mayavi import mlab src = mlab.pipeline.open('data_01.vti') src.play = True
Selecting the “loop” checkbox will loop over the files continuously. If you have multiple files that are part of a timeseries, you can choose the “sync timestep” option. This will sync all the timesteps of the other files that have the same number of timesteps as the current reader. The “Rescan files” button will rescan the files on the disc to find newer ones that are part of the timeseries.
Animating a visualization¶
Often users like to animate visualization without affecting the
interactive capabilities of the view. For example you may want to
rotate the camera continuously, take a snapshot while continuing to
interact with the Mayavi UI. To do this one can use the very convenient
animate() decorator provided with Mayavi. Here is a simple
from mayavi import mlab @mlab.animate def anim(): f = mlab.gcf() while 1: f.scene.camera.azimuth(10) f.scene.render() yield a = anim() # Starts the animation.
Notice the use of
yield in the above, this is very crucial to this
working. This example will continuously rotate the camera without
affecting the UI’s interactivity. It also pops up a little UI that lets
you start and stop the animation and change the time interval between
calls to your function. For more specialized use you can pass arguments
to the decorator:
from mayavi import mlab @mlab.animate(delay=500, ui=False) def anim(): # ... a = anim() # Starts the animation without a UI.
If you don’t want to import all of
mlab, the animate
decorator is available from:
from mayavi.tools.animator import animate
Note that to start the event loop, i.e. to get the animation running,
you will need to call
show() if you do not already have a GUI
For more details check the documentation of the
available in the MLab reference. For an example using it,
alongside with the visual handy for object-movement animation, see
Mlab visual example.
If you want to change the data of an object in an animation, see Animating the data
Creating a movie from an animation¶
It is easy to create a movie from either an animation or by playing a timeseries. To do this on the UI, select the Mayavi Scene and navigate to the Movie tab and select the record checkbox. After this, if one animates a timestep via the “play” checkbox referred to in Animating a timeseries, then a stack of images will be created in the directory specified in the movie UI. This will also happen if one runs an animation as discussed in Animating a visualization.
This can also be scripted with mlab for example as follows:
from mayavi import mlab f = mlab.figure() f.scene.movie_maker.record = True mlab.test_mesh_sphere_anim()
This will create a set of images, one for each step of the animation.
movie_maker instance is available on each created scene.
Animating a series of images¶
Let’s say you have a stack of PNG or JPEG files that are numbered
serially that you want to animate on a Mayavi scene. Here is a simple
# img_movie.py from pyface.timer.api import Timer def animate(src, N=10): for j in range(N): for i in range(len(src.file_list)): src.timestep = i yield if __name__ == '__main__': src = mayavi.engine.scenes.children animator = animate(src) t = Timer(250, animator.next)
Timer class lets you call a function without blocking the
running user interface. The first argument is the time after which the
function is to be called again in milliseconds. The
function is a generator and changes the timestep of the source. This
script will animate the stack of images 10 times. The script animates
the first data source by default. This may be changed easily.
To use this script do this:
$ mayavi2 -d your_image000.png -m ImageActor -x img_movie.py
Making movies from a stack of images¶
This isn’t really related to Mayavi but is a useful trick nonetheless.
Let’s say you generate a stack of images using Mayavi say of the form
anim001.png and so on), you
can make this into a movie. If you have
mencoder installed try
$ mencoder "mf://anim%03d.png" -mf fps=10 -o anim.avi \ -ovc lavc -lavcopts vcodec=msmpeg4v2:vbitrate=500
If you have ffmpeg installed you may try this:
$ ffmpeg -f image2 -r 10 -i anim%03d.png -sameq anim.mov -pass 2
Scripting from the command line¶
The Mayavi application allows for very powerful Command line arguments that lets you build a complex visualization from your shell. What follow is a bunch of simple examples illustrating these.
The following example creates a
ParametricSurface source and then
visualizes glyphs on its surface colored red:
$ mayavi2 -d ParametricSurface -m Glyph \ -s"glyph.glyph.scale_factor=0.1" \ -s"glyph.color_mode='no_coloring'" \ -s"actor.property.color = (1,0,0)"
-s"string" applies the string on the last object (also
last_obj), which is the glyph.
This example turns off coloring of the glyph and changes the glyph to display:
$ mayavi2 -d ParametricSurface -m Glyph\ -s"glyph.glyph.scale_factor=0.1" \ -s"glyph.color_mode='no_coloring'" \ -s"glyph.glyph_source.glyph_source = last_obj.glyph.glyph_source.glyph_list[-1]"
Note the use of
last_obj in the above.
Texture mapping actors¶
Here is a simple example showing how to texture map an iso-surface with the data that ships with the Mayavi sources (the data files are in the examples directory):
$ mayavi2 -d examples/tvtk/images/masonry.jpg \ -d examples/mayavi/data/heart.vti \ -m IsoSurface \ -s"actor.mapper.scalar_visibility=False" \ -s"actor.enable_texture=True"\ -s"actor.tcoord_generator_mode='cylinder'"\ -s"actor.texture_source_object=script.engine.current_scene.children"
It should be relatively straightforward to change this example to use a
ParametricSurface instead and any other image of your choice.
Notice how the texture image (
masonry.jpg) is set in the last line
of the above. The image reader is the first child of the current scene
and we set it as the
texture_source_object of the isosurface actor.
Shifting data and plotting¶
Sometimes you need to shift/transform your input data in space and
visualize that in addition to the original data. This is useful when
you’d like to do different things to the same data and see them on the
same plot. This can be done with Mayavi using the
Here is an example using the
ParametricSurface data source:
$ mayavi2 -d ParametricSurface \ -m Outline -m Surface \ -f TransformData -s "transform.translate(1,1,1)" \ -s "widget.set_transform(last_obj.transform)" \ -m Outline -m Surface
If you have an
ImageData dataset then you can change the origin,
spacing and extents alone by using the
filter. Here is a simple example with the standard Mayavi image data:
$ mayavi2 -d examples/mayavi/data/heart.vti -m Outline \ -m ImagePlaneWidget \ -f ImageChangeInformation \ -s "filter.origin_translation=(20,20,20)" \ -m Outline -m ImagePlaneWidget
UserDefined filter in Mayavi lets you wrap around existing VTK
filters easily. Here are a few examples:
$ mayavi2 -d ParametricSurface -s "function='dini'" \ -f UserDefined:GeometryFilter \ -s "filter.extent_clipping=True" \ -s "filter.extent = [-1,1,-1,1,0,5]" \ -f UserDefined:CleanPolyData \ -m Surface \ -s "actor.property.representation = 'p'" \ -s "actor.property.point_size=2"
This one uses a
tvtk.GeometryFilter to perform extent based clipping of
the parametric surface generated. Note the specification of the
UserDefined:GeometryFilter. This data is then cleaned using the
Under mlab, the Userdefined can be used to wrap eg a GeometryFilter VTK filter with:
filtered_obj = mlab.pipeline.user_defined(obj, filter='GeometryFilter')
With mlab, the user_defined function can either take as a filter argument the name of the VTK filter to be used, or an already-instanciated instance of the filter.
With the UserDefined filter, as with most Mayavi filter, the raw TVTK object can be accessed as the filter attribute of the Mayavi filter object.
The Image cursor filter example gives a full example of using the UserDefined filter. The Tvtk segmentation example is a full example of building a complex VTK pipeline with a heavy use of the UserDefined filter.
Changing the interaction with a scene¶
The default 3D interaction with the scene (left click on the background rotates the scene, right click scales, middle click pans) is not suited for every visualization. For instance, in can be interesting to restrict the movement to 2D, e.g. when viewing an object in the ‘x’ direction. This is done by changing the interactor_style of a scene. Here is an example to use Mayavi as a 2D image viewer:
from mayavi import mlab mlab.test_imshow() mlab.view(0, 0) fig = mlab.gcf() from tvtk.api import tvtk fig.scene.interactor.interactor_style = tvtk.InteractorStyleImage() mlab.show()
Another useful interactor is the ‘terrain’ interactor, handy to have natural movement in scenes where you want the ‘up’ vector to be always pointing in the ‘z’ direction:
from mayavi import mlab mlab.test_surf() fig = mlab.gcf() from tvtk.api import tvtk fig.scene.interactor.interactor_style = tvtk.InteractorStyleTerrain() mlab.show()
VTK has many different interactors. An easy way to list them is to display the VTK class browser (via the help menu, in the mayavi2 application) and to search for “Interactor”. Another option is to tab complete on Ipython, on tvtk.InteractorStyle.
Accelerating a Mayavi script¶
You’ve just created a nice Mayavi/mlab script and now want to generate
an animation or a series of images. You realize that it is way too slow
rendering the images and takes ages to finish. There are two simple
ways to speed up the rendering. Let’s assume that
obj is any Mayavi
pipeline object that has a
obj.scene.disable_render = True # Do all your scripting that takes ages. # ... # Once done, do the following: obj.scene.disable_render = False
This will speed things up for complex visualizations sometimes by an order of magnitude.
While saving the visualization to an image you can speed up the image generation at the cost of loosing out on anti-aliasing by doing the following:
obj.scene.anti_aliasing_frames = 0
The default value is typically 8 and the rendered image will be nicely anti-aliased. Setting it to zero will not produce too much difference in the rendered image but any smooth lines will now appear slightly jagged. However, the rendering will be much faster. So if this is acceptable (try it) this is a mechanism to speed up the generation of images.