Label

class Label(*args, **kwargs)

2D label actor with a 3D position coordinate.

Unlike Text, which uses 2D viewport coordinates to position text in a plot, this class instead uses a 3D position coordinate. This class may be positioned, oriented, and transformed in a manner similar to a 3D Actor.

In addition, this class supports an additional relative_position attribute. In general, it is recommended to simply use position when positioning a Label by itself. However, if the position of the label depends on the positioning of another actor, both position and relative_position may be used together. In these cases, the position of the label and actor should be kept in-sync. See the examples below.

Parameters:

textstr, optional

Text string to be displayed.

positionVectorLike[float]

Position of the text in XYZ coordinates.

relative_positionVectorLike[float]

Position of the text in XYZ coordinates relative to its position.

sizeint

Size of the text label.

proppyvista.TextProperty, optional

The property of this actor.

namestr, optional

The name of this actor used when tracking on a plotter.

Added in version 0.45.

Examples

Download Python source code | Download Jupyter notebook

Create a label for a point of interest. Here we add a label to the tip of a cone.

>>> import pyvista as pv
>>> cone_dataset = pv.Cone()
>>> tip = (0.5, 0, 0)
>>> label = pv.Label('tip', position=tip)

Plot the mesh and label.

>>> pl = pv.Plotter()
>>> cone_actor = pl.add_mesh(cone_dataset)
>>> _ = pl.add_actor(label)
>>> pl.show()

Static Scene

Interactive Scene

The previous example set the label’s position as the cone’s tip explicitly. However, this means that the two actors now have different positions.

>>> cone_actor.position
(0.0, 0.0, 0.0)
>>> label.position
(0.5, 0.0, 0.0)

And if we change the 3D orientation of the cone and label, the label is no longer positioned at the tip.

>>> cone_actor.orientation = 0, 0, 90
>>> label.orientation = 0, 0, 90
>>>
>>> pl = pv.Plotter()
>>> _ = pl.add_actor(cone_actor)
>>> _ = pl.add_actor(label)
>>> pl.show()

Static Scene

Interactive Scene

This is because rotations by pyvista.Prop3D are applied before the actor is moved to its final position, and therefore the label’s position is not considered in the rotation. Hence, the final position of the label remains at (0.5, 0.0, 0.0) as it did earlier, despite changing its orientation.

If we want the position of the label to have the same positioning relative to the cone, we can instead set its relative_position.

First, reset the label’s position to match the cone’s position.

>>> label.position = cone_actor.position
>>> label.position
(0.0, 0.0, 0.0)

Now set its relative_position to the tip of the cone.

>>> label.relative_position = tip
>>> label.relative_position
(0.5, 0.0, 0.0)

Plot the results. The label is now correctly positioned at the tip of the cone. This is because the relative_position is considered as part of the rotation.

>>> pl = pv.Plotter()
>>> _ = pl.add_actor(cone_actor)
>>> _ = pl.add_actor(label)
>>> pl.show()

Static Scene

Interactive Scene

As long as the label and cone’s pyvista.Prop3D attributes are modified together and synchronized, the label will remain at the tip of the cone.

Modify the position of the label and tip.

>>> cone_actor.position = (1.0, 2.0, 3.0)
>>> label.position = (1.0, 2.0, 3.0)
>>> pl = pv.Plotter()
>>> _ = pl.add_actor(cone_actor)
>>> _ = pl.add_actor(label)
>>> _ = pl.add_axes_at_origin()
>>> pl.show()

Static Scene

Interactive Scene

See Also

pyvista.Plotter.add_point_labels

Inheritance

Inherited members are documented on _Prop3DMixin, _BoundsSizeMixin, Text, _NameMixin.

See them all under Inherited Attributes.

Wraps vtkTextActor.

Attributes

Label.relative_position	Position of the label relative to its position.
Label.size	Size of the text label.

Inherited Attributes

_Prop3DMixin.bounds	Return the bounds of the entity.
_BoundsSizeMixin.bounds_size	Return the size of each axis of the object’s bounding box.
_Prop3DMixin.center	Return the center of the entity.
Text.input	Text string to be displayed.
_Prop3DMixin.length	Return the length of the entity.
_NameMixin.name	Get or set the unique name identifier used by PyVista.
_Prop3DMixin.orientation	Return or set the entity orientation angles.
_Prop3DMixin.origin	Return or set the entity origin.
_Prop3DMixin.position	Return or set the entity position.
Text.prop	Property of this actor.
_Prop3DMixin.scale	Return or set entity scale.
_Prop3DMixin.user_matrix	Return or set the user matrix.