260 lines
9.0 KiB
Python
260 lines
9.0 KiB
Python
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"]
|