# matplotlib.image¶

class matplotlib.image.AxesImage(ax, cmap=None, norm=None, interpolation=None, origin=None, extent=None, filternorm=1, filterrad=4.0, resample=False, **kwargs)[source]

Bases: matplotlib.image._ImageBase

Parameters: axAxesThe axes the image will belong to. cmapstr or Colormap, default: rcParams["image.cmap"] (default: 'viridis')The Colormap instance or registered colormap name used to map scalar data to colors. normNormalizeMaps luminance to 0-1. interpolationstr, default: rcParams["image.interpolation"] (default: 'antialiased')Supported values are 'none', 'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos'. origin{'upper', 'lower'}, default: rcParams["image.origin"] (default: 'upper')Place the [0, 0] index of the array in the upper left or lower left corner of the axes. The convention 'upper' is typically used for matrices and images. extenttuple, optionalThe data axes (left, right, bottom, top) for making image plots registered with data plots. Default is to label the pixel centers with the zero-based row and column indices. filternormbool, default: TrueA parameter for the antigrain image resize filter (see the antigrain documentation). If filternorm is set, the filter normalizes integer values and corrects the rounding errors. It doesn't do anything with the source floating point values, it corrects only integers according to the rule of 1.0 which means that any sum of pixel weights must be equal to 1.0. So, the filter function must produce a graph of the proper shape. filterradfloat > 0, default: 4The filter radius for filters that have a radius parameter, i.e. when interpolation is one of: 'sinc', 'lanczos' or 'blackman'. resamplebool, default: FalseWhen True, use a full resampling method. When False, only resample when the output image is larger than the input image. **kwargsArtist properties
Parameters: normThe normalizing object which scales data, typically into the interval [0, 1]. If None, norm defaults to a colors.Normalize object which initializes its scaling based on the first data processed. cmapstr or Colormap instanceThe colormap used to map normalized data values to RGBA colors.
format_cursor_data(self, data)[source]

Return a string representation of data.

Note

This method is intended to be overridden by artist subclasses. As an end-user of Matplotlib you will most likely not call this method yourself.

The default implementation converts ints and floats and arrays of ints and floats into a comma-separated string enclosed in square brackets.

get_cursor_data(self, event)[source]

Return the image value at the event position or None if the event is outside the image.

get_extent(self)[source]

Return the image extent as tuple (left, right, bottom, top).

get_window_extent(self, renderer=None)[source]

Get the axes bounding box in display space.

The bounding box' width and height are nonnegative.

Subclasses should override for inclusion in the bounding box "tight" calculation. Default is to return an empty bounding box at 0, 0.

Be careful when using this function, the results will not update if the artist window extent of the artist changes. The extent can change due to any changes in the transform stack, such as changing the axes limits, the figure size, or the canvas used (as is done when saving a figure). This can lead to unexpected behavior where interactive figures will look fine on the screen, but will save incorrectly.

make_image(self, renderer, magnification=1.0, unsampled=False)[source]

Normalize, rescale, and colormap this image's data for rendering using renderer, with the given magnification.

If unsampled is True, the image will not be scaled, but an appropriate affine transformation will be returned instead.

Returns: image(M, N, 4) uint8 arrayThe RGBA image, resampled unless unsampled is True. x, yfloatThe upper left corner where the image should be drawn, in pixel space. transAffine2DThe affine transformation from image to pixel space.
set_extent(self, extent)[source]

Set the image extent.

Parameters: extent4-tuple of floatThe position and size of the image as tuple (left, right, bottom, top) in data coordinates.

Notes

This updates ax.dataLim, and, if autoscaling, sets ax.viewLim to tightly fit the image, regardless of dataLim. Autoscaling state is not changed, so following this with ax.autoscale_view() will redo the autoscaling in accord with dataLim.

class matplotlib.image.BboxImage(bbox, cmap=None, norm=None, interpolation=None, origin=None, filternorm=1, filterrad=4.0, resample=False, interp_at_native=<deprecated parameter>, **kwargs)[source]

Bases: matplotlib.image._ImageBase

The Image class whose size is determined by the given bbox.

cmap is a colors.Colormap instance norm is a colors.Normalize instance to map luminance to 0-1

kwargs are an optional list of Artist keyword args

contains(self, mouseevent)[source]

Test whether the mouse event occurred within the image.

get_transform(self)[source]

Return the Transform instance used by this artist.

get_window_extent(self, renderer=None)[source]

Get the axes bounding box in display space.

The bounding box' width and height are nonnegative.

Subclasses should override for inclusion in the bounding box "tight" calculation. Default is to return an empty bounding box at 0, 0.

