add_legend#

Plotter.add_legend(labels=None, bcolor=(0.5, 0.5, 0.5), border=False, size=(0.2, 0.2), name=None, loc='upper right', face='triangle')#

Add a legend to render window.

Entries must be a list containing one string and color entry for each item.

Parameters
labelslist, optional

When set to None, uses existing labels as specified by

  • add_mesh

  • add_lines

  • add_points

List containing one entry for each item to be added to the legend. Each entry must contain two strings, [label, color], where label is the name of the item to add, and color is the color of the label to add.

bcolorcolor_like, optional

Background color, either a three item 0 to 1 RGB color list, or a matplotlib color string (e.g. 'w' or 'white' for a white color). If None, legend background is disabled.

borderbool, optional

Controls if there will be a border around the legend. Default False.

sizesequence, optional

Two float sequence, each float between 0 and 1. For example (0.1, 0.1) would make the legend 10% the size of the entire figure window.

namestr, optional

The name for the added actor so that it can be easily updated. If an actor of this name already exists in the rendering window, it will be replaced by the new actor.

locstr, optional

Location string. One of the following:

  • 'upper right'

  • 'upper left'

  • 'lower left'

  • 'lower right'

  • 'center left'

  • 'center right'

  • 'lower center'

  • 'upper center'

  • 'center'

facestr or pyvista.PolyData, optional

Face shape of legend face. One of the following:

  • None: None

  • Line: "-" or "line"

  • Triangle: "^" or 'triangle'

  • Circle: "o" or 'circle'

  • Rectangle: "r" or 'rectangle'

  • Custom: pyvista.PolyData

Default is 'triangle'. Passing None removes the legend face. A custom face can be created using pyvista.PolyData. This will be rendered from the XY plane.

Returns
vtk.vtkLegendBoxActor

Actor for the legend.

Examples

Create a legend by labeling the meshes when using add_mesh

>>> import pyvista
>>> from pyvista import examples
>>> sphere = pyvista.Sphere(center=(0, 0, 1))
>>> cube = pyvista.Cube()
>>> plotter = pyvista.Plotter()
>>> _ = plotter.add_mesh(sphere, 'grey', smooth_shading=True, label='Sphere')
>>> _ = plotter.add_mesh(cube, 'r', label='Cube')
>>> _ = plotter.add_legend(bcolor='w', face=None)
>>> plotter.show()
../../../_images/pyvista-Plotter-add_legend-1_00_00.png

Alternatively provide labels in the plotter.

>>> plotter = pyvista.Plotter()
>>> _ = plotter.add_mesh(sphere, 'grey', smooth_shading=True)
>>> _ = plotter.add_mesh(cube, 'r')
>>> legend_entries = []
>>> legend_entries.append(['My Mesh', 'w'])
>>> legend_entries.append(['My Other Mesh', 'k'])
>>> _ = plotter.add_legend(legend_entries)
>>> plotter.show()
../../../_images/pyvista-Plotter-add_legend-1_01_00.png