Objects populating the Mayavi pipeline

Here we give a brief description of the key objects in the Mayavi pipeline.

Note

Given a Mayavi object, a simple way to see what important attribute is, display it to call it’s print_traits(). Note that, for certain objects, when used in IPython, this can cause a segfault, due to threading problems in IPython.

Scene

Key attributes
scene	a TVTKScene (tvtk.pyface.tvtk_scene) object which is where all the rendering occurs.
children	a list of Source objects.

The Scene class is defined in the mayavi.core.scene module.

See also

API reference for the Scene class.

Source

All the data sources, file readers, Parametric surface etc. are subclasses of the Source class.

Key attributes
children	a list of either Modules or Filters
outputs	List of outputs produced by the source. These are TVTK datasets, that are explained in the section Data representation in Mayavi.

The Source class is defined in the mayavi.core.source module.

See also

API reference for the Source class.

Filter

All the Filters described in the Filters section are subclasses of this class.

Key attributes
children	a list of either Modules or other Filters.
inputs	a List of input TVTK dataset objects that feed into the filter.
outputs	a list of outputs produced by the filter. These are TVTK datasets, that are explained in the section Data representation in Mayavi.

Key methods
setup_pipeline()	used to create the underlying TVTK pipeline objects if needed.
update_pipeline()	called when the upstream pipeline has been changed, i.e. an upstream object fires a pipeline_changed event.
update_data()	called when the upstream pipeline has not been changed but the data in the pipeline has been changed. This happens when the upstream object fires a data_changed event.

The filter class is defined in the mayavi.core.filter module.

See also

API reference for the Filter class.

ModuleManager: Colors and legends node

This object is the one called Colors and legends in the tree view on the UI. The main purpose of this object is to control how data is turned in colors in the Modules it manages. All modules typically will use a lookup table (LUT) in order to produce a meaningful visualization. This lookup table is managed by the module manager.

Key attributes
source	the Source or Filter object that is the input of this object.
children	a list of the Modules it manages.
scalar_lut_manager	an instance of a LUTManager which basically manages the color mapping from scalar values to colors on the visualizations. This is basically a mapping from scalars to colors.
vector_lut_manager	an instance of a LUTManager which manages the color mapping from vector values to colors on the visualizations.
lut_data_mode	‘auto’, ‘point data’ and ‘cell data’. Specifies the data type to use for the LUTs. This can be changed inbetween . 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.

This class is defined in the mayavi.core.module_manager module.

See also

API reference for the ModuleManager class.

Module

These objects are the ones that typically produce a visualization on the scene. All the modules defined in the Modules section are subclasses of this.

A module is typically returned by the mlab 3D plotting functions.

Key attributes
module_manager	The ModuleManager instance that controls the colormaps and the legends of this Module
actor	The TVTK actor of the modules, in other words the object displayed in the scene. This is where you will have the properties such as scaling, or GL material properties.
components	a list 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 Component is basically a reusable piece of code that is used by various other objects. For example, almost every Module uses a TVTK actor, mapper and property. These are all “componentized” into a reusable Actor component that the modules use. Thus, components are a means to promote reuse between mayavi pipeline objects.

Key methods
setup_pipeline()	used to create the underlying TVTK pipeline objects if needed.
update_pipeline()	called when the upstream pipeline has been changed, i.e. an upstream object fires a pipeline_changed event.
update_data()	called when the upstream pipeline has not been changed but the data in the pipeline has been changed. This happens when the upstream object fires a data_changed event.

Defined in the mayavi.core.module module.

See also

API reference for the Module class.

Engine

The Mayavi engine is the central object dealing with life-cycle of visualization objects and scene, as well as connecting and updating the pipeline. It is at the root of the pipeline and is not displayed in the pipeline view.

For contextual operation, the engine has the notion of a ‘current object’ and a ‘current scene’ and features several methods that let one add a Filter/Source/Module instance to it. The contextual operations are important in a menu-driven graphical user interface.

It allows one to create new scenes and delete them. Also has methods to load and save the entire visualization.

When using mlab, the engine used by mlab can be retrieved using mlab.get_engine().

Key attributes
scenes	a list of Scene objects.
current_object	the object on which contextual operations, such as add_module will apply.
current_scene	the scene in which data sources will be added by default.
current_selection	The object selected in the pipeline view.

Key methods
new_scene()	this is the method called to create a new scene. Subclasses override this method.

Important sub-classes
EnvisageEngine	defined in the mayavi.plugins.envisage_engine module. It is the subclass of used in the mayavi2 application.
OffScreenEngine	defined in the mayavi.core.off_screen_engine module. It creates scenes that are not displayed on screen by default.
NullEngine	defined in the mayavi.core.null_engine module. With this engine, visualization objects are not added to a scene, and thus cannot be rendered. This engine is useful for testing and pure-data handling use of Mayavi’s data structures.

The Engine base class is defined in the mayavi.engine module.

See also

API reference for the Engine class.

Base class: PipelineBase

The PipelineBase is the base class for all objects in the mayavi pipeline except the Scene and Engine (which really isn’t in the pipeline but contains the pipeline). Defined in the mayavi.core.pipeline_base module. Derives from Base which merely abstracts out common functionality.

Key attributes
pipeline_changed	This is an Event Trait: it can only be assigned to and determines when the pipeline has been changed. Therefore, if one does: object.pipeline_changed = True then the pipeline_changed event is fired. Objects downstream of object in the pipeline are automatically setup to listen to events from an upstream object and will call their update_pipeline method.
data_changed	Similarly, if the data_changed event is fired then downstream objects will automatically call their update_data methods.
outputs	a list of outputs produced by the object.
scene	the scene to which the object is attached.
visible	a boolean that toggle the Hide/Show status of the object and its downstream pipeline.

Key methods
remove()	can be used to remove the object (if added) from the mayavi pipeline.

See also

API reference for the PipelineBase class.

Class hierarchy

The following figures show the class hierarchy of the various objects involved.

This hierarchy depicts the ``Base`` object, the ``Scene``, ``PipelineBase`` and the ``ModuleManager``.

This hierarchy depicts the ``PipelineBase`` object, the ``Source``, ``Filter``, ``Module`` and the ``Component``.