pyvista.Plotter.add_point_labels

pyvista.Plotter.add_point_labels#

Plotter.add_point_labels(
points: MatrixLike[float] | VectorLike[float] | DataSet | _vtk.vtkAlgorithm,
labels: list[str | int] | str,
italic: bool = False,
bold: bool = True,
font_size: int | None = None,
text_color: ColorLike | None = None,
font_family: FontFamilyOptions | None = None,
font_file: str | None = None,
shadow: bool = False,
show_points: bool = True,
point_color: ColorLike | None = None,
point_size: float | None = None,
name: str | None = None,
shape_color: ColorLike = 'grey',
shape: Literal['rect', 'rounded_rect'] | None = 'rounded_rect',
fill_shape: bool = True,
margin: int = 3,
shape_opacity: float = 1.0,
pickable: bool = False,
render_points_as_spheres: bool = False,
tolerance: float = 0.001,
reset_camera: bool | None = None,
always_visible: bool = False,
render: bool = True,
justification_horizontal: HorizontalOptions | None = None,
justification_vertical: VerticalOptions | None = None,
background_color: ColorLike | None = None,
background_opacity: float | None = None,
) → _vtk.vtkActor2D[source]#

Create a point actor with one label from list labels assigned to each point.

Parameters:
pointssequence | DataSet | vtkAlgorithm

An n x 3 sequence points or pyvista.DataSet with points or mesh-producing algorithm.

labelslist | str

List of labels. Must be the same length as points. If a string name is given with a pyvista.DataSet input for points, then these are fetched.

italicbool, default: False

Italicises title and bar labels.

boldbool, default: True

Bolds title and bar labels.

font_sizefloat, optional

Sets the size of the title font.

text_colorColorLike, optional

Color of text. Either a string, RGB sequence, or hex color string.

  • text_color='white'

  • text_color='w'

  • text_color=[1.0, 1.0, 1.0]

  • text_color='#FFFFFF'

font_familystr, optional

Font family. Must be either 'courier', 'times', or 'arial. This is ignored if the font_file is set.

font_filestr, default: None

The absolute file path to a local file containing a freetype readable font.

shadowbool, default: False

Adds a black shadow to the text.

show_pointsbool, default: True

Controls if points are visible.

point_colorColorLike, optional

Either a string, rgb list, or hex color string. One of the following.

  • point_color='white'

  • point_color='w'

  • point_color=[1.0, 1.0, 1.0]

  • point_color='#FFFFFF'

point_sizefloat, optional

Size of points if visible.

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.

shape_colorColorLike, default: “grey”

Color of shape (if visible). Either a string, rgb sequence, or hex color string.

shapestr, default: “rounded_rect”

The string name of the shape to use. Options are 'rect' or 'rounded_rect'. If you want no shape, pass None.

fill_shapebool, default: True

Fill the shape with the shape_color. Outlines if False.

marginint, default: 3

The size of the margin on the label background shape.

shape_opacityfloat, default: 1.0

The opacity of the shape in the range of [0, 1].

pickablebool, default: False

Set whether this actor is pickable.

render_points_as_spheresbool, default: False

Render points as spheres rather than dots.

tolerancefloat, default: 0.001

A tolerance to use to determine whether a point label is visible. A tolerance is usually required because the conversion from world space to display space during rendering introduces numerical round-off.

reset_camerabool, optional

Reset the camera after adding the points to the scene.

always_visiblebool, default: False

Skip adding the visibility filter.

renderbool, default: True

Force a render when True.

justification_horizontalstr, optional

Text’s horizontal justification. Should be either “left”, “center” or “right”.

Warning

If the justification is not default, the shape will be out of alignment with the label. If you use other than default, Please use the background color. See: pyvista/pyvista#5407

justification_verticalstr, optional

Text’s vertical justification. Should be either “bottom”, “center” or “top”.

Warning

If the justification is not default, the shape will be out of alignment with the label. If you use other than default, Please use the background color. See: pyvista/pyvista#5407

background_colorColor, optional

Background color of text’s property.

background_opacityfloat, optional

Background opacity of text’s property.

Returns:
vtkActor2D

VTK label actor. Can be used to change properties of the labels.

See also

Label Points

Examples

>>> import numpy as np
>>> import pyvista as pv
>>> pl = pv.Plotter()
>>> points = np.array([[0.0, 0.0, 0.0], [1.0, 1.0, 0.0], [2.0, 0.0, 0.0]])
>>> labels = ['Point A', 'Point B', 'Point C']
>>> actor = pl.add_point_labels(
...     points,
...     labels,
...     italic=True,
...     font_size=20,
...     point_color='red',
...     point_size=20,
...     render_points_as_spheres=True,
...     always_visible=True,
...     shadow=True,
... )
>>> pl.camera_position = 'xy'
>>> pl.show()
../../../_images/pyvista-Plotter-add_point_labels-1_00_00.png
Contents