Be careful when using this function, the results will not update if the artist window extent of the artist changes. The extent can change due to any changes in the transform stack, such as changing the axes limits, the figure size, or the canvas used (as is done when saving a figure). This can lead to unexpected behavior where interactive figures will look fine on the screen, but will save incorrectly.

property interp_at_native
make_image(self, renderer, magnification=1.0, unsampled=False)[source]

Normalize, rescale, and colormap this image's data for rendering using renderer, with the given magnification.

If unsampled is True, the image will not be scaled, but an appropriate affine transformation will be returned instead.

Returns: image(M, N, 4) uint8 arrayThe RGBA image, resampled unless unsampled is True. x, yfloatThe upper left corner where the image should be drawn, in pixel space. transAffine2DThe affine transformation from image to pixel space.
class matplotlib.image.FigureImage(fig, cmap=None, norm=None, offsetx=0, offsety=0, origin=None, **kwargs)[source]

Bases: matplotlib.image._ImageBase

cmap is a colors.Colormap instance norm is a colors.Normalize instance to map luminance to 0-1

kwargs are an optional list of Artist keyword args

get_extent(self)[source]

Return the image extent as tuple (left, right, bottom, top).

make_image(self, renderer, magnification=1.0, unsampled=False)[source]

Normalize, rescale, and colormap this image's data for rendering using renderer, with the given magnification.

If unsampled is True, the image will not be scaled, but an appropriate affine transformation will be returned instead.

Returns: image(M, N, 4) uint8 arrayThe RGBA image, resampled unless unsampled is True. x, yfloatThe upper left corner where the image should be drawn, in pixel space. transAffine2DThe affine transformation from image to pixel space.
set_data(self, A)[source]

Set the image array.

zorder = 0
class matplotlib.image.NonUniformImage(ax, *, interpolation='nearest', **kwargs)[source]
Parameters: interpolation{'nearest', 'bilinear'} **kwargsAll other keyword arguments are identical to those of AxesImage.
get_extent(self)[source]

Return the image extent as tuple (left, right, bottom, top).

make_image(self, renderer, magnification=1.0, unsampled=False)[source]

Normalize, rescale, and colormap this image's data for rendering using renderer, with the given magnification.

If unsampled is True, the image will not be scaled, but an appropriate affine transformation will be returned instead.

Returns: image(M, N, 4) uint8 arrayThe RGBA image, resampled unless unsampled is True. x, yfloatThe upper left corner where the image should be drawn, in pixel space. transAffine2DThe affine transformation from image to pixel space.
set_array(self, *args)[source]

Retained for backwards compatibility - use set_data instead.

Parameters: Aarray-like
set_cmap(self, cmap)[source]

set the colormap for luminance data

Parameters: cmapcolormap or registered colormap name
set_data(self, x, y, A)[source]

Set the grid for the pixel centers, and the pixel values.

Parameters: x, y1D array-likesMonotonic arrays of shapes (N,) and (M,), respectively, specifying pixel centers. Aarray-like(M, N) ndarray or masked array of values to be colormapped, or (M, N, 3) RGB array, or (M, N, 4) RGBA array.
set_filternorm(self, s)[source]

Set whether the resize filter normalizes the weights.

See help for imshow.

Parameters: filternormbool
set_filterrad(self, s)[source]

Set the resize filter radius only applicable to some interpolation schemes -- see help for imshow

set_interpolation(self, s)[source]
Parameters: sstr, NoneEither 'nearest', 'bilinear', or None.
set_norm(self, norm)[source]

Set the normalization instance.

Parameters: normNormalize

Notes

If there are any colorbars using the mappable for this norm, setting the norm of the mappable will reset the norm, locator, and formatters on the colorbar to default.

class matplotlib.image.PcolorImage(ax, x=None, y=None, A=None, cmap=None, norm=None, **kwargs)[source]

Make a pcolor-style plot with an irregular rectangular grid.

This uses a variation of the original irregular image code, and it is used by pcolorfast for the corresponding grid type.

cmap defaults to its rc setting

cmap is a colors.Colormap instance norm is a colors.Normalize instance to map luminance to 0-1

get_cursor_data(self, event)[source]

Return the image value at the event position or None if the event is outside the image.

make_image(self, renderer, magnification=1.0, unsampled=False)[source]

Normalize, rescale, and colormap this image's data for rendering using renderer, with the given magnification.

If unsampled is True, the image will not be scaled, but an appropriate affine transformation will be returned instead.

Returns: image(M, N, 4) uint8 arrayThe RGBA image, resampled unless unsampled is True. x, yfloatThe upper left corner where the image should be drawn, in pixel space. transAffine2DThe affine transformation from image to pixel space.
set_array(self, *args)[source]

