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

image

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:

grafik

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 tuple a,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 be N-1 and M-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:

grafik

where N' = N-1 and M' = 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: the imshow 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...