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
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
|
from pathlib import Path
import numpy as np
from ..config import known_extensions
from .request import InitializationError, IOMode
from .v3_plugin_api import ImageProperties, PluginV3
def _legacy_default_index(format):
if format._name == "FFMPEG":
index = Ellipsis
elif format._name == "GIF-PIL":
index = Ellipsis
else:
index = 0
return index
class LegacyPlugin(PluginV3):
"""A plugin to make old (v2.9) plugins compatible with v3.0
.. depreciated:: 2.9
`legacy_get_reader` will be removed in a future version of imageio.
`legacy_get_writer` will be removed in a future version of imageio.
This plugin is a wrapper around the old FormatManager class and exposes
all the old plugins via the new API. On top of this it has
``legacy_get_reader`` and ``legacy_get_writer`` methods to allow using
it with the v2.9 API.
Methods
-------
read(index=None, **kwargs)
Read the image at position ``index``.
write(image, **kwargs)
Write image to the URI.
iter(**kwargs)
Iteratively yield images from the given URI.
get_meta(index=None)
Return the metadata for the image at position ``index``.
legacy_get_reader(**kwargs)
Returns the v2.9 image reader. (depreciated)
legacy_get_writer(**kwargs)
Returns the v2.9 image writer. (depreciated)
Examples
--------
>>> import imageio.v3 as iio
>>> with iio.imopen("/path/to/image.tiff", "r", legacy_mode=True) as file:
>>> reader = file.legacy_get_reader() # depreciated
>>> for im in file.iter():
>>> print(im.shape)
"""
def __init__(self, request, legacy_plugin):
"""Instantiate a new Legacy Plugin
Parameters
----------
uri : {str, pathlib.Path, bytes, file}
The resource to load the image from, e.g. a filename, pathlib.Path,
http address or file object, see the docs for more info.
legacy_plugin : Format
The (legacy) format to use to interface with the URI.
"""
self._request = request
self._format = legacy_plugin
source = (
"<bytes>"
if isinstance(self._request.raw_uri, bytes)
else self._request.raw_uri
)
if self._request.mode.io_mode == IOMode.read:
if not self._format.can_read(request):
raise InitializationError(
f"`{self._format.name}`" f" can not read `{source}`."
)
else:
if not self._format.can_write(request):
raise InitializationError(
f"`{self._format.name}`" f" can not write to `{source}`."
)
def legacy_get_reader(self, **kwargs):
"""legacy_get_reader(**kwargs)
a utility method to provide support vor the V2.9 API
Parameters
----------
kwargs : ...
Further keyword arguments are passed to the reader. See :func:`.help`
to see what arguments are available for a particular format.
"""
# Note: this will break thread-safety
self._request._kwargs = kwargs
# safeguard for DICOM plugin reading from folders
try:
assert Path(self._request.filename).is_dir()
except OSError:
pass # not a valid path on this OS
except AssertionError:
pass # not a folder
else:
return self._format.get_reader(self._request)
self._request.get_file().seek(0)
return self._format.get_reader(self._request)
def read(self, *, index=None, **kwargs):
"""
Parses the given URI and creates a ndarray from it.
Parameters
----------
index : {integer, None}
If the URI contains a list of ndimages return the index-th
image. If None, stack all images into an ndimage along the
0-th dimension (equivalent to np.stack(imgs, axis=0)).
kwargs : ...
Further keyword arguments are passed to the reader. See
:func:`.help` to see what arguments are available for a particular
format.
Returns
-------
ndimage : np.ndarray
A numpy array containing the decoded image data.
"""
if index is None:
index = _legacy_default_index(self._format)
if index is Ellipsis:
img = np.stack([im for im in self.iter(**kwargs)])
return img
reader = self.legacy_get_reader(**kwargs)
return reader.get_data(index)
def legacy_get_writer(self, **kwargs):
"""legacy_get_writer(**kwargs)
Returns a :class:`.Writer` object which can be used to write data
and meta data to the specified file.
Parameters
----------
kwargs : ...
Further keyword arguments are passed to the writer. See :func:`.help`
to see what arguments are available for a particular format.
"""
# Note: this will break thread-safety
self._request._kwargs = kwargs
return self._format.get_writer(self._request)
def write(self, ndimage, *, is_batch=None, metadata=None, **kwargs):
"""
Write an ndimage to the URI specified in path.
If the URI points to a file on the current host and the file does not
yet exist it will be created. If the file exists already, it will be
appended if possible; otherwise, it will be replaced.
Parameters
----------
ndimage : numpy.ndarray
The ndimage or list of ndimages to write.
is_batch : bool
If True, treat the supplied ndimage as a batch of images. If False,
treat the supplied ndimage as a single image. If None, try to
determine ``is_batch`` from the ndimage's shape and ndim.
metadata : dict
The metadata passed to write alongside the image.
kwargs : ...
Further keyword arguments are passed to the writer. See
:func:`.help` to see what arguments are available for a
particular format.
Returns
-------
buffer : bytes
When writing to the special target "<bytes>", this function will
return the encoded image data as a bytes string. Otherwise it
returns None.
Notes
-----
Automatically determining ``is_batch`` may fail for some images due to
shape aliasing. For example, it may classify a channel-first color image
as a batch of gray images. In most cases this automatic deduction works
fine (it has for almost a decade), but if you do have one of those edge
cases (or are worried that you might) consider explicitly setting
``is_batch``.
"""
if is_batch or isinstance(ndimage, (list, tuple)):
pass # ndimage is list of images
elif is_batch is False:
ndimage = [ndimage]
else:
# Write the largest possible block by guessing the meaning of each
# dimension from the shape/ndim and then checking if any batch
# dimensions are left.
ndimage = np.asanyarray(ndimage)
batch_dims = ndimage.ndim
# two spatial dimensions
batch_dims = max(batch_dims - 2, 0)
# packed (channel-last) image
if ndimage.ndim >= 3 and ndimage.shape[-1] < 5:
batch_dims = max(batch_dims - 1, 0)
# format supports volumetric images
ext_infos = known_extensions.get(self._request.extension, list())
for ext_info in ext_infos:
if self._format.name in ext_info.priority and ext_info.volume_support:
batch_dims = max(batch_dims - 1, 0)
break
if batch_dims == 0:
ndimage = [ndimage]
with self.legacy_get_writer(**kwargs) as writer:
for image in ndimage:
image = np.asanyarray(image)
if image.ndim < 2:
raise ValueError(
"The image must have at least two spatial dimensions."
)
if not np.issubdtype(image.dtype, np.number) and not np.issubdtype(
image.dtype, bool
):
raise ValueError(
f"All images have to be numeric, and not `{image.dtype}`."
)
writer.append_data(image, metadata)
return writer.request.get_result()
def iter(self, **kwargs):
"""Iterate over a list of ndimages given by the URI
Parameters
----------
kwargs : ...
Further keyword arguments are passed to the reader. See
:func:`.help` to see what arguments are available for a particular
format.
"""
reader = self.legacy_get_reader(**kwargs)
for image in reader:
yield image
def properties(self, index=None):
"""Standardized ndimage metadata.
Parameters
----------
index : int
The index of the ndimage for which to return properties. If the
index is out of bounds a ``ValueError`` is raised. If ``None``,
return the properties for the ndimage stack. If this is impossible,
e.g., due to shape mismatch, an exception will be raised.
Returns
-------
properties : ImageProperties
A dataclass filled with standardized image metadata.
"""
if index is None:
index = _legacy_default_index(self._format)
# for backwards compatibility ... actually reads pixel data :(
if index is Ellipsis:
image = self.read(index=0)
n_images = self.legacy_get_reader().get_length()
return ImageProperties(
shape=(n_images, *image.shape),
dtype=image.dtype,
n_images=n_images,
is_batch=True,
)
image = self.read(index=index)
return ImageProperties(
shape=image.shape,
dtype=image.dtype,
is_batch=False,
)
def get_meta(self, *, index=None):
"""Read ndimage metadata from the URI
Parameters
----------
index : {integer, None}
If the URI contains a list of ndimages return the metadata
corresponding to the index-th image. If None, behavior depends on
the used api
Legacy-style API: return metadata of the first element (index=0)
New-style API: Behavior depends on the used Plugin.
Returns
-------
metadata : dict
A dictionary of metadata.
"""
return self.metadata(index=index, exclude_applied=False)
def metadata(self, index=None, exclude_applied: bool = True):
"""Format-Specific ndimage metadata.
Parameters
----------
index : int
The index of the ndimage to read. If the index is out of bounds a
``ValueError`` is raised. If ``None``, global metadata is returned.
exclude_applied : bool
This parameter exists for compatibility and has no effect. Legacy
plugins always report all metadata they find.
Returns
-------
metadata : dict
A dictionary filled with format-specific metadata fields and their
values.
"""
if index is None:
index = _legacy_default_index(self._format)
return self.legacy_get_reader().get_meta_data(index=index)
def __del__(self) -> None:
pass
# turns out we can't close the file here for LegacyPlugin
# because it would break backwards compatibility
# with legacy_get_writer and legacy_get_reader
# self._request.finish()
|
