I would say imagesare matrices. At least the convention is that images have the first pixels in the upper left corner.

Maybe better

The convention 'upper' is typically used for
matrices and images; 'lower' is typically used for displaying data arrays.

What are data arrays? numpy also uses the 'upper' convention:

>>> print(np.array([[1, 2], [3, 4]]))[[1, 2], [3, 4]]

For now, I don't have a good example for 'lower', so I just say

The convention 'upper' is typically used for matrices and images.

and don't give an example for lower.

can we sort out whatresample does?

I couldn't. I can track down its use to _image_interpolation.h l.987. but that C code doesn't speak to me. It appears to be written by@mdboom. Maybe he could enlighten us?

It is documented inthe resample C wrapper.

Thanks. I've copied the doc. Still I'm not 100% clear what this does:

• When will resampling (no matter if full or partial) occur.
• what are the output and the input images?

This is not quite right, I would say that 'origin' controls how the image is filled in, but not the meaning of 'top' and 'bottom'.

Changed to:

Note that the relation oftop andbottom to data coordinates depends onorigin.

"controls how the image is filled in" is true but does not help for describing the default values.

The meaning of 'top' and 'bottom' in data coordinates does not change, what changes is the orientation of the array in the bounding box.

https://8788-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/tutorials/intermediate/imshow_extent.html#sphx-glr-tutorials-intermediate-imshow-extent-py

The bounding box edges are exactly where expected in dataspace.

I suggest something like:

• If origin is set to "upper" then the default extents is (...)
• If origin is set to "lower" then the default extents is (...)

If the axes auto-scales the limits than this arranges such that the value in X[0, 0] is at (0, 0) in data-coordinates in both cases. In the case of "upper" the (0, 0) is in the upper left and the y-axis increases downward. In the case of "lower", the (0, 0) is in the lower left and the y-axis increases upward.

Maybe this needs a comment "having 'bottom > top' or 'left > right' may invert the drawn image"?

'... of the image's bounding box'

i.e. pixels will not be square....

strike "just"....

"... scalar data are used" (data is usually plural)....

I have no idea what image.origin defaults to. I think we could/should say what the default of the default is.

I found this first sentence strange.

"""By default the extent of the image is one data unit per pixel, centered on integer co-ordinates. So the horizontal axis ranges from 0 to N-1, and the vertical axes from 0 to M-1. Specifyingextent displays a subset of the data in this co-ordinate system.

By default the extent of the image is one data unit per pixel, centered on integer co-ordinates.

To me, that sounds even more strange. Extent is a range, which cannot be "one data unit per pixel". Also the extent is not centered, the pixels are.

Specifying extent displays a subset of the data in this co-ordinate system.

That sounds like clipping, which is not true. Extent scales the data.

Oops my mistake. What a confusing name for the kwarg. Regardless it still isn’t very clear.

How about pixels columns are linearly mapped between extent[0] and extent[3] and rows between ... by default these extents are ....

Wouldn't bother with columns and linear mapping to explain streching. Here's my current committed version:

The bounding box in data coordinates that the image will fill.
The image is stretched individually along x and y to fill the box.

The default extent is determined by the following conditions.
Pixels have unit size in data coordinates. Their centers are on
integer coordinates, and their center coordinates range from 0 to
columns-1 horizontally and from 0 to rows-1 vertically.

A totally minor suggestion: At this point it could make sense to link to theinterpolation_methods example.

Sure. Added. Revisiting the interpolation docstring revealed that it was not good anyway. So improved that as well.