Mayavi Documentation

Mayavi provides two primary ways to interact with 3D scientific data visualization and plotting in Python, depending on your workflow:

1. Interactive Application: Use the Mayavi application if you want an interactive environment to visualize your data in 3D without writing extensive code.
2. Python Scripting (mlab): Use the mlab API if you are a Python developer looking for a Matlab or pylab-like replacement for 3D plotting and data visualization, specifically when working with numpy arrays.

You can also find inspiration in the Example Gallery, which provides example Python code for various visualizations.

There are four primary ways to build a Mayavi pipeline:

1. User Interface: Creating a pipeline manually via a GUI (if available).
2. High-level mlab functions: Using functions like mlab.plot3d to create full pipelines (sources, filters, and modules) from NumPy arrays automatically.
3. Node-by-node mlab scripts: Using mlab.pipeline functions to build the pipeline step-by-step. The function names typically correspond to the names of the pipeline nodes seen in the pipeline view.
4. Manual Object Instantiation: Manually instantiating pipeline objects and adding them to the pipeline via code.

Mayavi can be used in three primary ways depending on your workflow:

1. Graphical Application: Use the mayavi2 application completely through a rich user interface with dialogs to interact with data and objects.
2. Plotting Engine: Use Mayavi within simple Python scripts (e.g., from IPython) combined with numpy. The mlab scripting API is specifically designed for this type of batch-processing and rapid scientific plotting.
3. Scripting and Embedding:
   • Automate the Application: Script the mayavi2 application to automate tasks or extend its behavior.
   • Custom Applications: Script Mayavi from your own Python-based applications.
   • Envisage Integration: Embed Mayavi as a plug-in into other Envisage-based applications for native integration.

TVTK provides a Traits-enabled version of VTK (Visualization Toolkit). It acts as a wrapper around VTK objects to provide several Pythonic enhancements:

• Traits Support: Enables the use of the Traits framework for object properties.
• Numpy Integration: Supports numpy arrays transparently.
• Pythonic API: Provides a more convenient API for Python developers compared to standard VTK.

TVTK is implemented mostly in pure Python and is distributed under a liberal BSD-style license alongside the Mayavi package.

The tvtk module provides a traits-enabled version of VTK. It wraps VTK objects to provide a more Pythonic API while maintaining compatibility with the underlying VTK functionality.

Key features include:

• All VTK classes are wrapped and available via tvtk.
• Support for traits_ (allowing for easy GUI integration and property management).
• Transparent handling of numpy arrays and Python lists.
• Support for a pipeline browser, ivtk, and the high-level mlab module.
• Elementary pickle support for the object's 'basic state'.

For every Mayavi module or filter, there is a corresponding function in mlab.pipeline.

Naming Convention: The function name is derived from the module/filter name by replacing alternating capitals with underscores. For example, the ScalarCutPlane module is accessed via mlab.pipeline.scalar_cut_plane().

Functionality: These functions create and connect the object to the pipeline. They often include additional logic exposed as keyword arguments (e.g., for setting colormaps or colors) to simplify common tasks. It is often easier to use these keyword arguments during creation than to set attributes on the objects after they are created.

Mayavi's support for specific GUI frameworks is dependent on the underlying traitsui and pyface libraries.

• Qt 5 support: Is contingent on traitsui and pyface providing support for Qt 5.
• wxPython 3 support: Is contingent on the necessary support being implemented in the stable releases of traitsui and pyface.

The Source class (defined in mayavi.core.source) represents all data sources, file readers, and parametric surfaces.

Key Attributes:

• children: A list of either Modules or Filters attached to this source.
• outputs: A list of TVTK datasets produced by the source.

Instead of recreating a visualization (which is inefficient and causes jerky motion), you can modify an existing plot by accessing its mlab_source attribute. The mlab_source object allows you to manipulate points (x, y, z) and scalars directly.

Important: When using pipelines created entirely via mlab functions, the mlab_source attribute is available. If you build a pipeline manually using other Mayavi components, this attribute might not be present.

import numpy as np
from mayavi import mlab

x, y = np.mgrid[0:3:1,0:3:1]
s = mlab.surf(x, y, np.asarray(x*0.1, 'd'))

# Update scalars without recreating the plot
for i in range(10):
    s.mlab_source.scalars = np.asarray(x*0.1*(i+1), 'd')

Mayavi is designed to be used interactively. Because it is often difficult to choose the perfect visualization parameters (colors, contours, view angles) in code, you should:

1. Use Dialogs: Use the edit_traits() method on objects or the pipeline interface to open property dialogs. This allows you to tweak parameters in real-time.
2. Record Changes: Once you find a visualization you like, use the record feature to generate the corresponding Python code. This is the easiest way to find the exact attributes and values needed for a reproducible script.
3. Pipeline View: Use the pipeline view dialog to explore the rich VTK-based attributes of the objects returned by mlab functions.

For attributes on the state path (those inferred from SetXToY methods), special_traits cannot be used because it is scoped to the get/set path. Instead, a separate registry is used to handle three specific scenarios:

• vtk_val: Prevents the emission of a mapped trait entirely, falling back to plain methods (e.g., vtkRenderView.InteractionMode).
• extra_val: Keeps the inferred map but tolerates an extra value by coercing it to the default. Warning: Use this only for 'junk' values (like uninitialized defaults) where the value is meaningless. Using this for meaningful values will cause the next resync to push the default value, potentially discarding user settings.
• The map itself: Allows adding name/value pairs that the SetXToY sweep could not discover (e.g., vtkTextProperty.FontFamily).