Skip to content

[Doc]: Rewrite of image tutorial #22790

Open

Description

@blu3r4d0n

Documentation Link

https://matplotlib.org/devdocs/tutorials/introductory/images.html

Problem

I found several issues within this introductory tutorial and I believe those issues can be solved by rewriting the tutorial.

Issues:

  • First, this tutorial was written prior to the depreciation of matplotlib.image.imread(), the current preferred method of opening images is using Pillow's Image.open(). The tutorial doesn't indicate this and reader's of the tutorial will see depreciation warnings when trying to go through the tutorial.
  • Second, I believe this tutorial is quite lengthy for an intro on how to use matplotlib.pyplot.imshow(). I think it would be better not to overwhelm new users with paragraphs of information on image analysis techniques and theory. Linking to pages about these topics might save users time.

Suggested improvement

I am considering rewriting this tutorial but first I want to get an idea of how to rewrite it in a way that avoids adding too many details but also gives users a good introduction to imshow(). As this is the first time I've contributed here, I wanted to get input from others before I started this process.

Activity

  1. jklymak commented on Apr 6, 2022

    @jklymak
    Member

    @philipmnelson I think this tutorial could well benefit from a fresh set of eyes and some de-crufting. The reason our docs accrete extraneous info is usually that a user trips across some rough edge, we explain it to them, they ask where they could have figured this out themselves, and then someone updates the most relevant tutorial. Over time, you paste enough of these asides on the tutorial and its hard to follow what is going on.

    Put the simple stuff first. All the detail isn't bad, but as you say upfront can be very confusing. Add many links - if there is a digression at the bottom that is important at the top, link to it at the top, but don't digress too much; if there is another place something explained link to it; if there are other tutorials or examples, link to them.

    You mention that we use deprecated imread, but Pillow doesn't normalize from 256 to 1; maybe worth opening another issue about that. I'm not sure if that was discussed when we decided to deprecate.

    Thanks for being willing to work on this.

  2. blu3r4d0n commented on Apr 6, 2022

    @blu3r4d0n
    Author

    @jklymak Yes, I noticed the normalization issue as well! the pillow method presented in the depreciation warning is not a 1:1 replacement for imread :) I'll probably open another issue today as #21484 didn't mention this in the docstring or depreciation warning. I just wasn't sure how to classify that in an issue. It's not a bug really just something that needs fixing or more clarification.

  3. blu3r4d0n commented on Apr 6, 2022

    @blu3r4d0n
    Author

    Okay, I just wanted to clarify for anybody who sees this issue that imread() is not deprecated, but the docs say that it exists only for historical reasons and that Pillow's Image.read() is preferred. Reading a URL with imread is deprecated and the alternative method provided in the reference docs and depreciation is not a complete replacement for imread's URL reading functionality.

  4. Bustead commented on Oct 4, 2023

    @Bustead

    @blu3r4d0n if you want a hand let me know! I'm just starting out too.

  5. timhoffm commented on Oct 5, 2023

    @timhoffm
    Member

    @Bustead since this is inactive for over a year, feel free to move forward on your own if there isn't response within a few days.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions