### Navigation

- index
- modules |
- next |
- previous |
- home|
- examples|
- tutorials|
- pyplot|
- docs »
- The Matplotlib API »

# 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)
  `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`()
  `get_window_extent`(renderer=None)
  `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`()
  `make_image`(renderer, magnification=1.0, unsampled=False)
  `set_array`(*args)
  `set_cmap`(cmap)
  `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_filterrad`(s)
  `set_interpolation`(s)
  `set_norm`(norm)

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)
  `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.

  Arguments:
    fname:
      A string containing a path 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:
      An MxN (luminance), MxNx3 (RGB) or MxNx4 (RGBA) array.
  Keyword arguments:
    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:
      cmap is a colors.Colormap instance, e.g., cm.jet. If None, default to the rc image.cmap value.
    format:
      One of the file extensions supported by the active backend. Most backends support png, pdf, ps, eps and svg.
    origin
      [ ‘upper’ | ‘lower’ ] Indicates where the [0,0] index of the array is in the upper left or lower left corner of the axes. Defaults to the rc image.origin value.
    dpi
      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. 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.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