Debian Codegraph @

pyvista/plotting/render_passes.py

raw
1 """Render passes module for PyVista."""
2
3 from __future__ import annotations
4
5 import weakref
6
7 from pyvista import _vtk
8 from pyvista._deprecate_positional_args import _deprecate_positional_args
9 from pyvista.core.utilities.misc import _NoNewAttrMixin
10
11 # The order of both the pre and post-passes matters.
12 PRE_PASS = [
13 'vtkEDLShading',
14 ]
15
16 POST_PASS = [
17 'vtkDepthOfFieldPass',
18 'vtkGaussianBlurPass',
19 'vtkOpenGLFXAAPass',
20 'vtkSSAOPass',
21 'vtkSSAAPass', # should be last
22 ]
23
24
25 class RenderPasses(_NoNewAttrMixin):
26 """Class to support multiple render passes for a renderer.
27
28 Notes
29 -----
30 Passes are organized here as "primary" (:vtk:`vtkOpenGLRenderPass`) that act
31 within the renderer and "post-processing" (:vtk:`vtkImageProcessingPass`) passes,
32 which act on the image generated from the renderer.
33
34 The primary passes are added as part of a :vtk:`vtkRenderPassCollection` or
35 are "stacked", while the post-processing passes are added as a final pass
36 to the rendered image.
37
38 Parameters
39 ----------
40 renderer : :vtk:`vtkRenderer`
41 Renderer to initialize render passes for.
42
43 """
44
45 def __init__(self, renderer):
46 """Initialize render passes."""
47 self._renderer_ref = weakref.ref(renderer)
48
49 self._passes = {}
50 self._fxaa_pass = None
51 self._shadow_map_pass = None
52 self._edl_pass = None
53 self._dof_pass = None
54 self._ssaa_pass = None
55 self._ssao_pass = None
56 self._blur_passes = []
57 self.__pass_collection = None
58 self.__seq_pass = None
59 self.__camera_pass = None
60
61 @property
62 def _pass_collection(self):
63 """Initialize (when necessary) the pass collection and return it.
64
65 This lets us lazily generate the pass collection only when we need it
66 rather than at initialization of the class.
67
68 """
69 if self.__pass_collection is None:
70 self._init_passes()
71 return self.__pass_collection
72
73 @property
74 def _seq_pass(self):
75 """Initialize (when necessary) the sequence collection and return it.
76
77 This lets us lazily generate the sequence collection only when we need it
78 rather than at initialization of the class.
79
80 """
81 if self.__seq_pass is None:
82 self._init_passes()
83 return self.__seq_pass
84
85 @property
86 def _camera_pass(self):
87 """Initialize (when necessary) the camera pass and return it.
88
89 This lets us lazily generate the camera pass only when we need it
90 rather than at initialization of the class.
91
92 """
93 if self.__camera_pass is None:
94 self._init_passes()
95 return self.__camera_pass
96
97 def _init_passes(self):
98 """Initialize the renderer's standard passes."""
99 # simulate the standard VTK rendering passes and put them in a sequence
100 self.__pass_collection = _vtk.vtkRenderPassCollection()
101 self.__pass_collection.AddItem(_vtk.vtkRenderStepsPass())
102
103 self.__seq_pass = _vtk.vtkSequencePass()
104 self.__seq_pass.SetPasses(self._pass_collection)
105
106 # Make the sequence the delegate of a camera pass.
107 self.__camera_pass = _vtk.vtkCameraPass()
108 self.__camera_pass.SetDelegatePass(self._seq_pass)
109
110 @property
111 def _renderer(self):
112 """Return the renderer."""
113 if self._renderer_ref is not None:
114 return self._renderer_ref()
115 return None # type: ignore[unreachable]
116
117 def deep_clean(self):
118 """Delete all render passes."""
119 if self._renderer is not None:
120 self._renderer.SetPass(None)
121 self._renderer_ref = None # type: ignore[assignment]
122 if self.__seq_pass is not None:
123 self.__seq_pass.SetPasses(None)
124 self.__seq_pass = None
125 self.__pass_collection = None
126 self.__camera_pass = None
127 self._passes = {}
128 self._shadow_map_pass = None
129 self._edl_pass = None
130 self._dof_pass = None
131 self._ssaa_pass = None
132 self._ssao_pass = None
133 self._blur_passes = []
134
135 def enable_edl_pass(self):
136 """Enable the EDL pass.
137
138 Returns
139 -------
140 :vtk:`vtkEDLShading`
141 The enabled EDL pass.
142
143 """
144 if self._edl_pass is not None:
145 return None
146 self._edl_pass = _vtk.vtkEDLShading()
147 self._add_pass(self._edl_pass)
148 return self._edl_pass
149
150 def disable_edl_pass(self):
151 """Disable the EDL pass."""
152 if self._edl_pass is None:
153 return
154 self._remove_pass(self._edl_pass)
155 self._edl_pass = None
156
157 def add_blur_pass(self):
158 """Add a :vtk:`vtkGaussianBlurPass` pass.
159
160 This is a :vtk:`vtkImageProcessingPass` and delegates to the last pass.
161
162 Returns
163 -------
164 :vtk:`vtkGaussianBlurPass`
165 The added Gaussian blur pass.
166
167 """
168 blur_pass = _vtk.vtkGaussianBlurPass()
169 self._add_pass(blur_pass)
170 self._blur_passes.append(blur_pass)
171 return blur_pass
172
173 def remove_blur_pass(self):
174 """Remove a single :vtk:`vtkGaussianBlurPass` pass."""
175 if self._blur_passes:
176 # order of the blur passes does not matter
177 self._remove_pass(self._blur_passes.pop())
178
179 def enable_shadow_pass(self):
180 """Enable shadow pass.
181
182 Returns
183 -------
184 :vtk:`vtkShadowMapPass`
185 The enabled shadow pass.
186
187 """
188 # shadow pass can be directly added to the base pass collection
189 if self._shadow_map_pass is not None:
190 return None
191 self._shadow_map_pass = _vtk.vtkShadowMapPass()
192 self._pass_collection.AddItem(self._shadow_map_pass.GetShadowMapBakerPass())
193 self._pass_collection.AddItem(self._shadow_map_pass)
194 self._update_passes()
195 return self._shadow_map_pass
196
197 def disable_shadow_pass(self):
198 """Disable shadow pass."""
199 if self._shadow_map_pass is None:
200 return
201 self._pass_collection.RemoveItem(self._shadow_map_pass.GetShadowMapBakerPass())
202 self._pass_collection.RemoveItem(self._shadow_map_pass)
203 self._update_passes()
204
205 @_deprecate_positional_args
206 def enable_depth_of_field_pass(self, automatic_focal_distance: bool = True): # noqa: FBT001, FBT002
207 """Enable the depth of field pass.
208
209 Parameters
210 ----------
211 automatic_focal_distance : bool, default: True
212 If ``True``, the depth of field effect will automatically compute
213 the focal distance. If ``False``, the user must specify the distance.
214
215 Returns
216 -------
217 :vtk:`vtkDepthOfFieldPass`
218 The enabled depth of field pass.
219
220 """
221 if self._dof_pass is not None:
222 return None
223
224 if self._ssao_pass is not None:
225 msg = 'Depth of field pass is incompatible with the SSAO pass.'
226 raise RuntimeError(msg)
227
228 self._dof_pass = _vtk.vtkDepthOfFieldPass()
229 self._dof_pass.SetAutomaticFocalDistance(automatic_focal_distance)
230 self._add_pass(self._dof_pass)
231 return self._dof_pass
232
233 def disable_depth_of_field_pass(self):
234 """Disable the depth of field pass."""
235 if self._dof_pass is None:
236 return
237 self._remove_pass(self._dof_pass)
238 self._dof_pass = None
239
240 @_deprecate_positional_args
241 def enable_ssao_pass( # noqa: PLR0917
242 self, radius, bias, kernel_size, blur
243 ):
244 """Enable the screen space ambient occlusion pass.
245
246 Parameters
247 ----------
248 radius : float
249 Radius of occlusion generation.
250 bias : float
251 Bias to adjust the occlusion generation.
252 kernel_size : int
253 Size of the kernel for occlusion generation.
254 blur : bool
255 If ``True``, the pass uses a blur stage.
256
257 Returns
258 -------
259 :vtk:`vtkSSAOPass`
260 The enabled screen space ambient occlusion pass.
261
262 """
263 if self._dof_pass is not None:
264 msg = 'SSAO pass is incompatible with the depth of field pass.'
265 raise RuntimeError(msg)
266
267 if self._ssao_pass is not None:
268 return None
269 self._ssao_pass = _vtk.vtkSSAOPass()
270 self._ssao_pass.SetRadius(radius)
271 self._ssao_pass.SetBias(bias)
272 self._ssao_pass.SetKernelSize(kernel_size)
273 self._ssao_pass.SetBlur(blur)
274 self._add_pass(self._ssao_pass)
275 return self._ssao_pass
276
277 def disable_ssao_pass(self):
278 """Disable the screen space ambient occlusion pass."""
279 if self._ssao_pass is None:
280 return
281 self._remove_pass(self._ssao_pass)
282 self._ssao_pass = None
283
284 def enable_ssaa_pass(self):
285 """Enable super-sample anti-aliasing pass.
286
287 Returns
288 -------
289 :vtk:`vtkSSAAPass`
290 The enabled super-sample anti-aliasing pass.
291
292 """
293 if self._ssaa_pass is not None:
294 return None
295 self._ssaa_pass = _vtk.vtkSSAAPass()
296 self._add_pass(self._ssaa_pass)
297 return self._ssaa_pass
298
299 def disable_ssaa_pass(self):
300 """Disable super-sample anti-aliasing pass."""
301 if self._ssaa_pass is None:
302 return
303 self._remove_pass(self._ssaa_pass)
304 self._ssaa_pass = None
305
306 def _update_passes(self):
307 """Reassemble pass delegation."""
308 if hasattr(self._renderer, '_closed') and self._renderer._closed:
309 msg = 'The renderer has been closed.'
310 raise RuntimeError(msg)
311
312 current_pass = self._camera_pass
313 for class_name in PRE_PASS + POST_PASS:
314 if class_name in self._passes:
315 for render_pass in self._passes[class_name]:
316 render_pass.SetDelegatePass(current_pass)
317 current_pass = render_pass
318
319 # reset to the default rendering if no special passes have been added
320 if current_pass is self._camera_pass and self._shadow_map_pass is None:
321 self._renderer.SetPass(None)
322 else:
323 self._renderer.SetPass(current_pass)
324
325 def _add_pass(self, render_pass):
326 """Add a render pass."""
327 class_name = render_pass.GetClassName()
328
329 if class_name in PRE_PASS and render_pass in self._passes:
330 return
331
332 if class_name not in self._passes:
333 self._passes[class_name] = [render_pass]
334 else:
335 self._passes[class_name].append(render_pass)
336
337 self._update_passes()
338
339 def _remove_pass(self, render_pass):
340 """Remove a pass.
341
342 Remove a pass and reassemble the pass ordering.
343
344 """
345 class_name = render_pass.GetClassName()
346
347 if class_name not in self._passes: # pragma: no cover
348 return
349 else:
350 self._passes[class_name].remove(render_pass)
351 if not self._passes[class_name]:
352 self._passes.pop(class_name)
353
354 self._update_passes()