viscid.plot.vlab module

Convevience module for making 3d plots with Mayavi

Note

You can’t set rc parameters for this module!

viscid.plot.vlab.add_field(fld, figure=None, center='', name='')[source]

Add a Viscid Field to a mayavi figure

Parameters:
  • fld (Field) – Some Viscid Field
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
  • center (str) – ‘cell’ or ‘node’, leave blank to use fld.center
  • name (str) – name of vtk object, leave black for fld.name
Returns:

mayavi.sources.vtk_data_source.VTKDataSource
viscid.plot.vlab.add_lines(lines, scalars=None, figure=None, name='NoName')[source]

Add list of lines to a figure

Parameters:
  • lines (list) – See lines2source()
  • scalars (ndarray) – See lines2source()
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
  • name (str) – name of vtk object
Returns:

mayavi.sources.vtk_data_source.VTKDataSource
viscid.plot.vlab.add_source(src, figure=None)[source]

Add a vtk data source to a figure

Parameters:
  • src (VTKDataSource) – Description
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
Returns:

None
viscid.plot.vlab.apply_cmap(target, cmap=None, lut=None, alpha=None, mode='scalar', clim=None, symmetric=False, logscale=False)[source]

Apply a Matplotlib colormap to a Mayavi object & adjust limits

Parameters:
  • target – Some Mayavi object on mode to apply the colormap
  • cmap (sequence, None, False) – name of a Matplotlib colormap, or a sequence of rgb(a) colors, or None to use the default, or False to leave the colormap alone.
  • lut (int) – number of entries desired in the lookup table
  • alpha (number, sequence) – scalar or array that sets the alpha (opacity) channel in the range [0..255]. This is expanded to both ends of the colormap using linear interpolation, i.e., [0, 255] will be a linear ramp from transparent to opaque over the whole colormap.
  • mode (str) – one of ‘scalar’, ‘vector’, or ‘other’
  • clim (sequence) – contains (vmin, vmax) for color scale
  • symmetric (bool) – force the limits on the colorbar to be symmetric around 0, and if no cmap is given, then also use the default symmetric colormap
  • logscale (bool) – Use a logarithmic color scale
Raises:
  • AttributeError – Description
  • ValueError – Description
viscid.plot.vlab.clear_data(figures=None)[source]

Workaround for Mayavi / VTK memory leak

This is needed when Mayavi/VTK keeps a reference to source data when you would expect it to be freed like on a call to mlab.clf() or when removing sources from the pipeline.

Note

This must be called when the pipeline still has the source, so before a call to mlab.clf(), etc.

  1. Set release_data_flag on all sources’ data
  2. Remove reference to the data
  3. Remove the data source
Parameters:figures (None, mayavi.core.scene.Scene, or 'all') – if None, gets current scene; if Scene object, just that one; if ‘all’, act on all scenes in the current engine. Can also be a list of Scene objects
viscid.plot.vlab.clf(figure=None)[source]

Clear source data, then clear figure

Parameters:figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
viscid.plot.vlab.colorbar(*args, **kwargs)[source]

Wraps mayavi.mlab.colorbar and adjusts cmap if you so choose

viscid.plot.vlab.fancy_axes(figure=None, target=None, nb_labels=5, xl=None, xh=None, tight=False, symmetric=False, padding=0.05, opacity=0.7, face_color=None, line_width=2.0, grid_color=None, labels=True, label_color=None, label_shadow=True, consolidate_labels=True)[source]

Make axes with 3 shaded walls and a grid similar to matplotlib

