Debian Codegraph @

pyvista/plotting/utilities/regression.py

raw
1 """Image regression module."""
2
3 from __future__ import annotations
4
5 from pathlib import Path
6 from typing import TYPE_CHECKING
7 from typing import TypeAlias
8 from typing import cast
9
10 import numpy as np
11
12 import pyvista as pv
13 from pyvista import _vtk
14 from pyvista._deprecate_positional_args import _deprecate_positional_args
15 from pyvista.core.utilities.arrays import point_array
16 from pyvista.core.utilities.helpers import wrap
17
18 if TYPE_CHECKING:
19 from pyvista import ImageData
20 from pyvista.core._typing_core import NumpyArray
21 from pyvista.plotting import Plotter
22
23 ImageCompareType: TypeAlias = str | Path | np.ndarray | Plotter | _vtk.vtkImageData
24
25
26 def remove_alpha(img: _vtk.vtkImageData) -> ImageData:
27 """Remove the alpha channel from a :vtk:`vtkImageData`.
28
29 Parameters
30 ----------
31 img : :vtk:`vtkImageData`
32 The input image data with an alpha channel.
33
34 Returns
35 -------
36 ImageData
37 The output image data with the alpha channel removed.
38
39 """
40 ec = _vtk.vtkImageExtractComponents()
41 ec.SetComponents(0, 1, 2)
42 ec.SetInputData(img)
43 ec.Update()
44 vtk_image: _vtk.vtkImageData = ec.GetOutput()
45 return pv.wrap(vtk_image)
46
47
48 def wrap_image_array(arr):
49 """Wrap a numpy array as a pyvista.ImageData.
50
51 Parameters
52 ----------
53 arr : np.ndarray
54 A numpy array of shape (X, Y, (3 or 4)) and dtype ``np.uint8``. For
55 example, an array of shape ``(768, 1024, 3)``.
56
57 Raises
58 ------
59 ValueError
60 If the input array does not have 3 dimensions, the third dimension of
61 the input array is not 3 or 4, or the input array is not of type
62 ``np.uint8``.
63
64 Returns
65 -------
66 pyvista.ImageData
67 A PyVista ImageData object with the wrapped array data.
68
69 """
70 if arr.ndim != 3:
71 msg = 'Expecting a X by Y by (3 or 4) array'
72 raise ValueError(msg)
73 if arr.shape[2] not in [3, 4]:
74 msg = 'Expecting a X by Y by (3 or 4) array'
75 raise ValueError(msg)
76 if arr.dtype != np.uint8:
77 msg = 'Expecting a np.uint8 array'
78 raise ValueError(msg)
79
80 img = _vtk.vtkImageData()
81 img.SetDimensions(arr.shape[1], arr.shape[0], 1)
82 wrap_img = pv.wrap(img)
83 wrap_img.point_data['PNGImage'] = arr[::-1].reshape(-1, arr.shape[2])
84 return wrap_img
85
86
87 def run_image_filter(imfilter: _vtk.vtkWindowToImageFilter) -> NumpyArray[float]:
88 """Run a :vtk:`vtkWindowToImageFilter` and get output as array.
89
90 Parameters
91 ----------
92 imfilter : :vtk:`vtkWindowToImageFilter`
93 The :vtk:`vtkWindowToImageFilter` instance to be processed.
94
95 Notes
96 -----
97 An empty array will be returned if an image cannot be extracted.
98
99 Returns
100 -------
101 numpy.ndarray
102 An array containing the filtered image data. The shape of the array
103 is given by (height, width, -1) where height and width are the
104 dimensions of the image.
105
106 """
107 # Update filter and grab pixels
108 imfilter.Modified()
109 imfilter.Update()
110 image = cast('ImageData | None', wrap(imfilter.GetOutput()))
111 if image is None:
112 return np.empty((0, 0, 0))
113 img_size = image.dimensions
114 img_array = cast('NumpyArray[float]', point_array(image, 'ImageScalars'))
115 # Reshape and flip vertically (VTK stores rows bottom-up). The flip via
116 # ``[::-1]`` produces a negative row stride, so wrap in
117 # ``ascontiguousarray`` to materialize a packed C-contiguous buffer that
118 # downstream consumers (image libs, encoders) can use without an implicit
119 # per-pixel copy.
120 tgt_size = (img_size[1], img_size[0], -1)
121 return np.ascontiguousarray(img_array.reshape(tgt_size)[::-1])
122
123
124 @_deprecate_positional_args(allowed=['render_window'])
125 def image_from_window( # noqa: PLR0917
126 render_window,
127 as_vtk: bool = False, # noqa: FBT001, FBT002
128 ignore_alpha: bool = False, # noqa: FBT001, FBT002
129 scale=1,
130 ):
131 """Extract the image from the render window as an array.
132
133 Parameters
134 ----------
135 render_window : :vtk:`vtkRenderWindow`
136 The render window to extract the image from.
137
138 as_vtk : bool, default: False
139 If set to True, the image will be returned as a VTK object.
140
141 ignore_alpha : bool, default: False
142 If set to True, the image will be returned in RGB format,
143 otherwise, it will be returned in RGBA format.
144
145 scale : int, default: 1
146 The scaling factor of the extracted image. The default value is 1
147 which means that no scaling is applied.
148
149 Returns
150 -------
151 output : ndarray | :vtk:`vtkImageData`
152 The image as an array or as a VTK object depending on the ``as_vtk`` parameter.
153
154 """
155 off = not render_window.GetInteractor().GetEnableRender()
156 if off:
157 render_window.GetInteractor().EnableRenderOn()
158 imfilter = _vtk.vtkWindowToImageFilter()
159 imfilter.SetInput(render_window)
160 imfilter.SetScale(scale)
161 imfilter.FixBoundaryOn()
162 imfilter.ReadFrontBufferOff()
163 imfilter.ShouldRerenderOff()
164 if ignore_alpha:
165 imfilter.SetInputBufferTypeToRGB()
166 else:
167 imfilter.SetInputBufferTypeToRGBA()
168 imfilter.ReadFrontBufferOn()
169 data = run_image_filter(imfilter)
170 if off:
171 # Critical for Trame and other offscreen tools
172 render_window.GetInteractor().EnableRenderOff()
173 if as_vtk:
174 return wrap_image_array(data)
175 return data
176
177
178 @_deprecate_positional_args(allowed=['im1', 'im2'])
179 def compare_images( # noqa: PLR0917
180 im1: ImageCompareType,
181 im2: ImageCompareType,
182 threshold: int = 1,
183 use_vtk: bool = True, # noqa: FBT001, FBT002
184 ) -> float:
185 """Compare two different images of the same size.
186
187 Parameters
188 ----------
189 im1 : str | pathlib.Path | numpy.ndarray | pyvista.Plotter | :vtk:`vtkImageData`
190 Path, :class:`pyvista.Plotter`, numpy array representing the output of
191 a render window, or :vtk:`vtkImageData`.
192
193 im2 : str | pathlib.Path | numpy.ndarray | pyvista.Plotter | :vtk:`vtkImageData`
194 Path, :class:`pyvista.Plotter`, numpy array representing the output of
195 a render window, or :vtk:`vtkImageData`.
196
197 threshold : int, default: 1
198 Threshold tolerance for pixel differences. This should be
199 greater than 0, otherwise it will always return an error, even
200 on identical images.
201
202 use_vtk : bool, default: True
203 When disabled, computes the mean pixel error over the entire
204 image using numpy. The difference between pixel is calculated
205 for each RGB channel, summed, and then divided by the number
206 of pixels. This is faster than using
207 :vtk:`vtkImageDifference` but potentially less accurate.
208
209 Returns
210 -------
211 float
212 Total error between the images if using ``use_vtk=True``, and
213 the mean pixel error when ``use_vtk=False``.
214
215 Examples
216 --------
217 Compare two active plotters.
218
219 >>> import pyvista as pv
220 >>> pl1 = pv.Plotter()
221 >>> _ = pl1.add_mesh(pv.Sphere(), smooth_shading=True)
222 >>> pl2 = pv.Plotter()
223 >>> _ = pl2.add_mesh(pv.Sphere(), smooth_shading=False)
224 >>> error = pv.compare_images(pl1, pl2)
225
226 Compare images from file.
227
228 >>> import pyvista as pv
229 >>> img1 = pv.read('img1.png') # doctest:+SKIP
230 >>> img2 = pv.read('img2.png') # doctest:+SKIP
231 >>> pv.compare_images(img1, img2) # doctest:+SKIP
232
233 """
234 from pyvista import ImageData # noqa: PLC0415
235 from pyvista import Plotter # noqa: PLC0415
236 from pyvista import read # noqa: PLC0415
237 from pyvista import wrap # noqa: PLC0415
238
239 def to_img(img: ImageCompareType) -> ImageData:
240 if isinstance(img, ImageData):
241 return img
242 elif isinstance(img, _vtk.vtkImageData): # pragma: no cover
243 return wrap(img)
244 elif isinstance(img, (str, Path)):
245 return read(img, cls=ImageData)
246 elif isinstance(img, np.ndarray):
247 return wrap_image_array(img)
248 elif isinstance(img, Plotter):
249 if img._first_time: # must be rendered first else segfault
250 img._on_first_render_request()
251 img.render()
252 if img.render_window is None:
253 msg = 'Unable to extract image from Plotter as it has already been closed.'
254 raise RuntimeError(msg)
255 return image_from_window(img.render_window, as_vtk=True, ignore_alpha=True)
256 else:
257 msg = (
258 f'Unsupported data type {type(img)}. Should be '
259 'either a np.ndarray, pyvista.Plotter, or vtk.vtkImageData'
260 )
261 raise TypeError(msg)
262
263 im1_proc = remove_alpha(to_img(im1))
264 im2_proc = remove_alpha(to_img(im2))
265
266 if im1_proc.dimensions != im2_proc.dimensions:
267 msg = 'Input images are not the same size.'
268 raise RuntimeError(msg)
269
270 if use_vtk:
271 img_diff = _vtk.vtkImageDifference()
272 img_diff.SetThreshold(threshold)
273 img_diff.SetInputData(im1_proc)
274 img_diff.SetImageData(im2_proc)
275 img_diff.AllowShiftOff() # vastly increases compute time when enabled
276 # img_diff.AveragingOff() # increases compute time
277 img_diff.Update()
278 return img_diff.GetThresholdedError()
279
280 # unlikely but possible
281 if im1_proc.active_scalars is None: # pragma: no cover
282 msg = 'Missing active scalars in first image'
283 raise RuntimeError(msg)
284 if im2_proc.active_scalars is None: # pragma: no cover
285 msg = 'Missing active scalars in second image'
286 raise RuntimeError(msg)
287
288 # otherwise, simply compute the mean pixel difference
289 diff = np.abs(im1_proc.active_scalars - im2_proc.active_scalars)
290 return float(np.sum(diff) / im1_proc.active_scalars.shape[0])