.. highlight:: rst

Mayavi2 tips
============


.. highlight:: python
   :linenothreshold: 5


The `mayavi.mlab` module, that we call mlab, provides an easy way to visualize data
in a script or from an interactive prompt with one-liners as done in the matplotlib ``pyplot``
interface but with an emphasis on 3D visualization using Mayavi2. This allows users
to perform quick 3D visualization while being able to use Mayavi's powerful features.
For more details see:

* `Scripting with mayavi2 <http://docs.enthought.com/mayavi/mayavi/mlab.html>`_
* `Reference manual <http://docs.enthought.com/mayavi/mayavi/auto/mlab_reference.html>`_

Try:

.. sourcecode:: ipython

    In [1]: import numpy as np

    In [2]: from mayavi import mlab

    In [3]: t = np.linspace(0, 2*np.pi, 50)

    In [4]: u = np.cos(t)*np.pi

    In [5]: x, y, z = np.sin(u), np.cos(u), np.sin(t)

    In [6]: mlab.points3d(x,y,z)

    In [7]: mlab.show()

    In [8]: mlab.points3d(x,y,z,t, scale_mode='none')

    In [9]: mlab.show()

    In [10]: mlab.points3d?

    In [11]: x, y = np.mgrid[-3:3:100j, -3:3:100j ]

    In [12]: z = np.sin(x*x + y*y)

    In [13]: mlab.surf(x,y,z)

    In [14]: mlab.show()

    In [15]: mlab.mesh(x,y,z)

    In [16]: mlab.show()

A simple example showing a 3D plot done with the help of mayavi2.
The following code shows what it takes to produce such an image.
The plotting is essentially only two lines of code!

.. literalinclude:: TutCodes/mayavi_fft_plot.py
   :language: python

.. image:: TutCodes/mayavi_fft_plot.png

And now an animated example:

.. literalinclude:: TutCodes/testy.py
   :language: python

The next example demonstrates how to use scalar cut planes in order to
evidence subtle characteristics of a plot. Here, we would like
to show the Gibbs oscillations in the Fourier series approximation of jumps.

The workflow for such a problem is:
  * write a simple program (let us call it pl.py) that plots your object
  * run mayavi2 -x pl.py (python pl.py works too for just executing the script)
  * use the 'spion' of mayavi2: click on the red point in the menu: the
    protocol of everything you do visually with the mouse is python-scripted
    in the opened window
  * play with the possibilities and variables that mayavi2 offers, till the
    image that you see satisfies your exigences
  * copy from the 'spion'-window the relevant information for your result into
    your pl.py file
  * save the picture, if you wish; CAUTION: the pictures that mayavi2 produces
    became huge, if saved in vector graphics ... so eps is not recommeded here!
  * re-run mayavi2 -x pl.py to see if this is really what you wanted
  * iterate the above process, if wished
  * improve speed and quality of the plot by avoiding rendering and increasing
    size

In the following code (that was developped following this receipt) you find
hints for your formulations.

.. literalinclude:: TutCodes/mayavi_fourier_series.py
   :language: python

.. image:: TutCodes/mayavi_fourier_series_plot.png