set_height_ratios(height_ratios)[source]

Set the relative heights of the rows. height_ratios must be of length nrows. Each row gets a relative height of height_ratios[i] / sum(height_ratios).


set_width_ratios(width_ratios)[source]

Set the relative widths of the columns. width_ratios must be of length ncols. Each column gets a relative width of width_ratios[i] / sum(width_ratios).


subplots(*, sharex=False, sharey=False, squeeze=True, subplot_kw=None)[source]

Add all subplots specified by this GridSpec to its parent figure. See Figure.subplots for detailed documentation.


matplotlib.gridspec.GridSpecFromSubplotSpec   classmatplotlib.gridspec.GridSpecFromSubplotSpec(nrows, ncols, subplot_spec, wspace=None, hspace=None, height_ratios=None, width_ratios=None)[source]

Bases: matplotlib.gridspec.GridSpecBase GridSpec whose subplot layout parameters are inherited from the location specified by a given SubplotSpec.  Parameters

nrows, ncolsint

Number of rows and number of columns of the grid.
subplot_specSubplotSpec

Spec from which the layout parameters are inherited.
wspace, hspacefloat, optional

See GridSpec for more details. If not specified default values (from the figure or rcParams) are used.
height_ratiosarray-like of length nrows, optional

See GridSpecBase for details.
width_ratiosarray-like of length ncols, optional

See GridSpecBase for details.       get_subplot_params(figure=None)[source]

Return a dictionary of subplot layout parameters.
   get_topmost_subplotspec()[source]

Return the topmost SubplotSpec instance associated with the subplot.

  Examples using matplotlib.gridspec.GridSpecFromSubplotSpec

   Resizing axes with constrained layout

   Nested Gridspecs

   Nested GridSpecs

   Constrained Layout Guide

   Arranging multiple Axes in a Figure


get_subplot_params(figure=None)[source]

Return a dictionary of subplot layout parameters.


get_topmost_subplotspec()[source]

Return the topmost SubplotSpec instance associated with the subplot.


matplotlib.gridspec.SubplotSpec   classmatplotlib.gridspec.SubplotSpec(gridspec, num1, num2=None)[source]

Bases: object The location of a subplot in a GridSpec.  Note Likely, you'll never instantiate a SubplotSpec yourself. Instead you will typically obtain one from a GridSpec using item-access.   Parameters

gridspecGridSpec

The GridSpec, which the subplot is referencing.
num1, num2int

The subplot will occupy the num1-th cell of the given gridspec. If num2 is provided, the subplot will span between num1-th cell and num2-th cell inclusive. The index starts from 0.       propertycolspan

The columns spanned by this subplot, as a range object.
   get_geometry()[source]

Return the subplot geometry as tuple (n_rows, n_cols, start, stop). The indices start and stop define the range of the subplot within the GridSpec. stop is inclusive (i.e. for a single cell start == stop).
   get_gridspec()[source]

   get_position(figure, return_all=<deprecated parameter>)[source]

Update the subplot position from figure.subplotpars.
   get_topmost_subplotspec()[source]

Return the topmost SubplotSpec instance associated with the subplot.
   is_first_col()[source]

   is_first_row()[source]

   is_last_col()[source]

   is_last_row()[source]

   propertynum2

   propertyrowspan

The rows spanned by this subplot, as a range object.
   subgridspec(nrows, ncols, **kwargs)[source]

Create a GridSpec within this subplot. The created GridSpecFromSubplotSpec will have this SubplotSpec as a parent.  Parameters

nrowsint

Number of rows in grid.
ncolsint

Number or columns in grid.    Returns
 GridSpecFromSubplotSpec
  Other Parameters
 **kwargs

All other parameters are passed to GridSpecFromSubplotSpec.      See also  matplotlib.pyplot.subplots
  Examples Adding three subplots in the space occupied by a single subplot: fig = plt.figure()
gs0 = fig.add_gridspec(3, 1)
ax1 = fig.add_subplot(gs0[0])
ax2 = fig.add_subplot(gs0[1])
gssub = gs0[2].subgridspec(1, 3)
for i in range(3):
    fig.add_subplot(gssub[0, i])

  Examples using matplotlib.gridspec.SubplotSpec

   Nested GridSpecs

   Constrained Layout Guide

   Arranging multiple Axes in a Figure


get_geometry()[source]

Return the subplot geometry as tuple (n_rows, n_cols, start, stop). The indices start and stop define the range of the subplot within the GridSpec. stop is inclusive (i.e. for a single cell start == stop).


get_position(figure, return_all=<deprecated parameter>)[source]

Update the subplot position from figure.subplotpars.


subgridspec(nrows, ncols, **kwargs)[source]

Create a GridSpec within this subplot. The created GridSpecFromSubplotSpec will have this SubplotSpec as a parent.  Parameters

nrowsint

Number of rows in grid.
ncolsint

Number or columns in grid.    Returns
 GridSpecFromSubplotSpec
  Other Parameters
 **kwargs

All other parameters are passed to GridSpecFromSubplotSpec.      See also  matplotlib.pyplot.subplots
  Examples Adding three subplots in the space occupied by a single subplot: fig = plt.figure()
