@@ -4988,82 +4988,109 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
49884988origin = None ,extent = None ,shape = None ,filternorm = 1 ,
49894989filterrad = 4.0 ,imlim = None ,resample = None ,url = None ,** kwargs ):
49904990"""
4991- Display an imagethe axes .
4991+ Display an image, i.e. data ona 2D regular raster .
49924992
49934993 Parameters
49944994 ----------
4995- X : array_like, shape (n, m) or (n, m, 3) or (n, m, 4)
4996- Display the image in `X` to current axes. `X` may be an
4997- array or a PIL image. If `X` is an array, it
4998- can have the following shapes and types:
4995+ X : array-like or PIL image
4996+ The image data. Supported array shapes are:
49994997
5000- - MxN -- values to be mapped (float or int)
5001- - MxNx3 -- RGB (float or uint8)
5002- - MxNx4 -- RGBA (float or uint8)
4998+ - (M, N): an image with scalar data. The data is visualized
4999+ using a colormap.
5000+ - (M, N, 3): an image with RGB values (float or uint8).
5001+ - (M, N, 4): an image with RGBA values (float or uint8), i.e.
5002+ including transparency.
50035003
5004- MxN arrays are mapped to colors based on the `norm` (mapping
5005- scalar to scalar) and the `cmap` (mapping the normed scalar to
5006- a color).
5004+ The first two dimensions (M, N) define the rows and columns of
5005+ the image.
50075006
5008- Elements of RGB and RGBA arrays represent pixels of an MxN image.
5009- All values should be in the range [0 .. 1] for floats or
5007+ The RGB(A) values should be in the range [0 .. 1] for floats or
50105008 [0 .. 255] for integers. Out-of-range values will be clipped to
50115009 these bounds.
50125010
5013- cmap : `~matplotlib.colors.Colormap`, optional, default: None
5014- If None, default to rc `image.cmap` value. `cmap` is ignored
5015- if `X` is 3-D, directly specifying RGB(A) values.
5011+ cmap : str or `~matplotlib.colors.Colormap`, optional
5012+ A Colormap instance or registered colormap name. The colormap
5013+ maps scalar data to colors. It is ignored for RGB(A) data.
5014+ Defaults to :rc:`image.cmap`.
50165015
5017- aspect : ['auto' | 'equal' | scalar], optional, default: None
5018- If 'auto', changes the image aspect ratio to match that of the
5019- axes.
5016+ aspect : {'equal', 'auto'} or float, optional
5017+ Controls the aspect ratio of the axes. The aspect is of particular
5018+ relevance for images since it may distort the image, i.e. pixel
5019+ will not be square.
50205020
5021- If 'equal', and `extent` is None, changes the axes aspect ratio to
5022- match that of the image. If `extent` is not `None`, the axes
5023- aspect ratio is changed to match that of the extent.
5021+ This parameter is a shortcut for explicitly calling
5022+ `.Axes.set_aspect`. See there for further details.
50245023
5025- If None, default to rc ``image.aspect`` value.
5024+ - 'equal': Ensures an aspect ratio of 1. Pixels will be square
5025+ (unless pixel sizes are explicitly made non-square in data
5026+ coordinates using *extent*).
5027+ - 'auto': The axes is kept fixed and the aspect is adjusted so
5028+ that the data fit in the axes. In general, this will result in
5029+ non-square pixels.
5030+
5031+ Defaults to :rc:`image.aspect`.
50265032
5027- interpolation :string , optional, default: None
5028- Acceptable values are 'none', 'nearest', 'bilinear', 'bicubic',
5033+ interpolation :str , optional
5034+ Supported values are 'none', 'nearest', 'bilinear', 'bicubic',
50295035 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser',
50305036 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc',
5031- 'lanczos'
5037+ 'lanczos'.
5038+
5039+ Defaults to :rc:`image.interpolation`.
50325040
5033- If `interpolation` is None, default to rc `image.interpolation`.
5034- See also the `filternorm` and `filterrad` parameters.
5035- If `interpolation` is 'none', then no interpolation is performed
5041+ See also the *filternorm* and *filterrad* parameters.
5042+ If *interpolation* is 'none', then no interpolation is performed
50365043 on the Agg, ps and pdf backends. Other backends will fall back to
50375044 'nearest'.
50385045
5039- norm : `~matplotlib.colors.Normalize`, optional, default: None
5040- A `~matplotlib.colors.Normalize` instance is used to scale
5041- a 2-D float `X` input to the (0, 1) range for input to the
5042- `cmap`. If `norm` is None, use the default func:`normalize`.
5043- If `norm` is an instance of `~matplotlib.colors.NoNorm`,
5044- `X` must be an array of integers that index directly into
5045- the lookup table of the `cmap`.
5046+ norm : `~matplotlib.colors.Normalize`, optional
5047+ If scalar data are used, the Normalize instance scales the
5048+ data values to the canonical colormap range [0,1] for mapping
5049+ to colors. By default, the data range is mapped to the
5050+ colorbar range using linear scaling. This parameter is ignored for
5051+ RGB(A) data.
50465052
5047- vmin, vmax : scalar, optional, default: None
5048- `vmin` and `vmax` are used in conjunction with norm to normalize
5049- luminance data. Note if you pass a `norm` instance, your
5050- settings for `vmin` and `vmax` will be ignored.
5053+ vmin, vmax : scalar, optional
5054+ When using scalar data and no explicit *norm*, *vmin* and *vmax*
5055+ define the data range that the colormap covers. By default,
5056+ the colormap covers the complete value range of the supplied
5057+ data. *vmin*, *vmax* are ignored if the *norm* parameter is used.
50515058
5052- alpha : scalar, optional, default: None
5059+ alpha : scalar, optional
50535060 The alpha blending value, between 0 (transparent) and 1 (opaque).
5054- The ``alpha`` argument is ignored for RGBA input data.
5061+ This parameter is ignored for RGBA input data.
50555062
5056- origin :[ 'upper' | 'lower'] , optional, default: None
5063+ origin :{ 'upper', 'lower'} , optional
50575064 Place the [0,0] index of the array in the upper left or lower left
5058- corner of the axes. If None, default to rc `image.origin`.
5065+ corner of the axes. The convention 'upper' is typically used for
5066+ matrices and images.
5067+ If not given, :rc:`image.origin` is used, defaulting to 'upper'.
5068+
5069+ Note that the vertical axes points upward for 'lower'
5070+ but downward for 'upper'.
5071+
5072+ extent : scalars (left, right, bottom, top), optional
5073+ The bounding box in data coordinates that the image will fill.
5074+ The image is stretched individually along x and y to fill the box.
50595075
5060- extent : scalars (left, right, bottom, top), optional, default: None
5061- The location, in data-coordinates, of the lower-left and
5062- upper-right corners. If `None`, the image is positioned such that
5063- the pixel centers fall on zero-based (row, column) indices.
5076+ The default extent is determined by the following conditions.
5077+ Pixels have unit size in data coordinates. Their centers are on
5078+ integer coordinates, and their center coordinates range from 0 to
5079+ columns-1 horizontally and from 0 to rows-1 vertically.
5080+
5081+ Note that the direction of the vertical axis and thus the default
5082+ values for top and bottom depend on *origin*:
5083+
5084+ - For ``origin == 'upper'`` the default is
5085+ ``(-0.5, numcols-0.5, numrows-0.5, -0.5)``.
5086+ - For ``origin == 'lower'`` the default is
5087+ ``(-0.5, numcols-0.5, -0.5, numrows-0.5)``.
5088+
5089+ See the example :doc:`/tutorials/intermediate/imshow_extent` for a
5090+ more detailed description.
50645091
50655092 shape : scalars (columns, rows), optional, default: None
5066- For raw buffer images
5093+ For raw buffer images.
50675094
50685095 filternorm : bool, optional, default: True
50695096 A parameter for the antigrain image resize filter (see the
@@ -5074,17 +5101,26 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
50745101 that any sum of pixel weights must be equal to 1.0. So, the
50755102 filter function must produce a graph of the proper shape.
50765103
5077- filterrad :scalar , optional, default: 4.0
5104+ filterrad :float > 0 , optional, default: 4.0
50785105 The filter radius for filters that have a radius parameter, i.e.
5079- when interpolation is one of: 'sinc', 'lanczos' or 'blackman'
5106+ when interpolation is one of: 'sinc', 'lanczos' or 'blackman'.
5107+
5108+ resample : bool, optional
5109+ When *True*, use a full resampling method. When *False*, only
5110+ resample when the output image is larger than the input image.
5111+
5112+ url : str, optional
5113+ Set the url of the created `.AxesImage`. See `.Artist.set_url`.
50805114
50815115 Returns
50825116 -------
50835117 image : `~matplotlib.image.AxesImage`
50845118
50855119 Other Parameters
50865120 ----------------
5087- **kwargs : `~matplotlib.artist.Artist` properties.
5121+ **kwargs : `~matplotlib.artist.Artist` properties
5122+ These parameters are passed on to the constructor of the
5123+ `.AxesImage` artist.
50885124
50895125 See also
50905126 --------
@@ -5096,7 +5132,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
50965132 coordinates. In other words: the origin will coincide with the center
50975133 of pixel (0, 0).
50985134
5099- Two typical representations are used for RGB images with an alpha
5135+ There are two common representations for RGB images with an alpha
51005136 channel:
51015137
51025138 - Straight (unassociated) alpha: R, G, and B channels represent the
@@ -5122,8 +5158,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
51225158if im .get_clip_path ()is None :
51235159# image does not already have clipping set, clip to axes patch
51245160im .set_clip_path (self .patch )
5125- #if norm is None and shape is None:
5126- # im.set_clim(vmin, vmax)
51275161if vmin is not None or vmax is not None :
51285162im .set_clim (vmin ,vmax )
51295163else :
@@ -7273,7 +7307,7 @@ def matshow(self, Z, **kwargs):
72737307
72747308 Parameters
72757309 ----------
7276- Z : array-like(N, M )
7310+ Z : array-like(M, N )
72777311 The matrix to be displayed.
72787312
72797313 Returns