From f308ccc9566e56dfcd7cdc33343d3e049f414e5f Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sun, 8 Apr 2018 02:12:07 +0200 Subject: [PATCH] Improve docstring of Axes.imshow --- lib/matplotlib/axes/_axes.py | 154 ++++++++++++++++++++++------------- 1 file changed, 98 insertions(+), 56 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index cbf97d1f68e7..722cdb592b47 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -4988,82 +4988,117 @@ def imshow(self, X, cmap=None, norm=None, aspect=None, origin=None, extent=None, shape=None, filternorm=1, filterrad=4.0, imlim=None, resample=None, url=None, **kwargs): """ - Display an image on the axes. + Display an image, i.e. data on a 2D regular raster. Parameters ---------- - X : array_like, shape (n, m) or (n, m, 3) or (n, m, 4) - Display the image in `X` to current axes. `X` may be an - array or a PIL image. If `X` is an array, it - can have the following shapes and types: + X : array-like or PIL image + The image data. Supported array shapes are: - - MxN -- values to be mapped (float or int) - - MxNx3 -- RGB (float or uint8) - - MxNx4 -- RGBA (float or uint8) + - (M, N): an image with scalar data. The data is visualized + using a colormap. + - (M, N, 3): an image with RGB values (float or uint8). + - (M, N, 4): an image with RGBA values (float or uint8), i.e. + including transparency. - MxN arrays are mapped to colors based on the `norm` (mapping - scalar to scalar) and the `cmap` (mapping the normed scalar to - a color). + The first two dimensions (M, N) define the rows and columns of + the image. - Elements of RGB and RGBA arrays represent pixels of an MxN image. - All values should be in the range [0 .. 1] for floats or + The RGB(A) values should be in the range [0 .. 1] for floats or [0 .. 255] for integers. Out-of-range values will be clipped to these bounds. - cmap : `~matplotlib.colors.Colormap`, optional, default: None - If None, default to rc `image.cmap` value. `cmap` is ignored - if `X` is 3-D, directly specifying RGB(A) values. + cmap : str or `~matplotlib.colors.Colormap`, optional + A Colormap instance or registered colormap name. The colormap + maps scalar data to colors. It is ignored for RGB(A) data. + Defaults to :rc:`image.cmap`. - aspect : ['auto' | 'equal' | scalar], optional, default: None - If 'auto', changes the image aspect ratio to match that of the - axes. + aspect : {'equal', 'auto'} or float, optional + Controls the aspect ratio of the axes. The aspect is of particular + relevance for images since it may distort the image, i.e. pixel + will not be square. - If 'equal', and `extent` is None, changes the axes aspect ratio to - match that of the image. If `extent` is not `None`, the axes - aspect ratio is changed to match that of the extent. + This parameter is a shortcut for explicitly calling + `.Axes.set_aspect`. See there for further details. - If None, default to rc ``image.aspect`` value. + - 'equal': Ensures an aspect ratio of 1. Pixels will be square + (unless pixel sizes are explicitly made non-square in data + coordinates using *extent*). + - 'auto': The axes is kept fixed and the aspect is adjusted so + that the data fit in the axes. In general, this will result in + non-square pixels. + + Defaults to :rc:`image.aspect`. + + interpolation : str, optional + The interpolation method used. If *None* + :rc:`image.interpolation` is used, which defaults to 'nearest'. - interpolation : string, optional, default: None - Acceptable values are 'none', 'nearest', 'bilinear', 'bicubic', + Supported values are 'none', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', - 'lanczos' + 'lanczos'. - If `interpolation` is None, default to rc `image.interpolation`. - See also the `filternorm` and `filterrad` parameters. - If `interpolation` is 'none', then no interpolation is performed + If *interpolation* is 'none', then no interpolation is performed on the Agg, ps and pdf backends. Other backends will fall back to 'nearest'. - norm : `~matplotlib.colors.Normalize`, optional, default: None - A `~matplotlib.colors.Normalize` instance is used to scale - a 2-D float `X` input to the (0, 1) range for input to the - `cmap`. If `norm` is None, use the default func:`normalize`. - If `norm` is an instance of `~matplotlib.colors.NoNorm`, - `X` must be an array of integers that index directly into - the lookup table of the `cmap`. + See + :doc:`/gallery/images_contours_and_fields/interpolation_methods` + for an overview of the supported interpolation methods. - vmin, vmax : scalar, optional, default: None - `vmin` and `vmax` are used in conjunction with norm to normalize - luminance data. Note if you pass a `norm` instance, your - settings for `vmin` and `vmax` will be ignored. + Some interpolation methods require an additional radius parameter, + which can be set by *filterrad*. Additionally, the antigrain image + resize filter is controlled by the parameter *filternorm*. - alpha : scalar, optional, default: None + norm : `~matplotlib.colors.Normalize`, optional + If scalar data are used, the Normalize instance scales the + data values to the canonical colormap range [0,1] for mapping + to colors. By default, the data range is mapped to the + colorbar range using linear scaling. This parameter is ignored for + RGB(A) data. + + vmin, vmax : scalar, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* + define the data range that the colormap covers. By default, + the colormap covers the complete value range of the supplied + data. *vmin*, *vmax* are ignored if the *norm* parameter is used. + + alpha : scalar, optional The alpha blending value, between 0 (transparent) and 1 (opaque). - The ``alpha`` argument is ignored for RGBA input data. + This parameter is ignored for RGBA input data. - origin : ['upper' | 'lower'], optional, default: None + origin : {'upper', 'lower'}, optional Place the [0,0] index of the array in the upper left or lower left - corner of the axes. If None, default to rc `image.origin`. + corner of the axes. The convention 'upper' is typically used for + matrices and images. + If not given, :rc:`image.origin` is used, defaulting to 'upper'. + + Note that the vertical axes points upward for 'lower' + but downward for 'upper'. + + extent : scalars (left, right, bottom, top), optional + The bounding box in data coordinates that the image will fill. + The image is stretched individually along x and y to fill the box. - extent : scalars (left, right, bottom, top), optional, default: None - The location, in data-coordinates, of the lower-left and - upper-right corners. If `None`, the image is positioned such that - the pixel centers fall on zero-based (row, column) indices. + 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. + + Note that the direction of the vertical axis and thus the default + values for top and bottom depend on *origin*: + + - For ``origin == 'upper'`` the default is + ``(-0.5, numcols-0.5, numrows-0.5, -0.5)``. + - For ``origin == 'lower'`` the default is + ``(-0.5, numcols-0.5, -0.5, numrows-0.5)``. + + See the example :doc:`/tutorials/intermediate/imshow_extent` for a + more detailed description. shape : scalars (columns, rows), optional, default: None - For raw buffer images + For raw buffer images. filternorm : bool, optional, default: True A parameter for the antigrain image resize filter (see the @@ -5074,9 +5109,16 @@ def imshow(self, X, cmap=None, norm=None, aspect=None, that any sum of pixel weights must be equal to 1.0. So, the filter function must produce a graph of the proper shape. - filterrad : scalar, optional, default: 4.0 + filterrad : float > 0, optional, default: 4.0 The filter radius for filters that have a radius parameter, i.e. - when interpolation is one of: 'sinc', 'lanczos' or 'blackman' + when interpolation is one of: 'sinc', 'lanczos' or 'blackman'. + + resample : bool, optional + When *True*, use a full resampling method. When *False*, only + resample when the output image is larger than the input image. + + url : str, optional + Set the url of the created `.AxesImage`. See `.Artist.set_url`. Returns ------- @@ -5084,7 +5126,9 @@ def imshow(self, X, cmap=None, norm=None, aspect=None, Other Parameters ---------------- - **kwargs : `~matplotlib.artist.Artist` properties. + **kwargs : `~matplotlib.artist.Artist` properties + These parameters are passed on to the constructor of the + `.AxesImage` artist. See also -------- @@ -5096,7 +5140,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None, coordinates. In other words: the origin will coincide with the center of pixel (0, 0). - Two typical representations are used for RGB images with an alpha + There are two common representations for RGB images with an alpha channel: - Straight (unassociated) alpha: R, G, and B channels represent the @@ -5122,8 +5166,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None, if im.get_clip_path() is None: # image does not already have clipping set, clip to axes patch im.set_clip_path(self.patch) - #if norm is None and shape is None: - # im.set_clim(vmin, vmax) if vmin is not None or vmax is not None: im.set_clim(vmin, vmax) else: @@ -7273,7 +7315,7 @@ def matshow(self, Z, **kwargs): Parameters ---------- - Z : array-like(N, M) + Z : array-like(M, N) The matrix to be displayed. Returns