Debian Codegraph @

pyvista/plotting/follower.py

raw
1 """Wrap :vtk:`vtkFollower` module."""
2
3 from __future__ import annotations
4
5 from typing import TYPE_CHECKING
6
7 from pyvista import _vtk
8
9 from .actor import Actor
10
11 if TYPE_CHECKING:
12 from ._property import Property
13 from .camera import Camera
14 from .mapper import _BaseMapper
15
16
17 class Follower(Actor, _vtk.vtkFollower):
18 """Wrap :vtk:`vtkFollower`.
19
20 A Follower is a subclass of Actor that always faces the camera. It
21 is useful for screen-aligned labels and billboarding effects.
22
23 The Follower maintains the position and scale of the actor but updates
24 its orientation continuously to face the camera.
25
26 Parameters
27 ----------
28 mapper : pyvista.DataSetMapper, optional
29 DataSetMapper.
30
31 prop : pyvista.Property, optional
32 Property of the actor.
33
34 name : str, optional
35 The name of this actor used when tracking on a plotter.
36
37 Examples
38 --------
39 Create a scene with a Follower text that always faces the camera and a transparent cube.
40
41 >>> import pyvista as pv
42 >>> from pyvista import examples
43 >>> pl = pv.Plotter()
44
45 Create the "Hello" text that will follow the camera.
46
47 >>> text_mesh = pv.Text3D('Hello', depth=0.1)
48 >>> text_mesh = text_mesh.translate(
49 ... [-text_mesh.center[0], -text_mesh.center[1], 0]
50 ... )
51
52 Create mapper and follower actor for the text.
53
54 >>> text_mapper = pv.DataSetMapper(text_mesh)
55 >>> follower = pv.Follower(mapper=text_mapper)
56 >>> follower.prop.color = 'gold'
57 >>> _ = pl.add_actor(follower)
58
59 Create a transparent cube that doesn't follow the camera.
60
61 >>> cube = pv.Cube()
62 >>> cube_actor = pl.add_mesh(
63 ... cube, color='MidnightBlue', opacity=0.3, show_edges=False
64 ... )
65
66 Set the follower's camera and show the scene.
67
68 >>> follower.camera = pl.camera
69 >>> pl.show()
70
71 """
72
73 def __init__(
74 self,
75 mapper: _BaseMapper | None = None,
76 prop: Property | None = None,
77 name: str | None = None,
78 ) -> None:
79 """Initialize follower."""
80 super().__init__(mapper=mapper, prop=prop, name=name)
81
82 @property
83 def camera(self) -> Camera | None: # numpydoc ignore=RT01
84 """Return or set the camera of this follower.
85
86 The follower will continuously update its orientation to face this camera.
87
88 """
89 return self.GetCamera() # type: ignore[return-value]
90
91 @camera.setter
92 def camera(self, cam: Camera) -> None:
93 self.SetCamera(cam)