Retained for backwards compatibility - use set_data instead.

Parameters: Aarray-like
set_data(self, x, y, A)[source]

Set the grid for the rectangle boundaries, and the data values.

Parameters: x, y1D array-likes or NoneMonotonic arrays of shapes (N + 1,) and (M + 1,), respectively, specifying rectangle boundaries. If None, will default to range(N + 1) and range(M + 1), respectively. Aarray-like(M, N) ndarray or masked array of values to be colormapped, or (M, N, 3) RGB array, or (M, N, 4) RGBA array.
matplotlib.image.composite_images(images, renderer, magnification=1.0)[source]

Composite a number of RGBA images into one. The images are composited in the order in which they appear in the images list.

Parameters: imageslist of ImagesEach must have a make_image method. For each image, can_composite should return True, though this is not enforced by this function. Each image must have a purely affine transformation with no shear. rendererRendererBase instance magnificationfloatThe additional magnification to apply for the renderer in use. tupleimage, offset_x, offset_yReturns the tuple: image: A numpy array of the same type as the input images. offset_x, offset_y: The offset of the image (left, bottom) in the output figure.
matplotlib.image.imread(fname, format=None)[source]

Read an image from a file into an array.

Parameters: fnamestr or file-likeThe image file to read: a filename, a URL or a file-like object opened in read-binary mode. formatstr, optionalThe image file format assumed for reading the data. If not given, the format is deduced from the filename. If nothing can be deduced, PNG is tried. imagedatanumpy.arrayThe image data. The returned array has shape (M, N) for grayscale images. (M, N, 3) for RGB images. (M, N, 4) for RGBA images.

Notes

Matplotlib can only read PNGs natively. Further image formats are supported via the optional dependency on Pillow. Note, URL strings are not compatible with Pillow. Check the Pillow documentation for more information.

matplotlib.image.imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None, origin=None, dpi=100, *, metadata=None, pil_kwargs=None)[source]

Save an array as an image file.

Parameters: fnamestr or PathLike or file-likeA path or a file-like object to store the image in. If format is not set, then the output format is inferred from the extension of fname, if any, and from rcParams["savefig.format"] (default: 'png') otherwise. If format is set, it determines the output format. arrarray-likeThe image data. The shape can be one of MxN (luminance), MxNx3 (RGB) or MxNx4 (RGBA). vmin, vmaxscalar, optionalvmin and vmax set the color scaling for the image by fixing the values that map to the colormap color limits. If either vmin or vmax is None, that limit is determined from the arr min/max value. cmapstr or Colormap, optionalA Colormap instance or registered colormap name. The colormap maps scalar data to colors. It is ignored for RGB(A) data. Defaults to rcParams["image.cmap"] (default: 'viridis') ('viridis'). formatstr, optionalThe file format, e.g. 'png', 'pdf', 'svg', ... The behavior when this is unset is documented under fname. origin{'upper', 'lower'}, optionalIndicates whether the (0, 0) index of the array is in the upper left or lower left corner of the axes. Defaults to rcParams["image.origin"] (default: 'upper') ('upper'). dpiintThe DPI to store in the metadata of the file. This does not affect the resolution of the output image. metadatadict, optionalMetadata in the image file. The supported keys depend on the output format, see the documentation of the respective backends for more information. pil_kwargsdict, optionalIf set to a non-None value, always use Pillow to save the figure (regardless of the output format), and pass these keyword arguments to PIL.Image.save. If the 'pnginfo' key is present, it completely overrides metadata, including the default 'Software' key.
matplotlib.image.pil_to_array(pilImage)[source]

Load a PIL image and return it as a numpy array.

Returns: numpy.arrayThe array shape depends on the image type: (M, N) for grayscale images. (M, N, 3) for RGB images. (M, N, 4) for RGBA images.
matplotlib.image.thumbnail(infile, thumbfile, scale=0.1, interpolation='bilinear', preview=False)[source]

Make a thumbnail of image in infile with output filename thumbfile.

See Image Thumbnail.

Parameters: infilestr or file-likeThe image file -- must be PNG, or Pillow-readable if you have Pillow installed. thumbfilestr or file-likeThe thumbnail filename. scalefloat, optionalThe scale factor for the thumbnail. interpolationstr, optionalThe interpolation scheme used in the resampling. See the interpolation parameter of imshow for possible values. previewbool, optionalIf True, the default backend (presumably a user interface backend) will be used which will cause a figure to be raised if show is called. If it is False, the figure is created using FigureCanvasBase and the drawing backend is selected as savefig would normally do. figureFigureThe figure instance containing the thumbnail.