matplotlib.pyplot.imshow #

matplotlib.pyplot.imshow(X,cmap=None,norm=None,*,aspect=None,interpolation=None,alpha=None,vmin=None,vmax=None,colorizer=None,origin=None,extent=None,interpolation_stage=None,filternorm=True,filterrad=4.0,resample=None,url=None,data=None,**kwargs)[source]#

Display data as an image, i.e., on a 2D regular raster.

The input may either be actual RGB(A) data, or 2D scalar data, whichwill be rendered as a pseudocolor image. For displaying a grayscaleimage, set up the colormapping using the parameterscmap='gray',vmin=0,vmax=255.

The number of pixels used to render an image is set by the Axes sizeand the figuredpi. This can lead to aliasing artifacts whenthe image is resampled, because the displayed image size will usuallynot match the size ofX (seeImage resampling).The resampling can be controlled via theinterpolation parameterand/orrcParams["image.interpolation"] (default:'auto').

Parameters:

Xarray-like or PIL image

The image data. Supported array shapes are:

(M, N): an image with scalar data. The values are mapped tocolors using normalization and a colormap. See parametersnorm,cmap,vmin,vmax.
(M, N, 3): an image with RGB values (0-1 float or 0-255 int).
(M, N, 4): an image with RGBA values (0-1 float or 0-255 int),i.e. including transparency.

The first two dimensions (M, N) define the rows and columns ofthe image.

Out-of-range RGB(A) values are clipped.

cmapstr orColormap, default:rcParams["image.cmap"] (default:'viridis')

The Colormap instance or registered colormap name used to map scalar datato colors.

This parameter is ignored ifX is RGB(A).

normstr orNormalize, optional

The normalization method used to scale scalar data to the [0, 1] rangebefore mapping to colors usingcmap. By default, a linear scaling isused, mapping the lowest value to 0 and the highest to 1.

If given, this can be one of the following:

An instance ofNormalize or one of its subclasses(seeColormap normalization).
A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For alist of available scales, callmatplotlib.scale.get_scale_names().In that case, a suitableNormalize subclass is dynamically generatedand instantiated.

This parameter is ignored ifX is RGB(A).

vmin, vmaxfloat, optional

When using scalar data and no explicitnorm,vmin andvmax definethe data range that the colormap covers. By default, the colormap coversthe complete value range of the supplied data. It is an error to usevmin/vmax when anorm instance is given (but using astrnormname together withvmin/vmax is acceptable).

This parameter is ignored ifX is RGB(A).

colorizerColorizer or None, default: None

The Colorizer object used to map color to data. If None, a Colorizerobject is created from anorm andcmap.

This parameter is ignored ifX is RGB(A).

aspect{'equal', 'auto'} or float or None, default: None

The aspect ratio of the Axes. This parameter is particularlyrelevant for images since it determines whether data pixels aresquare.

This parameter is a shortcut for explicitly callingAxes.set_aspect. See there for further details.

'equal': Ensures an aspect ratio of 1. Pixels will be square(unless pixel sizes are explicitly made non-square in datacoordinates usingextent).
'auto': The Axes is kept fixed and the aspect is adjusted sothat the data fit in the Axes. In general, this will result innon-square pixels.

Normally, None (the default) means to usercParams["image.aspect"] (default:'equal'). However, ifthe image uses a transform that does not contain the axes data transform,then None means to not modify the axes aspect at all (in that case, directlycallAxes.set_aspect if desired).

interpolationstr, default:rcParams["image.interpolation"] (default:'auto')

The interpolation method used.

Supported values are 'none', 'auto', 'nearest', 'bilinear','bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite','kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell','sinc', 'lanczos', 'blackman'.

The dataX is resampled to the pixel size of the image on thefigure canvas, using the interpolation method to either up- ordownsample the data.

Ifinterpolation is 'none', then for the ps, pdf, and svgbackends no down- or upsampling occurs, and the image data ispassed to the backend as a native image. Note that different ps,pdf, and svg viewers may display these raw pixels differently. Onother backends, 'none' is the same as 'nearest'.

Ifinterpolation is the default 'auto', then 'nearest'interpolation is used if the image is upsampled by more than afactor of three (i.e. the number of display pixels is at leastthree times the size of the data array). If the upsampling rate issmaller than 3, or the image is downsampled, then 'hanning'interpolation is used to act as an anti-aliasing filter, unless theimage happens to be upsampled by exactly a factor of two or one.

SeeInterpolations for imshowfor an overview of the supported interpolation methods, andImage resampling fora discussion of image antialiasing.

Some interpolation methods require an additional radius parameter,which can be set byfilterrad. Additionally, the antigrain imageresize filter is controlled by the parameterfilternorm.

interpolation_stage{'auto', 'data', 'rgba'}, default: 'auto'

Supported values:

'data': Interpolation is carried out on the data provided by the userThis is useful if interpolating between pixels during upsampling.
'rgba': The interpolation is carried out in RGBA-space after thecolor-mapping has been applied. This is useful if downsampling andcombining pixels visually.
'auto': Select a suitable interpolation stage automatically. This uses'rgba' when downsampling, or upsampling at a rate less than 3, and'data' when upsampling at a higher rate.

SeeImage resampling fora discussion of image antialiasing.

alphafloat or array-like, optional

The alpha blending value, between 0 (transparent) and 1 (opaque).Ifalpha is an array, the alpha blending values are applied pixelby pixel, andalpha must have the same shape asX.

origin{'upper', 'lower'}, default:rcParams["image.origin"] (default:'upper')

Place the [0, 0] index of the array in the upper left or lowerleft corner of the Axes. The convention (the default) 'upper' istypically used for matrices and images.

Note that the vertical axis points upward for 'lower'but downward for 'upper'.

See theorigin and extent in imshow tutorial forexamples and a more detailed description.

extentfloats (left, right, bottom, top), optional

The bounding box in data coordinates that the image will fill.These values may be unitful and match the units of the Axes.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 oninteger coordinates, and their center coordinates range from 0 tocolumns-1 horizontally and from 0 to rows-1 vertically.

Note that the direction of the vertical axis and thus the defaultvalues for top and bottom depend onorigin:

Fororigin=='upper' the default is(-0.5,numcols-0.5,numrows-0.5,-0.5).
Fororigin=='lower' the default is(-0.5,numcols-0.5,-0.5,numrows-0.5).

See theorigin and extent in imshow tutorial forexamples and a more detailed description.

filternormbool, default: True

A parameter for the antigrain image resize filter (see theantigrain documentation). Iffilternorm is set, the filternormalizes integer values and corrects the rounding errors. Itdoesn't do anything with the source floating point values, itcorrects only integers according to the rule of 1.0 which meansthat any sum of pixel weights must be equal to 1.0. So, thefilter function must produce a graph of the proper shape.

filterradfloat > 0, default: 4.0

The filter radius for filters that have a radius parameter, i.e.when interpolation is one of: 'sinc', 'lanczos' or 'blackman'.

resamplebool, default:rcParams["image.resample"] (default:True)

WhenTrue, use a full resampling method. WhenFalse, onlyresample when the output image is larger than the input image.

urlstr, optional

Set the url of the createdAxesImage. SeeArtist.set_url.

Returns:

AxesImage

Other Parameters:

dataindexable object, optional: If given, all parameters also accept a strings, which isinterpreted asdata[s] ifs is a key indata.
**kwargsArtist properties: These parameters are passed on to the constructor of theAxesImage artist.