Parameters:
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
  • target (Mayavi Element) – If either xl or xh are not given, then get that limit from a bounding box around target
  • nb_labels (int, sequence) – number of labels in all, or each (x, y, z) directions
  • xl (float, sequence) – lower corner of axes
  • xh (float, sequence) – upper corner of axes
  • tight (bool) – If False, then let xl and xh expand to make nicer labels. This uses matplotlib to determine new extrema
  • symmetric (bool) – If True, then xl + xh = 0
  • padding (float) – add padding as a fraction of the total length
  • opacity (float) – opacity of faces
  • face_color (sequence) – color (r, g, b) of faces
  • line_width (float) – Width of grid lines
  • grid_color (sequence) – Color of grid lines
  • labels (bool) – Whether or not to put axis labels on
  • label_color (sequence) – color of axis labels
  • label_shadow (bool) – Add shadows to all labels
  • consolidate_labels (bool) – if all nb_labels are the same, then only make one axis for the labels
Returns:

source to which 2 surfaces and 3 axes belong
Return type:

VTKDataSource
viscid.plot.vlab.field2cell_source(fld, name=None)[source]

Convert a field to a vtk cell data source

viscid.plot.vlab.field2point_source(fld, name=None)[source]

Convert a field to a vtk point data source

viscid.plot.vlab.field2source(fld, center=None, name=None)[source]

Convert a field to a vtk data source

This dispatches to either field_to_point_source() or field_to_cell_source() depending on the centering of fld.

Parameters:
  • fld – field to convert
  • center (str) – Either “cell”, “node”, or “” to use the same centering as fld
  • name (str) – Add specific name. Leave as “” to use fld.name
Returns:

mayavi source
Raises:

NotImplementedError – If center (or fld.center) is not recognized
viscid.plot.vlab.figure(*args, **kwargs)[source]
viscid.plot.vlab.get_cmap(cmap=None, lut=None, symmetric=False)[source]

Get a Matplotlib colormap as an rgba ndarray

Parameters:
  • cmap (str) – name of colormap, or an ndarray of rgb(a) colors
  • lut (int) – number of entries desired in the lookup table
Returns:

Nx4 array of N rgba colors
Return type:

ndarray
viscid.plot.vlab.hide_window(figure, debug=False)[source]

Try to hide the window; only does something on Qt backend

viscid.plot.vlab.insert_filter(filtr, module_manager)[source]

Insert a filter above an existing module_manager

Parameters:
  • filter (TYPE) – Description
  • module_manager (TYPE) – Description
viscid.plot.vlab.interact(stack_depth=0, **kwargs)[source]
viscid.plot.vlab.iso_surface(src, backface_culling=True, **kwargs)[source]

Wraps mayavi.mlab.pipeline.iso_surface; mind the caveats

Note that backfaces are culled by default.

Note

This function will automatically switch to the default Matplotlib colormap (or the one from your viscidrc file)

If src is a Mayavi source, it must be node centered.

If you call this multiple times with the same viscid.field.Field, you should consider using field2source yourself and passing the Mayavi source object

Parameters:
  • src (Mayavi Source or ScalarField) – If src is a ScalarField, then the field is wrapped into a Mayavi Source and added to the figure. If a Mayavi Source, then it must be node centered.
  • backface_culling (bool) – Cull backfaces by default. Useful for translucent surfaces.
  • **kwargs – Passed to mayavi.mlab.pipeline.scalar_cut_plane
Keyword Arguments:
 
Returns:

mayavi.modules.iso_surface.IsoSurface
viscid.plot.vlab.lines2source(lines, scalars=None, name='NoName')[source]

Turn a list of lines as ndarrays into vtk data source

Parameters:
  • lines (list) – List of 3xN, 4xN, 6xN ndarrays of xyz, xyzs, or xyzrgb data for N points along the line. N need not be the same for all lines.
  • scalars (ndarray, list) – Scalars for each point, or each line. See viscid.vutil.prepare_lines() for more details
  • name (str) – name of vtk object
Returns:

mayavi.sources.vtk_data_source.VTKDataSource

See also

  • viscid.vutil.prepare_lines()
viscid.plot.vlab.make_fig_offscreen(figure, hide=True)[source]
viscid.plot.vlab.mesh(x, y, z, scalars=None, **kwargs)[source]

Wraps mayavi.mlab.mesh

Note

This function will automatically switch to the default Matplotlib colormap (or the one from your viscidrc file)

