Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

imshow extent keyword (documentation?) #990

Closed
jomade opened this issue Jul 8, 2012 · 7 comments
Closed

imshow extent keyword (documentation?) #990

jomade opened this issue Jul 8, 2012 · 7 comments

Comments

@jomade
Copy link

jomade commented Jul 8, 2012

The imshow documentation as of version 1.1.0 contains the following statement:

*extent*: [ None | scalars (left, right, bottom, top) ]
   Data limits for the axes.  The default assigns zero-based row,
   column indices to the *x*, *y* centers of the pixels.

Which is kind of correct but misleading in two cases (and why is there stars around x and y? - there is no other x and y in the doc as far as I can see):

Case 1

Extent does not expect a list of indices as described in the text, but only two numbers per dimension (as given in the heading).
I would propose to move the description how data is displayed (with zero based row and column indices) to the top of the documentation

By default the data is displayed with range(M) and range(N) as axis 
coordinates for the row and column centers of the pixels, respectively. See 
use of *extent* keyword to adjust axis coordinates.

Case 2

The documentation suggests (at least to me) that extent is to specify for the pixel centers and not the borders.
For illustration try:

figure()
imshow(np.array([[1,2,3],[4,5,6]]), interpolation='nearest')

vs

figure()
imshow(np.array([[1,2,3],[4,5,6]]), interpolation='nearest', extent=(0,2,0,1))

So
imshow(X, extent=(0, N, 0, M))
will not give you default behaviour.
The default behaviour can be achieved if half a pixel size is added on each side:
imshow(X, extent=(0-0.5, N+0.5, 0-0.5, M+0.5))

I'm not sure if this is intended behaviour or not.

It would be nice to be able to produce and image from the pixel centers given as keyword arguments as
imshow(X, row_axis=range(M), column_axis=range(N))
or something like that.

However, if it is intended behaviour: I would propose the following documentation for the extent keyword:
extent: [ None | scalars (left, right, bottom, top) ]
Data limits for the axes. The limits range from the beginning of the first to the end of the
last pixel. Thus the extent specification for the default behaviour is:
imshow(X, extent=(-0.5, N+0.5, -0.5, M+0.5)).

@WeatherGod
Copy link
Member

I think the issue is mostly with misleading documentation. While I would like it to behave as documented (assinging extent=(0, 2, 0, 1) is more intuitive to me), it is quite unlikely that we will be able to change that now without the risk of breaking backwards compatibility. I will tag this as a documentation issue and update it accordingly.

tacaswell added a commit to tacaswell/matplotlib that referenced this issue Jan 16, 2014
@tacaswell
Copy link
Member

@jomade Can you please comment on my proposed change?

@pelson
Copy link
Member

pelson commented Jan 17, 2014

Nice PR. Closing the issue.

@pelson pelson closed this as completed Jan 17, 2014
@jeremyherbert
Copy link

jeremyherbert commented Jan 4, 2017

Just in case anyone finds this via google (like I did), if you want to set the centre of the four corner pixels instead of the extent values, here is a small function to do so:

def set_corner_pixels(image, x_min, x_max, y_min, y_max):
    x_diff = x_max-x_min
    y_diff = y_max-y_min
    
    y_size, x_size = image.get_size()
    
    x_ppx = x_diff/(x_size-1)
    y_ppx = y_diff/(y_size-1)
    
    extents = [
        x_min - 0.5*x_ppx, 
        x_max + 0.5*x_ppx,
        y_min - 0.5*y_ppx,
        y_max + 0.5*y_ppx
    ]
    
    image.set_extent(extents)

Use it like this:

image = [[0, 1], [2, 3], [4, 5]]

i = plt.imshow(image,
               aspect="auto",
               interpolation='nearest')

set_corner_pixels(i, 5, 10, 0, 12.5)

It's only minimally tested, so use at your own risk ;)

@jeremyherbert
Copy link

I'd also be willing to build this into a patch (@pelson, @tacaswell) to add a corner_extents=[] kwarg if you think that would be useful. I find myself doing this thing quite often.

@efiring
Copy link
Member

efiring commented Jan 4, 2017

This seems reasonable to me--but we need a better name! center_extents? pixel_extents? (Actually, I hate the "extents" terminology because I can never remember exactly what it refers to. I would prefer "lrbt". Say, "lrbt_edges" and "lrbt_centers". I suspect this is too much clutter and too much of a departure from tradition to be accepted, though.)
I will reopen this; we can quickly close it again if there is a consensus against adding a kwarg.

@efiring efiring reopened this Jan 4, 2017
@dstansby dstansby modified the milestones: v1.3.x, needs sorting Feb 14, 2018
@efiring
Copy link
Member

efiring commented Jun 11, 2018

Closing for lack of activity, and because the original issue has been addressed.

@efiring efiring closed this as completed Jun 11, 2018
@story645 story645 removed this from the future releases milestone Oct 6, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

8 participants