Debian Codegraph @

pyvista/plotting/axes_actor.py

raw
1 """Axes actor module."""
2
3 from __future__ import annotations
4
5 from collections.abc import Iterable
6 from enum import Enum
7
8 import pyvista as pv
9 from pyvista import _vtk
10 from pyvista.core._typing_core import BoundsTuple
11 from pyvista.core._vtk_utilities import DisableVtkSnakeCase
12 from pyvista.core.utilities.misc import _BoundsSizeMixin
13 from pyvista.core.utilities.misc import _NameMixin
14 from pyvista.core.utilities.misc import _NoNewAttrMixin
15
16 from .actor_properties import ActorProperties
17
18
19 class AxesActor(
20 _NoNewAttrMixin, _NameMixin, _BoundsSizeMixin, DisableVtkSnakeCase, _vtk.vtkAxesActor
21 ):
22 """Axes actor wrapper for :vtk:`vtkAxesActor`.
23
24 Hybrid 2D/3D actor used to represent 3D axes in a scene. The user
25 can define the geometry to use for the shaft or the tip, and the
26 user can set the text for the three axes. To see full customization
27 options, refer to :vtk:`vtkAxesActor`.
28
29 See Also
30 --------
31 :class:`~pyvista.AxesAssembly`
32
33 :ref:`axes_objects_example`
34 Example showing different axes objects.
35
36 Examples
37 --------
38 Customize the axis shaft color and shape.
39
40 >>> import pyvista as pv
41
42 >>> axes = pv.Axes()
43 >>> axes.axes_actor.z_axis_shaft_properties.color = (0.0, 1.0, 1.0)
44 >>> axes.axes_actor.shaft_type = axes.axes_actor.ShaftType.CYLINDER
45 >>> pl = pv.Plotter()
46 >>> _ = pl.add_actor(axes.axes_actor)
47 >>> _ = pl.add_mesh(pv.Sphere())
48 >>> pl.show()
49
50 Or you can use this as a custom orientation widget with
51 :func:`add_orientation_widget() <pyvista.Renderer.add_orientation_widget>`:
52
53 >>> import pyvista as pv
54
55 >>> axes = pv.Axes()
56 >>> axes_actor = axes.axes_actor
57 >>> axes.axes_actor.shaft_type = 0
58
59 >>> axes_actor.x_axis_shaft_properties.color = (1.0, 1.0, 1.0)
60 >>> axes_actor.y_axis_shaft_properties.color = (1.0, 1.0, 1.0)
61 >>> axes_actor.z_axis_shaft_properties.color = (1.0, 1.0, 1.0)
62
63 >>> axes_actor.x_label = 'U'
64 >>> axes_actor.y_label = 'V'
65 >>> axes_actor.z_label = 'W'
66
67 >>> pl = pv.Plotter()
68 >>> _ = pl.add_mesh(pv.Cone())
69 >>> _ = pl.add_orientation_widget(
70 ... axes_actor,
71 ... viewport=(0, 0, 0.5, 0.5),
72 ... )
73 >>> pl.show()
74
75 """
76
77 class ShaftType(Enum):
78 """Types of shaft shapes available."""
79
80 CYLINDER = 0
81 LINE = 1
82
83 class TipType(Enum):
84 """Types of tip shapes available."""
85
86 CONE = 0
87 SPHERE = 1
88
89 def __init__(self):
90 """Initialize actor."""
91 super().__init__()
92
93 self.x_axis_shaft_properties.color = pv.global_theme.axes.x_color.float_rgb
94 self.x_axis_tip_properties.color = pv.global_theme.axes.x_color.float_rgb
95 self.x_axis_shaft_properties.opacity = pv.global_theme.axes.x_color.float_rgba[3]
96 self.x_axis_tip_properties.opacity = pv.global_theme.axes.x_color.float_rgba[3]
97 self.x_axis_shaft_properties.lighting = pv.global_theme.lighting
98
99 self.y_axis_shaft_properties.color = pv.global_theme.axes.y_color.float_rgb
100 self.y_axis_tip_properties.color = pv.global_theme.axes.y_color.float_rgb
101 self.y_axis_shaft_properties.opacity = pv.global_theme.axes.y_color.float_rgba[3]
102 self.y_axis_tip_properties.opacity = pv.global_theme.axes.y_color.float_rgba[3]
103 self.y_axis_shaft_properties.lighting = pv.global_theme.lighting
104
105 self.z_axis_shaft_properties.color = pv.global_theme.axes.z_color.float_rgb
106 self.z_axis_tip_properties.color = pv.global_theme.axes.z_color.float_rgb
107 self.z_axis_shaft_properties.opacity = pv.global_theme.axes.z_color.float_rgba[3]
108 self.z_axis_tip_properties.opacity = pv.global_theme.axes.z_color.float_rgba[3]
109 self.z_axis_shaft_properties.lighting = pv.global_theme.lighting
110
111 @property
112 def bounds(self) -> BoundsTuple:
113 """Return the bounding box of this.
114
115 Returns
116 -------
117 BoundsTuple
118 Bounding box.
119 The form is: ``(x_min, x_max, y_min, y_max, z_min, z_max)``.
120
121 """
122 return BoundsTuple(*self.GetBounds())
123
124 @property
125 def center(self) -> tuple[float, float, float]:
126 """Return the center.
127
128 Returns
129 -------
130 tuple[float, float, float]
131 Center of axes actor.
132
133 """
134 return self.GetCenter()
135
136 @property
137 def visibility(self) -> bool: # numpydoc ignore=RT01
138 """Return or set AxesActor visibility.
139
140 Examples
141 --------
142 Create an Axes object and then access the
143 visibility attribute of its AxesActor.
144
145 >>> import pyvista as pv
146 >>> axes = pv.Axes()
147 >>> axes.axes_actor.visibility
148 True
149
150 """
151 return bool(self.GetVisibility())
152
153 @visibility.setter
154 def visibility(self, value: bool):
155 self.SetVisibility(value)
156
157 @property
158 def total_length(self) -> tuple[float, float, float]: # numpydoc ignore=RT01
159 """Return or set the length of all axes.
160
161 Examples
162 --------
163 >>> import pyvista as pv
164 >>> axes = pv.Axes()
165 >>> axes.axes_actor.total_length
166 (1.0, 1.0, 1.0)
167 >>> axes.axes_actor.total_length = 1.2
168 >>> axes.axes_actor.total_length
169 (1.2, 1.2, 1.2)
170 >>> axes.axes_actor.total_length = (1.0, 0.9, 0.5)
171 >>> axes.axes_actor.total_length
172 (1.0, 0.9, 0.5)
173
174 """
175 return self.GetTotalLength()
176
177 @total_length.setter
178 def total_length(self, length):
179 if isinstance(length, Iterable):
180 self.SetTotalLength(length[0], length[1], length[2]) # type: ignore[index]
181 else:
182 self.SetTotalLength(length, length, length)
183
184 @property
185 def shaft_length(self) -> tuple[float, float, float]: # numpydoc ignore=RT01
186 """Return or set the length of the axes shaft.
187
188 Examples
189 --------
190 >>> import pyvista as pv
191 >>> axes = pv.Axes()
192 >>> axes.axes_actor.shaft_length
193 (0.8, 0.8, 0.8)
194 >>> axes.axes_actor.shaft_length = 0.7
195 >>> axes.axes_actor.shaft_length
196 (0.7, 0.7, 0.7)
197 >>> axes.axes_actor.shaft_length = (1.0, 0.9, 0.5)
198 >>> axes.axes_actor.shaft_length
199 (1.0, 0.9, 0.5)
200
201 """
202 return self.GetNormalizedShaftLength()
203
204 @shaft_length.setter
205 def shaft_length(self, length):
206 if isinstance(length, Iterable):
207 self.SetNormalizedShaftLength(length[0], length[1], length[2]) # type: ignore[index]
208 else:
209 self.SetNormalizedShaftLength(length, length, length)
210
211 @property
212 def tip_length(self) -> tuple[float, float, float]: # numpydoc ignore=RT01
213 """Return or set the length of the tip.
214
215 Examples
216 --------
217 >>> import pyvista as pv
218 >>> axes = pv.Axes()
219 >>> axes.axes_actor.tip_length
220 (0.2, 0.2, 0.2)
221 >>> axes.axes_actor.tip_length = 0.3
222 >>> axes.axes_actor.tip_length
223 (0.3, 0.3, 0.3)
224 >>> axes.axes_actor.tip_length = (0.1, 0.4, 0.2)
225 >>> axes.axes_actor.tip_length
226 (0.1, 0.4, 0.2)
227
228 """
229 return self.GetNormalizedTipLength()
230
231 @tip_length.setter
232 def tip_length(self, length):
233 if isinstance(length, Iterable):
234 self.SetNormalizedTipLength(length[0], length[1], length[2]) # type: ignore[index]
235 else:
236 self.SetNormalizedTipLength(length, length, length)
237
238 @property
239 def label_position(self) -> tuple[float, float, float]: # numpydoc ignore=RT01
240 """Position of the label along the axes.
241
242 Examples
243 --------
244 >>> import pyvista as pv
245 >>> axes = pv.Axes()
246 >>> axes.axes_actor.label_position
247 (1.0, 1.0, 1.0)
248 >>> axes.axes_actor.label_position = 0.3
249 >>> axes.axes_actor.label_position
250 (0.3, 0.3, 0.3)
251 >>> axes.axes_actor.label_position = (0.1, 0.4, 0.2)
252 >>> axes.axes_actor.label_position
253 (0.1, 0.4, 0.2)
254
255 """
256 return self.GetNormalizedLabelPosition()
257
258 @label_position.setter
259 def label_position(self, length):
260 if isinstance(length, Iterable):
261 self.SetNormalizedLabelPosition(length[0], length[1], length[2]) # type: ignore[index]
262 else:
263 self.SetNormalizedLabelPosition(length, length, length)
264
265 @property
266 def cone_resolution(self) -> int: # numpydoc ignore=RT01
267 """Return or set the resolution of the cone tip.
268
269 Examples
270 --------
271 >>> import pyvista as pv
272 >>> axes = pv.Axes()
273 >>> axes.axes_actor.cone_resolution
274 16
275 >>> axes.axes_actor.cone_resolution = 24
276 >>> axes.axes_actor.cone_resolution
277 24
278
279 """
280 return self.GetConeResolution()
281
282 @cone_resolution.setter
283 def cone_resolution(self, res: int):
284 self.SetConeResolution(res)
285
286 @property
287 def sphere_resolution(self) -> int: # numpydoc ignore=RT01
288 """Return or set the resolution of the spherical tip.
289
290 Examples
291 --------
292 >>> import pyvista as pv
293 >>> axes = pv.Axes()
294 >>> axes.axes_actor.sphere_resolution
295 16
296 >>> axes.axes_actor.sphere_resolution = 24
297 >>> axes.axes_actor.sphere_resolution
298 24
299
300 """
301 return self.GetSphereResolution()
302
303 @sphere_resolution.setter
304 def sphere_resolution(self, res: int):
305 self.SetSphereResolution(res)
306
307 @property
308 def cylinder_resolution(self) -> int: # numpydoc ignore=RT01
309 """Return or set the resolution of the shaft cylinder.
310
311 Examples
312 --------
313 >>> import pyvista as pv
314 >>> axes = pv.Axes()
315 >>> axes.axes_actor.cylinder_resolution
316 16
317 >>> axes.axes_actor.cylinder_resolution = 24
318 >>> axes.axes_actor.cylinder_resolution
319 24
320
321 """
322 return self.GetCylinderResolution()
323
324 @cylinder_resolution.setter
325 def cylinder_resolution(self, res: int):
326 self.SetCylinderResolution(res)
327
328 @property
329 def cone_radius(self) -> float: # numpydoc ignore=RT01
330 """Return or set the radius of the cone tip.
331
332 Examples
333 --------
334 >>> import pyvista as pv
335 >>> axes = pv.Axes()
336 >>> axes.axes_actor.cone_radius
337 0.4
338 >>> axes.axes_actor.cone_radius = 0.8
339 >>> axes.axes_actor.cone_radius
340 0.8
341
342 """
343 return self.GetConeRadius()
344
345 @cone_radius.setter
346 def cone_radius(self, rad: float):
347 self.SetConeRadius(rad)
348
349 @property
350 def sphere_radius(self) -> float: # numpydoc ignore=RT01
351 """Return or set the radius of the spherical tip.
352
353 Examples
354 --------
355 >>> import pyvista as pv
356 >>> axes = pv.Axes()
357 >>> axes.axes_actor.sphere_radius
358 0.4
359 >>> axes.axes_actor.sphere_radius = 0.8
360 >>> axes.axes_actor.sphere_radius
361 0.8
362
363 """
364 return self.GetSphereRadius()
365
366 @sphere_radius.setter
367 def sphere_radius(self, rad: float):
368 self.SetSphereRadius(rad)
369
370 @property
371 def cylinder_radius(self) -> float: # numpydoc ignore=RT01
372 """Return or set the radius of the shaft cylinder.
373
374 Examples
375 --------
376 >>> import pyvista as pv
377 >>> axes = pv.Axes()
378 >>> axes.axes_actor.cylinder_radius
379 0.05
380 >>> axes.axes_actor.cylinder_radius = 0.03
381 >>> axes.axes_actor.cylinder_radius
382 0.03
383
384 """
385 return self.GetCylinderRadius()
386
387 @cylinder_radius.setter
388 def cylinder_radius(self, rad: float):
389 self.SetCylinderRadius(rad)
390
391 @property
392 def shaft_type(self) -> ShaftType: # numpydoc ignore=RT01
393 """Return or set the shaft type.
394
395 Can be either a cylinder(0) or a line(1).
396
397 Examples
398 --------
399 >>> import pyvista as pv
400 >>> axes = pv.Axes()
401 >>> axes.axes_actor.shaft_type = axes.axes_actor.ShaftType.LINE
402 >>> axes.axes_actor.shaft_type
403 <ShaftType.LINE: 1>
404
405 """
406 return AxesActor.ShaftType(self.GetShaftType())
407
408 @shaft_type.setter
409 def shaft_type(self, shaft_type: ShaftType | int):
410 shaft_type = AxesActor.ShaftType(shaft_type)
411 if shaft_type == AxesActor.ShaftType.CYLINDER:
412 self.SetShaftTypeToCylinder()
413 elif shaft_type == AxesActor.ShaftType.LINE:
414 self.SetShaftTypeToLine()
415
416 @property
417 def tip_type(self) -> TipType: # numpydoc ignore=RT01
418 """Return or set the shaft type.
419
420 Can be either a cone(0) or a sphere(1).
421
422 Examples
423 --------
424 >>> import pyvista as pv
425 >>> axes = pv.Axes()
426 >>> axes.axes_actor.tip_type = axes.axes_actor.TipType.SPHERE
427 >>> axes.axes_actor.tip_type
428 <TipType.SPHERE: 1>
429
430 """
431 return AxesActor.TipType(self.GetTipType())
432
433 @tip_type.setter
434 def tip_type(self, tip_type: TipType | int):
435 tip_type = AxesActor.TipType(tip_type)
436 if tip_type == AxesActor.TipType.CONE:
437 self.SetTipTypeToCone()
438 elif tip_type == AxesActor.TipType.SPHERE:
439 self.SetTipTypeToSphere()
440
441 @property
442 def labels(self) -> tuple[str, str, str]: # numpydoc ignore=RT01
443 """Return or set the axes labels.
444
445 This property may be used as an alternative to using :attr:`~x_label`,
446 :attr:`~y_label`, and :attr:`~z_label` separately.
447
448 .. versionadded:: 0.44.0
449
450 Examples
451 --------
452 >>> import pyvista as pv
453 >>> axes_actor = pv.AxesActor()
454 >>> axes_actor.labels = ['X Axis', 'Y Axis', 'Z Axis']
455 >>> axes_actor.labels
456 ('X Axis', 'Y Axis', 'Z Axis')
457
458 """
459 return self.x_label, self.y_label, self.z_label
460
461 @labels.setter
462 def labels(self, labels: list[str] | tuple[str]):
463 if not isinstance(labels, (list, tuple)):
464 msg = f'Labels must be a list or tuple. Got {labels} instead.' # type: ignore[unreachable]
465 raise TypeError(msg)
466
467 if len(labels) != 3:
468 msg = f'Labels must be a list or tuple with three items. Got {labels} instead.'
469 raise ValueError(msg)
470 self.x_label = labels[0]
471 self.y_label = labels[1]
472 self.z_label = labels[2]
473
474 @property
475 def x_label(self) -> str: # numpydoc ignore=RT01
476 """Return or set the label for the x-axis.
477
478 Examples
479 --------
480 >>> import pyvista as pv
481 >>> axes = pv.Axes()
482 >>> axes.axes_actor.x_label = 'This axis'
483 >>> axes.axes_actor.x_label
484 'This axis'
485
486 """
487 return self.GetXAxisLabelText()
488
489 @x_label.setter
490 def x_label(self, label: str):
491 self.SetXAxisLabelText(label)
492
493 @property
494 def y_label(self) -> str: # numpydoc ignore=RT01
495 """Return or set the label for the y-axis.
496
497 Examples
498 --------
499 >>> import pyvista as pv
500 >>> axes = pv.Axes()
501 >>> axes.axes_actor.y_label = 'This axis'
502 >>> axes.axes_actor.y_label
503 'This axis'
504
505 """
506 return self.GetYAxisLabelText()
507
508 @y_label.setter
509 def y_label(self, label: str):
510 self.SetYAxisLabelText(label)
511
512 @property
513 def z_label(self) -> str: # numpydoc ignore=RT01
514 """Return or set the label for the z-axis.
515
516 Examples
517 --------
518 >>> import pyvista as pv
519 >>> axes = pv.Axes()
520 >>> axes.axes_actor.z_label = 'This axis'
521 >>> axes.axes_actor.z_label
522 'This axis'
523
524 """
525 return self.GetZAxisLabelText()
526
527 @z_label.setter
528 def z_label(self, label: str):
529 self.SetZAxisLabelText(label)
530
531 @property
532 def x_axis_shaft_properties(self): # numpydoc ignore=RT01
533 """Return or set the properties of the x-axis shaft."""
534 return ActorProperties(self.GetXAxisShaftProperty())
535
536 @property
537 def y_axis_shaft_properties(self): # numpydoc ignore=RT01
538 """Return or set the properties of the y-axis shaft."""
539 return ActorProperties(self.GetYAxisShaftProperty())
540
541 @property
542 def z_axis_shaft_properties(self): # numpydoc ignore=RT01
543 """Return or set the properties of the z-axis shaft."""
544 return ActorProperties(self.GetZAxisShaftProperty())
545
546 @property
547 def x_axis_tip_properties(self): # numpydoc ignore=RT01
548 """Return or set the properties of the x-axis tip."""
549 return ActorProperties(self.GetXAxisTipProperty())
550
551 @x_axis_tip_properties.setter
552 def x_axis_tip_properties(self, properties: ActorProperties):
553 self.x_axis_tip_properties = properties
554
555 @property
556 def y_axis_tip_properties(self): # numpydoc ignore=RT01
557 """Return or set the properties of the y-axis tip."""
558 return ActorProperties(self.GetYAxisTipProperty())
559
560 @y_axis_tip_properties.setter
561 def y_axis_tip_properties(self, properties: ActorProperties):
562 self.y_axis_tip_properties = properties
563
564 @property
565 def z_axis_tip_properties(self): # numpydoc ignore=RT01
566 """Return or set the properties of the z-axis tip."""
567 return ActorProperties(self.GetZAxisTipProperty())
568
569 @z_axis_tip_properties.setter
570 def z_axis_tip_properties(self, properties: ActorProperties):
571 self.z_axis_tip_properties = properties