Parameters:
  • x (TYPE) – 2D array of vertices’ x-values
  • y (TYPE) – 2D array of vertices’ y-values
  • z (TYPE) – 2D array of vertices’ z-values
  • scalars (ndarray, ScalarField) – optional scalar data
  • **kwargs – Passed to mayavi.mlab.mesh
Keyword Arguments:
 
Returns:

mayavi.modules.surface.Surface
viscid.plot.vlab.mesh_from_seeds(seeds, scalars=None, fill_holes=<class 'viscid.NOT_SPECIFIED'>, **kwargs)[source]

Wraps mayavi.mlab.mesh for Viscid seed generators

Note

This function will automatically switch to the default Matplotlib colormap (or the one from your viscidrc file)

Parameters:
  • seeds (Viscid.SeedGen) – Some seed generator with a 2D mesh representation
  • scalars (ndarray, ScalarField) – data mapped onto the mesh, i.e., the result of viscid.interp_trilin(seeds, …)
  • **kwargs – Passed to mayavi.mlab.mesh
Keyword Arguments:
 
Returns:

mayavi.modules.surface.Surface
viscid.plot.vlab.plot3d_lines(lines, scalars=None, style='tube', figure=None, name='Lines', tube_radius=0.05, tube_sides=6, **kwargs)

Make 3D mayavi plot of lines

Scalars can be a bunch of single values, or a bunch of rgb data to set the color of each line / vertex explicitly. This is explained in lines2source().

Example

A common use case of setting the line color from a topology will want to use viscid.topology2color():

>>> import viscid
>>> from viscid.plot import vlab
>>>
>>> B = viscid.make_dipole()
>>> seeds = viscid.Line([-4, 0, 0], [4, 0, 0])
>>> lines, topology = viscid.calc_streamlines(B, seeds,
>>>                                           ibound=0.05)
>>> scalars = viscid.topology2color(topology)
>>> vlab.plot_lines(lines, scalars, tube_radius=0.02)
>>> vlab.savefig("dipole.x3d")
>>> viscid.meshlab_convert("dipole.x3d", "dae")
>>> vlab.show()
Parameters:
  • lines (list) – See lines2source()
  • scalars (TYPE) – See lines2source()
  • style (str) – ‘tube’ or ‘none’
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
  • name (str) – Description
  • tube_radius (float) – Radius if style == ‘tube’
  • tube_sides (int) – Angular resolution if style == ‘tube’
  • **kwargs – passed to mayavi.mlab.pipeline.surface(). This is useful for setting a colormap among other things.
Keyword Arguments:
 
Returns:

Mayavi surface module
Raises:

ValueError – if style is neither tube nor strip
viscid.plot.vlab.plot_blue_marble(r=1.0, figure=None, nphi=128, ntheta=64, map_style=None, lines=False, res=2, rotate=None, crd_system='gse')[source]

Plot Earth using the Natural Earth dataset maps

Parameters:
  • r (float) – radius of earth
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
  • nphi (int) – phi resolution of Earth’s mesh
  • ntheta (int) – theta resolution of Earth’s mesh
  • map_style (str) – Nothing for standard map, or ‘faded’
  • lines (bool) – Whether or not to show equator, tropics, arctic circles, and a couple meridians.
  • res (int) – Resolution in thousands of pixels longitude (must be one of 1, 2, 4, 8)
  • rotate (None, sequence, str, datetime64) – sequence of length 4 that contains (angle, ux, uy, uz) for the angle and axis of a rotation, or a UT time as string or datetime64 to rotate earth to a specific date/time, or a cotr object in conjunction with crd_system
  • crd_system (str, other) – Used if rotate is datetime-like. Can be one of (‘gse’, ‘mhd’), or anything that returns from viscid.as_crd_system().
Returns:

(VTKDataSource, mayavi.modules.surface.Surface)
viscid.plot.vlab.plot_earth_3d(figure=None, daycol=(1, 1, 1), nightcol=(0, 0, 0), radius=1.0, res=24, crd_system='gse', night_only=False, **kwargs)[source]

