imrect

Create draggable rectangle

Syntax

h = imrect
h = imrect(hparent)
h = imrect(hparent, position)
h = imrect(..., param1, val1,...)

Description

h = imrect begins interactive placement of a rectangle on the current axes. The function returns h, a handle to an imrect object. The rectangle has a context menu associated with it that controls aspects of its appearance and behavior—see Interactive Behavior. Right-click on the rectangle to access this context menu.

h = imrect(hparent) begins interactive placement of a rectangle on the object specified by hparent. hparent specifies the HG parent of the rectangle graphics, which is typically an axes but can also be any other object that can be the parent of an hggroup.

h = imrect(hparent, position) creates a draggable rectangle on the object specified by hparent. position is a four-element vector that specifies the initial size and location of the rectangle. position has the form [xmin ymin width height].

h = imrect(..., param1, val1,...) creates a draggable rectangle, specifying parameters and corresponding values that control the behavior of the rectangle. The following table lists the parameter available. Parameter names can be abbreviated, and case does not matter.

ParameterDescription

'PositionConstraintFcn'

Function handle fcn that 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 method for information about valid function handles.

Interactive Behavior

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. The following figure shows the rectangle.

The following 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;

Methods

Each imrect object supports a number of methods, listed below. Type methods imrect to see a list of the methods.

addNewPositionCallback — Add new-position callback to ROI object

See imroi for information.

createMask — Create mask within image

See imroi for information.

delete — Delete ROI object

See imroi for information.

getColor — Get color used to draw ROI object

See imroi for information.

getPosition — Return current position of rectangle

pos = getPosition(h) returns the current position of the rectangle h. The returned position, pos, is a 1-by-4 array [xmin ymin width height].

getPositionConstraintFcn — Return function handle to current position constraint function

See imroi for information.

removeNewPositionCallback — Remove new-position callback from ROI object.

See imroi for information.

resume — Resume execution of MATLAB command line

See imroi for information.

setColor — Set color used to draw ROI object

See imroi for information.

setConstrainedPosition — Set ROI object to new position

See imroi for information.

setFixedAspectRatioMode — Control whether aspect ratio preserved during resize

setFixedAspectRatioMode(h,TF) sets the interactive resize behavior of the rectangle h. TF is a logical scalar. True means that the current aspect ratio is preserved during interactive resizing. False means that interactive resizing is not constrained.

setPosition — Set rectangle to new position

setPosition(h,pos) sets the rectangle h to a new position. The new position, pos, has the form [xmin ymin width height].

setPositionConstraintFcn — Set position constraint function of ROI object

See imroi for information.

setResizable — Set resize behavior of rectangle

setResizable(h,TF) sets whether the rectangle h may be resized interactively. TF is a logical scalar.

wait — Block MATLAB command line until ROI creation is finished

See imroi for information.

Examples

Example 1

Display updated position in the title. Specify a position constraint function using makeConstrainToRectFcn to keep the rectangle inside the original Xlim and Ylim ranges.

figure, imshow('cameraman.tif');
h = imrect(gca, [10 10 100 100]);
addNewPositionCallback(h,@(p) title(mat2str(p,3)));
fcn = makeConstrainToRectFcn('imrect',get(gca,'XLim'),get(gca,'YLim'));
setPositionConstraintFcn(h,fcn); 

Now drag the rectangle using the mouse.

Example 2

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.

figure, imshow('pout.tif');
h = imrect;
position = wait(h);

More About

expand all

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.

When the API function setResizable is used to make the rectangle non-resizable, the Fix Aspect Ratio context menu item is not provided.

Was this topic helpful?