image

matplotlib.image

The image module supports basic image loading, rescaling and display operations.

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

interpolation and cmap default to their rc settings

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

extent is 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.

Additional kwargs are matplotlib.artist properties

get_cursor_data(event) [source]: Get the cursor data for a given event

get_extent() [source]: Get the image extent: left, right, bottom, top

get_window_extent(renderer=None) [source]

Get the axes bounding box in display space. 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(renderer, magnification=1.0, unsampled=False) [source]

set_extent(extent) [source]

extent is data axes (left, right, bottom, top) for making image plots

This updates ax.dataLim, and, if autoscaling, sets 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=True, **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

interp_at_native is a flag that determines whether or not interpolation should still be applied when the image is displayed at its native resolution. A common use case for this is when displaying an image for annotational purposes; it is treated similarly to Photoshop (interpolation is only used when displaying the image at non-native resolutions).

kwargs are an optional list of Artist keyword args

contains(mouseevent) [source]: Test whether the mouse event occurred within the image.

get_transform() [source]: Return the Transform instance used by this artist.

get_window_extent(renderer=None) [source]

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

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

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() [source]: Get the image extent: left, right, bottom, top

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

set_data(A) [source]: Set the image array.

zorder = 0

class matplotlib.image.NonUniformImage(ax, *, interpolation='nearest', **kwargs) [source]

Bases: matplotlib.image.AxesImage

kwargs are identical to those for AxesImage, except that 'nearest' and 'bilinear' are the only supported 'interpolation' options.

get_extent() [source]: Get the image extent: left, right, bottom, top

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

set_array(*args) [source]

Retained for backwards compatibility - use set_data instead.

Parameters:	`A : array-like`

set_cmap(cmap) [source]

set the colormap for luminance data

Parameters:	`cmap : colormap or registered colormap name`

set_data(x, y, A) [source]

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

x and y are monotonic 1-D ndarrays of lengths N and M,: respectively, specifying pixel centers
A is an (M,N) ndarray or masked array of values to be: colormapped, or a (M,N,3) RGB array, or a (M,N,4) RGBA array.

set_filternorm(s) [source]

Set whether the resize filter normalizes the weights.

See help for imshow.

Parameters:	`filternorm : bool`

set_filterrad(s) [source]

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

Parameters:	`filterrad : positive float`

set_interpolation(s) [source]

Parameters:	`s : str, None` Either 'nearest', 'bilinear', or `None`.

set_norm(norm) [source]

Set the normalization instance.

Parameters:	`norm : Normalize`

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

Bases: matplotlib.image.AxesImage

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

Additional kwargs are matplotlib.artist properties

get_cursor_data(event) [source]: Get the cursor data for a given event

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

set_array(*args) [source]

Retained for backwards compatibility - use set_data instead.

Parameters:	`A : array-like`

set_data(x, y, A) [source]

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

x and y are monotonic 1-D ndarrays of lengths N+1 and M+1,: respectively, specifying rectangle boundaries. If None, they will be created as uniform arrays from 0 through N and 0 through M, respectively.
A is an (M,N) ndarray or masked array of values to be: colormapped, or a (M,N,3) RGB array, or a (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:	`images : list of Images` Each 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. `renderer : RendererBase instance` `magnification : float` The additional magnification to apply for the renderer in use.
Returns:	`tuple : image, offset_x, offset_y` Returns 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:	`fname : str or file-like` The image file to read. This can be a filename, a URL or a Python file-like object opened in read-binary mode. `format : str, optional` The 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.
Returns:	`imagedata : numpy.array` The 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) [source]

Save an array as in image file.

The output formats available depend on the backend being used.

Parameters:

Parameters:	`fname : str or file-like` The filename or a Python file-like object to store the image in. The necessary output format is inferred from the filename extension but may be explicitly overwritten using format. `arr : array-like` The image data. The shape can be one of MxN (luminance), MxNx3 (RGB) or MxNx4 (RGBA). `vmin, vmax : scalar, optional` vmin 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. `cmap : str or 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 `rcParams["image.cmap"]` ('viridis'). `format : str, optional` The file format, e.g. 'png', 'pdf', 'svg', ... . If not given, the format is deduced form the filename extension in fname. See `Figure.savefig` for details. `origin : {'upper', 'lower'}, optional` Indicates 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"]` ('upper'). `dpi : int` The DPI to store in the metadata of the file. This does not affect the resolution of the output image.

fname : str or file-like: The filename or a Python file-like object to store the image in. The necessary output format is inferred from the filename extension but may be explicitly overwritten using format.
arr : array-like: The image data. The shape can be one of MxN (luminance), MxNx3 (RGB) or MxNx4 (RGBA).
vmin, vmax : scalar, optional: vmin 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.
cmap : str or 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 rcParams["image.cmap"] ('viridis').
format : str, optional: The file format, e.g. 'png', 'pdf', 'svg', ... . If not given, the format is deduced form the filename extension in fname. See Figure.savefig for details.
origin : {'upper', 'lower'}, optional: Indicates 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"] ('upper').
dpi : int: The DPI to store in the metadata of the file. This does not affect the resolution of the output image.

matplotlib.image.pil_to_array(pilImage) [source]

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

Returns:	numpy.array The 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:

Parameters:	`infile : str or file-like` The image file -- must be PNG, Pillow-readable if you have Pillow installed. `thumbfile : str or file-like` The thumbnail filename. `scale : float, optional` The scale factor for the thumbnail. `interpolation : str, optional` The interpolation scheme used in the resampling. See the interpolation parameter of `imshow` for possible values. `preview : bool, optional` If 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.
Returns:	`figure : Figure` The figure instance containing the thumbnail.

infile : str or file-like: The image file -- must be PNG, Pillow-readable if you have Pillow installed.
thumbfile : str or file-like: The thumbnail filename.
scale : float, optional: The scale factor for the thumbnail.
interpolation : str, optional: The interpolation scheme used in the resampling. See the interpolation parameter of imshow for possible values.
preview : bool, optional: If 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.

Returns:

figure : Figure: The figure instance containing the thumbnail.