matplotlib.image#

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

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

Bases: _ImageBase

An image with pixels on a regular grid, attached to an Axes.

Parameters:

axAxes

The 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.

normstr or Normalize

Maps luminance to 0-1.

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

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

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

If 'data', interpolation is carried out on the data provided by the user. If 'rgba', the interpolation is carried out after the colormapping has been applied (visual interpolation).

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, optional

The 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: True

A 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: 4

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

resamplebool, default: False

When True, use a full resampling method. When False, only resample when the output image is larger than the input image.

**kwargsArtist properties

Parameters:

colorizercolorizer.Colorizer

get_cursor_data(event)[source]#

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

See also

matplotlib.artist.Artist.get_cursor_data

get_extent()[source]#

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

get_window_extent(renderer=None)[source]#

Get the artist's bounding box in display space, ignoring clipping.

The bounding box's width and height are non-negative.

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

Warning

The extent can change due to any changes in the transform stack, such as changing the Axes limits, the figure size, the canvas used (as is done when saving a figure), or the DPI.

Relying on a once-retrieved window extent can lead to unexpected behavior in various cases such as interactive figures being resized or moved to a screen with different dpi, or figures that look fine on screen render incorrectly when saved to file.

To get accurate results you may need to manually call savefig or draw_without_rendering to have Matplotlib compute the rendered size.

Parameters:

rendererRendererBase, optional

Renderer used to draw the figure (i.e. fig.canvas.get_renderer()).

See also

Artist.get_tightbbox

Get the artist bounding box, taking clipping into account.

make_image(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) numpy.uint8 array

The RGBA image, resampled unless unsampled is True.

x, yfloat

The upper left corner where the image should be drawn, in pixel space.

transAffine2D

