matplotlib.image
#
The image module supports basic image loading, rescaling and display operations.
- class matplotlib.image.AxesImage(ax, *, cmap=None, norm=None, interpolation=None, origin=None, extent=None, filternorm=True, filterrad=4.0, resample=False, interpolation_stage=None, **kwargs)[source]#
Bases:
_ImageBase
An image attached to an Axes.
- Parameters:
- ax
Axes
The axes the image will belong to.
- cmapstr or
Colormap
, default:rcParams["image.cmap"]
(default:'viridis'
) The Colormap instance or registered colormap name used to map scalar data to colors.
- normstr or
Normalize
Maps luminance to 0-1.
- interpolationstr, default:
rcParams["image.interpolation"]
(default:'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.
- **kwargs
Artist
properties
- ax
- Parameters:
- norm
Normalize
(or subclass thereof) or str or None The normalizing object which scales data, typically into the interval
[0, 1]
. If astr
, aNormalize
subclass is dynamically generated based on the scale with the corresponding name. 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.
- norm
- get_cursor_data(event)[source]#
Return the image value at the event position or None if the event is outside 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>, extent=<UNSET>, filternorm=<UNSET>, filterrad=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, interpolation=<UNSET>, interpolation_stage=<UNSET>, label=<UNSET>, mouseover=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, resample=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#
Set multiple properties at once.
Supported properties are
Property
Description
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha
float or 2D array-like or None
bool
array
array-like
(vmin: float, vmax: float)
bool
Patch or (Path, Transform) or None
Colormap
or str or Nonedata
array-like or
PIL.Image.Image
4-tuple of float
filternorm
bool
filterrad
positive float
str
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
object
bool
Normalize
or str or NoneNone or bool or float or callable
bool
resample
bool or None
(scale: float, length: float, randomness: float)
bool or None
str
bool
float
- set_extent(extent, **kwargs)[source]#
Set the image extent.
- Parameters:
- extent4-tuple of float
The position and size of the image as tuple
(left, right, bottom, top)
in data coordinates.- **kwargs
Other parameters from which unit info (i.e., the xunits, yunits, zunits (for 3D axes), runits and thetaunits (for polar axes) entries are applied, if present.
Notes
This updates
ax.dataLim
, and, if autoscaling, setsax.viewLim
to tightly fit the image, regardless ofdataLim
. Autoscaling state is not changed, so following this withax.autoscale_view()
will redo the autoscaling in accord withdataLim
.
- class matplotlib.image.BboxImage(bbox, *, cmap=None, norm=None, interpolation=None, origin=None, filternorm=True, filterrad=4.0, resample=False, **kwargs)[source]#
Bases:
_ImageBase
The Image class whose size is determined by the given bbox.
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_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>, mouseover=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, resample=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#
Set multiple properties at once.
Supported properties are
Property
Description
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha
float or 2D array-like or None
bool
array
array-like
(vmin: float, vmax: float)
bool
Patch or (Path, Transform) or None
Colormap
or str or Nonedata
array-like or
PIL.Image.Image
filternorm
bool
filterrad
positive float
str
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
object
bool
Normalize
or str or NoneNone or bool or float or callable
bool
resample
bool or None
(scale: float, length: float, randomness: float)
bool or None
str
bool
float
- class matplotlib.image.FigureImage(fig, *, cmap=None, norm=None, offsetx=0, offsety=0, origin=None, **kwargs)[source]#
Bases:
_ImageBase
An image attached to a figure.
cmap is a colors.Colormap instance norm is a colors.Normalize instance to map luminance to 0-1
kwargs are an optional list of Artist keyword args
- 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>, mouseover=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, resample=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#
Set multiple properties at once.
Supported properties are
Property
Description
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha
float or 2D array-like or None
bool
array
array-like
(vmin: float, vmax: float)
bool
Patch or (Path, Transform) or None
Colormap
or str or Noneunknown
filternorm
bool
filterrad
positive float
str
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
object
bool
Normalize
or str or NoneNone or bool or float or callable
bool
resample
bool or None
(scale: float, length: float, randomness: float)
bool or None
str
bool
float
- zorder = 0#
- class matplotlib.image.NonUniformImage(ax, *, interpolation='nearest', **kwargs)[source]#
Bases:
AxesImage
- Parameters:
- 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>, mouseover=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, resample=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#
Set multiple properties at once.
Supported properties are
Property
Description
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha
float or 2D array-like or None
bool
array
unknown
(vmin: float, vmax: float)
bool
Patch or (Path, Transform) or None
unknown
unknown
4-tuple of float
filternorm
unknown
filterrad
unknown
str
bool
{'nearest', 'bilinear'} or None
interpolation_stage
{'data', 'rgba'} or None
object
bool
unknown
None or bool or float or callable
bool
resample
bool or None
(scale: float, length: float, randomness: float)
bool or None
str
bool
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:
- cmap
Colormap
or str or None
- cmap
- 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'
).
- class matplotlib.image.PcolorImage(ax, x=None, y=None, A=None, *, cmap=None, norm=None, **kwargs)[source]#
Bases:
AxesImage
Make a pcolor-style plot with an irregular rectangular grid.
This uses a variation of the original irregular image code, and it is used by pcolorfast for the corresponding grid type.
- Parameters:
- ax
Axes
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)
andrange(M + 1)
, respectively.- Aarray-like
The data to be color-coded. The interpretation depends on the shape:
(M, N)
ndarray
or masked array: values to be colormapped(M, N, 3): RGB array
(M, N, 4): RGBA array
- cmapstr or
Colormap
, default:rcParams["image.cmap"]
(default:'viridis'
) The Colormap instance or registered colormap name used to map scalar data to colors.
- normstr or
Normalize
Maps luminance to 0-1.
- **kwargs
Artist
properties
- ax
- get_cursor_data(event)[source]#
Return the image value at the event position or None if the event is outside the image.
- 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>, mouseover=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, resample=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#
Set multiple properties at once.
Supported properties are
Property
Description
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha
float or 2D array-like or None
bool
array
unknown
(vmin: float, vmax: float)
bool
Patch or (Path, Transform) or None
Colormap
or str or Noneunknown
4-tuple of float
filternorm
bool
filterrad
positive float
str
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
object
bool
Normalize
or str or NoneNone or bool or float or callable
bool
resample
bool or None
(scale: float, length: float, randomness: float)
bool or None
str
bool
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)
andrange(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 returnTrue
, though this is not enforced by this function. Each image must have a purely affine transformation with no shear.- renderer
RendererBase
- 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 a URL. In all other cases, format is ignored and the format is auto-detected by
PIL.Image.open
.
- Returns:
numpy.array
The image data. The returned array has shape
(M, N) for grayscale images.
(M, N, 3) for RGB images.
(M, N, 4) for RGBA images.
PNG images are returned as float arrays (0-1). All other formats are returned as int arrays, with a bit depth determined by the file's contents.
- matplotlib.image.imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None, origin=None, dpi=100, *, metadata=None, pil_kwargs=None)[source]#
Colormap and save an array as an image file.
RGB(A) images are passed through. Single channel images will be colormapped according to cmap and norm.
Note
If you want to save a single channel image as gray scale please use an image I/O library (such as pillow, tifffile, or imageio) directly.
- Parameters:
- fnamestr or path-like or file-like
A path or a file-like object to store the image in. If format is not set, then the output format is inferred from the extension of fname, if any, and from
rcParams["savefig.format"]
(default:'png'
) otherwise. If format is set, it determines the output format.- arrarray-like
The image data. 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 usingFigureCanvasBase
and the drawing backend is selected asFigure.savefig
would normally do.
- Returns:
Figure
The figure instance containing the thumbnail.