From f008a90a921440e0a314be4769f427bcba650db6 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Fri, 9 Apr 2021 12:29:33 +0200 Subject: [PATCH] Discourage use of imread & improve its docs. It's been around for too long to really be deprecatable. --- lib/matplotlib/image.py | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) 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