MATLAB Function Reference | Search  Help Desk |
Image Properties | See Also |
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:CData
has only one row or column, the height or width respectively is always one data unit and is centered about the first YData
or XData
element respectively. For example, using a 4-by-1 matrix of random data,
C = rand(4,1); image(C,'CDataMapping','scaled') axis imageproduces:
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 values of 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 you can query 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.
CallbackObject
property, which you can query 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. While the object is still visible on the screen after erasing with EraseMode
none
, you cannot print it because MATLAB stores no information about its former location.
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
, or the Figure background Color
Color
is set to none
. This damages objects that are behind the erased Image, but Images are always properly colored.
Printing with Non-normal Erase Modes
EraseMode
of all objects is normal
. This means graphics objects created with EraseMode
set to none
, xor
, or background
can look different on screen than on paper. On screen, MATLAB may mathematically combine layers of colors (e.g., XORing a pixel color with that of the pixel behind it) and ignore three-dimensional sorting to obtain greater rendering speed. However, these techniques are not applied to the printed output.
You can use the MATLAB capture
command or other screen capture application to create an image of a Figure containing non-normal mode objects.
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. HandleVisibility
is useful for preventing command-line users from accidentally drawing into or deleting a Figure that contains only user interface devices (such as a dialog box).
HandleVisibility
is on
.
Setting HandleVisibility
to callback
causes handles to be visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provide a means to protect GUIs from command-line users, while allowing callback routines to have complete access to object handles.
Setting HandleVisibility
to off
makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaling a user-typed string), and so temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent's list of children, it cannot be returned by functions that obtain handles by searching the object hierarchy or querying handle properties. This includes 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.
You can set the Root ShowHiddenHandles
property to on to 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.
HitTest
{on} | off
Selectable by mouse click. HitTest
determines if the Image can become the current object (as returned by the gco
command and the Figure CurrentObject
property) as a result of a mouse click on the Image. If HiTest
is off
, clicking on the Image selects the object below it (which maybe the Axes containing it).
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
'.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the Image. Assign this property the handle of a Uicontextmenu object created in the same Figure as the Image. Use the uicontextmenu
function to create the context menu. MATLAB displays the context menu whenever you right-click over the Image (Control-click on Macintosh systems).
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(CData,2)]
by default
Control placement of image along x-axis. A vector specifying the locations of the centers of the elements CData(1,1)
and CData(m,n)
, where CData
has a size of m
-by-n
. Element CData(1,1)
is centered over the coordinate defined by the first elements in XData
and YData
. Element CData(m,n)
is centered over the coordinate defined by the last elements in XData
and YData
. The centers of the remaining elements of CData
are evenly distributed between those two points.
CData
element is determined by the expression:
(XData(2)-XData(1))/(size(CData,2)-1)You can also specify a single value for
XData
. In this case, image
centers the first element at this coordinate and centers each following element one unit apart.
YData
[1 size(CData,1)]
by default
Control placement of image along y-axis. A vector specifying the locations of the centers of the elements CData(1,1)
and CData(m,n)
, where CData
has a size of m
-by-n
. Element CData(1,1)
is centered over the coordinate defined by the first elements in XData
and YData
. Element CData(m,n)
is centered over the coordinate defined by the last elements in XData
and YData
. The centers of the remaining elements of CData
are evenly distributed between those two points.
CData
element is determined by the expression:
(YData(2)-YData(1))/(size(CData,1)-1)You can also specify a single value for
YData
. In this case, image
centers the first element at this coordinate and centers each following elements one unit apart.
colormap
, imfinfo
, imread
, imwrite
, pcolor
, newplot
, surface
The "Image" chapter the Using MATLAB Graphics manual