[Doc]: Suggestion to use PIL.image.open is not a 1:1 replacement for imread

[Debilski]

Documentation Link

https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.imread.html

Problem

Following the deprecation message in matplotlib.pyplot.imread (when used with a URL) and trying to replace the code as suggested with PIL.Image.open(urllib.request.urlopen(url)), the resulting object is a PIL image object and not a numpy array as it used to be. As we are typically suggesting imread to create a numpy array from an image file (or URL) in some of our teaching materials, this is a bit confusing.

This is probably not a problem for matplotlib itself, as it can perfectly deal with the PIL object in eg. imshow, therefore I don’t know if it needs to be changed (it could be out of scope for the matplotlib documentation to clarify this).

Suggested improvement

Additionally present code that shows how to transform the PIL image object into an array.

Matplotlib Version

3.4.3

Matplotlib documentation version

3.4.3

[jklymak]

imread is a historical convenience function. If you plan to manipulate the images as numpy arrays, then indeed you will have to do something like np.array(image) first. Overall, I would not recommend using our imread.

[Debilski]

Ah, I didn’t even know that np.array(image) works out of the box. Yeah, I happily change our code away from imread. But for symmetry reasons (imshow prints numpy arrays) we kind of always assumed that imread is the best tool for doing the reverse.

[tacaswell]

@Debilski Can you open a PR with a note about this? I very much agree with @jklymak that you should not use imread (really use anything else), but the type instability in our suggested replacement is not great.

I think we should either drop the code snippet and instead link to Image.open (without implying it is a drop in replacement) or switch to a code snippet that is a drop-in replacement.

[Debilski]

I’ve added np.array to all code snippets in #21484 as a quick fix.

[timhoffm]

Closed by #21484

[petim0]

Hello, numpy(Image) doesn't do the trick, you also have to divide by 255 to find the same output as imread