Plot a black and white sphere (Earth) showing sunward direction

Parameters:
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
  • daycol (tuple, optional) – color of dayside (RGB)
  • nightcol (tuple, optional) – color of nightside (RGB)
  • res (optional) – rosolution of teh sphere
  • crd_system (str, other) – One of (‘mhd’, ‘gse’), or anything that returns from viscid.as_crd_system().
Returns:

Tuple (day, night) as vtk sources
viscid.plot.vlab.plot_ionosphere(fld, radius=1.063, figure=None, bounding_lat=0.0, rotate=None, crd_system='gse', **kwargs)[source]

Plot an ionospheric field

Parameters:
  • fld (Field) – Some spherical (phi, theta) / (lot, lat) field
  • radius (float) – Defaults to 1Re + 400km == 1.063Re
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
  • bounding_lat (float) – Description
  • rotate (None, sequence, str, datetime64) – sequence of length 4 that contains (angle, ux, uy, uz) for the angle and axis of a rotation, or a UT time as string or datetime64 to rotate earth to a specific date/time, or a cotr object in conjunction with crd_system
  • crd_system (str, other) – Used if rotate is datetime-like. Can be one of (‘gse’, ‘mhd’), or anything that returns from viscid.as_crd_system().
  • **kwargs – passed to mayavi.mlab.mesh()
Keyword Arguments:
 
No Longer Raises:
ValueError: Description
viscid.plot.vlab.plot_line(line, scalars=None, **kwargs)[source]

Wrap plot_lines() for a single line

viscid.plot.vlab.plot_lines(lines, scalars=None, style='tube', figure=None, name='Lines', tube_radius=0.05, tube_sides=6, **kwargs)[source]

Make 3D mayavi plot of lines

Scalars can be a bunch of single values, or a bunch of rgb data to set the color of each line / vertex explicitly. This is explained in lines2source().

Example

A common use case of setting the line color from a topology will want to use viscid.topology2color():

>>> import viscid
>>> from viscid.plot import vlab
>>>
>>> B = viscid.make_dipole()
>>> seeds = viscid.Line([-4, 0, 0], [4, 0, 0])
>>> lines, topology = viscid.calc_streamlines(B, seeds,
>>>                                           ibound=0.05)
>>> scalars = viscid.topology2color(topology)
>>> vlab.plot_lines(lines, scalars, tube_radius=0.02)
>>> vlab.savefig("dipole.x3d")
>>> viscid.meshlab_convert("dipole.x3d", "dae")
>>> vlab.show()
Parameters:
  • lines (list) – See lines2source()
  • scalars (TYPE) – See lines2source()
  • style (str) – ‘tube’ or ‘none’
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
  • name (str) – Description
  • tube_radius (float) – Radius if style == ‘tube’
  • tube_sides (int) – Angular resolution if style == ‘tube’
  • **kwargs – passed to mayavi.mlab.pipeline.surface(). This is useful for setting a colormap among other things.
Keyword Arguments:
 
Returns:

Mayavi surface module
Raises:

ValueError – if style is neither tube nor strip
viscid.plot.vlab.plot_lines3d(lines, scalars=None, style='tube', figure=None, name='Lines', tube_radius=0.05, tube_sides=6, **kwargs)

Make 3D mayavi plot of lines

Scalars can be a bunch of single values, or a bunch of rgb data to set the color of each line / vertex explicitly. This is explained in lines2source().

Example

A common use case of setting the line color from a topology will want to use viscid.topology2color():

