1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
|
"""Read/Write images using OpenCV.
Backend Library: `OpenCV <https://opencv.org/>`_
This plugin wraps OpenCV (also known as ``cv2``), a popular image processing
library. Currently, it exposes OpenCVs image reading capability (no video or GIF
support yet); however, this may be added in future releases.
Methods
-------
.. note::
Check the respective function for a list of supported kwargs and their
documentation.
.. autosummary::
:toctree:
OpenCVPlugin.read
OpenCVPlugin.iter
OpenCVPlugin.write
OpenCVPlugin.properties
OpenCVPlugin.metadata
Pixel Formats (Colorspaces)
---------------------------
OpenCV is known to process images in BGR; however, most of the python ecosystem
(in particular matplotlib and other pydata libraries) use the RGB. As such,
images are converted to RGB, RGBA, or grayscale (where applicable) by default.
"""
import warnings
from pathlib import Path
from typing import Any, Dict, List, Optional, Union
import cv2
import numpy as np
from ..core import Request
from ..core.request import URI_BYTES, InitializationError, IOMode
from ..core.v3_plugin_api import ImageProperties, PluginV3
from ..typing import ArrayLike
class OpenCVPlugin(PluginV3):
def __init__(self, request: Request) -> None:
super().__init__(request)
self.file_handle = request.get_local_filename()
if request._uri_type is URI_BYTES:
self.filename = "<bytes>"
else:
self.filename = request.raw_uri
mode = request.mode.io_mode
if mode == IOMode.read and not cv2.haveImageReader(self.file_handle):
raise InitializationError(f"OpenCV can't read `{self.filename}`.")
elif mode == IOMode.write and not cv2.haveImageWriter(self.file_handle):
raise InitializationError(f"OpenCV can't write to `{self.filename}`.")
def read(
self,
*,
index: int = None,
colorspace: Union[int, str] = None,
flags: int = cv2.IMREAD_COLOR,
) -> np.ndarray:
"""Read an image from the ImageResource.
Parameters
----------
index : int, Ellipsis
If int, read the index-th image from the ImageResource. If ``...``,
read all images from the ImageResource and stack them along a new,
prepended, batch dimension. If None (default), use ``index=0`` if
the image contains exactly one image and ``index=...`` otherwise.
colorspace : str, int
The colorspace to convert into after loading and before returning
the image. If None (default) keep grayscale images as is, convert
images with an alpha channel to ``RGBA`` and all other images to
``RGB``. If int, interpret ``colorspace`` as one of OpenCVs
`conversion flags
<https://docs.opencv.org/4.x/d8/d01/group__imgproc__color__conversions.html>`_
and use it for conversion. If str, convert the image into the given
colorspace. Possible string values are: ``"RGB"``, ``"BGR"``,
``"RGBA"``, ``"BGRA"``, ``"GRAY"``, ``"HSV"``, or ``"LAB"``.
flags : int
The OpenCV flag(s) to pass to the reader. Refer to the `OpenCV docs
<https://docs.opencv.org/4.x/d4/da8/group__imgcodecs.html#ga288b8b3da0892bd651fce07b3bbd3a56>`_
for details.
Returns
-------
ndimage : np.ndarray
The decoded image as a numpy array.
"""
if index is None:
n_images = cv2.imcount(self.file_handle, flags)
index = 0 if n_images == 1 else ...
if index is ...:
retval, img = cv2.imreadmulti(self.file_handle, flags=flags)
is_batch = True
else:
retval, img = cv2.imreadmulti(self.file_handle, index, 1, flags=flags)
is_batch = False
if retval is False:
raise ValueError(f"Could not read index `{index}` from `{self.filename}`.")
if img[0].ndim == 2:
in_colorspace = "GRAY"
out_colorspace = colorspace or "GRAY"
elif img[0].shape[-1] == 4:
in_colorspace = "BGRA"
out_colorspace = colorspace or "RGBA"
else:
in_colorspace = "BGR"
out_colorspace = colorspace or "RGB"
if isinstance(colorspace, int):
cvt_space = colorspace
elif in_colorspace == out_colorspace.upper():
cvt_space = None
else:
out_colorspace = out_colorspace.upper()
cvt_space = getattr(cv2, f"COLOR_{in_colorspace}2{out_colorspace}")
if cvt_space is not None:
img = np.stack([cv2.cvtColor(x, cvt_space) for x in img])
else:
img = np.stack(img)
return img if is_batch else img[0]
def iter(
self,
colorspace: Union[int, str] = None,
flags: int = cv2.IMREAD_COLOR,
) -> np.ndarray:
"""Yield images from the ImageResource.
Parameters
----------
colorspace : str, int
The colorspace to convert into after loading and before returning
the image. If None (default) keep grayscale images as is, convert
images with an alpha channel to ``RGBA`` and all other images to
``RGB``. If int, interpret ``colorspace`` as one of OpenCVs
`conversion flags
<https://docs.opencv.org/4.x/d8/d01/group__imgproc__color__conversions.html>`_
and use it for conversion. If str, convert the image into the given
colorspace. Possible string values are: ``"RGB"``, ``"BGR"``,
``"RGBA"``, ``"BGRA"``, ``"GRAY"``, ``"HSV"``, or ``"LAB"``.
flags : int
The OpenCV flag(s) to pass to the reader. Refer to the `OpenCV docs
<https://docs.opencv.org/4.x/d4/da8/group__imgcodecs.html#ga288b8b3da0892bd651fce07b3bbd3a56>`_
for details.
Yields
------
ndimage : np.ndarray
The decoded image as a numpy array.
"""
for idx in range(cv2.imcount(self.file_handle)):
yield self.read(index=idx, flags=flags, colorspace=colorspace)
def write(
self,
ndimage: Union[ArrayLike, List[ArrayLike]],
is_batch: bool = False,
params: List[int] = None,
) -> Optional[bytes]:
"""Save an ndimage in the ImageResource.
Parameters
----------
ndimage : ArrayLike, List[ArrayLike]
The image data that will be written to the file. It is either a
single image, a batch of images, or a list of images.
is_batch : bool
If True, the provided ndimage is a batch of images. If False (default), the
provided ndimage is a single image. If the provided ndimage is a list of images,
this parameter has no effect.
params : List[int]
A list of parameters that will be passed to OpenCVs imwrite or
imwritemulti functions. Possible values are documented in the
`OpenCV documentation
<https://docs.opencv.org/4.x/d4/da8/group__imgcodecs.html#gabbc7ef1aa2edfaa87772f1202d67e0ce>`_.
Returns
-------
encoded_image : bytes, None
If the ImageResource is ``"<bytes>"`` the call to write returns the
encoded image as a bytes string. Otherwise it returns None.
"""
if isinstance(ndimage, list):
ndimage = np.stack(ndimage, axis=0)
elif not is_batch:
ndimage = ndimage[None, ...]
if ndimage[0].ndim == 2:
n_channels = 1
else:
n_channels = ndimage[0].shape[-1]
if n_channels == 1:
ndimage_cv2 = [x for x in ndimage]
elif n_channels == 4:
ndimage_cv2 = [cv2.cvtColor(x, cv2.COLOR_RGBA2BGRA) for x in ndimage]
else:
ndimage_cv2 = [cv2.cvtColor(x, cv2.COLOR_RGB2BGR) for x in ndimage]
retval = cv2.imwritemulti(self.file_handle, ndimage_cv2, params)
if retval is False:
# not sure what scenario would trigger this, but
# it can occur theoretically.
raise IOError("OpenCV failed to write.") # pragma: no cover
if self.request._uri_type == URI_BYTES:
return Path(self.file_handle).read_bytes()
def properties(
self,
index: int = None,
colorspace: Union[int, str] = None,
flags: int = cv2.IMREAD_COLOR,
) -> ImageProperties:
"""Standardized image metadata.
Parameters
----------
index : int, Ellipsis
If int, get the properties of the index-th image in the
ImageResource. If ``...``, get the properties of the image stack
that contains all images. If None (default), use ``index=0`` if the
image contains exactly one image and ``index=...`` otherwise.
colorspace : str, int
The colorspace to convert into after loading and before returning
the image. If None (default) keep grayscale images as is, convert
images with an alpha channel to ``RGBA`` and all other images to
``RGB``. If int, interpret ``colorspace`` as one of OpenCVs
`conversion flags
<https://docs.opencv.org/4.x/d8/d01/group__imgproc__color__conversions.html>`_
and use it for conversion. If str, convert the image into the given
colorspace. Possible string values are: ``"RGB"``, ``"BGR"``,
``"RGBA"``, ``"BGRA"``, ``"GRAY"``, ``"HSV"``, or ``"LAB"``.
flags : int
The OpenCV flag(s) to pass to the reader. Refer to the `OpenCV docs
<https://docs.opencv.org/4.x/d4/da8/group__imgcodecs.html#ga288b8b3da0892bd651fce07b3bbd3a56>`_
for details.
Returns
-------
props : ImageProperties
A dataclass filled with standardized image metadata.
Notes
-----
Reading properties with OpenCV involves decoding pixel data, because
OpenCV doesn't provide a direct way to access metadata.
"""
if index is None:
n_images = cv2.imcount(self.file_handle, flags)
is_batch = n_images > 1
elif index is Ellipsis:
n_images = cv2.imcount(self.file_handle, flags)
is_batch = True
else:
is_batch = False
# unfortunately, OpenCV doesn't allow reading shape without reading pixel data
if is_batch:
img = self.read(index=0, flags=flags, colorspace=colorspace)
return ImageProperties(
shape=(n_images, *img.shape),
dtype=img.dtype,
n_images=n_images,
is_batch=True,
)
img = self.read(index=index, flags=flags, colorspace=colorspace)
return ImageProperties(shape=img.shape, dtype=img.dtype, is_batch=False)
def metadata(
self, index: int = None, exclude_applied: bool = True
) -> Dict[str, Any]:
"""Format-specific metadata.
.. warning::
OpenCV does not support reading metadata. When called, this function
will raise a ``NotImplementedError``.
Parameters
----------
index : int
This parameter has no effect.
exclude_applied : bool
This parameter has no effect.
"""
warnings.warn("OpenCV does not support reading metadata.", UserWarning)
return dict()
|