gs0 = fig.add_gridspec(3, 1)
ax1 = fig.add_subplot(gs0[0])
ax2 = fig.add_subplot(gs0[1])
gssub = gs0[2].subgridspec(1, 3)
for i in range(3):
    fig.add_subplot(gssub[0, i])


matplotlib.image The image module supports basic image loading, rescaling and display operations.   classmatplotlib.image.AxesImage(ax, cmap=None, norm=None, interpolation=None, origin=None, extent=None, filternorm=True, filterrad=4.0, resample=False, *, interpolation_stage=None, **kwargs)[source]

Bases: matplotlib.image._ImageBase An image 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.
normNormalize

Maps 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', '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

normmatplotlib.colors.Normalize (or subclass thereof)

The 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

The colormap used to map normalized data values to RGBA colors.       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. 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(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 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>, 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. 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
alpha float or 2D array-like or None
animated bool
array array-like
clim (vmin: float, vmax: float)
clip_box Bbox
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
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
transform Transform
url str
visible bool
zorder float
   set_extent(extent)[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.     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.

   classmatplotlib.image.BboxImage(bbox, cmap=None, norm=None, interpolation=None, origin=None, filternorm=True, filterrad=4.0, resample=False, **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(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. 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(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 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>, 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. 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
alpha float or 2D array-like or None
animated bool
array array-like
clim (vmin: float, vmax: float)
clip_box Bbox
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
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
transform Transform
url str
visible bool
zorder float

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

Bases: matplotlib.image._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) 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>, 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. 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
alpha float or 2D array-like or None
animated bool
array array-like
clim (vmin: float, vmax: float)
clip_box Bbox
clip_on bool
clip_path Patch or (Path, Transform) or None
cmap Colormap or str or None
data unknown
figure Figure
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
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

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

Bases: matplotlib.image.AxesImage  Parameters

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

**kwargs

All other keyword arguments are identical to those of AxesImage.       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) 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.
   mouseover=False

   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>, 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. 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
alpha float or 2D array-like or None
animated bool
array unknown
clim (vmin: float, vmax: float)
clip_box Bbox
clip_on bool
clip_path Patch or (Path, Transform) or None
cmap unknown
data unknown
extent 4-tuple of float
figure Figure
filternorm unknown
filterrad unknown
gid str
in_layout bool
interpolation {'nearest', 'bilinear'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm unknown
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
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(s)[source]

Set whether the resize filter normalizes the weights. See help for imshow.  Parameters

filternormbool

   set_filterrad(s)[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: 'antialiased').
   set_norm(norm)[source]

Set the normalization instance.  Parameters

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

   classmatplotlib.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.  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.
normNormalize

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) 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>, 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. 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
alpha float or 2D array-like or None
animated bool
array unknown
clim (vmin: float, vmax: float)
clip_box Bbox
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
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
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

imageuint8 array (M, N, 4)

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

Save an array as an image file.  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. 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.
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]

Make a thumbnail of image in infile with output filename thumbfile. See Image Thumbnail.  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.


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

Bases: matplotlib.image._ImageBase An image 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.
normNormalize

Maps 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', '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

normmatplotlib.colors.Normalize (or subclass thereof)

The 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

The colormap used to map normalized data values to RGBA colors.       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. 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(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 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>, 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. 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
alpha float or 2D array-like or None
animated bool
array array-like
clim (vmin: float, vmax: float)
clip_box Bbox
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
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
transform Transform
url str
visible bool
zorder float
   set_extent(extent)[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.     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.


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. 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(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 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>, 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. 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
alpha float or 2D array-like or None
animated bool
array array-like
clim (vmin: float, vmax: float)
clip_box Bbox
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
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
transform Transform
url str
visible bool
zorder float


set_extent(extent)[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.     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.


classmatplotlib.image.BboxImage(bbox, cmap=None, norm=None, interpolation=None, origin=None, filternorm=True, filterrad=4.0, resample=False, **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(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. 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(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 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>, 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. 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
alpha float or 2D array-like or None
animated bool
array array-like
clim (vmin: float, vmax: float)
clip_box Bbox
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
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
transform Transform
url str
visible bool
zorder float


contains(mouseevent)[source]

Test whether the mouse event occurred within the image.


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>, 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. 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
alpha float or 2D array-like or None
animated bool
array array-like
clim (vmin: float, vmax: float)
clip_box Bbox
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
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
transform Transform
url str
visible bool
zorder float


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

imageuint8 array (M, N, 4)

The composited RGBA image.
offset_x, offset_yfloat

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


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

Bases: matplotlib.image._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) 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>, 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. 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
alpha float or 2D array-like or None
animated bool
array array-like
clim (vmin: float, vmax: float)
clip_box Bbox
clip_on bool
clip_path Patch or (Path, Transform) or None
cmap Colormap or str or None
data unknown
figure Figure
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
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


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>, 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. 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
alpha float or 2D array-like or None
animated bool
array array-like
clim (vmin: float, vmax: float)
clip_box Bbox
clip_on bool
clip_path Patch or (Path, Transform) or None
cmap Colormap or str or None
data unknown
figure Figure
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
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.


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

Save an array as an image file.  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. 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.
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.


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

Bases: matplotlib.image.AxesImage  Parameters

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

**kwargs

All other keyword arguments are identical to those of AxesImage.       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) 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.
   mouseover=False

   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>, 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. 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
alpha float or 2D array-like or None
animated bool
array unknown
clim (vmin: float, vmax: float)
clip_box Bbox
clip_on bool
clip_path Patch or (Path, Transform) or None
cmap unknown
data unknown
extent 4-tuple of float
figure Figure
filternorm unknown
filterrad unknown
gid str
in_layout bool
interpolation {'nearest', 'bilinear'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm unknown
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
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(s)[source]

Set whether the resize filter normalizes the weights. See help for imshow.  Parameters

filternormbool

   set_filterrad(s)[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: 'antialiased').
   set_norm(norm)[source]

Set the normalization instance.  Parameters

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


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>, 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. 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
alpha float or 2D array-like or None
animated bool
array unknown
clim (vmin: float, vmax: float)
clip_box Bbox
clip_on bool
clip_path Patch or (Path, Transform) or None
cmap unknown
data unknown
extent 4-tuple of float
figure Figure
filternorm unknown
filterrad unknown
gid str
in_layout bool
interpolation {'nearest', 'bilinear'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm unknown
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
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(s)[source]

Set whether the resize filter normalizes the weights. See help for imshow.  Parameters

filternormbool


set_filterrad(s)[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: 'antialiased').


set_norm(norm)[source]

Set the normalization instance.  Parameters

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


classmatplotlib.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.  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.
normNormalize

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) 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>, 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. 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
alpha float or 2D array-like or None
animated bool
array unknown
clim (vmin: float, vmax: float)
clip_box Bbox
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
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
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


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) 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>, 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. 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
alpha float or 2D array-like or None
animated bool
array unknown
clim (vmin: float, vmax: float)
clip_box Bbox
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
filternorm bool
filterrad positive float
gid str
in_layout bool
interpolation {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
interpolation_stage {'data', 'rgba'} or None
label object
norm Normalize or None
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
resample bool or None
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
transform Transform
url str
visible bool
zorder float


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

Make a thumbnail of image in infile with output filename thumbfile. See Image Thumbnail.  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.


matplotlib.interactive(b)[source]

Set whether to redraw after every plotting command (e.g. pyplot.xlabel).


matplotlib.is_interactive()[source]

Return whether to redraw after every plotting command.  Note This function is only intended for use in backends. End users should use pyplot.isinteractive instead.


matplotlib.legend The legend module defines the Legend class, which is responsible for drawing legends associated with axes and/or figures.  Important It is unlikely that you would ever create a Legend instance manually. Most users would normally create a legend via the legend function. For more details on legends there is also a legend guide.  The Legend class is a container of legend handles and legend texts. The legend handler map specifies how to create legend handles from artists (lines, patches, etc.) in the axes or figures. Default legend handlers are defined in the legend_handler module. While not all artist types are covered by the default legend handlers, custom legend handlers can be defined to support arbitrary objects. See the legend guide for more information.   classmatplotlib.legend.DraggableLegend(legend, use_blit=False, update='loc')[source]

Bases: matplotlib.offsetbox.DraggableOffsetBox Wrapper around a Legend to support mouse dragging.  Parameters

legendLegend

The Legend instance to wrap.
use_blitbool, optional

Use blitting for faster image composition. For details see FuncAnimation.
update{'loc', 'bbox'}, optional

If "loc", update the loc parameter of the legend upon finalizing. If "bbox", update the bbox_to_anchor parameter.       finalize_offset()[source]

   classmatplotlib.legend.Legend(parent, handles, labels, loc=None, numpoints=None, markerscale=None, markerfirst=True, scatterpoints=None, scatteryoffsets=None, prop=None, fontsize=None, labelcolor=None, borderpad=None, labelspacing=None, handlelength=None, handleheight=None, handletextpad=None, borderaxespad=None, columnspacing=None, ncol=1, mode=None, fancybox=None, shadow=None, title=None, title_fontsize=None, framealpha=None, edgecolor=None, facecolor=None, bbox_to_anchor=None, bbox_transform=None, frameon=None, handler_map=None, title_fontproperties=None)[source]

Bases: matplotlib.artist.Artist Place a legend on the axes at location loc.  Parameters

parentAxes or Figure

The artist that contains the legend.
handleslist of Artist

A list of Artists (lines, patches) to be added to the legend.
labelslist of str

A list of labels to show next to the artists. The length of handles and labels should be the same. If they are not, they are truncated to the smaller of both lengths.    Other Parameters

locstr or pair of floats, default: rcParams["legend.loc"] (default: 'best') ('best' for axes, 'upper right' for figures)

The location of the legend. The strings 'upper left', 'upper right', 'lower left', 'lower right' place the legend at the corresponding corner of the axes/figure. The strings 'upper center', 'lower center', 'center left', 'center right' place the legend at the center of the corresponding edge of the axes/figure. The string 'center' places the legend at the center of the axes/figure. The string 'best' places the legend at the location, among the nine locations defined so far, with the minimum overlap with other drawn artists. This option can be quite slow for plots with large amounts of data; your plotting speed may benefit from providing a specific location. The location can also be a 2-tuple giving the coordinates of the lower-left corner of the legend in axes coordinates (in which case bbox_to_anchor will be ignored). For back-compatibility, 'center right' (but no other location) can also be spelled 'right', and each "string" locations can also be given as a numeric value:
Location String Location Code
'best' 0
'upper right' 1
'upper left' 2
'lower left' 3
'lower right' 4
'right' 5
'center left' 6
'center right' 7
'lower center' 8
'upper center' 9
'center' 10
bbox_to_anchorBboxBase, 2-tuple, or 4-tuple of floats

Box that is used to position the legend in conjunction with loc. Defaults to axes.bbox (if called as a method to Axes.legend) or figure.bbox (if Figure.legend). This argument allows arbitrary placement of the legend. Bbox coordinates are interpreted in the coordinate system given by bbox_transform, with the default transform Axes or Figure coordinates, depending on which legend is called. If a 4-tuple or BboxBase is given, then it specifies the bbox (x, y, width, height) that the legend is placed in. To put the legend in the best location in the bottom right quadrant of the axes (or figure): loc='best', bbox_to_anchor=(0.5, 0., 0.5, 0.5)
 A 2-tuple (x, y) places the corner of the legend specified by loc at x, y. For example, to put the legend's upper right-hand corner in the center of the axes (or figure) the following keywords can be used: loc='upper right', bbox_to_anchor=(0.5, 0.5)

ncolint, default: 1

The number of columns that the legend has.
propNone or matplotlib.font_manager.FontProperties or dict

The font properties of the legend. If None (default), the current matplotlib.rcParams will be used.
fontsizeint or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

The font size of the legend. If the value is numeric the size will be the absolute font size in points. String values are relative to the current default font size. This argument is only used if prop is not specified.
labelcolorstr or list, default: rcParams["legend.labelcolor"] (default: 'None')

The color of the text in the legend. Either a valid color string (for example, 'red'), or a list of color strings. The labelcolor can also be made to match the color of the line or marker using 'linecolor', 'markerfacecolor' (or 'mfc'), or 'markeredgecolor' (or 'mec'). Labelcolor can be set globally using rcParams["legend.labelcolor"] (default: 'None'). If None, use rcParams["text.color"] (default: 'black').
numpointsint, default: rcParams["legend.numpoints"] (default: 1)

The number of marker points in the legend when creating a legend entry for a Line2D (line).
scatterpointsint, default: rcParams["legend.scatterpoints"] (default: 1)

The number of marker points in the legend when creating a legend entry for a PathCollection (scatter plot).
scatteryoffsetsiterable of floats, default: [0.375, 0.5, 0.3125]

The vertical offset (relative to the font size) for the markers created for a scatter plot legend entry. 0.0 is at the base the legend text, and 1.0 is at the top. To draw all markers at the same height, set to [0.5].
markerscalefloat, default: rcParams["legend.markerscale"] (default: 1.0)

The relative size of legend markers compared with the originally drawn ones.
markerfirstbool, default: True

If True, legend marker is placed to the left of the legend label. If False, legend marker is placed to the right of the legend label.
frameonbool, default: rcParams["legend.frameon"] (default: True)

Whether the legend should be drawn on a patch (frame).
fancyboxbool, default: rcParams["legend.fancybox"] (default: True)

Whether round edges should be enabled around the FancyBboxPatch which makes up the legend's background.
shadowbool, default: rcParams["legend.shadow"] (default: False)

Whether to draw a shadow behind the legend.
framealphafloat, default: rcParams["legend.framealpha"] (default: 0.8)

The alpha transparency of the legend's background. If shadow is activated and framealpha is None, the default value is ignored.
facecolor"inherit" or color, default: rcParams["legend.facecolor"] (default: 'inherit')

The legend's background color. If "inherit", use rcParams["axes.facecolor"] (default: 'white').
edgecolor"inherit" or color, default: rcParams["legend.edgecolor"] (default: '0.8')

The legend's background patch edge color. If "inherit", use take rcParams["axes.edgecolor"] (default: 'black').
mode{"expand", None}

If mode is set to "expand" the legend will be horizontally expanded to fill the axes area (or bbox_to_anchor if defines the legend's size).
bbox_transformNone or matplotlib.transforms.Transform

The transform for the bounding box (bbox_to_anchor). For a value of None (default) the Axes' transAxes transform will be used.
titlestr or None

The legend's title. Default is no title (None).
title_fontpropertiesNone or matplotlib.font_manager.FontProperties or dict

The font properties of the legend's title. If None (default), the title_fontsize argument will be used if present; if title_fontsize is also None, the current rcParams["legend.title_fontsize"] (default: None) will be used.
title_fontsizeint or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: rcParams["legend.title_fontsize"] (default: None)

The font size of the legend's title. Note: This cannot be combined with title_fontproperties. If you want to set the fontsize alongside other font properties, use the size parameter in title_fontproperties.
borderpadfloat, default: rcParams["legend.borderpad"] (default: 0.4)

The fractional whitespace inside the legend border, in font-size units.
labelspacingfloat, default: rcParams["legend.labelspacing"] (default: 0.5)

The vertical space between the legend entries, in font-size units.
handlelengthfloat, default: rcParams["legend.handlelength"] (default: 2.0)

The length of the legend handles, in font-size units.
handleheightfloat, default: rcParams["legend.handleheight"] (default: 0.7)

The height of the legend handles, in font-size units.
handletextpadfloat, default: rcParams["legend.handletextpad"] (default: 0.8)

The pad between the legend handle and text, in font-size units.
borderaxespadfloat, default: rcParams["legend.borderaxespad"] (default: 0.5)

The pad between the axes and legend border, in font-size units.
columnspacingfloat, default: rcParams["legend.columnspacing"] (default: 2.0)

The spacing between columns, in font-size units.
handler_mapdict or None

The custom dictionary mapping instances or types to a legend handler. This handler_map updates the default handler map found at matplotlib.legend.Legend.get_legend_handler_map.     Notes Users can specify any arbitrary location for the legend using the bbox_to_anchor keyword argument. bbox_to_anchor can be a BboxBase (or derived there from) or a tuple of 2 or 4 floats. See set_bbox_to_anchor for more detail. The legend location can be specified by setting loc with a tuple of 2 floats, which is interpreted as the lower-left corner of the legend in the normalized axes coordinate.   codes={'best': 0, 'center': 10, 'center left': 6, 'center right': 7, 'lower center': 8, 'lower left': 3, 'lower right': 4, 'right': 5, 'upper center': 9, 'upper left': 2, 'upper right': 1}

   contains(event)[source]

Test whether the artist contains the mouse event.  Parameters

mouseeventmatplotlib.backend_bases.MouseEvent

  Returns

containsbool

Whether any values are within the radius.
detailsdict

An artist-specific dictionary of details of the event context, such as which points are contained in the pick radius. See the individual Artist subclasses for details.
   draw(renderer)[source]

Draw the Artist (and its children) using the given renderer. This has no effect if the artist is not visible (Artist.get_visible returns False).  Parameters

rendererRendererBase subclass.

   Notes This method is overridden in the Artist subclasses.
   draw_frame(b)[source]

Set whether the legend box patch is drawn.  Parameters

bbool

   get_bbox_to_anchor()[source]

Return the bbox that the legend will be anchored to.
   get_children()[source]

Return a list of the child Artists of this Artist.
   classmethodget_default_handler_map()[source]

A class method that returns the default handler map.
   get_draggable()[source]

Return True if the legend is draggable, False otherwise.
   get_frame()[source]

Return the Rectangle used to frame the legend.
   get_frame_on()[source]

Get whether the legend box patch is drawn.
   staticget_legend_handler(legend_handler_map, orig_handle)[source]

Return a legend handler from legend_handler_map that corresponds to orig_handler. legend_handler_map should be a dictionary object (that is returned by the get_legend_handler_map method). It first checks if the orig_handle itself is a key in the legend_handler_map and return the associated value. Otherwise, it checks for each of the classes in its method-resolution-order. If no matching key is found, it returns None.
   get_legend_handler_map()[source]

Return the handler map.
   get_lines()[source]

Return the list of Line2Ds in the legend.
   get_patches()[source]

Return the list of Patchs in the legend.
   get_texts()[source]

Return the list of Texts in the legend.
   get_tightbbox(renderer)[source]

Like Artist.get_window_extent, but includes any clipping.  Parameters

rendererRendererBase subclass

renderer that will be used to draw the figures (i.e. fig.canvas.get_renderer())    Returns
 Bbox

The enclosing bounding box (in figure pixel coordinates).
   get_title()[source]

Return the Text instance for the legend title.
   get_window_extent(renderer=None)[source]

Get the artist's 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.
   set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, bbox_to_anchor=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, draggable=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]

Set multiple properties at once. 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
alpha scalar or None
animated bool
bbox_to_anchor BboxBase or tuple
clip_box Bbox
clip_on bool
clip_path Patch or (Path, Transform) or None
draggable bool
figure Figure
frame_on bool
gid str
in_layout bool
label object
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
title unknown
transform Transform
url str
visible bool
zorder float
   set_bbox_to_anchor(bbox, transform=None)[source]

Set the bbox that the legend will be anchored to.  Parameters

bboxBboxBase or tuple

The bounding box can be specified in the following ways:  A BboxBase instance A tuple of (left, bottom, width, height) in the given transform (normalized axes coordinate if None) A tuple of (left, bottom) where the width and height will be assumed to be zero.
None, to remove the bbox anchoring, and use the parent bbox.
transformTransform, optional

A transform to apply to the bounding box. If not specified, this will use a transform to the bounding box of the parent.
   classmethodset_default_handler_map(handler_map)[source]

A class method to set the default handler map.
   set_draggable(state, use_blit=False, update='loc')[source]

Enable or disable mouse dragging support of the legend.  Parameters

statebool

Whether mouse dragging is enabled.
use_blitbool, optional

Use blitting for faster image composition. For details see FuncAnimation.
update{'loc', 'bbox'}, optional

The legend parameter to be changed when dragged:  'loc': update the loc parameter of the legend 'bbox': update the bbox_to_anchor parameter of the legend     Returns

DraggableLegend or None

If state is True this returns the DraggableLegend helper instance. Otherwise this returns None.
   set_frame_on(b)[source]

Set whether the legend box patch is drawn.  Parameters

bbool

   set_title(title, prop=None)[source]

Set the legend title. Fontproperties can be optionally set with prop parameter.
   classmethodupdate_default_handler_map(handler_map)[source]

A class method to update the default handler map.
   zorder=5


classmatplotlib.legend.DraggableLegend(legend, use_blit=False, update='loc')[source]

Bases: matplotlib.offsetbox.DraggableOffsetBox Wrapper around a Legend to support mouse dragging.  Parameters

legendLegend

The Legend instance to wrap.
use_blitbool, optional

Use blitting for faster image composition. For details see FuncAnimation.
update{'loc', 'bbox'}, optional

If "loc", update the loc parameter of the legend upon finalizing. If "bbox", update the bbox_to_anchor parameter.       finalize_offset()[source]


classmatplotlib.legend.Legend(parent, handles, labels, loc=None, numpoints=None, markerscale=None, markerfirst=True, scatterpoints=None, scatteryoffsets=None, prop=None, fontsize=None, labelcolor=None, borderpad=None, labelspacing=None, handlelength=None, handleheight=None, handletextpad=None, borderaxespad=None, columnspacing=None, ncol=1, mode=None, fancybox=None, shadow=None, title=None, title_fontsize=None, framealpha=None, edgecolor=None, facecolor=None, bbox_to_anchor=None, bbox_transform=None, frameon=None, handler_map=None, title_fontproperties=None)[source]

Bases: matplotlib.artist.Artist Place a legend on the axes at location loc.  Parameters

parentAxes or Figure

The artist that contains the legend.
handleslist of Artist

A list of Artists (lines, patches) to be added to the legend.
labelslist of str

A list of labels to show next to the artists. The length of handles and labels should be the same. If they are not, they are truncated to the smaller of both lengths.    Other Parameters

locstr or pair of floats, default: rcParams["legend.loc"] (default: 'best') ('best' for axes, 'upper right' for figures)

The location of the legend. The strings 'upper left', 'upper right', 'lower left', 'lower right' place the legend at the corresponding corner of the axes/figure. The strings 'upper center', 'lower center', 'center left', 'center right' place the legend at the center of the corresponding edge of the axes/figure. The string 'center' places the legend at the center of the axes/figure. The string 'best' places the legend at the location, among the nine locations defined so far, with the minimum overlap with other drawn artists. This option can be quite slow for plots with large amounts of data; your plotting speed may benefit from providing a specific location. The location can also be a 2-tuple giving the coordinates of the lower-left corner of the legend in axes coordinates (in which case bbox_to_anchor will be ignored). For back-compatibility, 'center right' (but no other location) can also be spelled 'right', and each "string" locations can also be given as a numeric value:
Location String Location Code
'best' 0
'upper right' 1
'upper left' 2
'lower left' 3
'lower right' 4
'right' 5
'center left' 6
'center right' 7
'lower center' 8
'upper center' 9
'center' 10
bbox_to_anchorBboxBase, 2-tuple, or 4-tuple of floats

Box that is used to position the legend in conjunction with loc. Defaults to axes.bbox (if called as a method to Axes.legend) or figure.bbox (if Figure.legend). This argument allows arbitrary placement of the legend. Bbox coordinates are interpreted in the coordinate system given by bbox_transform, with the default transform Axes or Figure coordinates, depending on which legend is called. If a 4-tuple or BboxBase is given, then it specifies the bbox (x, y, width, height) that the legend is placed in. To put the legend in the best location in the bottom right quadrant of the axes (or figure): loc='best', bbox_to_anchor=(0.5, 0., 0.5, 0.5)
 A 2-tuple (x, y) places the corner of the legend specified by loc at x, y. For example, to put the legend's upper right-hand corner in the center of the axes (or figure) the following keywords can be used: loc='upper right', bbox_to_anchor=(0.5, 0.5)

ncolint, default: 1

The number of columns that the legend has.
propNone or matplotlib.font_manager.FontProperties or dict

The font properties of the legend. If None (default), the current matplotlib.rcParams will be used.
fontsizeint or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

The font size of the legend. If the value is numeric the size will be the absolute font size in points. String values are relative to the current default font size. This argument is only used if prop is not specified.
labelcolorstr or list, default: rcParams["legend.labelcolor"] (default: 'None')

The color of the text in the legend. Either a valid color string (for example, 'red'), or a list of color strings. The labelcolor can also be made to match the color of the line or marker using 'linecolor', 'markerfacecolor' (or 'mfc'), or 'markeredgecolor' (or 'mec'). Labelcolor can be set globally using rcParams["legend.labelcolor"] (default: 'None'). If None, use rcParams["text.color"] (default: 'black').
numpointsint, default: rcParams["legend.numpoints"] (default: 1)

The number of marker points in the legend when creating a legend entry for a Line2D (line).
scatterpointsint, default: rcParams["legend.scatterpoints"] (default: 1)

The number of marker points in the legend when creating a legend entry for a PathCollection (scatter plot).
scatteryoffsetsiterable of floats, default: [0.375, 0.5, 0.3125]

The vertical offset (relative to the font size) for the markers created for a scatter plot legend entry. 0.0 is at the base the legend text, and 1.0 is at the top. To draw all markers at the same height, set to [0.5].
markerscalefloat, default: rcParams["legend.markerscale"] (default: 1.0)

The relative size of legend markers compared with the originally drawn ones.
markerfirstbool, default: True

If True, legend marker is placed to the left of the legend label. If False, legend marker is placed to the right of the legend label.
frameonbool, default: rcParams["legend.frameon"] (default: True)

Whether the legend should be drawn on a patch (frame).
fancyboxbool, default: rcParams["legend.fancybox"] (default: True)

Whether round edges should be enabled around the FancyBboxPatch which makes up the legend's background.
shadowbool, default: rcParams["legend.shadow"] (default: False)

Whether to draw a shadow behind the legend.
framealphafloat, default: rcParams["legend.framealpha"] (default: 0.8)

The alpha transparency of the legend's background. If shadow is activated and framealpha is None, the default value is ignored.
facecolor"inherit" or color, default: rcParams["legend.facecolor"] (default: 'inherit')

The legend's background color. If "inherit", use rcParams["axes.facecolor"] (default: 'white').
edgecolor"inherit" or color, default: rcParams["legend.edgecolor"] (default: '0.8')

The legend's background patch edge color. If "inherit", use take rcParams["axes.edgecolor"] (default: 'black').
mode{"expand", None}

If mode is set to "expand" the legend will be horizontally expanded to fill the axes area (or bbox_to_anchor if defines the legend's size).
bbox_transformNone or matplotlib.transforms.Transform

The transform for the bounding box (bbox_to_anchor). For a value of None (default) the Axes' transAxes transform will be used.
titlestr or None

The legend's title. Default is no title (None).
title_fontpropertiesNone or matplotlib.font_manager.FontProperties or dict

The font properties of the legend's title. If None (default), the title_fontsize argument will be used if present; if title_fontsize is also None, the current rcParams["legend.title_fontsize"] (default: None) will be used.
title_fontsizeint or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: rcParams["legend.title_fontsize"] (default: None)

The font size of the legend's title. Note: This cannot be combined with title_fontproperties. If you want to set the fontsize alongside other font properties, use the size parameter in title_fontproperties.
borderpadfloat, default: rcParams["legend.borderpad"] (default: 0.4)

The fractional whitespace inside the legend border, in font-size units.
labelspacingfloat, default: rcParams["legend.labelspacing"] (default: 0.5)

The vertical space between the legend entries, in font-size units.
handlelengthfloat, default: rcParams["legend.handlelength"] (default: 2.0)

The length of the legend handles, in font-size units.
handleheightfloat, default: rcParams["legend.handleheight"] (default: 0.7)

The height of the legend handles, in font-size units.
handletextpadfloat, default: rcParams["legend.handletextpad"] (default: 0.8)

The pad between the legend handle and text, in font-size units.
borderaxespadfloat, default: rcParams["legend.borderaxespad"] (default: 0.5)

The pad between the axes and legend border, in font-size units.
columnspacingfloat, default: rcParams["legend.columnspacing"] (default: 2.0)

The spacing between columns, in font-size units.
handler_mapdict or None

The custom dictionary mapping instances or types to a legend handler. This handler_map updates the default handler map found at matplotlib.legend.Legend.get_legend_handler_map.     Notes Users can specify any arbitrary location for the legend using the bbox_to_anchor keyword argument. bbox_to_anchor can be a BboxBase (or derived there from) or a tuple of 2 or 4 floats. See set_bbox_to_anchor for more detail. The legend location can be specified by setting loc with a tuple of 2 floats, which is interpreted as the lower-left corner of the legend in the normalized axes coordinate.   codes={'best': 0, 'center': 10, 'center left': 6, 'center right': 7, 'lower center': 8, 'lower left': 3, 'lower right': 4, 'right': 5, 'upper center': 9, 'upper left': 2, 'upper right': 1}

   contains(event)[source]

Test whether the artist contains the mouse event.  Parameters

mouseeventmatplotlib.backend_bases.MouseEvent

  Returns

containsbool

Whether any values are within the radius.
detailsdict

An artist-specific dictionary of details of the event context, such as which points are contained in the pick radius. See the individual Artist subclasses for details.
   draw(renderer)[source]

Draw the Artist (and its children) using the given renderer. This has no effect if the artist is not visible (Artist.get_visible returns False).  Parameters

rendererRendererBase subclass.

   Notes This method is overridden in the Artist subclasses.
   draw_frame(b)[source]

Set whether the legend box patch is drawn.  Parameters

bbool

   get_bbox_to_anchor()[source]

Return the bbox that the legend will be anchored to.
   get_children()[source]

Return a list of the child Artists of this Artist.
   classmethodget_default_handler_map()[source]

A class method that returns the default handler map.
   get_draggable()[source]

Return True if the legend is draggable, False otherwise.
   get_frame()[source]

Return the Rectangle used to frame the legend.
   get_frame_on()[source]

Get whether the legend box patch is drawn.
   staticget_legend_handler(legend_handler_map, orig_handle)[source]

Return a legend handler from legend_handler_map that corresponds to orig_handler. legend_handler_map should be a dictionary object (that is returned by the get_legend_handler_map method). It first checks if the orig_handle itself is a key in the legend_handler_map and return the associated value. Otherwise, it checks for each of the classes in its method-resolution-order. If no matching key is found, it returns None.
   get_legend_handler_map()[source]

Return the handler map.
   get_lines()[source]

Return the list of Line2Ds in the legend.
   get_patches()[source]

Return the list of Patchs in the legend.
   get_texts()[source]

Return the list of Texts in the legend.
   get_tightbbox(renderer)[source]

Like Artist.get_window_extent, but includes any clipping.  Parameters

rendererRendererBase subclass

renderer that will be used to draw the figures (i.e. fig.canvas.get_renderer())    Returns
 Bbox

The enclosing bounding box (in figure pixel coordinates).
   get_title()[source]

Return the Text instance for the legend title.
   get_window_extent(renderer=None)[source]

Get the artist's 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.
   set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, bbox_to_anchor=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, draggable=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]

Set multiple properties at once. 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
alpha scalar or None
animated bool
bbox_to_anchor BboxBase or tuple
clip_box Bbox
clip_on bool
clip_path Patch or (Path, Transform) or None
draggable bool
figure Figure
frame_on bool
gid str
in_layout bool
label object
path_effects AbstractPathEffect
picker None or bool or float or callable
rasterized bool
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
title unknown
transform Transform
url str
visible bool
zorder float
   set_bbox_to_anchor(bbox, transform=None)[source]

Set the bbox that the legend will be anchored to.  Parameters

bboxBboxBase or tuple

The bounding box can be specified in the following ways:  A BboxBase instance A tuple of (left, bottom, width, height) in the given transform (normalized axes coordinate if None) A tuple of (left, bottom) where the width and height will be assumed to be zero.
None, to remove the bbox anchoring, and use the parent bbox.
transformTransform, optional

A transform to apply to the bounding box. If not specified, this will use a transform to the bounding box of the parent.
   classmethodset_default_handler_map(handler_map)[source]

A class method to set the default handler map.
   set_draggable(state, use_blit=False, update='loc')[source]

Enable or disable mouse dragging support of the legend.  Parameters

statebool

Whether mouse dragging is enabled.
use_blitbool, optional

Use blitting for faster image composition. For details see FuncAnimation.
update{'loc', 'bbox'}, optional

The legend parameter to be changed when dragged:  'loc': update the loc parameter of the legend 'bbox': update the bbox_to_anchor parameter of the legend     Returns

DraggableLegend or None

If state is True this returns the DraggableLegend helper instance. Otherwise this returns None.
   set_frame_on(b)[source]

Set whether the legend box patch is drawn.  Parameters

bbool

   set_title(title, prop=None)[source]

Set the legend title. Fontproperties can be optionally set with prop parameter.
   classmethodupdate_default_handler_map(handler_map)[source]

A class method to update the default handler map.
   zorder=5


codes={'best': 0, 'center': 10, 'center left': 6, 'center right': 7, 'lower center': 8, 'lower left': 3, 'lower right': 4, 'right': 5, 'upper center': 9, 'upper left': 2, 'upper right': 1}


contains(event)[source]

Test whether the artist contains the mouse event.  Parameters

mouseeventmatplotlib.backend_bases.MouseEvent

  Returns

containsbool

Whether any values are within the radius.
detailsdict

An artist-specific dictionary of details of the event context, such as which points are contained in the pick radius. See the individual Artist subclasses for details.


draw(renderer)[source]

Draw the Artist (and its children) using the given renderer. This has no effect if the artist is not visible (Artist.get_visible returns False).  Parameters

rendererRendererBase subclass.

   Notes This method is overridden in the Artist subclasses.


draw_frame(b)[source]

Set whether the legend box patch is drawn.  Parameters

bbool


get_bbox_to_anchor()[source]

Return the bbox that the legend will be anchored to.


get_children()[source]

Return a list of the child Artists of this Artist.


classmethodget_default_handler_map()[source]

A class method that returns the default handler map.


get_draggable()[source]

Return True if the legend is draggable, False otherwise.


get_frame()[source]

Return the Rectangle used to frame the legend.


get_frame_on()[source]

Get whether the legend box patch is drawn.


staticget_legend_handler(legend_handler_map, orig_handle)[source]

Return a legend handler from legend_handler_map that corresponds to orig_handler. legend_handler_map should be a dictionary object (that is returned by the get_legend_handler_map method). It first checks if the orig_handle itself is a key in the legend_handler_map and return the associated value. Otherwise, it checks for each of the classes in its method-resolution-order. If no matching key is found, it returns None.