Debian Codegraph @

pyvista/plotting/volume.py

raw
1 """PyVista volume module."""
2
3 from __future__ import annotations
4
5 from typing import TYPE_CHECKING
6
7 from pyvista import _vtk
8 from pyvista._deprecate_positional_args import _deprecate_positional_args
9
10 from .prop3d import Prop3D
11
12 if TYPE_CHECKING:
13 from typing_extensions import Self
14
15 from .mapper import _BaseMapper
16 from .volume_property import VolumeProperty
17
18
19 class Volume(Prop3D, _vtk.vtkVolume):
20 """Wrapper class for VTK volume.
21
22 This class represents a volume in a rendered scene. It inherits
23 functions related to the volume's position, orientation and origin
24 from Prop3D.
25
26 """
27
28 def __init__(self):
29 """Initialize volume."""
30 super().__init__()
31
32 @property
33 def mapper(self) -> _BaseMapper: # numpydoc ignore=RT01
34 """Return or set the mapper of the volume.
35
36 Examples
37 --------
38 Add a volume to a :class:`pyvista.Plotter` and get its mapper.
39
40 >>> import pyvista as pv
41 >>> vol = pv.ImageData(dimensions=(10, 10, 10))
42 >>> vol['scalars'] = 255 - vol.z * 25
43 >>> pl = pv.Plotter()
44 >>> actor = pl.add_volume(vol)
45 >>> actor.mapper.bounds
46 BoundsTuple(x_min = 0.0,
47 x_max = 9.0,
48 y_min = 0.0,
49 y_max = 9.0,
50 z_min = 0.0,
51 z_max = 9.0)
52
53 """
54 return self.GetMapper() # type: ignore[return-value]
55
56 @mapper.setter
57 def mapper(self, obj):
58 self.SetMapper(obj)
59
60 @property
61 def prop(self): # numpydoc ignore=RT01
62 """Return or set the property of this actor.
63
64 Examples
65 --------
66 Create an volume and get its properties.
67
68 >>> import pyvista as pv
69 >>> vol = pv.ImageData(dimensions=(10, 10, 10))
70 >>> vol['scalars'] = 255 - vol.z * 25
71 >>> pl = pv.Plotter()
72 >>> actor = pl.add_volume(vol)
73 >>> actor.prop.GetShade()
74 0
75
76 """
77 return self.GetProperty()
78
79 @prop.setter
80 def prop(self, obj: VolumeProperty):
81 self.SetProperty(obj)
82
83 @_deprecate_positional_args
84 def copy(self: Self, deep: bool = True) -> Self: # noqa: FBT001, FBT002
85 """Create a copy of this volume.
86
87 Parameters
88 ----------
89 deep : bool, default: True
90 Create a shallow or deep copy of the volume. A deep copy will have a
91 new property and mapper, while a shallow copy will use the mapper
92 and property of this volume.
93
94 Returns
95 -------
96 Volume
97 Deep or shallow copy of this volume.
98
99 Examples
100 --------
101 Create a volume of by adding it to a :class:`~pyvista.Plotter`
102 and then copy the volume.
103
104 >>> import pyvista as pv
105 >>> mesh = pv.Wavelet()
106 >>> pl = pv.Plotter()
107 >>> volume = pl.add_volume(mesh, diffuse=0.5)
108 >>> new_volume = volume.copy()
109
110 Change the copy's properties. A deep copy is made by default, so the original
111 volume is not affected.
112
113 >>> new_volume.prop.diffuse = 1.0
114 >>> new_volume.prop.diffuse
115 1.0
116
117 >>> volume.prop.diffuse
118 0.5
119
120 """
121 new_actor = type(self)()
122 if deep:
123 if self.mapper is not None:
124 new_actor.mapper = self.mapper.copy()
125 new_actor.prop = self.prop.copy()
126 else:
127 new_actor.ShallowCopy(self)
128 return new_actor