imrect

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 Compatibility Considerations.

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

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.

example

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

h = imrect(___,Name,Value) specifies name-value pairs that control the behavior of the rectangle.

Input Arguments

expand all

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 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).

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Position constraint function, specified as the comma-separated pair consisting of 'PositionConstraintFcn' and a function handle. fcn is called whenever the mouse is dragged. You can use this function to control where the rectangle can be dragged. See the help for the setPositionConstraintFcn function for information about valid function handles.

Properties

expand all

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 BehaviorDescription
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 positionMove 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 rectangleMove 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.

addNewPositionCallbackAdd new-position callback to ROI object
createMaskCreate mask within image
deleteDelete handle object
getColorGet color used to draw ROI object
getPositionReturn current position of ROI object
getPositionConstraintFcnReturn function handle to current position constraint function
removeNewPositionCallbackRemove new-position callback from ROI object
resume(Not recommended) Resume execution of MATLAB command line
setColorSet color used to draw ROI object
setConstrainedPositionSet ROI object to new position
setFixedAspectRatioModePreserve aspect ratio when resizing ROI object
setPositionMove ROI object to new position
setPositionConstraintFcnSet position constraint function of ROI object
setResizableSet 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.

Compatibility Considerations

expand all

Not recommended starting in R2018b

Introduced before R2006a