>>> import viscid
>>> from viscid.plot import vlab
>>>
>>> B = viscid.make_dipole()
>>> seeds = viscid.Line([-4, 0, 0], [4, 0, 0])
>>> lines, topology = viscid.calc_streamlines(B, seeds,
>>>                                           ibound=0.05)
>>> scalars = viscid.topology2color(topology)
>>> vlab.plot_lines(lines, scalars, tube_radius=0.02)
>>> vlab.savefig("dipole.x3d")
>>> viscid.meshlab_convert("dipole.x3d", "dae")
>>> vlab.show()
Parameters:
  • lines (list) – See lines2source()
  • scalars (TYPE) – See lines2source()
  • style (str) – ‘tube’ or ‘none’
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
  • name (str) – Description
  • tube_radius (float) – Radius if style == ‘tube’
  • tube_sides (int) – Angular resolution if style == ‘tube’
  • **kwargs – passed to mayavi.mlab.pipeline.surface(). This is useful for setting a colormap among other things.
Keyword Arguments:
 
Returns:

Mayavi surface module
Raises:

ValueError – if style is neither tube nor strip
viscid.plot.vlab.plot_natural_earth(r=1.0, figure=None, nphi=128, ntheta=64, map_style=None, lines=False, res=2, rotate=None, crd_system='gse')

Plot Earth using the Natural Earth dataset maps

Parameters:
  • r (float) – radius of earth
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
  • nphi (int) – phi resolution of Earth’s mesh
  • ntheta (int) – theta resolution of Earth’s mesh
  • map_style (str) – Nothing for standard map, or ‘faded’
  • lines (bool) – Whether or not to show equator, tropics, arctic circles, and a couple meridians.
  • res (int) – Resolution in thousands of pixels longitude (must be one of 1, 2, 4, 8)
  • rotate (None, sequence, str, datetime64) – sequence of length 4 that contains (angle, ux, uy, uz) for the angle and axis of a rotation, or a UT time as string or datetime64 to rotate earth to a specific date/time, or a cotr object in conjunction with crd_system
  • crd_system (str, other) – Used if rotate is datetime-like. Can be one of (‘gse’, ‘mhd’), or anything that returns from viscid.as_crd_system().
Returns:

(VTKDataSource, mayavi.modules.surface.Surface)
viscid.plot.vlab.plot_nulls(nulls, Acolor=(0.0, 0.263, 0.345), Bcolor=(0.686, 0.314, 0.0), Ocolor=(0.239, 0.659, 0.557), **kwargs)[source]
viscid.plot.vlab.points2source(vertices, scalars=None, name='NoName')[source]
viscid.plot.vlab.points3d(*args, **kwargs)[source]

Wraps mayavi.mlab.points3d

Parameters:
  • *args – passed to mayavi.mlab.points3d
  • **kwargs – Other Arguments are popped, then kwargs is passed to mayavi.mlab.points3d
Keyword Arguments:
 
  • modify_args (bool) – if True (default), then check if args is a single 2d sequence of shape 3xN or Nx3. Then split them up appropriately. if False, then args are passed through to mlab.points3d unchanged, nomatter what.
  • cmap (str, None, False) – see apply_cmap()
  • alpha (number, sequence) – see apply_cmap()
  • clim (sequence) – see apply_cmap()
  • symmetric (bool) – see apply_cmap()
  • logscale (bool) – see apply_cmap()
Returns:

Description
Return type:

TYPE
viscid.plot.vlab.quiver3d(*args, **kwargs)[source]

Wraps mayavi.mlab.quiver3d

Parameters:
  • *args – passed to mayavi.mlab.quiver3d
  • **kwargs – Other Arguments are popped, then kwargs is passed to mayavi.mlab.quiver3d
Keyword Arguments:
 
Returns:

Description
Return type:

TYPE
viscid.plot.vlab.remove_source(src)[source]

Safely remove a specific vtk source

Parameters:src (vtk_data_source) – vtk data source to remove
viscid.plot.vlab.resize(size, figure=None)[source]

Summary

Parameters:
  • size (tuple) – width, height in pixels
  • figure (mayavi.core.scene.Scene) – specific figure, or None for mayavi.mlab.gcf()
Returns:

None
viscid.plot.vlab.savefig(*args, **kwargs)[source]

Wrap mayavi.mlab.savefig with offscreen hack

viscid.plot.vlab.scalar_cut_plane(src, center=None, **kwargs)[source]

