image

matplotlib.image

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

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

Bases: matplotlib.image._ImageBase

interpolation and cmap default to their rc settings

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

extent is data axes (left, right, bottom, top) for making image plots registered with data plots. Default is to label the pixel centers with the zero-based row and column indices.

Additional kwargs are matplotlib.artist properties

get_cursor_data(event)

Get the cursor data for a given event

get_extent()

Get the image extent: left, right, bottom, top

get_window_extent(renderer=None)

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

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

make_image(renderer, magnification=1.0, unsampled=False)

set_extent(extent)

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

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

class matplotlib.image.BboxImage(bbox, cmap=None, norm=None, interpolation=None, origin=None, filternorm=1, filterrad=4.0, resample=False, interp_at_native=True, **kwargs)

Bases: matplotlib.image._ImageBase

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

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

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

kwargs are an optional list of Artist keyword args

contains(mouseevent)

Test whether the mouse event occurred within the image.

get_transform()

Return the Transform instance used by this artist.

get_window_extent(renderer=None)

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

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

make_image(renderer, magnification=1.0, unsampled=False)

class matplotlib.image.FigureImage(fig, cmap=None, norm=None, offsetx=0, offsety=0, origin=None, **kwargs)

Bases: matplotlib.image._ImageBase

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

kwargs are an optional list of Artist keyword args

get_extent()

Get the image extent: left, right, bottom, top

make_image(renderer, magnification=1.0, unsampled=False)

set_data(A)

Set the image array.

zorder = 0

class matplotlib.image.NonUniformImage(ax, **kwargs)

Bases: matplotlib.image.AxesImage

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

get_extent()

Get the image extent: left, right, bottom, top

make_image(renderer, magnification=1.0, unsampled=False)

set_array(*args)

Retained for backwards compatibility - use set_data instead

ACCEPTS: numpy array A or PIL Image

set_cmap(cmap)

set the colormap for luminance data

ACCEPTS: a colormap or registered colormap name

set_data(x, y, A)

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

x and y are monotonic 1-D ndarrays of lengths N and M,

respectively, specifying pixel centers

A is an (M,N) ndarray or masked array of values to be

colormapped, or a (M,N,3) RGB array, or a (M,N,4) RGBA array.

set_filternorm(s)

Set whether the resize filter norms the weights -- see help for imshow

ACCEPTS: 0 or 1

set_filterrad(s)

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

ACCEPTS: positive float

set_interpolation(s)

Parameters:

s : str, None

Either 'nearest', 'bilinear', or None.

set_norm(norm)

Set the normalization instance.

Parameters:

norm : Normalize

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

Bases: matplotlib.image.AxesImage

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

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

cmap defaults to its rc setting

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

Additional kwargs are matplotlib.artist properties

get_cursor_data(event)

Get the cursor data for a given event

make_image(renderer, magnification=1.0, unsampled=False)

set_array(*args)

Retained for backwards compatibility - use set_data instead

ACCEPTS: numpy array A or PIL Image

set_data(x, y, A)

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

x and y are monotonic 1-D ndarrays of lengths N+1 and M+1,

respectively, specifying rectangle boundaries. If None, they will be created as uniform arrays from 0 through N and 0 through M, respectively.

A is an (M,N) ndarray or masked array of values to be

colormapped, or a (M,N,3) RGB array, or a (M,N,4) RGBA array.

matplotlib.image.composite_images(images, renderer, magnification=1.0)

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

Parameters:

images : list of Images

Each must have a make_image method. For each image, can_composite should return True, though this is not enforced by this function. Each image must have a purely affine transformation with no shear.

renderer : RendererBase instance

magnification : float

The additional magnification to apply for the renderer in use.

Returns:

tuple : image, offset_x, offset_y

Returns the tuple:

• image: A numpy array of the same type as the input images.
• offset_x, offset_y: The offset of the image (left, bottom) in the output figure.

matplotlib.image.imread(fname, format=None)

Read an image from a file into an array.

fname may be a string path, a valid URL, or a Python file-like object. If using a file object, it must be opened in binary mode.

If format is provided, will try to read file of that type, otherwise the format is deduced from the filename. If nothing can be deduced, PNG is tried.

Return value is a numpy.array. For grayscale images, the return array is MxN. For RGB images, the return value is MxNx3. For RGBA images the return value is MxNx4.

matplotlib can only read PNGs natively, but if PIL is installed, it will use it to load the image and return an array (if possible) which can be used with imshow(). Note, URL strings may not be compatible with PIL. Check the PIL documentation for more information.

matplotlib.image.imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None, origin=None, dpi=100)

Save an array as in image file.

The output formats available depend on the backend being used.

Parameters:

fname : str or file-like

Path string to a filename, or a Python file-like object. If format is None and fname is a string, the output format is deduced from the extension of the filename.

arr : array-like

An MxN (luminance), MxNx3 (RGB) or MxNx4 (RGBA) array.

vmin, vmax: [ None | scalar ]

vmin and vmax set the color scaling for the image by fixing the values that map to the colormap color limits. If either vmin or vmax is None, that limit is determined from the arr min/max value.

cmap : matplotlib.colors.Colormap, optional

For example, cm.viridis. If None, defaults to the image.cmap rcParam.

format : str

One of the file extensions supported by the active backend. Most backends support png, pdf, ps, eps and svg.

origin : [ 'upper' | 'lower' ]

Indicates whether the (0, 0) index of the array is in the upper left or lower left corner of the axes. Defaults to the image.origin rcParam.

dpi : int

The DPI to store in the metadata of the file. This does not affect the resolution of the output image.

matplotlib.image.pil_to_array(pilImage)

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

Grayscale images are returned as (M, N) arrays. RGB images are returned as (M, N, 3) arrays. RGBA images are returned as (M, N, 4) arrays.

matplotlib.image.thumbnail(infile, thumbfile, scale=0.1, interpolation='bilinear', preview=False)

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

infile the image file -- must be PNG or Pillow-readable if you

have Pillow installed

thumbfile

the thumbnail filename

scale

the scale factor for the thumbnail

interpolation

the interpolation scheme used in the resampling

preview

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, a pure image backend will be used depending on the extension, 'png'->FigureCanvasAgg, 'pdf'->FigureCanvasPdf, 'svg'->FigureCanvasSVG

See examples/misc/image_thumbnail.py.

Image Thumbnail

Return value is the figure instance containing the thumbnail