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
1# -*- coding: utf-8 -*-
2# Copyright (c) 2014-2020, imageio contributors
3# imageio is distributed under the terms of the (new) BSD License.
5# This docstring is used at the index of the documentation pages, and
6# gets inserted into a slightly larger description (in setup.py) for
7# the page on Pypi:
8"""
9Imageio is a Python library that provides an easy interface to read and
10write a wide range of image data, including animated images, volumetric
11data, and scientific formats. It is cross-platform, runs on Python 3.5+,
12and is easy to install.
14Main website: https://imageio.readthedocs.io/
15"""
17# flake8: noqa
19__version__ = "2.35.1"
21import warnings
23# Load some bits from core
24from .core import FormatManager, RETURN_BYTES
26# Instantiate the old format manager
27formats = FormatManager()
28show_formats = formats.show
30from . import v2
31from . import v3
32from . import plugins
34# import config after core to avoid circular import
35from . import config
37# import all APIs into the top level (meta API)
38from .v2 import (
39 imread as imread_v2,
40 mimread,
41 volread,
42 mvolread,
43 imwrite,
44 mimwrite,
45 volwrite,
46 mvolwrite,
47 # aliases
48 get_reader as read,
49 get_writer as save,
50 imwrite as imsave,
51 mimwrite as mimsave,
52 volwrite as volsave,
53 mvolwrite as mvolsave,
54 # misc
55 help,
56 get_reader,
57 get_writer,
58)
59from .v3 import (
60 imopen,
61 # imread, # Will take over once v3 is released
62 # imwrite, # Will take over once v3 is released
63 imiter,
64)
67def imread(uri, format=None, **kwargs):
68 """imread(uri, format=None, **kwargs)
70 Reads an image from the specified file. Returns a numpy array, which
71 comes with a dict of meta data at its 'meta' attribute.
73 Note that the image data is returned as-is, and may not always have
74 a dtype of uint8 (and thus may differ from what e.g. PIL returns).
76 Parameters
77 ----------
78 uri : {str, pathlib.Path, bytes, file}
79 The resource to load the image from, e.g. a filename, pathlib.Path,
80 http address or file object, see the docs for more info.
81 format : str
82 The format to use to read the file. By default imageio selects
83 the appropriate for you based on the filename and its contents.
84 kwargs : ...
85 Further keyword arguments are passed to the reader. See :func:`.help`
86 to see what arguments are available for a particular format.
87 """
89 warnings.warn(
90 "Starting with ImageIO v3 the behavior of this function will switch to that of"
91 " iio.v3.imread. To keep the current behavior (and make this warning disappear)"
92 " use `import imageio.v2 as imageio` or call `imageio.v2.imread` directly.",
93 DeprecationWarning,
94 stacklevel=2,
95 )
97 return imread_v2(uri, format=format, **kwargs)
100__all__ = [
101 "v2",
102 "v3",
103 "config",
104 "plugins",
105 # v3 API
106 "imopen",
107 "imread",
108 "imwrite",
109 "imiter",
110 # v2 API
111 "mimread",
112 "volread",
113 "mvolread",
114 "imwrite",
115 "mimwrite",
116 "volwrite",
117 "mvolwrite",
118 # v2 aliases
119 "read",
120 "save",
121 "imsave",
122 "mimsave",
123 "volsave",
124 "mvolsave",
125 # functions to deprecate
126 "help",
127 "get_reader",
128 "get_writer",
129 "formats",
130 "show_formats",
131]