Documentation Center

  • Trial Software
  • Product Updates


Display image object


handle = image(...)


For a list of properties, see Image Properties.


image creates an image graphics object by interpreting each element in a matrix as an index into the figure's colormap or directly as RGB values, depending on the data specified.

The image function has two forms:

  • A high-level function that calls newplot to determine where to draw the graphics objects and sets the following axes properties:

    • XLim and YLim to enclose the image

    • Layer to top to place the image in front of the tick marks and grid lines

    • YDir to reverse

    • View to [0 90]

  • A low-level function that adds the image to the current axes without calling newplot. The low-level function argument list can contain only property name/property value pairs.

You can specify properties as property name/property value pairs, structure arrays, and cell arrays (see set and get for examples of how to specify these data types).

image(C) displays matrix C as an image. Each element of C specifies the color of a rectangular segment in the image.

image(x,y,C), where x and y are two-element vectors, specifies the range of the x- and y-axis labels, but produces the same image as image(C). This can be useful, for example, if you want the axis tick labels to correspond to real physical dimensions represented by the image. If x(1) > x(2) or y(1) > y(2), the image is flipped left-right or up-down, respectively. It can also be useful when you want to place the image within a set of axes already created. In this case, use hold on with the current figure and enter x and y values corresponding to the corners of the desired image location. The image is stretched and oriented as applicable.

image(x,y,C,'PropertyName',PropertyValue,...) is a high-level function that also specifies property name/property value pairs. For a description of the properties, see Image Properties. This syntax calls newplot before drawing the image.

image('PropertyName',PropertyValue,...) is the low-level syntax of the image function. It specifies only property name/property value pairs as input arguments.

handle = image(...) returns the handle of the image object it creates. You can obtain the handle with all forms of the image function.


expand all

Load MAT-File and Display Image

Load the mandrill file which contains an indexed image, X, and its associated colormap, map. Display the image using its colormap.

load mandrill

Remove the axis tick marks and tick labels. Set the aspect ratio to obtain square pixels.

axis off
axis image

Load and Display JPEG Image File

Load a JPEG image file of the Cat's Eye Nebula from the Hubble Space Telescope (image courtesy NASA). Display the original image using its RGB color values (left) as a subplot.

Create a linked subplot (same size and scale) to display the transformed intensity image as a heat map (right).

ax(1) = subplot(1,2,1);
rgb = imread('ngc6543a.jpg');
title('RGB image')

ax(2) = subplot(1,2,2);
im = mean(rgb,3);
title('Intensity Heat Map')

Setting Default Properties

You can set default image properties on the axes, figure, and rootobject levels:


where Property is the name of the image property and PropertyValue is the value you are specifying. Use set and get to access image properties.


For more information, see Working with Images in MATLAB Graphics .

More About

expand all


Image data can be either indexed or true color. An indexed image stores colors as an array of indices into the figure colormap. A true color image does not use a colormap; instead, the color values for each pixel are stored directly as RGB triplets. In MATLAB® graphics, the CData property of a truecolor image object is a three-dimensional (m-by-n-by-3) array. This array consists of three m-by-n matrices (representing the red, green, and blue color planes) concatenated along the third dimension.

The imread function reads image data into MATLAB arrays from graphics files in various standard formats, such as TIFF. You can write MATLAB image data to graphics files using the imwrite function. imread and imwrite both support a variety of graphics file formats and compression schemes.

When you read image data into the MATLAB workspace using imread, the data is usually stored as an array of 8-bit integers. However, imread also supports reading 16-bit-per-pixel data from TIFF and PNG files. These are more efficient storage methods than the double-precision (64-bit) floating-point numbers that MATLAB typically uses. However, it is necessary to interpret 8-bit and 16-bit image data differently from 64-bit data. This table summarizes these differences.

You cannot interactively pan or zoom outside the x-limits or y-limits of an image, unless the axes limits are already been set outside the bounds of the image, in which case there is no such restriction. If other objects (such as lineseries) occupy the axes and extend beyond the bounds of the image, you can pan or zoom to the bounds of the other objects, but no further.

Image Type

Double-Precision Data (double Array)

8-Bit Data (uint8 Array) 16-Bit Data (uint16 Array)

Indexed (colormap)

Image is stored as a two-dimensional (m-by-n) array of integers in the range [1, length(colormap)]; colormap is an m-by-3 array of floating-point values in the range [0, 1].

Image is stored as a two-dimensional (m-by-n) array of integers in the range [0, 255] (uint8) or [0, 65535] (uint16); colormap is an m-by-3 array of floating-point values in the range [0, 1].

True color (RGB)

Image is stored as a three-dimensional (m-by-n-by-3) array of floating-point values in the range [0, 1].

Image is stored as a three-dimensional (m-by-n-by-3) array of integers in the range [0, 255] (uint8) or [0, 65535] (uint16).

By default, image plots the y-axis from lowest to highest value, top to bottom. To reverse this, type set(gca,'YDir','normal'). This will reverse both the y-axis and the image.

Indexed Images

In an indexed image of class double, the value 1 points to the first row in the colormap, the value 2 points to the second row, and so on. In a uint8 or uint16 indexed image, there is an offset; the value 0 points to the first row in the colormap, the value 1 points to the second row, and so on.

If you want to convert a uint8 or uint16 indexed image to double, you need to add 1 to the result. For example,

X64 = double(X8) + 1;


X64 = double(X16) + 1;

To convert from double to uint8 or uint16, you need to first subtract 1, and then use round to ensure all the values are integers.

X8 = uint8(round(X64 - 1));


X16 = uint16(round(X64 - 1));

When you write an indexed image using imwrite, values are automatically converted if necessary.


MATLAB colormaps are always m-by-3 arrays of double-precision floating-point numbers in the range [0, 1]. In most graphics file formats, colormaps are stored as integers, but MATLAB colormaps cannot have integer values. imread and imwrite automatically convert colormap values when reading and writing files.

True Color Images

In a true color image of class double, the data values are floating-point numbers in the range [0, 1]. In a true color image of class uint8, the data values are integers in the range [0, 255], and for true color images of class uint16 the data values are integers in the range [0, 65535].

If you want to convert a true color image from one data type to the other, you must rescale the data. For example, this statement converts a uint8 true color image to double.

RGB64 = double(RGB8)/255;

or for uint16 images,

RGB64 = double(RGB16)/65535;

This statement converts a double true color image to uint8:

RGB8 = uint8(round(RGB64*255));

or to obtain uint16 images, type

RGB16 = uint16(round(RGB64*65535));

When you write a true color image using imwrite, values are automatically converted if necessary.

See Also

| | | | | | | |

Was this topic helpful?