# image

## Purpose

Display image by creating image object.

## Synopsis

    image(C)
    image(x,y,C)
    image('PropertyName',PropertyValue,...)
    h = image(...)

## Description

`image` is both a high-level command for displaying images and a low-level function for creating image objects.

Image objects are children of axes objects. MATLAB displays an image by mapping each element in a matrix to an entry in the figure's colormap. The `image` function allows you to specify property name/property value pairs as input arguments. These properties, which control various aspects of the image object, are described under "Object Properties." You can also set and query property values after creating the object using the `set` and `get` commands.

`image(C)` displays matrix `C` as an image. Each element of `C` specifies the color of a rectilinear patch in the image. The elements of `C` are used as indices into the current colormap to determine the color.

`image(x,y,C)`, where `x` and `y` are vectors, specifies the bounds of the image data on the x- and y-axes, but produces the same image as `image(C)`. The matrix arguments can be followed by property name/property value pairs to specify additional image properties. You can omit the matrix arguments entirely and specify all properties using property name/property value pairs.

`h = image('PropertyName',PropertyValue,...)` specifies property name/property value pairs as input arguments.

`h = image(...)` returns the handle of the object it creates.

`image` and `pcolor` are similar, however, there are important differences:

`image(C)`:

- specifies the colors of patches
- uses pixel replication to fill each rectangle
- uses matrix coordinates if `hold` is not `on` (y-axis reversed)
- uses indices into the colormap directly
  `pcolor(C)`:

- specifies the colors of vertices
- uses bilinear interpolation when shading mode is `interp`
- goes through `caxis` limits into the colormap
  The number of rectangles for `image(C)` is the same as the number of vertices for `pcolor(C)`.

  ## Object Properties

  This section lists property names along with the type of values each accepts.

  `ButtonDownFcn`
    Callback string, object selection.
    Any legal MATLAB expression, including the name of an M-file or function. When you select the object, the string is passed to the `eval` function to execute the specified function. Initially the empty matrix.
  `CData`
    Color data.
    A matrix of values that specifies the color at each element of the image. `image(C)` assigns `C` to `CData`. The elements of `CData` are indices into the current colormap, determining the color at each rectilinear patch in the image. Values with a decimal portion are fixed to the nearest, lower integer. Values less than 1 are mapped to the lowest value in the colormap, and values greater than `length(colormap)` are mapped to the highest value.
  `Children`
    Children of image.
    Always the empty matrix; image objects have no children.
  `Clipping`
    Clipping mode.
    `on` (Default.) Any portion of the image outside the axes rectangle is not displayed.
    `off` Image data is not clipped.
  `Interruptible`
    Callback interruptibility.
    `yes` The callback specified by `ButtonDownFcn` is interruptible by other callbacks.
    `no` (Default.) The `ButtonDownFcn` callback is not interruptible.
  `Parent`
    Handle of the image's parent object.
    A read-only property that contains the handle of the image's parent object. The parent of an image object is the axes in which it is displayed.
  `Type`
    Type of object.
    A read-only string; always `'image'` for an image object.
  `UserData`
    User-specified data.
    Any matrix you want to associate with the image object. The object does not use this data, but you can retrieve it using the `get` command`.`
  `Visible`
    Image visibility.
    `on` (Default.) Image is visible on the screen.
    `off` Image is not displayed.
  `XData`
    Image x-data.
    Specifies the position of the image rows. If omitted, the row numbers of `CData` are used.
  `YData`
    Image y-data.
    Specifies the position of the image columns. If omitted, the column numbers of `CData` are used.

  ## Examples

  Some purely mathematical constructs generate interesting images. For example,

      colormap(cool)
      image(((real(fft(eye(64)))+1)/2)*64)

  Alternatively, you can read images such as photographs and drawings from external files:

      load earth
      colormap(map)
      image(X)

  ## See Also

      colormap, pcolor

  (c) Copyright 1994 by The MathWorks, Inc.