Geat tutorial! I did suggest to have such example around in#10982 without seeing this one being created.

I used triangular shaped data to explain a point I wanted to make in that PR, something like

This would make it easier to grasp at which corner the data is shown compared to the original array. Would this be an option here?

Also it helps to display the indices in the plots:

def index_to_coordinate(index, extent, origin):    left, right, bottom, top = extent    # convert from extent to corner pixel centers        hshift = 0.5 if left < right else -0.5    left, right = left + hshift, right - hshift    vshift = 0.5 if bottom < top else -0.5    bottom, top = bottom + vshift, top - vshift        # handle vertical fill order    if origin == 'upper':        bottom, top = top, bottom        return {        '0, 0': (left, bottom),        'M, 0': (left, top),        '0, N': (right, bottom),        'M, N': (right, top),    }[index]

and in the inner for loop:

            for index in ['0, 0', '0, N', 'M, 0', 'M, N']:                ax.text(*index_to_coordinate(index, extent, origin),                        index, color='white', ha='center', va='center')

Just mind the notation. In the imshow docs (#10982), arrays are of shape(N,M).This is consistent with widely used conventions. So if updating the coordinates as proposed above, it would make sense to use this convention as well, and not suddenly chage it to(M,N). Independently something seems to be wrong in the above suggestion.

• For a tuplea,b one needs to decide if this is a cartesian point(x,y) or an array index[i,j]
• In either case, the last coordinate or index should beN-1 andM-1 respectively.

@ImportanceOfBeingErnest Agreed on all points.

• Should use (N,M).
• The exact notation would be[N-1, M-1], but there is no way of fitting that in square pixels while maintaining a reasonably small figure size. I could discuss away the square brackets with a sentence: "Values in pixels describe their indices". No good idea how to cope with the-1 issue. One could define them one-smaller by "array of shape (N+1,M+1)". That would be consistent within the example, but other than the original docstring notation (N, M).

Probably the best solution is using boxes for the indices as well:

whereN' = N-1 andM' = M-1

and code:

def get_color(index, data, cmap):    val = {        "[0, 0]": data[0, 0],        "[0, M']": data[0, -1],        "[N', 0]": data[-1, 0],        "[N', M']": data[-1, -1],    }[index]    return cmap(val / data.max())

            for index in ["[0, 0]", "[0, M']", "[N', 0]", "[N', M']"]:                ax.text(*index_to_coordinate(index, extent, origin),                        index, color='white', ha='center', va='center',                        bbox={'boxstyle': 'square',                              'facecolor': get_color(index, d, im.get_cmap())}                        )

@timhoffm@ImportanceOfBeingErnest feel free to push directly to this branch, I think all of these suggestions are great 👍

Would probably push the index labels in a bit or give them some alpha, they are covering the tick labels and the arrow. The index labels make also make the arrow superfluous.

@ImportanceOfBeingErnest Why is the convention (N, M)? Is this only for images? I find it quite confusing--why use reversed-alphabetical order? What about indices--are they (i, j), or (j, i)?

@efiring Good point. For some reason we're using this convention, but upon reflection and googling, I did not find profound evidence for it being "widely used". I was then somehow confirmed by the recently proposed changes to the imshow docs (#10982). (@timhoffm Might this be a typical german thing?)

So restart from scratch: theimshow docs need to decide for one convention (#10323,#10982), this convention needs to be documented (#10225). This guide here needs to use the same convention.

From a bit of googling and also looking at wikipedia it seems(m,n) /(M,N) /M x N could be preferable above(n,m) /(N,M) /N x M.

You are right.(M, N) is common, e.g.
https://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.lstsq.html#numpy.linalg.lstsq
http://scikit-image.org/docs/dev/api/skimage.filters.html#skimage.filters.inverse

Changed.

I think this is good to go.

For reviewers, here's how it looks like:
https://9315-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/tutorials/intermediate/imshow_extent.html?highlight=extent

I really like the changes! Thanks@ImportanceOfBeingErnest and@timhoffm !

I am 👍 on merging this, but don't want to push the button as I have commits in this and can not approve is github things this is my PR.

• Rephrased the section with "bounding box in data space".
• Fixed some typos.

Probably this example could be improved even further, but that would require significant restructuring of code and description. I'm pushing this forward to have a reference to point to from the imshow docstring and get my associated PR#10982 approved. As a first step this PR is now good enough for that. Further improvements can be added later.

I merged as a stand-alone improvement. Can be refined upon...