imrect

(Not recommended) Create draggable rectangle

imrect is not recommended. Use the new Rectangle ROI object instead. You can also use the new ROI convenience function drawrectangle. For more information, see Version History.

Description

An imrect object encapsulates an interactive rectangle over an image.

You can adjust the size and position of the rectangle by using the mouse. The rectangle also has a context menu that controls aspects of its appearance and behavior. For more information, see Usage.

Creation

Syntax

h = imrect

h = imrect(hparent)

h = imrect(hparent,position)

h = imrect(___,"PositionConstraintFcn",fcn)

Description

h = imrect begins interactive placement of a rectangle on the current axes, and returns an imrect object.

h = imrect(hparent) begins interactive placement of a rectangle on the object specified by hparent.

h = imrect(hparent,position) creates a draggable rectangle at the position position on the object specified by hparent.

h = imrect(___,"PositionConstraintFcn",fcn) also specifies where the rectangle can be dragged using a position constraint function, fcn.

Input Arguments

hparent — Handle to parent object

handle

Handle to parent object, specified as a handle. The parent is typically an axes object, but can also be any other object that can be the parent of an hggroup object.

position — Position of rectangle

4-element vector

Position of the rectangle, specified as a 4-element vector of the form [xmin ymin width height]. The initial size of the rectangle is width-by-height, and the upper-left corner of the rectangle is at the (x,y) coordinate (xmin,ymin).

fcn — Position constraint function

function handle

Position constraint function, specified as a function handle. fcn is called whenever the mouse is dragged. You can use this function to control where the ellipse can be dragged. See the help for the setPositionConstraintFcn function for information about valid function handles.

Properties

Deletable — ROI can be deleted

true (default) | false

ROI can be deleted, specified as true or false.

Data Types: logical

Usage

When you call imrect with an interactive syntax, the pointer changes to a cross hairs when over the image. You can create the rectangle and adjust its size and position using the mouse. The rectangle also supports a context menu that you can use to control aspects of its appearance and behavior. Right-click on the rectangle to access this context menu.

The table lists the interactive behaviors supported by imrect.

Interactive Behavior	Description
Moving the rectangle.	Move the pointer inside the rectangle. The pointer changes to a fleur shape . Click and drag the mouse to move the rectangle.
Resizing the rectangle.	Move the pointer over any of the edges or corners of the rectangle, the shape changes to a double-ended arrow, . Click and drag the edge or corner using the mouse.
Changing the color of the rectangle.	Move the pointer inside the rectangle. Right-click and select Set Color from the context menu.
Retrieving the coordinates of the current position	Move the pointer inside the polygon. Right-click and select Copy Position from the context menu. imrect copies a four-element position vector to the clipboard.
Preserve the current aspect ratio of the rectangle during interactive resizing.	Move the pointer inside the rectangle. Right-click and select Fix Aspect Ratio from the context menu.
Deleting the rectangle	Move the pointer inside the rectangle or on an edge of the rectangle. Right-click and select Delete from the context menu. To remove this option from the context menu, set the Deletable property to false: h = imrect(); h.Deletable = false;

When you use setResizeable to make the rectangle non-resizable, the Fix Aspect Ratio context menu item is not provided.

Object Functions

Each imrect object supports a number of functions. Type methods imrect to see a complete list.

addNewPositionCallback	Add new-position callback to ROI object
createMask	(Not recommended) Create mask within image
delete	Delete handle object
getColor	Get color used to draw ROI object
getPosition	Return current position of ROI object
getPositionConstraintFcn	Return function handle to current position constraint function
removeNewPositionCallback	Remove new-position callback from ROI object
resume	(Not recommended) Resume execution of MATLAB command line
setColor	(Not recommended) Set color used to draw ROI object
setConstrainedPosition	Set ROI object to new position
setFixedAspectRatioMode	Preserve aspect ratio when resizing ROI object
setPosition	(Not recommended) Move ROI object to new position
setPositionConstraintFcn	Set position constraint function of ROI object
setResizable	Set resize behavior of ROI object
wait	(Not recommended) Block MATLAB command line until ROI creation is finished

Examples

Update Title when Rectangle Moves

Display a rectangle ROI over an image. Display the position of the rectangle in the title. The title updates when you move the rectangle. Try dragging one side of the rectangle outside the boundary of the image.

imshow("cameraman.tif")
h = imrect(gca,[10 10 100 100]);
addNewPositionCallback(h,@(p) title(mat2str(p,3)));

Specify a position constraint function using makeConstrainToRectFcn to keep the rectangle inside the original XLim and YLim ranges of the image.

fcn = makeConstrainToRectFcn("imrect",get(gca,"XLim"),get(gca,"YLim"));
setPositionConstraintFcn(h,fcn);

Now drag the rectangle using the mouse. Observe that the rectangle can no longer extend past the image boundary.

Click and Drag to Place Rectangle

Interactively place a rectangle by clicking and dragging. Use wait to block the MATLAB^® command line. Double-click on the rectangle to resume execution of the MATLAB command line.

imshow("pout.tif");
h = imrect;
position = wait(h);

Tips

If you use imrect with an axes that contains an image object, and do not specify a position constraint function, users can drag the rectangle outside the extent of the image. When used with an axes created by the plot function, the axes limits automatically expand to accommodate the movement of the rectangle.

Version History

Introduced before R2006a

R2018b: imrect is not recommended

Starting in R2018b, a new set of ROI objects replaces the existing set of ROI objects. The new objects provide more functional capabilities, such as face color transparency. The new classes also support events that you can use to respond to changes in your ROI such as moving or being clicked. Although there are no plans to remove the old ROI objects at this time, switch to the new ROIs to take advantage of the additional capabilities and flexibility. For more information on creating ROIs using the new ROI functions, see Create ROI Shapes.

Replace use of the imrect ROI object with the new Rectangle ROI object. You can also use the ROI creation convenience function drawrectangle.

Update ROI Creation Code

Update all instances of imrect.

Discouraged Usage	Recommended Replacement
This example creates a rectangular ROI. imshow("cameraman.tif"); h = imrect(gca,[10 10 100 150]);	Here is equivalent code, replacing the old ROI object with the new ROI object. This example uses the ROI creation convenience function. Note that you must specify the size and position information as a name-value argument. imshow("cameraman.tif"); h = drawrectangle(gca,"Position",[10 10 100 150]);

Other ROI Code Updates

Update code that uses any of the object functions of the imrect ROI object. In many cases, you can replace the call to an imrect object function by simply accessing or setting the value of a Rectangle ROI object property. For example, replace calls to getColor or setColor with use of the Color property. In some cases, you must replace the imrect object function with an object function of the new Rectangle ROI. Each of the individual imrect ROI object functions include information about migrating to the new Rectangle ROI object. For a migration overview, see ROI Migration.