The affine transformation from image to pixel space.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, array=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, data=<UNSET>, extent=<UNSET>, filternorm=<UNSET>, filterrad=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, interpolation=<UNSET>, interpolation_stage=<UNSET>, label=<UNSET>, mouseover=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, resample=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Property	Description
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	float or 2D array-like or None
animated	bool
array	array-like
clim	(vmin: float, vmax: float)
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
cmap	Colormap or str or None
data	array-like or PIL.Image.Image
extent	4-tuple of float
figure	Figure or SubFigure
filternorm	bool
filterrad	positive float
gid	str
in_layout	bool
interpolation	{'auto', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage	{'data', 'rgba', 'auto'}, default: rcParams["image.interpolation_stage"] (default: 'auto')
label	object
mouseover	bool
norm	Normalize or str or None
path_effects	list of AbstractPathEffect
picker	None or bool or float or callable
rasterized	bool
resample	bool, default: rcParams["image.resample"] (default: True)
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
transform	Transform
url	str
visible	bool
zorder	float

set_extent(extent, **kwargs)[source]#

Set the image extent.

Parameters:

extent4-tuple of float

The position and size of the image as tuple (left, right, bottom, top) in data coordinates.

**kwargs

Other parameters from which unit info (i.e., the xunits, yunits, zunits (for 3D Axes), runits and thetaunits (for polar Axes) entries are applied, if present.

Notes

This updates Axes.dataLim, and, if autoscaling, sets Axes.viewLim to tightly fit the image, regardless of dataLim. Autoscaling state is not changed, so a subsequent call to Axes.autoscale_view will redo the autoscaling in accord with dataLim.

class matplotlib.image.BboxImage(bbox, *, cmap=None, norm=None, colorizer=None, interpolation=None, origin=None, filternorm=True, filterrad=4.0, resample=False, **kwargs)[source]#

Bases: _ImageBase

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

Parameters:

bboxBboxBase or Callable[RendererBase, BboxBase]

The bbox or a function to generate the bbox

Warning

If using matplotlib.artist.Artist.get_window_extent as the callable ensure that the other artist is drawn first (lower zorder) or you may need to renderer the figure twice to ensure that the computed bbox is accurate.

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

The Colormap instance or registered colormap name used to map scalar data to colors. This parameter is ignored if X is RGB(A).

normstr or Normalize

Maps luminance to 0-1. This parameter is ignored if X is RGB(A).

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

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

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.

filternormbool, default: True

A 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: 4

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

resamplebool, default: False

When True, use a full resampling method. When False, only resample when the output image is larger than the input image.

**kwargsArtist properties

Parameters:

colorizercolorizer.Colorizer

contains(mouseevent)[source]#

Test whether the mouse event occurred within the image.

get_window_extent(renderer=None)[source]#

Get the artist's bounding box in display space, ignoring clipping.

The bounding box's width and height are non-negative.

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

Warning

The extent can change due to any changes in the transform stack, such as changing the Axes limits, the figure size, the canvas used (as is done when saving a figure), or the DPI.

Relying on a once-retrieved window extent can lead to unexpected behavior in various cases such as interactive figures being resized or moved to a screen with different dpi, or figures that look fine on screen render incorrectly when saved to file.

To get accurate results you may need to manually call savefig or draw_without_rendering to have Matplotlib compute the rendered size.

Parameters:

rendererRendererBase, optional

Renderer used to draw the figure (i.e. fig.canvas.get_renderer()).

See also

Artist.get_tightbbox

Get the artist bounding box, taking clipping into account.

make_image(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) numpy.uint8 array

The RGBA image, resampled unless unsampled is True.

x, yfloat

The upper left corner where the image should be drawn, in pixel space.

transAffine2D

The affine transformation from image to pixel space.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, array=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, data=<UNSET>, filternorm=<UNSET>, filterrad=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, interpolation=<UNSET>, interpolation_stage=<UNSET>, label=<UNSET>, mouseover=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, resample=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Property	Description
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	float or 2D array-like or None
animated	bool
array	array-like
clim	(vmin: float, vmax: float)
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
cmap	Colormap or str or None
data	array-like or PIL.Image.Image
figure	Figure or SubFigure
filternorm	bool
filterrad	positive float
gid	str
in_layout	bool
interpolation	{'auto', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage	{'data', 'rgba', 'auto'}, default: rcParams["image.interpolation_stage"] (default: 'auto')
label	object
mouseover	bool
norm	Normalize or str or None
path_effects	list of AbstractPathEffect
picker	None or bool or float or callable
rasterized	bool
resample	bool, default: rcParams["image.resample"] (default: True)
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
transform	Transform
url	str
visible	bool
zorder	float

class matplotlib.image.FigureImage(fig, *, cmap=None, norm=None, colorizer=None, offsetx=0, offsety=0, origin=None, **kwargs)[source]#

Bases: _ImageBase

An image attached to a figure.

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]#

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

make_image(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) numpy.uint8 array

The RGBA image, resampled unless unsampled is True.

x, yfloat

The upper left corner where the image should be drawn, in pixel space.

transAffine2D

The affine transformation from image to pixel space.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, array=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, data=<UNSET>, filternorm=<UNSET>, filterrad=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, interpolation=<UNSET>, interpolation_stage=<UNSET>, label=<UNSET>, mouseover=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, resample=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Property	Description
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	float or 2D array-like or None
animated	bool
array	array-like
clim	(vmin: float, vmax: float)
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
cmap	Colormap or str or None
data	unknown
figure	Figure or SubFigure
filternorm	bool
filterrad	positive float
gid	str
in_layout	bool
interpolation	{'auto', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage	{'data', 'rgba', 'auto'}, default: rcParams["image.interpolation_stage"] (default: 'auto')
label	object
mouseover	bool
norm	Normalize or str or None
path_effects	list of AbstractPathEffect
picker	None or bool or float or callable
rasterized	bool
resample	bool, default: rcParams["image.resample"] (default: True)
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
transform	Transform
url	str
visible	bool
zorder	float

set_data(A)[source]#

Set the image array.

zorder = 0#

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

Bases: AxesImage

An image with pixels on a rectilinear grid.

In contrast to AxesImage, where pixels are on a regular grid, NonUniformImage allows rows and columns with individual heights / widths.

See also Image nonuniform.

Parameters:

axAxes

The Axes the image will belong to.

interpolation{'nearest', 'bilinear'}, default: 'nearest'

The interpolation scheme used in the resampling.

**kwargs

All other keyword arguments are identical to those of AxesImage.

get_cursor_data(event)[source]#

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

See also

matplotlib.artist.Artist.get_cursor_data

get_extent()[source]#

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

make_image(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) numpy.uint8 array

The RGBA image, resampled unless unsampled is True.

x, yfloat

The upper left corner where the image should be drawn, in pixel space.

transAffine2D

The affine transformation from image to pixel space.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, array=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, data=<UNSET>, extent=<UNSET>, filternorm=<UNSET>, filterrad=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, interpolation=<UNSET>, interpolation_stage=<UNSET>, label=<UNSET>, mouseover=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, resample=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Property	Description
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	float or 2D array-like or None
animated	bool
array	unknown
clim	(vmin: float, vmax: float)
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
cmap	unknown
data	unknown
extent	4-tuple of float
figure	Figure or SubFigure
filternorm	unknown
filterrad	unknown
gid	str
in_layout	bool
interpolation	{'nearest', 'bilinear'} or None
interpolation_stage	{'data', 'rgba', 'auto'}, default: rcParams["image.interpolation_stage"] (default: 'auto')
label	object
mouseover	bool
norm	unknown
path_effects	list of AbstractPathEffect
picker	None or bool or float or callable
rasterized	bool
resample	bool, default: rcParams["image.resample"] (default: True)
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
transform	Transform
url	str
visible	bool
zorder	float

set_array(*args)[source]#

Retained for backwards compatibility - use set_data instead.

Parameters:

Aarray-like

set_cmap(cmap)[source]#

Set the colormap for luminance data.

Parameters:

cmapColormap or str or None

set_data(x, y, A)[source]#

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

Parameters:

x, y1D array-like

Monotonic 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(filternorm)[source]#

Set whether the resize filter normalizes the weights.

See help for imshow.

Parameters:

filternormbool

set_filterrad(filterrad)[source]#

Set the resize filter radius (only applicable to some interpolation schemes).

See help for imshow.

Parameters:

filterradpositive float

set_interpolation(s)[source]#

Parameters:

s{'nearest', 'bilinear'} or None

If None, use rcParams["image.interpolation"] (default: 'auto').

set_norm(norm)[source]#

Set the normalization instance.

Parameters:

normNormalize or str or None

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, colorizer=None, **kwargs)[source]#

Bases: 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.

Parameters:

axAxes

The Axes the image will belong to.

x, y1D array-like, optional

Monotonic arrays of length N+1 and M+1, respectively, specifying rectangle boundaries. If not given, will default to range(N + 1) and range(M + 1), respectively.

Aarray-like

The data to be color-coded. The interpretation depends on the shape:

• (M, N) ndarray or masked array: values to be colormapped

• (M, N, 3): RGB array

• (M, N, 4): RGBA array

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

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

normstr or Normalize

Maps luminance to 0-1.

**kwargsArtist properties

get_cursor_data(event)[source]#

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

See also

matplotlib.artist.Artist.get_cursor_data

make_image(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) numpy.uint8 array

The RGBA image, resampled unless unsampled is True.

x, yfloat

The upper left corner where the image should be drawn, in pixel space.

transAffine2D

The affine transformation from image to pixel space.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, array=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, data=<UNSET>, extent=<UNSET>, filternorm=<UNSET>, filterrad=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, interpolation=<UNSET>, interpolation_stage=<UNSET>, label=<UNSET>, mouseover=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, resample=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Property	Description
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	float or 2D array-like or None
animated	bool
array	unknown
clim	(vmin: float, vmax: float)
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
cmap	Colormap or str or None
data	unknown
extent	4-tuple of float
figure	Figure or SubFigure
filternorm	bool
filterrad	positive float
gid	str
in_layout	bool
interpolation	{'auto', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage	{'data', 'rgba', 'auto'}, default: rcParams["image.interpolation_stage"] (default: 'auto')
label	object
mouseover	bool
norm	Normalize or str or None
path_effects	list of AbstractPathEffect
picker	None or bool or float or callable
rasterized	bool
resample	bool, default: rcParams["image.resample"] (default: True)
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
transform	Transform
url	str
visible	bool
zorder	float

set_array(*args)[source]#

Retained for backwards compatibility - use set_data instead.

Parameters:

Aarray-like

set_data(x, y, A)[source]#

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

Parameters:

x, y1D array-like, optional

Monotonic arrays of length N+1 and M+1, respectively, specifying rectangle boundaries. If not given, will default to range(N + 1) and range(M + 1), respectively.

Aarray-like

The data to be color-coded. The interpretation depends on the shape:

• (M, N) ndarray or masked array: values to be colormapped

• (M, N, 3): RGB array

• (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 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.

rendererRendererBase

magnificationfloat, default: 1

The additional magnification to apply for the renderer in use.

Returns:

image(M, N, 4) numpy.uint8 array

The composited RGBA image.

offset_x, offset_yfloat

The (left, bottom) offset where the composited image should be placed in the output figure.

matplotlib.image.imread(fname, format=None)[source]#

Read an image from a file into an array.

Note

This function exists for historical reasons. It is recommended to use PIL.Image.open instead for loading images.

Parameters:

fnamestr or file-like

The image file to read: a filename, a URL or a file-like object opened in read-binary mode.

Passing a URL is deprecated. Please open the URL for reading and pass the result to Pillow, e.g. with np.array(PIL.Image.open(urllib.request.urlopen(url))).

formatstr, optional

The image file format assumed for reading the data. The image is loaded as a PNG file if format is set to "png", if fname is a path or opened file with a ".png" extension, or if it is a URL. In all other cases, format is ignored and the format is auto-detected by PIL.Image.open.

Returns:

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.

PNG images are returned as float arrays (0-1). All other formats are returned as int arrays, with a bit depth determined by the file's contents.

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

Colormap and save an array as an image file.

RGB(A) images are passed through. Single channel images will be colormapped according to cmap and norm.

Note

If you want to save a single channel image as gray scale please use an image I/O library (such as pillow, tifffile, or imageio) directly.

Parameters:

fnamestr or path-like or file-like

A 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-like

The image data. Accepts NumPy arrays or sequences (e.g., lists or tuples). The shape can be one of MxN (luminance), MxNx3 (RGB) or MxNx4 (RGBA).

vmin, vmaxfloat, 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.

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

A Colormap instance or registered colormap name. The colormap maps scalar data to colors. It is ignored for RGB(A) data.

formatstr, optional

The file format, e.g. 'png', 'pdf', 'svg', ... The behavior when this is unset is documented under fname.

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

Indicates whether the (0, 0) index of the array is in the upper left or lower left corner of the Axes.

dpifloat

The DPI to store in the metadata of the file. This does not affect the resolution of the output image. Depending on file format, this may be rounded to the nearest integer.

metadatadict, optional

Metadata in the image file. The supported keys depend on the output format, see the documentation of the respective backends for more information. Currently only supported for "png", "pdf", "ps", "eps", and "svg".

pil_kwargsdict, optional

Keyword arguments passed to PIL.Image.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 int 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]#

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

See Pillow for a replacement.

Parameters:

infilestr or file-like

The image file. Matplotlib relies on Pillow for image reading, and thus supports a wide range of file formats, including PNG, JPG, TIFF and others.

thumbfilestr or file-like

The thumbnail filename.

scalefloat, default: 0.1

The scale factor for the thumbnail.

interpolationstr, default: 'bilinear'

The interpolation scheme used in the resampling. See the interpolation parameter of imshow for possible values.

previewbool, default: False

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 Figure.savefig would normally do.

Returns:

Figure

The figure instance containing the thumbnail.

Notes

Deprecated since version 3.11: Use Pillow's PIL.Image.Image.thumbnail instead.