image (MATLAB Function Reference)

Display image object

Syntax

image(C)
image(x,y,C)
image(...,'PropertyName',PropertyValue,...)
image('PropertyName',PropertyValue,...) Formal synatx - PN/PV only
handle = image(...)

Description

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.

image(x,y,C,'PropertyName',PropertyValue,...) is a high-level function that also specifies property name/property value pairs. 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.

Remarks

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 , 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 MATLAB 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 method than the double-precision (64-bit) floating-point numbers that MATLAB typically uses. However, it is necessary for MATLAB to interpret 8-bit and 16-bit image data differently from 64-bit data. This table summarizes these differences.

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] (unit8) or [0, 65535] (uint16); colormap is an m-by-3 array of floating-point values in the range [0, 1]

truecolor (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] (unit8) or [0, 65535] (uint16)

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] (`unit8`) or [0, 65535] (`uint16`); colormap is an `m`-by-3 array of floating-point values in the range [0, 1]
truecolor (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] (`unit8`) or [0, 65535] (`uint16`)

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 unit16, 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));

The order of the operations must be as shown in these examples, because you cannot perform mathematical operations on uint8 or uint16 arrays.

When you write an indexed image using imwrite, MATLAB automatically converts the values if necessary.

Colormaps

Colormaps in MATLAB are alway 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 does not support colormaps with integer values. imread and imwrite automatically convert colormap values when reading and writing files.

True Color Images

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

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

RGB64 = double(RGB8)/255;

or for uint16 images,

RGB64 = double(RGB16)/65535;

This statement converts a double truecolor image to uint8.

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

or for uint16 images,

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

The order of the operations must be as shown in these examples, because you cannot perform mathematical operations on uint8 or uint16 arrays.

When you write a truecolor image using imwrite, MATLAB automatically converts the values if necessary.

Object Hierarchy

Setting Default Properties

You can set default image properties on the axes, figure, and root levels.

set(0,'DefaultImageProperty',PropertyValue...)
set(gcf,'DefaultImageProperty',PropertyValue...)
set(gca,'DefaultImageProperty',PropertyValue...)

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.

The following table lists all image properties and provides a brief description of each. The property name links take you to an expanded description of the properties.

Property Name
Property Description
Property Value

Data Defining the Object

CData
The image data
Values: matrix or m-by-n-by-3 array
Default: enter
image;axis image ij
and see

CDataMapping
Specify the mapping of data to colormap
Values: scaled, direct
Default: direct

XData
Control placement of image along x-axis
Values: [min max]
Default: [1 size(CData,2)]

YData
Control placement of image along y-axis
Values: [min max]
Default: [1 size(CData,1)]

Specifying Transparency

alphadata
Transparency data
m-by-n matrix of double or
uint8
Default: 1 (opaque)

alphadatamapping
Transparency mapping method
none, direct, scaled
Default: none

Controlling the Appearance

Clipping
Clipping to axes rectangle
Values: on, off
Default: on

EraseMode
Method of drawing and erasing the image (useful for animation)
Values: normal, none, xor, background
Default: normal

SelectionHighlight
Highlight image when selected (Selected property set to on)
Values: on, off
Default: on

Visible
Make the image visible or invisible
Values: on, off
Default: on

Controlling Access to Objects

HandleVisibility
Determines if and when the the line's handle is visible to other functions
Values: on, callback, off
Default: on

HitTest
Determine if image can become the current object (see the figure CurrentObject property)
Values: on, off
Default: on

General Information About the Image

Children
Image objects have no children
Values: [] (empty matrix)

Parent
The parent of an image object is always an axes object
Value: axes handle

Selected
Indicate whether image is in a "selected" state.
Values: on, off
Default: on

Tag
User-specified label
Value: any string
Default: '' (empty string)

Type
The type of graphics object (read only)
Value: the string 'image'

UserData
User-specified data
Value: any matrix
Default: [] (empty matrix)

Properties Related to Callback Routine Execution

BusyAction
Specify how to handle callback routine interruption
Values: cancel, queue
Default: queue

ButtonDownFcn
Define a callback routine that executes when a mouse button is pressed on over the image
Values: string
Default: empty string

CreateFcn
Define a callback routine that executes when an image is created
Values: string
Default: empty string

DeleteFcn
Define a callback routine that executes when the image is deleted (via close or delete)
Values: string
Default: empty string

Interruptible
Determine if callback routine can be interrupted
Values: on, off
Default: on (can be interrupted)

UIContextMenu
Associate a context menu with the image
Values: handle of a uicontextmenu

Property Name	Property Description	Property Value
Data Defining the Object
`CData`	The image data	Values: matrix or m-by-n-by-3 array Default: enter `image;axis image ij` and see
`CDataMapping`	Specify the mapping of data to colormap	Values: `scaled`, `direct` Default: `direct`
`XData`	Control placement of image along x-axis	Values: `[min max]` Default: `[1 size(CData,2)]`
`YData`	Control placement of image along y-axis	Values: `[min max]` Default: `[1 size(CData,1)]`
Specifying Transparency
`alphadata`	Transparency data	m-by-n matrix of double or uint8 Default: 1 (opaque)
`alphadatamapping`	Transparency mapping method	none, direct, scaled Default: none
Controlling the Appearance
Clipping	Clipping to axes rectangle	Values: `on`, `off` Default: `on`
EraseMode	Method of drawing and erasing the image (useful for animation)	Values: `normal`, `none`, `xor`, `background` Default: `normal`
`SelectionHighlight`	Highlight image when selected (`Selected` property set to `on`)	Values: `on`, `off` Default: `on`
`Visible`	Make the image visible or invisible	Values: `on`, `off` Default: `on`
Controlling Access to Objects
`HandleVisibility`	Determines if and when the the line's handle is visible to other functions	Values: `on`, `callback`, `off` Default: `on`
`HitTest`	Determine if image can become the current object (see the figure `CurrentObject` property)	Values: `on`, `off` Default: `on`
General Information About the Image
`Children`	Image objects have no children	Values: `[]` (empty matrix)
`Parent`	The parent of an image object is always an axes object	Value: axes handle
`Selected`	Indicate whether image is in a "selected" state.	Values: `on`, `off` Default: `on`
`Tag`	User-specified label	Value: any string Default: `''` (empty string)
`Type`	The type of graphics object (read only)	Value: the string `'image'`
`UserData`	User-specified data	Value: any matrix Default: `[]` (empty matrix)
Properties Related to Callback Routine Execution
`BusyAction`	Specify how to handle callback routine interruption	Values: `cancel`, `queue` Default: `queue`
`ButtonDownFcn`	Define a callback routine that executes when a mouse button is pressed on over the image	Values: string Default: empty string
`CreateFcn`	Define a callback routine that executes when an image is created	Values: string Default: empty string
`DeleteFcn`	Define a callback routine that executes when the image is deleted (via `close` or `delete`)	Values: string Default: empty string
`Interruptible`	Determine if callback routine can be interrupted	Values: `on`, `off` Default: `on` (can be interrupted)
`UIContextMenu`	Associate a context menu with the image	Values: handle of a uicontextmenu

imag Image Properties