Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1import numpy as np
3from .core.imopen import imopen
6def imread(uri, *, index=None, plugin=None, extension=None, format_hint=None, **kwargs):
7 """Read an ndimage from a URI.
9 Opens the given URI and reads an ndimage from it. The exact behavior
10 depends on both the file type and plugin used to open the file. To learn
11 about the exact behavior, check the documentation of the relevant plugin.
12 Typically, imread attempts to read all data stored in the URI.
14 Parameters
15 ----------
16 uri : {str, pathlib.Path, bytes, file}
17 The resource to load the image from, e.g. a filename, pathlib.Path,
18 http address or file object, see the docs for more info.
19 index : {int, Ellipsis, None}
20 If the ImageResource contains multiple ndimages, and index is an
21 integer, select the index-th ndimage from among them and return it. If
22 index is an ellipsis (...), read all ndimages in the file and stack them
23 along a new batch dimension. If index is None, let the plugin decide.
24 plugin : {str, None}
25 The plugin to use. If set to None (default) imread will perform a
26 search for a matching plugin. If not None, this takes priority over
27 the provided format hint (if present).
28 extension : str
29 If not None, treat the provided ImageResource as if it had the given
30 extension. This affects the order in which backends are considered.
31 format_hint : str
32 Deprecated. Use `extension` instead.
33 **kwargs :
34 Additional keyword arguments will be passed to the plugin's read call.
36 Returns
37 -------
38 image : ndimage
39 The ndimage located at the given URI.
40 """
42 plugin_kwargs = {
43 "legacy_mode": False,
44 "plugin": plugin,
45 "format_hint": format_hint,
46 "extension": extension,
47 }
49 call_kwargs = kwargs
50 if index is not None:
51 call_kwargs["index"] = index
53 with imopen(uri, "r", **plugin_kwargs) as img_file:
54 return np.asarray(img_file.read(**call_kwargs))
57def imiter(uri, *, plugin=None, extension=None, format_hint=None, **kwargs):
58 """Read a sequence of ndimages from a URI.
60 Returns an iterable that yields ndimages from the given URI. The exact
61 behavior depends on both, the file type and plugin used to open the file.
62 To learn about the exact behavior, check the documentation of the relevant
63 plugin.
65 Parameters
66 ----------
67 uri : {str, pathlib.Path, bytes, file}
68 The resource to load the image from, e.g. a filename, pathlib.Path,
69 http address or file object, see the docs for more info.
70 plugin : {str, None}
71 The plugin to use. If set to None (default) imiter will perform a
72 search for a matching plugin. If not None, this takes priority over
73 the provided format hint (if present).
74 extension : str
75 If not None, treat the provided ImageResource as if it had the given
76 extension. This affects the order in which backends are considered.
77 format_hint : str
78 Deprecated. Use `extension` instead.
79 **kwargs :
80 Additional keyword arguments will be passed to the plugin's ``iter``
81 call.
83 Yields
84 ------
85 image : ndimage
86 The next ndimage located at the given URI.
88 """
90 with imopen(
91 uri,
92 "r",
93 legacy_mode=False,
94 plugin=plugin,
95 format_hint=format_hint,
96 extension=extension,
97 ) as img_file:
98 for image in img_file.iter(**kwargs):
99 # Note: casting to ndarray here to ensure compatibility
100 # with the v2.9 API
101 yield np.asarray(image)
104def imwrite(uri, image, *, plugin=None, extension=None, format_hint=None, **kwargs):
105 """Write an ndimage to the given URI.
107 The exact behavior depends on the file type and plugin used. To learn about
108 the exact behavior, check the documentation of the relevant plugin.
110 Parameters
111 ----------
112 uri : {str, pathlib.Path, bytes, file}
113 The resource to save the image to, e.g. a filename, pathlib.Path,
114 http address or file object, check the docs for more info.
115 image : np.ndarray
116 The image to write to disk.
117 plugin : {str, None}
118 The plugin to use. If set to None (default) imwrite will perform a
119 search for a matching plugin. If not None, this takes priority over
120 the provided format hint (if present).
121 extension : str
122 If not None, treat the provided ImageResource as if it had the given
123 extension. This affects the order in which backends are considered, and
124 may also influence the format used when encoding.
125 format_hint : str
126 Deprecated. Use `extension` instead.
127 **kwargs :
128 Additional keyword arguments will be passed to the plugin's ``write``
129 call.
131 Returns
132 -------
133 encoded_image : None or Bytes
134 Returns ``None`` in all cases, except when ``uri`` is set to ``<bytes>``.
135 In this case it returns the encoded ndimage as a bytes string.
137 """
139 with imopen(
140 uri,
141 "w",
142 legacy_mode=False,
143 plugin=plugin,
144 format_hint=format_hint,
145 extension=extension,
146 ) as img_file:
147 encoded = img_file.write(image, **kwargs)
149 return encoded
152def improps(uri, *, index=None, plugin=None, extension=None, **kwargs):
153 """Read standardized metadata.
155 Opens the given URI and reads the properties of an ndimage from it. The
156 properties represent standardized metadata. This means that they will have
157 the same name regardless of the format being read or plugin/backend being
158 used. Further, any field will be, where possible, populated with a sensible
159 default (may be `None`) if the ImageResource does not declare a value in its
160 metadata.
162 Parameters
163 ----------
164 index : int
165 If the ImageResource contains multiple ndimages, and index is an
166 integer, select the index-th ndimage from among them and return its
167 properties. If index is an ellipsis (...), read all ndimages in the file
168 and stack them along a new batch dimension and return their properties.
169 If index is None, let the plugin decide.
170 plugin : {str, None}
171 The plugin to be used. If None, performs a search for a matching
172 plugin.
173 extension : str
174 If not None, treat the provided ImageResource as if it had the given
175 extension. This affects the order in which backends are considered.
176 **kwargs :
177 Additional keyword arguments will be passed to the plugin's ``properties``
178 call.
180 Returns
181 -------
182 properties : ImageProperties
183 A dataclass filled with standardized image metadata.
185 Notes
186 -----
187 Where possible, this will avoid loading pixel data.
189 See Also
190 --------
191 imageio.core.v3_plugin_api.ImageProperties
193 """
195 plugin_kwargs = {"legacy_mode": False, "plugin": plugin, "extension": extension}
197 call_kwargs = kwargs
198 if index is not None:
199 call_kwargs["index"] = index
201 with imopen(uri, "r", **plugin_kwargs) as img_file:
202 properties = img_file.properties(**call_kwargs)
204 return properties
207def immeta(
208 uri, *, index=None, plugin=None, extension=None, exclude_applied=True, **kwargs
209):
210 """Read format-specific metadata.
212 Opens the given URI and reads metadata for an ndimage from it. The contents
213 of the returned metadata dictionary is specific to both the image format and
214 plugin used to open the ImageResource. To learn about the exact behavior,
215 check the documentation of the relevant plugin. Typically, immeta returns a
216 dictionary specific to the image format, where keys match metadata field
217 names and values are a field's contents.
219 Parameters
220 ----------
221 uri : {str, pathlib.Path, bytes, file}
222 The resource to load the image from, e.g. a filename, pathlib.Path, http
223 address or file object, see the docs for more info.
224 index : {int, None}
225 If the ImageResource contains multiple ndimages, and index is an
226 integer, select the index-th ndimage from among them and return its
227 metadata. If index is an ellipsis (...), return global metadata. If
228 index is None, let the plugin decide the default.
229 plugin : {str, None}
230 The plugin to be used. If None (default), performs a search for a
231 matching plugin.
232 extension : str
233 If not None, treat the provided ImageResource as if it had the given
234 extension. This affects the order in which backends are considered.
235 **kwargs :
236 Additional keyword arguments will be passed to the plugin's metadata
237 method.
239 Returns
240 -------
241 image : ndimage
242 The ndimage located at the given URI.
244 """
246 plugin_kwargs = {"legacy_mode": False, "plugin": plugin, "extension": extension}
248 call_kwargs = kwargs
249 call_kwargs["exclude_applied"] = exclude_applied
250 if index is not None:
251 call_kwargs["index"] = index
253 with imopen(uri, "r", **plugin_kwargs) as img_file:
254 metadata = img_file.metadata(**call_kwargs)
256 return metadata
259__all__ = ["imopen", "imread", "imwrite", "imiter", "improps", "immeta"]