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.