Spaces:
Running
on
Zero
Running
on
Zero
File size: 9,267 Bytes
d1ed09d |
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 |
import numpy as np
from .core.imopen import imopen
def imread(uri, *, index=None, plugin=None, extension=None, format_hint=None, **kwargs):
"""Read an ndimage from a URI.
Opens the given URI and reads an ndimage from it. The exact behavior
depends on both the file type and plugin used to open the file. To learn
about the exact behavior, check the documentation of the relevant plugin.
Typically, imread attempts to read all data stored in the URI.
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.
index : {int, Ellipsis, None}
If the ImageResource contains multiple ndimages, and index is an
integer, select the index-th ndimage from among them and return it. If
index is an ellipsis (...), read all ndimages in the file and stack them
along a new batch dimension. If index is None, let the plugin decide.
plugin : {str, None}
The plugin to use. If set to None (default) imread will perform a
search for a matching plugin. If not None, this takes priority over
the provided format hint (if present).
extension : str
If not None, treat the provided ImageResource as if it had the given
extension. This affects the order in which backends are considered.
format_hint : str
Deprecated. Use `extension` instead.
**kwargs :
Additional keyword arguments will be passed to the plugin's read call.
Returns
-------
image : ndimage
The ndimage located at the given URI.
"""
plugin_kwargs = {
"legacy_mode": False,
"plugin": plugin,
"format_hint": format_hint,
"extension": extension,
}
call_kwargs = kwargs
if index is not None:
call_kwargs["index"] = index
with imopen(uri, "r", **plugin_kwargs) as img_file:
return np.asarray(img_file.read(**call_kwargs))
def imiter(uri, *, plugin=None, extension=None, format_hint=None, **kwargs):
"""Read a sequence of ndimages from a URI.
Returns an iterable that yields ndimages from the given URI. The exact
behavior depends on both, the file type and plugin used to open the file.
To learn about the exact behavior, check the documentation of the relevant
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.
plugin : {str, None}
The plugin to use. If set to None (default) imiter will perform a
search for a matching plugin. If not None, this takes priority over
the provided format hint (if present).
extension : str
If not None, treat the provided ImageResource as if it had the given
extension. This affects the order in which backends are considered.
format_hint : str
Deprecated. Use `extension` instead.
**kwargs :
Additional keyword arguments will be passed to the plugin's ``iter``
call.
Yields
------
image : ndimage
The next ndimage located at the given URI.
"""
with imopen(
uri,
"r",
legacy_mode=False,
plugin=plugin,
format_hint=format_hint,
extension=extension,
) as img_file:
for image in img_file.iter(**kwargs):
# Note: casting to ndarray here to ensure compatibility
# with the v2.9 API
yield np.asarray(image)
def imwrite(uri, image, *, plugin=None, extension=None, format_hint=None, **kwargs):
"""Write an ndimage to the given URI.
The exact behavior depends on the file type and plugin used. To learn about
the exact behavior, check the documentation of the relevant plugin.
Parameters
----------
uri : {str, pathlib.Path, bytes, file}
The resource to save the image to, e.g. a filename, pathlib.Path,
http address or file object, check the docs for more info.
image : np.ndarray
The image to write to disk.
plugin : {str, None}
The plugin to use. If set to None (default) imwrite will perform a
search for a matching plugin. If not None, this takes priority over
the provided format hint (if present).
extension : str
If not None, treat the provided ImageResource as if it had the given
extension. This affects the order in which backends are considered, and
may also influence the format used when encoding.
format_hint : str
Deprecated. Use `extension` instead.
**kwargs :
Additional keyword arguments will be passed to the plugin's ``write``
call.
Returns
-------
encoded_image : None or Bytes
Returns ``None`` in all cases, except when ``uri`` is set to ``<bytes>``.
In this case it returns the encoded ndimage as a bytes string.
"""
with imopen(
uri,
"w",
legacy_mode=False,
plugin=plugin,
format_hint=format_hint,
extension=extension,
) as img_file:
encoded = img_file.write(image, **kwargs)
return encoded
def improps(uri, *, index=None, plugin=None, extension=None, **kwargs):
"""Read standardized metadata.
Opens the given URI and reads the properties of an ndimage from it. The
properties represent standardized metadata. This means that they will have
the same name regardless of the format being read or plugin/backend being
used. Further, any field will be, where possible, populated with a sensible
default (may be `None`) if the ImageResource does not declare a value in its
metadata.
Parameters
----------
index : int
If the ImageResource contains multiple ndimages, and index is an
integer, select the index-th ndimage from among them and return its
properties. If index is an ellipsis (...), read all ndimages in the file
and stack them along a new batch dimension and return their properties.
If index is None, let the plugin decide.
plugin : {str, None}
The plugin to be used. If None, performs a search for a matching
plugin.
extension : str
If not None, treat the provided ImageResource as if it had the given
extension. This affects the order in which backends are considered.
**kwargs :
Additional keyword arguments will be passed to the plugin's ``properties``
call.
Returns
-------
properties : ImageProperties
A dataclass filled with standardized image metadata.
Notes
-----
Where possible, this will avoid loading pixel data.
See Also
--------
imageio.core.v3_plugin_api.ImageProperties
"""
plugin_kwargs = {"legacy_mode": False, "plugin": plugin, "extension": extension}
call_kwargs = kwargs
if index is not None:
call_kwargs["index"] = index
with imopen(uri, "r", **plugin_kwargs) as img_file:
properties = img_file.properties(**call_kwargs)
return properties
def immeta(
uri, *, index=None, plugin=None, extension=None, exclude_applied=True, **kwargs
):
"""Read format-specific metadata.
Opens the given URI and reads metadata for an ndimage from it. The contents
of the returned metadata dictionary is specific to both the image format and
plugin used to open the ImageResource. To learn about the exact behavior,
check the documentation of the relevant plugin. Typically, immeta returns a
dictionary specific to the image format, where keys match metadata field
names and values are a field's contents.
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.
index : {int, None}
If the ImageResource contains multiple ndimages, and index is an
integer, select the index-th ndimage from among them and return its
metadata. If index is an ellipsis (...), return global metadata. If
index is None, let the plugin decide the default.
plugin : {str, None}
The plugin to be used. If None (default), performs a search for a
matching plugin.
extension : str
If not None, treat the provided ImageResource as if it had the given
extension. This affects the order in which backends are considered.
**kwargs :
Additional keyword arguments will be passed to the plugin's metadata
method.
Returns
-------
image : ndimage
The ndimage located at the given URI.
"""
plugin_kwargs = {"legacy_mode": False, "plugin": plugin, "extension": extension}
call_kwargs = kwargs
call_kwargs["exclude_applied"] = exclude_applied
if index is not None:
call_kwargs["index"] = index
with imopen(uri, "r", **plugin_kwargs) as img_file:
metadata = img_file.metadata(**call_kwargs)
return metadata
__all__ = ["imopen", "imread", "imwrite", "imiter", "improps", "immeta"]
|