pyvista.Plotter.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.

bcolorColorLike, default: (0.5, 0.5, 0.5)

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, default: False

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

sizesequence[float], default: (0.2, 0.2)

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, default: “upper right”

Location string. One of the following:

• 'upper right'

• 'upper left'

• 'lower left'

• 'lower right'

• 'center left'

• 'center right'

• 'lower center'

• 'upper center'

• 'center'

facestr | pyvista.PolyData | NoneType, default: “triangle”

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

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 as pv
>>> from pyvista import examples
>>> sphere = pv.Sphere(center=(0, 0, 1))
>>> cube = pv.Cube()
>>> plotter = pv.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()

Alternatively provide labels in the plotter.

>>> plotter = pv.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()