Wraps mayavi.mlab.pipeline.scalar_cut_plane

Note

This function will automatically switch to the default Matplotlib colormap (or the one from your viscidrc file)

If you call this multiple times with the same viscid.field.Field, you should consider using field2source yourself and passing the Mayavi source object

Parameters:
  • src (Mayavi Source or ScalarField) – If src is a ScalarField, then the field is wrapped into a Mayavi Source and added to the figure
  • center (str) – centering for the Mayavi source, ‘cell’ will make the grid visible, while ‘node’ will interpolate between points
  • **kwargs – Passed to mayavi.mlab.pipeline.scalar_cut_plane
Keyword Arguments:
 
Returns:

mayavi.modules.scalar_cut_plane.ScalarCutPlane
viscid.plot.vlab.scalarbar(*args, **kwargs)[source]

Wraps mayavi.mlab.scalarbar and adjusts cmap if you so choose

viscid.plot.vlab.show(stop=False)[source]

Calls mayavi.mlab.show(stop=stop)()

viscid.plot.vlab.streamline(v_src, scalars=None, **kwargs)[source]

Wraps mayavi.mlab.pipeline.streamline; mind the caveats

Note

This function will automatically switch to the default Matplotlib colormap (or the one from your viscidrc file)

Side-effect: If scalars are given, then v_src is modified to point to the scalar data!

If v_src and scalars are Mayavi sources, they must be node centered.

If you call this multiple times with the same v_src and scalars, you should consider using field2source yourself and passing the Mayavi source objects, unless you’re using different scalars with the same vector field, since this function has side-effects on the vector sourc.

Parameters:
  • v_src (Mayavi Source, or VectorField) – Vector to streamline. If a Mayavi Source, then it must be node centered.
  • scalars (Mayavi Source, or ScalarField) – Optional scalar data. If a Mayavi Source, then it must be node centered.
  • **kwargs – Passed to mayavi.mlab.mesh
Keyword Arguments:
 
Returns:

mayavi.modules.streamline.Streamline
viscid.plot.vlab.to_mpl(figure=None, ax=None, size=None, antialiased=True, hide=True, fit=None, **kwargs)[source]

Display a mayavi figure inline in an Jupyter Notebook.

This function takes a screenshot of a figure and blits it to a matplotlib figure using matplotlib.pyplot.imshow()

Parameters:
  • figure – A mayavi figure, if not specified, uses mlab.gcf()
  • ax – Matplotlib axis of the destination (plt.gca() if None)
  • size (None, tuple) – if given, resize the scene in pixels (x, y)
  • antialiased (bool) – Antialias mayavi plot
  • hide (bool) – if True, try to hide the render window
  • fit (None, bool) – Resize mpl window to fit image exactly. If None, then fit if figure does not currently exist.
  • **kwargs – passed to mayavi.mlab.screenshot()
viscid.plot.vlab.vector_cut_plane(v_src, scalars=None, color_mode='vector', **kwargs)[source]

Wraps mayavi.mlab.pipeline.vector_cut_plane

Note

This function will automatically switch to the default Matplotlib colormap (or the one from your viscidrc file)

If you call this multiple times with the same viscid.field.Field, you should consider using field2source yourself and passing the Mayavi source object

Parameters:
  • v_src (Mayavi Source, or VectorField) – Vector to cut-plane. If a Mayavi Source, then it must be node centered.
  • scalars (Mayavi Source, or ScalarField) – Optional scalar data. If a Mayavi Source, then it must be node centered. This will enable scale_mode and color_mode by ‘scalar’
  • color_mode (str) – Color by ‘vector’, ‘scalar’, or ‘none’
  • **kwargs – Passed to mayavi.mlab.pipeline.vector_cut_plane
Keyword Arguments:
 
Returns:

mayavi.modules.vector_cut_plane.VectorCutPlane
viscid.plot.vlab.vectorbar(*args, **kwargs)[source]

Wraps mayavi.mlab.vectorbar and adjusts cmap if you so choose