Spaces:
Running
on
Zero
Running
on
Zero
| 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"] | |