Debian Codegraph @

pyvista/plotting/_property.py

raw
1 """Wrapper for :vtk:`vtkProperty`."""
2
3 from __future__ import annotations
4
5 import pyvista as pv
6 from pyvista import _vtk
7 from pyvista import vtk_version_info
8 from pyvista._deprecate_positional_args import _deprecate_positional_args
9 from pyvista._warn_external import warn_external
10 from pyvista.core._vtk_utilities import DisableVtkSnakeCase
11 from pyvista.core.utilities.misc import _check_range
12 from pyvista.core.utilities.misc import _NoNewAttrMixin
13
14 from .colors import Color
15 from .opts import InterpolationType
16
17
18 class Property(_NoNewAttrMixin, DisableVtkSnakeCase, _vtk.vtkProperty):
19 """Wrap :vtk:`vtkProperty` and expose it pythonically.
20
21 This class is used to set the property of actors.
22
23 Parameters
24 ----------
25 theme : pyvista.plotting.themes.Theme, optional
26 Plot-specific theme.
27
28 interpolation : str, default: :attr:`pyvista.plotting.themes._LightingConfig.interpolation`
29 Set the method of shading. One of the following:
30
31 * ``'Physically based rendering'`` - Physically based rendering.
32 * ``'pbr'`` - Alias for Physically based rendering.
33 * ``'Phong'`` - Phong shading.
34 * ``'Gouraud'`` - Gouraud shading.
35 * ``'Flat'`` - Flat Shading.
36
37 This parameter is case insensitive.
38
39 color : ColorLike, default: :attr:`pyvista.plotting.themes.Theme.color`
40 Used to make the entire mesh have a single solid color.
41 Either a string, RGB list, or hex color string. For example:
42 ``color='white'``, ``color='w'``, ``color=[1.0, 1.0, 1.0]``, or
43 ``color='#FFFFFF'``. Color will be overridden if scalars are
44 specified.
45
46 style : str, default: 'surface'
47 Visualization style of the mesh. One of the following:
48 ``style='surface'``, ``style='wireframe'``, ``style='points'``.
49 Note that ``'wireframe'`` only shows a wireframe of the outer
50 geometry.
51
52 metallic : float, default: :attr:`pyvista.plotting.themes._LightingConfig.metallic`
53 Usually this value is either 0 or 1 for a real material but any
54 value in between is valid. This parameter is only used by PBR
55 :attr:`interpolation`.
56
57 roughness : float, default: :attr:`pyvista.plotting.themes._LightingConfig.roughness`
58 This value has to be between 0 (glossy) and 1 (rough). A glossy
59 material has reflections and a high specular part. This parameter
60 is only used by PBR :attr:`interpolation`.
61
62 point_size : float, default: :attr:`pyvista.plotting.themes.Theme.point_size`
63 Size of the points represented by this property.
64
65 opacity : float, default: :attr:`pyvista.plotting.themes.Theme.opacity`
66 Opacity of the mesh. A single float value that will be applied globally
67 opacity of the mesh and uniformly applied everywhere - should be
68 between 0 and 1.
69
70 ambient : float, default: :attr:`pyvista.plotting.themes._LightingConfig.ambient`
71 When lighting is enabled, this is the amount of light in the range
72 of 0 to 1 that reaches the actor when not directed at the light
73 source emitted from the viewer.
74
75 diffuse : float, default: :attr:`pyvista.plotting.themes._LightingConfig.diffuse`
76 The diffuse lighting coefficient.
77
78 specular : float, default: :attr:`pyvista.plotting.themes._LightingConfig.specular`
79 The specular lighting coefficient.
80
81 specular_power : float, default: :attr:`pyvista.plotting.themes._LightingConfig.specular_power`
82 The specular power. Must be between 0.0 and 128.0.
83
84 show_edges : bool, default: :attr:`pyvista.plotting.themes.Theme.show_edges`
85 Shows the edges. Does not apply to a wireframe representation.
86
87 edge_color : ColorLike, default: :attr:`pyvista.plotting.themes.Theme.edge_color`
88 The solid color to give the edges when ``show_edges=True``.
89 Either a string, RGB list, or hex color string.
90
91 render_points_as_spheres : bool, \
92 default: :attr:`pyvista.plotting.themes.Theme.render_points_as_spheres`
93
94 Render points as spheres rather than dots.
95
96 render_lines_as_tubes : bool, \
97 default: :attr:`pyvista.plotting.themes.Theme.render_lines_as_tubes`
98
99 Show lines as thick tubes rather than flat lines. Control
100 the width with ``line_width``.
101
102 lighting : bool, default: :attr:`pyvista.plotting.themes.Theme.lighting`
103 Enable or disable view direction lighting.
104
105 line_width : float, default: :attr:`pyvista.plotting.themes.Theme.line_width`
106 Thickness of lines. Only valid for wireframe and surface
107 representations.
108
109 culling : str | bool, optional
110 Does not render faces that are culled. This can be helpful for
111 dense surface meshes, especially when edges are visible, but can
112 cause flat meshes to be partially displayed. Defaults to
113 ``'none'``. One of the following:
114
115 * ``"back"`` - Enable backface culling
116 * ``"front"`` - Enable frontface culling
117 * ``'none'`` - Disable both backface and frontface culling
118
119 edge_opacity : float, default: :attr:`pyvista.plotting.themes.Theme.edge_opacity`
120 Edge opacity of the mesh. A single float value that will be applied globally
121 edge opacity of the mesh and uniformly applied everywhere - should be
122 between 0 and 1.
123
124 .. note::
125 `edge_opacity` uses ``SetEdgeOpacity`` as the underlying method which
126 requires VTK version 9.3 or higher. If ``SetEdgeOpacity`` is not
127 available, `edge_opacity` is set to 1.
128
129 Examples
130 --------
131 Create a :class:`pyvista.Actor` and assign properties to it.
132
133 >>> import pyvista as pv
134 >>> actor = pv.Actor()
135 >>> actor.prop = pv.Property(
136 ... color='r',
137 ... show_edges=True,
138 ... interpolation='Physically based rendering',
139 ... metallic=0.5,
140 ... roughness=0.1,
141 ... )
142
143 Visualize how the property would look when applied to a mesh.
144
145 >>> actor.prop.plot()
146
147 Set custom properties not directly available in
148 :func:`pyvista.Plotter.add_mesh`. Here, we set diffuse, ambient, and
149 specular power and colors.
150
151 >>> pl = pv.Plotter()
152 >>> actor = pl.add_mesh(pv.Sphere())
153 >>> prop = actor.prop
154 >>> prop.diffuse = 0.6
155 >>> prop.diffuse_color = 'w'
156 >>> prop.ambient = 0.3
157 >>> prop.ambient_color = 'r'
158 >>> prop.specular = 0.5
159 >>> prop.specular_color = 'b'
160 >>> pl.show()
161
162 """
163
164 _theme = None
165 _color_set = None
166
167 @_deprecate_positional_args(allowed=['theme'])
168 def __init__( # noqa: PLR0917
169 self,
170 theme=None,
171 interpolation=None,
172 color=None,
173 style='surface',
174 metallic=None,
175 roughness=None,
176 point_size=None,
177 opacity=None,
178 ambient=None,
179 diffuse=None,
180 specular=None,
181 specular_power=None,
182 show_edges=None,
183 edge_color=None,
184 render_points_as_spheres=None,
185 render_lines_as_tubes=None,
186 lighting=None,
187 line_width=None,
188 culling=None,
189 edge_opacity=None,
190 ):
191 """Initialize this property."""
192 self._theme = pv.themes.Theme()
193 if theme is None:
194 # copy global theme to ensure local property theme is fixed
195 # after creation.
196 self._theme.load_theme(pv.global_theme)
197 else:
198 self._theme.load_theme(theme)
199
200 if interpolation is None:
201 interpolation = self._theme.lighting_params.interpolation
202 self.interpolation = interpolation
203
204 self.color = color
205
206 if style is not None:
207 self.style = style
208
209 if self.interpolation == InterpolationType.PBR:
210 if metallic is None:
211 metallic = self._theme.lighting_params.metallic
212 self.metallic = metallic
213 if roughness is None:
214 roughness = self._theme.lighting_params.roughness
215 self.roughness = roughness
216
217 if point_size is None:
218 point_size = self._theme.point_size
219 self.point_size = point_size
220 if opacity is None:
221 opacity = self._theme.opacity
222 self.opacity = opacity
223 if ambient is None:
224 ambient = self._theme.lighting_params.ambient
225 self.ambient = ambient
226 if diffuse is None:
227 diffuse = self._theme.lighting_params.diffuse
228 self.diffuse = diffuse
229 if specular is None:
230 specular = self._theme.lighting_params.specular
231 self.specular = specular
232 if specular_power is None:
233 specular_power = self._theme.lighting_params.specular_power
234 self.specular_power = specular_power
235
236 if show_edges is None:
237 self.show_edges = self._theme.show_edges
238 else:
239 self.show_edges = show_edges
240
241 self.edge_color = edge_color
242 if render_points_as_spheres is None:
243 render_points_as_spheres = self._theme.render_points_as_spheres
244 self.render_points_as_spheres = render_points_as_spheres
245 if render_lines_as_tubes is None:
246 render_lines_as_tubes = self._theme.render_lines_as_tubes
247 self.render_lines_as_tubes = render_lines_as_tubes
248 self.lighting = lighting
249 if line_width is None:
250 line_width = self._theme.line_width
251 self.line_width = line_width
252 if culling is not None:
253 self.culling = culling
254 if vtk_version_info < (9, 3) and edge_opacity is not None: # pragma: no cover
255 warn_external(
256 '`edge_opacity` cannot be used under VTK v9.3.0. '
257 'Try installing VTK v9.3.0 or newer.',
258 UserWarning,
259 )
260 if edge_opacity is None:
261 edge_opacity = self._theme.edge_opacity
262 self.edge_opacity = edge_opacity
263
264 @property
265 def style(self) -> str: # numpydoc ignore=RT01
266 """Return or set the visualization style of the mesh.
267
268 One of the following (case insensitive):
269
270 * ``'surface'``
271 * ``'wireframe'``
272 * ``'points'``
273
274 Examples
275 --------
276 Get the default style and visualize it.
277
278 >>> import pyvista as pv
279 >>> prop = pv.Property()
280 >>> prop.style
281 'Surface'
282
283 >>> prop.plot()
284
285 Visualize the wireframe style.
286
287 >>> prop.style = 'wireframe'
288 >>> prop.plot()
289
290 Visualize the points style.
291
292 >>> prop.style = 'points'
293 >>> prop.point_size = 5.0
294 >>> prop.plot()
295
296 """
297 return self.GetRepresentationAsString()
298
299 @style.setter
300 def style(self, new_style: str):
301 new_style = new_style.lower()
302
303 if new_style == 'wireframe':
304 self.SetRepresentationToWireframe()
305 if not self._color_set:
306 self.color = self._theme.outline_color # type: ignore[union-attr] # type: ignore[attr-defined]
307 elif new_style == 'points':
308 self.SetRepresentationToPoints()
309 elif new_style == 'surface':
310 self.SetRepresentationToSurface()
311 else:
312 msg = (
313 f'Invalid style "{new_style}". Must be one of the following:\n'
314 '\t"surface"\n'
315 '\t"wireframe"\n'
316 '\t"points"\n'
317 )
318 raise ValueError(msg)
319
320 @property
321 def color(self) -> Color: # numpydoc ignore=RT01
322 """Return or set the color of this property.
323
324 Either a string, RGB list, or hex color string. For example:
325 ``color='white'``, ``color='w'``, ``color=[1.0, 1.0, 1.0]``, or
326 ``color='#FFFFFF'``. Color will be overridden if scalars are
327 specified.
328
329 Examples
330 --------
331 Get the default color and visualize it.
332
333 >>> import pyvista as pv
334 >>> prop = pv.Property()
335 >>> prop.color
336 Color(name='light_blue', hex='#add8e6ff', opacity=255)
337
338 >>> prop.plot()
339
340 Visualize a red color.
341
342 >>> prop.color = 'red'
343 >>> prop.plot()
344
345 Visualize an RGB color.
346
347 >>> prop.color = (0.5, 0.5, 0.1)
348 >>> prop.plot()
349
350 """
351 return Color(self.GetColor())
352
353 @color.setter
354 def color(self, value):
355 self._color_set = value is not None
356 rgb_color = Color(value, default_color=self._theme.color) # type: ignore[union-attr]
357 self.SetColor(rgb_color.float_rgb) # type: ignore[call-overload]
358
359 @property
360 def edge_color(self) -> Color: # numpydoc ignore=RT01
361 """Return or set the edge color of this property.
362
363 The solid color to give the edges when ``show_edges=True``.
364 Either a string, RGB list, or hex color string.
365
366 Examples
367 --------
368 Get the default edge color and visualize it. Set the edge's visibility
369 to ``True`` so we can see them.
370
371 >>> import pyvista as pv
372 >>> prop = pv.Property()
373 >>> prop.edge_color
374 Color(name='black', hex='#000000ff', opacity=255)
375
376 >>> prop.show_edges = True
377 >>> prop.plot()
378
379 Visualize red edges.
380
381 >>> prop.edge_color = 'red'
382 >>> prop.plot()
383
384 """
385 return Color(self.GetEdgeColor())
386
387 @edge_color.setter
388 def edge_color(self, value):
389 rgb_color = Color(value, default_color=self._theme.edge_color) # type: ignore[union-attr]
390 self.SetEdgeColor(rgb_color.float_rgb)
391
392 @property
393 def opacity(self) -> float: # numpydoc ignore=RT01
394 """Return or set the opacity of this property.
395
396 The opacity is applied to the surface uniformly.
397
398 Property has range ``[0.0, 1.0]``. A value of ``1.0`` is totally opaque
399 and ``0.0`` is completely transparent.
400
401 Examples
402 --------
403 Get the default opacity and visualize it.
404
405 >>> import pyvista as pv
406 >>> prop = pv.Property()
407 >>> prop.opacity
408 1.0
409
410 >>> prop.plot()
411
412 Visualize an opacity value of ``0.75``.
413
414 >>> prop.opacity = 0.75
415 >>> prop.plot()
416
417 Visualize an opacity of ``0.25``.
418
419 >>> prop.opacity = 0.25
420 >>> prop.plot()
421
422 """
423 return self.GetOpacity()
424
425 @opacity.setter
426 def opacity(self, value: float):
427 _check_range(value, (0, 1), 'opacity')
428 self.SetOpacity(value)
429
430 @property
431 def edge_opacity(self) -> float: # numpydoc ignore=RT01
432 """Return or set the edge opacity of this property.
433
434 Edge opacity of the mesh. A single float value that will be applied globally
435 edge opacity of the mesh and uniformly applied everywhere. Between 0 and 1.
436
437 .. note::
438 `edge_opacity` uses ``SetEdgeOpacity`` as the underlying method which
439 requires VTK version 9.3 or higher. If ``SetEdgeOpacity`` is not
440 available, `edge_opacity` is set to 1.
441
442 Examples
443 --------
444 Get the default edge opacity and visualize it.
445
446 >>> import pyvista as pv
447 >>> prop = pv.Property()
448 >>> prop.edge_opacity
449 1.0
450 >>> prop.show_edges = True
451 >>> prop.plot()
452
453 Visualize an edge opacity of ``0.75``.
454
455 >>> prop.edge_opacity = 0.75
456 >>> prop.plot()
457
458 Visualize wn edge opacity of ``0.25``.
459
460 >>> prop.edge_opacity = 0.25
461 >>> prop.plot()
462
463 """
464 if vtk_version_info < (9, 3):
465 return 1.0
466 else:
467 return self.GetEdgeOpacity()
468
469 @edge_opacity.setter
470 def edge_opacity(self, value: float):
471 _check_range(value, (0, 1), 'edge_opacity')
472 if vtk_version_info >= (9, 3):
473 self.SetEdgeOpacity(value)
474
475 @property
476 def show_edges(self) -> bool: # numpydoc ignore=RT01
477 """Return or set the visibility of edges.
478
479 Shows or hides the edges. Does not apply to a wireframe
480 :attr:`style`.
481
482 Examples
483 --------
484 Get the default edge visibility and visualize it.
485
486 >>> import pyvista as pv
487 >>> prop = pv.Property()
488 >>> prop.show_edges
489 False
490 >>> prop.plot()
491
492 Visualize setting the visibility to ``True``.
493
494 >>> prop.show_edges = True
495 >>> prop.plot()
496
497 """
498 return bool(self.GetEdgeVisibility())
499
500 @show_edges.setter
501 def show_edges(self, value: bool):
502 self.SetEdgeVisibility(value)
503
504 @property
505 def lighting(self) -> bool: # numpydoc ignore=RT01
506 """Return or set view direction lighting.
507
508 Examples
509 --------
510 Get the default lighting and visualize it
511
512 >>> import pyvista as pv
513 >>> prop = pv.Property()
514 >>> prop.lighting
515 True
516 >>> prop.plot()
517
518 Visualize disabled lighting.
519
520 >>> prop.lighting = False
521 >>> prop.plot()
522
523 """
524 return self.GetLighting()
525
526 @lighting.setter
527 def lighting(self, value: bool | None):
528 if value is None:
529 value = self._theme.lighting # type: ignore[union-attr]
530 self.SetLighting(value)
531
532 @property
533 def ambient(self) -> float: # numpydoc ignore=RT01
534 """Return or set ambient.
535
536 Default :attr:`pyvista.plotting.themes._LightingConfig.ambient`.
537
538 When lighting is enabled, this is the amount of light that reaches
539 the actor when not directed at the light source emitted from the
540 viewer.
541
542 Property has range ``[0.0, 1.0]``.
543
544 Examples
545 --------
546 Get the default ambient value and visualize it.
547
548 >>> import pyvista as pv
549 >>> prop = pv.Property()
550 >>> prop.ambient
551 0.0
552
553 >>> prop.plot()
554
555 Visualize ambient at ``0.25``.
556
557 >>> prop.ambient = 0.25
558 >>> prop.plot()
559
560 Visualize ambient at ``0.75``.
561
562 >>> prop.ambient = 0.75
563 >>> prop.plot()
564
565 """
566 return self.GetAmbient()
567
568 @ambient.setter
569 def ambient(self, value: float):
570 _check_range(value, (0, 1), 'ambient')
571 self.SetAmbient(value)
572
573 @property
574 def diffuse(self) -> float: # numpydoc ignore=RT01
575 """Return or set the diffuse lighting coefficient.
576
577 Default :attr:`pyvista.plotting.themes._LightingConfig.diffuse`.
578
579 This is the scattering of light by reflection or
580 transmission. Diffuse reflection results when light strikes an
581 irregular surface such as a frosted window or the surface of a
582 frosted or coated light bulb.
583
584 Property has range ``[0.0, 1.0]``.
585
586 Examples
587 --------
588 Get the default diffuse value and visualize it.
589
590 >>> import pyvista as pv
591 >>> prop = pv.Property()
592 >>> prop.diffuse
593 1.0
594 >>> prop.plot()
595
596 Visualize diffuse at ``0.5``.
597
598 >>> prop.diffuse = 0.5
599 >>> prop.plot()
600
601 Visualize diffuse at ``0.0``.
602
603 >>> prop.diffuse = 0.0
604 >>> prop.plot()
605
606 """
607 return self.GetDiffuse()
608
609 @diffuse.setter
610 def diffuse(self, value: float):
611 _check_range(value, (0, 1), 'diffuse')
612 self.SetDiffuse(value)
613
614 @property
615 def specular(self) -> float: # numpydoc ignore=RT01
616 """Return or set specular.
617
618 Default :attr:`pyvista.plotting.themes._LightingConfig.specular`.
619
620 Specular lighting simulates the bright spot of a light that appears
621 on shiny objects.
622
623 Property has range ``[0.0, 1.0]``.
624
625 Examples
626 --------
627 Get the default specular value and visualize it with Phong shading.
628
629 >>> import pyvista as pv
630 >>> prop = pv.Property()
631 >>> prop.specular
632 0.0
633 >>> prop.interpolation = 'phong'
634 >>> prop.plot()
635
636 Visualize specular at ``0.5``.
637
638 >>> prop.specular = 0.5
639 >>> prop.plot()
640
641 Visualize specular at ``1.0``.
642
643 >>> prop.specular = 1.0
644 >>> prop.plot()
645
646 """
647 return self.GetSpecular()
648
649 @specular.setter
650 def specular(self, value: float):
651 _check_range(value, (0, 1), 'specular')
652 self.SetSpecular(value)
653
654 @property
655 def specular_power(self) -> float: # numpydoc ignore=RT01
656 """Return or set specular power.
657
658 Default :attr:`pyvista.plotting.themes._LightingConfig.specular_power`.
659
660 Property has range ``[0, 128]``.
661
662 Examples
663 --------
664 Get the default specular power value and visualize it with ``specular = 1.0``
665 and Phong shading.
666
667 >>> import pyvista as pv
668 >>> prop = pv.Property()
669 >>> prop.specular_power
670 100.0
671 >>> prop.specular = 1.0
672 >>> prop.interpolation = 'phong'
673 >>> prop.plot()
674
675 Visualize specular power at ``50.0``.
676
677 >>> prop.specular_power = 50.0
678 >>> prop.plot()
679
680 Visualize specular power at ``10.0``.
681
682 >>> prop.specular_power = 10.0
683 >>> prop.plot()
684
685 """
686 return self.GetSpecularPower()
687
688 @specular_power.setter
689 def specular_power(self, value: float):
690 _check_range(value, (0, 128), 'specular_power')
691 self.SetSpecularPower(value)
692
693 @property
694 def metallic(self) -> float: # numpydoc ignore=RT01
695 """Return or set metallic.
696
697 Default :attr:`pyvista.plotting.themes._LightingConfig.metallic`.
698
699 This requires that the :attr:`interpolation` be set to ``'Physically based
700 rendering'``.
701
702 Property has range ``[0.0, 1.0]``.
703
704 Examples
705 --------
706 Get the default metallic value and visualize it.
707
708 >>> import pyvista as pv
709 >>> prop = pv.Property()
710 >>> prop.interpolation = 'pbr' # required
711 >>> prop.metallic
712 0.0
713 >>> prop.plot()
714
715 Visualize metallic at ``0.5``.
716
717 >>> prop.metallic = 0.5
718 >>> prop.plot()
719
720 Visualize metallic at ``1.0``.
721
722 >>> prop.metallic = 1.0
723 >>> prop.plot()
724
725 """
726 return self.GetMetallic()
727
728 @metallic.setter
729 def metallic(self, value: float):
730 _check_range(value, (0, 1), 'metallic')
731 self.SetMetallic(value)
732
733 @property
734 def roughness(self) -> float: # numpydoc ignore=RT01
735 """Return or set roughness.
736
737 Default :attr:`pyvista.plotting.themes._LightingConfig.roughness`.
738
739 This requires that the :attr:`interpolation` be set to ``'Physically based
740 rendering'``.
741
742 Property has range ``[0.0, 1.0]``. A value of 0 is glossy and a value of 1
743 is rough.
744
745 Examples
746 --------
747 Get the default roughness value.
748
749 >>> import pyvista as pv
750 >>> prop = pv.Property()
751 >>> prop.roughness
752 0.5
753
754 Visualize default roughness with metallic of ``0.5`` and physically-based
755 rendering.
756
757 >>> prop.interpolation = 'pbr'
758 >>> prop.metallic = 0.5
759 >>> prop.plot()
760
761 Visualize roughness at ``0.1``.
762
763 >>> prop.roughness = 0.0
764 >>> prop.plot()
765
766 Visualize roughness at ``1.0``.
767
768 >>> prop.roughness = 1.0
769 >>> prop.plot()
770
771 """
772 return self.GetRoughness()
773
774 @roughness.setter
775 def roughness(self, value: bool):
776 _check_range(value, (0, 1), 'roughness')
777 self.SetRoughness(value)
778
779 @property
780 def interpolation(self) -> InterpolationType: # numpydoc ignore=RT01
781 """Return or set the method of shading.
782
783 Defaults to :attr:`pyvista.plotting.themes._LightingConfig.interpolation`.
784
785 One of the following options.
786
787 * ``'Physically based rendering'`` - Physically based rendering.
788 * ``'pbr'`` - Alias for Physically based rendering.
789 * ``'Phong'`` - Phong shading.
790 * ``'Gouraud'`` - Gouraud shading.
791 * ``'Flat'`` - Flat Shading.
792
793 This parameter is case insensitive.
794
795 Examples
796 --------
797 Get the default interpolation and visualize it.
798
799 >>> import pyvista as pv
800 >>> prop = pv.Property()
801 >>> prop.interpolation
802 <InterpolationType.FLAT: 0>
803 >>> prop.plot()
804
805 Visualize gouraud shading.
806
807 >>> prop.interpolation = 'gouraud'
808 >>> prop.plot()
809
810 Visualize phong shading.
811
812 >>> prop.interpolation = 'phong'
813 >>> prop.plot()
814
815 Visualize physically based rendering.
816
817 >>> prop.interpolation = 'pbr'
818 >>> prop.plot()
819
820 """
821 return InterpolationType.from_any(self.GetInterpolation())
822
823 @interpolation.setter
824 def interpolation(self, value: str | int | InterpolationType):
825 value = InterpolationType.from_any(value).value
826 if value == InterpolationType.PBR:
827 self.SetInterpolationToPBR()
828 else:
829 self.SetInterpolation(value) # type: ignore[arg-type]
830
831 @property
832 def render_points_as_spheres(self) -> bool: # numpydoc ignore=RT01
833 """Return or set rendering points as spheres.
834
835 Defaults to :attr:`pyvista.plotting.themes.Theme.render_points_as_spheres`.
836
837 Requires representation style be set to ``'points'``.
838
839 Examples
840 --------
841 Get the default point rendering and visualize it.
842
843 >>> import pyvista as pv
844 >>> prop = pv.Property()
845 >>> prop.render_points_as_spheres
846 False
847 >>> prop.style = 'points'
848 >>> prop.point_size = 20
849 >>> prop.plot()
850
851 Visualize rendering points as spheres.
852
853 >>> prop.render_points_as_spheres = True
854 >>> prop.plot()
855
856 """
857 return self.GetRenderPointsAsSpheres()
858
859 @render_points_as_spheres.setter
860 def render_points_as_spheres(self, value: bool):
861 self.SetRenderPointsAsSpheres(value)
862
863 @property
864 def render_lines_as_tubes(self) -> bool: # numpydoc ignore=RT01
865 """Return or set rendering lines as tubes.
866
867 Defaults to :attr:`pyvista.plotting.themes.Theme.render_lines_as_tubes`.
868
869 Requires lines in the scene, e.g. with :attr:`style` set to ``'wireframe'`` or
870 :attr:`show_edges` set to ``True``.
871
872 See Also
873 --------
874 :ref:`create_truss_example`
875 Example that uses ``render_lines_as_tubes``.
876
877 Examples
878 --------
879 Get the default line rendering and visualize it.
880
881 >>> import pyvista as pv
882 >>> prop = pv.Property()
883 >>> prop.render_lines_as_tubes
884 False
885 >>> prop.show_edges = True
886 >>> prop.line_width = 10
887 >>> prop.edge_color = 'yellow'
888 >>> prop.plot()
889
890 Visualize rendering lines as tubes.
891
892 >>> prop.render_lines_as_tubes = True
893 >>> prop.plot()
894
895 """
896 return self.GetRenderLinesAsTubes()
897
898 @render_lines_as_tubes.setter
899 def render_lines_as_tubes(self, value: bool):
900 self.SetRenderLinesAsTubes(value)
901
902 @property
903 def line_width(self) -> float: # numpydoc ignore=RT01
904 """Return or set the line width.
905
906 Defaults to :attr:`pyvista.plotting.themes.Theme.line_width`.
907
908 The width is expressed in screen units and must be positive.
909
910 Examples
911 --------
912 Get the default line width and visualize it.
913
914 >>> import pyvista as pv
915 >>> prop = pv.Property()
916 >>> prop.line_width
917 1.0
918
919 >>> prop.show_edges = True
920 >>> prop.plot()
921
922 Visualize a line width of ``5.0``.
923
924 >>> prop.line_width = 5.0
925 >>> prop.plot()
926
927 Visualize a line width of ``10.0``.
928
929 >>> prop.line_width = 10.0
930 >>> prop.plot()
931
932 """
933 return self.GetLineWidth()
934
935 @line_width.setter
936 def line_width(self, value: float):
937 _check_range(value, [0, float('inf')], parm_name='line_width')
938 self.SetLineWidth(value)
939
940 @property
941 def point_size(self): # numpydoc ignore=RT01
942 """Return or set the point size.
943
944 Defaults to :attr:`pyvista.plotting.themes.Theme.point_size`.
945
946 This requires that the :attr:`style` be set to ``'points'``.
947
948 The size is expressed in screen units and must be positive.
949
950 Examples
951 --------
952 Get the default point size and visualize it.
953
954 >>> import pyvista as pv
955 >>> prop = pv.Property()
956 >>> prop.point_size
957 5.0
958 >>> prop.style = 'points'
959 >>> prop.plot()
960
961 Visualize a point size of ``10.0``.
962
963 >>> prop.point_size = 10.0
964 >>> prop.plot()
965
966 Visualize a point size of ``50.0``.
967
968 >>> prop.point_size = 50.0
969 >>> prop.plot()
970
971 """
972 return self.GetPointSize()
973
974 @point_size.setter
975 def point_size(self, new_size):
976 _check_range(new_size, [0, float('inf')], parm_name='point_size')
977 self.SetPointSize(new_size)
978
979 @property
980 def culling(self) -> str: # numpydoc ignore=RT01
981 """Return or set face culling.
982
983 Does not render faces that are culled. This can be helpful for dense
984 surface meshes, especially when edges are visible, but can cause flat
985 meshes to be partially displayed. Defaults to ``'none'``. One of the
986 following:
987
988 * ``"back"`` - Enable backface culling
989 * ``"front"`` - Enable frontface culling
990 * ``'none'`` - Disable both backface and frontface culling
991
992 Examples
993 --------
994 Get the default culling value and visualize it.
995
996 >>> import pyvista as pv
997 >>> prop = pv.Property()
998 >>> prop.culling
999 'none'
1000
1001
1002 >>> prop.plot()
1003
1004 Visualize backface culling. This looks the same as the default culling
1005 ``'none'`` because the forward facing faces are already obscuring the
1006 back faces.
1007
1008 >>> prop.culling = 'back'
1009 >>> prop.plot()
1010
1011 Plot frontface culling. Here, the forward facing faces are hidden
1012 entirely.
1013
1014 >>> prop.culling = 'front'
1015 >>> prop.plot()
1016
1017 """
1018 if self.GetBackfaceCulling():
1019 return 'back'
1020 elif self.GetFrontfaceCulling():
1021 return 'front'
1022 return 'none'
1023
1024 @culling.setter
1025 def culling(self, value):
1026 if isinstance(value, str):
1027 value = value.lower()
1028
1029 if value == 'back':
1030 try:
1031 self.BackfaceCullingOn()
1032 self.FrontfaceCullingOff()
1033 except AttributeError: # pragma: no cover
1034 pass
1035 elif value == 'front':
1036 try:
1037 self.FrontfaceCullingOn()
1038 self.BackfaceCullingOff()
1039 except AttributeError: # pragma: no cover
1040 pass
1041 elif value == 'none':
1042 self.FrontfaceCullingOff()
1043 self.BackfaceCullingOff()
1044 else:
1045 msg = f'Invalid culling "{value}". Should be either:\n"back", "front", or "None"'
1046 raise ValueError(msg)
1047
1048 @property
1049 def ambient_color(self) -> Color: # numpydoc ignore=RT01
1050 """Return or set the ambient color of this property.
1051
1052 Either a string, RGB list, or hex color string. For example:
1053 ``color='white'``, ``color='w'``, ``color=[1.0, 1.0, 1.0]``, or
1054 ``color='#FFFFFF'``. Color will be overridden if scalars are
1055 specified.
1056
1057 Examples
1058 --------
1059 Get the default ambient color and visualize it with ``ambient = 0.5``.
1060
1061 >>> import pyvista as pv
1062 >>> prop = pv.Property()
1063 >>> prop.ambient_color
1064 Color(name='light_blue', hex='#add8e6ff', opacity=255)
1065
1066 >>> prop.ambient = 0.5
1067 >>> prop.plot()
1068
1069 Visualize red ambient color.
1070
1071 >>> prop.ambient_color = 'red'
1072 >>> prop.plot()
1073
1074 """
1075 return Color(self.GetAmbientColor())
1076
1077 @ambient_color.setter
1078 def ambient_color(self, value):
1079 self.SetAmbientColor(Color(value).float_rgb)
1080
1081 @property
1082 def specular_color(self) -> Color: # numpydoc ignore=RT01
1083 """Return or set the specular color of this property.
1084
1085 Either a string, RGB list, or hex color string. For example:
1086 ``color='white'``, ``color='w'``, ``color=[1.0, 1.0, 1.0]``, or
1087 ``color='#FFFFFF'``.
1088
1089 Examples
1090 --------
1091 Get the default specular color and visualize it with ``specular = 0.5`` and
1092 Phong shading.
1093
1094 >>> import pyvista as pv
1095 >>> prop = pv.Property()
1096 >>> prop.specular_color
1097 Color(name='light_blue', hex='#add8e6ff', opacity=255)
1098
1099 >>> prop.specular = 0.5
1100 >>> prop.interpolation = 'phong'
1101 >>> prop.plot()
1102
1103 Visualize red specular color.
1104
1105 >>> prop.specular_color = 'red'
1106 >>> prop.plot()
1107
1108 Visualize white specular color.
1109
1110 >>> prop.specular_color = 'white'
1111 >>> prop.plot()
1112
1113 """
1114 return Color(self.GetSpecularColor())
1115
1116 @specular_color.setter
1117 def specular_color(self, value):
1118 self.SetSpecularColor(Color(value).float_rgb)
1119
1120 @property
1121 def diffuse_color(self) -> Color: # numpydoc ignore=RT01
1122 """Return or set the diffuse color of this property.
1123
1124 Either a string, RGB list, or hex color string. For example:
1125 ``color='white'``, ``color='w'``, ``color=[1.0, 1.0, 1.0]``, or
1126 ``color='#FFFFFF'``.
1127
1128 Examples
1129 --------
1130 Get the default diffuse color and visualize it with ``diffuse = 0.5``.
1131
1132 >>> import pyvista as pv
1133 >>> prop = pv.Property()
1134 >>> prop.ambient_color
1135 Color(name='light_blue', hex='#add8e6ff', opacity=255)
1136
1137 >>> prop.diffuse = 0.5
1138 >>> prop.plot()
1139
1140 Visualize red diffuse color.
1141
1142 >>> prop.diffuse_color = 'red'
1143 >>> prop.plot()
1144
1145 Visualize white diffuse color.
1146
1147 >>> prop.diffuse_color = 'white'
1148 >>> prop.plot()
1149
1150 """
1151 return Color(self.GetDiffuseColor())
1152
1153 @diffuse_color.setter
1154 def diffuse_color(self, value):
1155 self.SetDiffuseColor(Color(value).float_rgb)
1156
1157 @property
1158 def anisotropy(self) -> float: # numpydoc ignore=RT01
1159 """Return or set the anisotropy coefficient.
1160
1161 This value controls the anisotropy of the material (0.0 means
1162 isotropic). This requires that the :attr:`interpolation` be set
1163 to ``'Physically based rendering'``.
1164
1165 For further details see `PBR Journey Part 2 : Anisotropy model with VTK
1166 <https://www.kitware.com/pbr-journey-part-2-anisotropy-model-with-vtk/>`_
1167
1168 Property has range ``[0.0, 1.0]``.
1169
1170 Notes
1171 -----
1172 This attribute requires VTK v9.1.0 or newer.
1173
1174 Examples
1175 --------
1176 Get the default anisotropy and visualize it with physically-based rendering.
1177
1178 >>> import pyvista as pv
1179 >>> prop = pv.Property()
1180 >>> prop.anisotropy
1181 0.0
1182
1183 >>> prop.interpolation = 'pbr' # required
1184 >>> prop.plot()
1185
1186 """
1187 if not hasattr(self, 'GetAnisotropy'): # pragma: no cover
1188 from pyvista.core.errors import VTKVersionError # noqa: PLC0415
1189
1190 msg = 'Anisotropy requires VTK v9.1.0 or newer.'
1191 raise VTKVersionError(msg)
1192 return self.GetAnisotropy()
1193
1194 @anisotropy.setter
1195 def anisotropy(self, value: float):
1196 if not hasattr(self, 'SetAnisotropy'): # pragma: no cover
1197 from pyvista.core.errors import VTKVersionError # noqa: PLC0415
1198
1199 msg = 'Anisotropy requires VTK v9.1.0 or newer.'
1200 raise VTKVersionError(msg)
1201 _check_range(value, (0, 1), 'anisotropy')
1202 self.SetAnisotropy(value)
1203
1204 def plot(self, **kwargs) -> None:
1205 """Plot this property on the Stanford Bunny.
1206
1207 This is useful for visualizing how this property would be applied to an
1208 actor.
1209
1210 Parameters
1211 ----------
1212 **kwargs : dict, optional
1213 Keyword arguments for :class:`pyvista.Plotter`.
1214
1215 Examples
1216 --------
1217 >>> import pyvista as pv
1218 >>> prop = pv.Property(
1219 ... show_edges=True,
1220 ... color='brown',
1221 ... edge_color='blue',
1222 ... line_width=4,
1223 ... specular=1.0,
1224 ... )
1225 >>> prop.plot()
1226
1227 """
1228 from pyvista import examples # avoid circular import # noqa: PLC0415
1229
1230 before_close_callback = kwargs.pop('before_close_callback', None)
1231
1232 pl = pv.Plotter(**kwargs)
1233 actor = pl.add_mesh(examples.download_bunny_coarse())
1234 actor.SetProperty(self)
1235
1236 if str(self.interpolation) == 'Physically based rendering':
1237 cubemap = examples.download_sky_box_cube_map()
1238 pl.set_environment_texture(cubemap)
1239
1240 pl.camera_position = 'xy'
1241 pl.show(before_close_callback=before_close_callback)
1242
1243 def copy(self) -> Property:
1244 """Create a deep copy of this property.
1245
1246 Returns
1247 -------
1248 pyvista.Property
1249 Deep copy of this property.
1250
1251 Examples
1252 --------
1253 >>> import pyvista as pv
1254 >>> prop = pv.Property()
1255 >>> prop_copy = prop.copy()
1256
1257 """
1258 new_prop = Property()
1259 new_prop.DeepCopy(self)
1260 return new_prop
1261
1262 def __repr__(self):
1263 """Representation of this property."""
1264 from pyvista.core.errors import VTKVersionError # noqa: PLC0415
1265
1266 props = [
1267 f'{type(self).__name__} ({hex(id(self))})',
1268 ]
1269
1270 for attr in dir(self):
1271 if not attr.startswith('_') and attr[0].islower():
1272 name = ' '.join(attr.split('_')).capitalize() + ':'
1273 try:
1274 value = getattr(self, attr)
1275 except (VTKVersionError, AttributeError): # pragma:no cover
1276 continue
1277 if callable(value):
1278 continue
1279 if isinstance(value, str):
1280 value = f'"{value}"'
1281 props.append(f' {name:28s} {value}')
1282
1283 return '\n'.join(props)