MATLAB Functions

Display Image object

image(C)
image(x,y,C)
image(...,'PropertyName',PropertyValue,...)
image('PropertyName',PropertyValue,...) Formal synatx - PN/PV pairs 
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 the set and get reference pages 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 stored as an array of 8-bit integers. This is a much 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 image data differently from 64-bit data. This table summarizes these differences:


`Image type`	`Double-precision data (double array)`	`8-bit data (uint8 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]; 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]

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 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. The uint8 convention is also used in graphics file formats, and enables 8-bit indexed images to support up to 256 colors. Note that when you read in an indexed image with imread, the resulting image array is always of class uint8. (The colormap, however, is of class double; see below.)

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

X64 = double(X8) + 1;

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

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

The order of the operations must be as shown in these examples, because you cannot perform mathematical operations on uint8 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].

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

RGB64 = double(RGB8)/255;

This statement converts a double truecolor image to uint8:

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

The order of the operations must be as shown in these examples, because you cannot perform mathematical operations on uint8 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.

Image Properties

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

BusyAction cancel | {queue}

Callback routine interruption. The BusyAction property enables you to control how MATLAB handles events that potentially interrupt executing callback routines. If there is a callback routine executing, subsequently invoked callback routes always attempt to interrupt it. If the Interruptible property of the object whose callback is executing is set to on (the default), then interruption occurs at the next point where the event queue is processed. If the Interruptible property is off, the BusyAction property (of the object owning the executing callback) determines how MATLAB handles the event. The choices are:

cancel - discard the event that attempted to execute a second callback routine.
queue - queue the event that attempted to execute a second callback routine until the current callback finishes.

ButtonDownFcn string

Button press callback routine. A callback routine that executes whenever you press a mouse button while the pointer is over the Image object. Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace.

CData matrix or m-by-n-by-3 array

The Image data. A matrix of values specifying the color of each rectangular area defining the Image. image(C) assigns the values of C to CData. MATLAB determines the coloring of the Image in one of three ways:

Using the elements of CData as indices into the current colormap (the default)
Scaling the elements of CData to range between the values min(get(gca,'CLim')) and max(get(gca,'CLim')) (CDataMapping set to scaled)
Interpreting the elements of CData directly as RGB values (true color specification)

A true color specification for CData requires an m-by-n-by-3 array of RGB values. The first page contains the red component, the second page the green component, and the third page the blue component of each element in the Image. RGB values range from 0 to 1. The following picture illustrates the relative dimensions of CData for the two color models:

CDataMapping scaled | {direct}

Direct or scaled indexed colors. This property determines whether MATLAB interprets the values in CData as indices into the Figure colormap (the default) or scales the values according to the Axes CLim property.

When CDataMapping is direct, the values of CData should be in the range 1 to length(get(gcf,'Colormap')). If you use true color specification for CData, this property has no effect.

Children handles

The empty matrix; Image objects have no children.

Clipping on | off

Clipping mode. By default, MATLAB clips Images to the Axes rectangle. If you set Clipping to off, the Image can display outside the Axes rectangle. For example, if you create an Image, set hold to on, freeze axis scaling (axis manual), and then create a larger Image, it extends beyond the axis limits.

CreateFcn string

Callback routine executed during object creation. This property defines a callback routine that executes when MATLAB creates an Image object. You must define this property as a default value for Images. For example, the statement,

set(0,'DefaultImageCreateFcn','axis image')

defines a default value on the Root level that sets the aspect ratio and the axis limits so the Image has square pixels. MATLAB executes this routine after setting all Image properties. Setting this property on an existing Image object has no effect.

The handle of the object whose CreateFcn is being executed is accessible only through the Root CallbackObject property, which can be queried using gcbo.

DeleteFcn string

Delete Image callback routine. A callback routine that executes when you delete the Image object (i.e., when you issue a delete command or clear the Axes or Figure containing the Image). MATLAB executes the routine before destroying the object's properties so these values are available to the callback routine.

The handle of the object whose DeleteFcn is being executed is accessible only through the Root CallbackObject property, which can be queried using gcbo.

EraseMode {normal} | none | xor | background

Erase mode. This property controls the technique MATLAB uses to draw and erase Image objects. Alternative erase modes are useful for creating animated sequences, where control of the way individual objects redraw is necessary to improve performance and obtain the desired effect.

normal (the default) -- Redraw the affected region of the display, performing the three-dimensional analysis necessary to ensure that all objects are rendered correctly. This mode produces the most accurate picture, but is the slowest. The other modes are faster, but do not perform a complete redraw and are therefore less accurate.
none - Do not erase the Image when it is moved or changed.
xor - Draw and erase the Image by performing an exclusive OR (XOR) with the color of the screen beneath it. This mode does not damage the color of the objects beneath the Image. However, the Image's color depends on the color of whatever is beneath it on the display.
background - Erase the Image by drawing it in the Axes' background color. This damages objects that are behind the erased Image, but Images are always properly colored.

HandleVisibility {on} | callback | off

Control access to object's handle by command-line users and GUIs. This property determines when an object's handle is visible in its parent's list of children. Handles are always visible when HandleVisibility is on. When HandleVisibility is callback, handles are visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line - a useful way to protect GUIs from command-line users, while permitting their callbacks complete access to their own handles. Setting HandleVisibility to off makes handles invisible at all times - which is occasionally necessary when a callback needs to invoke a function that might potentially damage the UI, and so wants to temporarily hide its own handles during the execution of that function.

When a handle is not visible in its parent's list of children, it can not be returned by any functions which obtain handles by searching the object hierarchy or querying handle properties, including get, findobj, gca, gcf, gco, newplot, cla, clf, and close. When a handle's visibility is restricted using callback or off, the object's handle does not appear in its parent's Children property, Figures do not appear in the Root's CurrentFigure property, objects do not appear in the Root's CallbackObject property or in the Figure's CurrentObject property, and Axes do not appear in their parent's CurrentAxes property.

The Root ShowHiddenHandles property can be set to on to temporarily make all handles visible, regardless of their HandleVisibility settings (this does not affect the values of the HandleVisibility properties).

Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles. This property is useful for preventing command-line users from accidently drawing into or deleting a Figure that contains only user interface devices (such as a dialog box).

Interruptible {on} | off

Callback routine interruption mode. The Interruptible property controls whether an Image callback routine can be interrupted by subsequently invoked callback routines. Only callback routines defined for the ButtonDownFcn are affected by the Interruptible property. MATLAB checks for events that can interrupt a callback routine only when it encounters a drawnow, figure, getframe, or pause command in the routine.

Parent handle of parent Axes

Image's parent. The handle of the Image object's parent Axes. You can move an Image object to another Axes by changing this property to the new Axes handle.

Selected on | off

Is object selected. When this property is on. MATLAB displays selection handles if the SelectionHighlight property is also on. You can, for example, define the ButtonDownFcn to set this property, allowing users to select the object with the mouse.

SelectionHighlight {on} | off

Objects highlight when selected. When the Selected property is on, MATLAB indicates the selected state by drawing four edge handles and four corner handles. When SelectionHighlight is off, MATLAB does not draw the handles.

Tag string

User-specified object label. The Tag property provides a means to identify graphics objects with a user-specified label. This is particularly useful when constructing interactive graphics programs that would otherwise need to define object handles as global variables or pass them as arguments between callback routines. You can define Tag as any string.

Type string (read only)

Type of graphics object. This property contains a string that identifies the class of graphics object. For Image objects, Type is always 'image'.

UserData matrix

User specified data. This property can be any data you want to associate with the Image object. The Image does not use this property, but you can access it using set and get.

Visible on | off

Image visibility. By default, Image objects are visible. Setting this property to off prevents the Image from being displayed. However, the object still exists and you can set and query its properties.

XData [1 size(C,2)]

X-axis range. A two-element vector specifying the x-coordinates spanned by the Image, along the x-axis. By default, the second element in XData is equal to the number of columns in the Image CData property.

YData [1 size(C,1)]

Y-axis range. A two-element vector specifying the y-coordinates spanned by the Image, along the y-axis. By default, the second element in YData is equal to the number of rows in the Image CData property.