Rasterio: Small Update to plotting_extent docs and doc strings

[lwasser]

Hello @sgillies and all rasterio devs / maintainers.

i found what i think is a small bug / or not quite correctly documented function - plotting_extent().

As documented in the doc string AND readthedocs, it says

"""Returns an extent in the format needed
     for matplotlib's imshow (left, right, bottom, top)
     instead of rasterio's bounds (left, bottom, top, right)
    Parameters
    ----------
    source : array or dataset object opened in 'r' mode
        input data
    transform: Affine, required if source is array
        Defines the affine transform if source is an array
"""

However if you have a multi layer array (ie a multi band image for instance), opened with rasterio, you do not get the correct plotting extent. I believe this is because of this line:

rows, cols = source.shape[0:2]

which attempts to grab the first 2 dimensions of the image BUT those dimensions by default in a multi-band raster are bands, rows not rows, cols. Because it could be difficult to determine if an array is band order or not programmatically, i propose that the documentation is updated to reflect that this function expects an array with dimensions rows, cols. And that if the data are not in that order, the user should either flip the data dimension order (ie transpose) OR provide array[0] if bands are the first dimension.

Thoughts on this? It would be a small update to the doc string and docs that i'm happy to submit if it's welcome. I've had many students mistakenly provide the function a band order first array following the help(plotting_extent).

Something like this perhaps:

"""Returns an extent in the format needed
     for matplotlib's imshow (left, right, bottom, top)
     instead of rasterio's bounds (left, bottom, top, right)
    Parameters
    ----------
    source : array or dataset object opened in 'r' mode
        input data in the order rows, columns and optionally bands. If bands are the first dimension in the array use source[0]
    transform: Affine, required if source is array
        Defines the affine transform if source is an array
"""

Best
Leah

[sgillies]

I'd be grateful for the contribution @lwasser ! In many places I have assumed that arrays are in row, col order and am sorry that I haven't made that as clear as it could be.

[lwasser]

Wonderful. Thank you @sgillies this package is fantastic so please do not apologize. I am just happy to be able to contribute in a small way. I'm using it in my class this semester! PR is submitted :)

[sgillies]

Done.