| 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]) |