diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py index 98e2b5eb790a..0aa34e467fb2 100644 --- a/lib/matplotlib/image.py +++ b/lib/matplotlib/image.py @@ -1425,6 +1425,11 @@ def imread(fname, format=None): """ Read an image from a file into an array. + .. note:: + + This function exists for historical reasons. It is recommended to + use `PIL.Image.open` instead for loading images. + Parameters ---------- fname : str or file-like @@ -1435,9 +1440,11 @@ def imread(fname, format=None): for reading and pass the result to Pillow, e.g. with ``PIL.Image.open(urllib.request.urlopen(url))``. format : str, optional - The image file format assumed for reading the data. If not - given, the format is deduced from the filename. If nothing can - be deduced, PNG is tried. + The image file format assumed for reading the data. The image is + loaded as a PNG file if *format* is set to "png", if *fname* is a path + or opened file with a ".png" extension, or if it is an URL. In all + other cases, *format* is ignored and the format is auto-detected by + `PIL.Image.open`. Returns ------- @@ -1447,6 +1454,10 @@ def imread(fname, format=None): - (M, N) for grayscale images. - (M, N, 3) for RGB images. - (M, N, 4) for RGBA images. + + PNG images are returned as float arrays (0-1). All other formats are + returned as int arrays, with a bit depth determined by the file's + contents. """ # hide imports to speed initial import on systems with slow linkers from urllib import parse