MATLAB Functions | Help Desk |
image
Display Image objectimage(C) image(x,y,C) image(...,'PropertyName',PropertyValue,...) image('PropertyName',PropertyValue,...) Formal synatx - PN/PV pairs only handle = image(...)
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:
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
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.
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: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 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.
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.
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.
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
stringButton 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:
CData
as indices into the current colormap (the default)
CData
to range between the values min(get(gca,'CLim'))
and max(get(gca,'CLim'))
(CDataMapping
set to scaled
)
CData
directly as RGB values (true color specification)
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.
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
handlesThe 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
stringCallback 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.
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.
colormap
, iminfo
, imread
, imwrite
, pcolor
,newplot
,surface