Image Processing Toolbox™

imellipse - Create draggable ellipse

Syntax

h = imellipse
h = imellipse(hparent)
h = imellipse(hparent, position)
H = imellipse(...,param1, val1, ...)

Description

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

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

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

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

Interactive Behavior

When you call imellipse with an interactive syntax, the pointer changes to a cross hairs when over an image. Click and drag the mouse to specify the size and position of the ellipse. The ellipse also supports a context menu that you can use to control aspects of its appearance and behavior. The following figure illustrates the ellipse with its context menu.

The following table lists the interactive behavior supported by imellipse.

Interactive Behavior	Description
Moving the entire ellipse.	Move the pointer inside the ellipse. The pointer changes to a fleur shape . Click and drag the mouse to move the ellipse.
Resizing the ellipse.	Move the pointer over a resizing handle on the ellipse. The pointer changes to a double-ended arrow shape . Click and drag the mouse to resize the ellipse.
Changing the color used to display the ellipse.	Move the pointer inside the ellipse. Right-click and select Set Color from the context menu.
Retrieving the current position of the ellipse.	Move the pointer inside the ellipse. Right-click and select Copy Position from the context menu. imellipse copies a four-element position vector [xmin ymin width height] to the clipboard.
Preserving the current aspect ratio of the ellipse during resizing.	Move the pointer inside the ellipse. Right-click and select Fix Aspect Ratio from the context menu.

Methods

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

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.

getPosition — Return current position of ellipse

See imrect for information.

getPositionConstraintFcn — Return function handle to current position constraint function

See imroi for information.

getVertices — Return vertices on perimeter of ellipse

vert = getVertices(h) returns a set of vertices which lie along the perimeter of the ellipse h. vert is a N-by-2 array.

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

See imrect for information.

setPosition — Set ellipse to new position

See imrect for information.

setPositionConstraintFcn — Set position constraint function of ROI object.

See imroi for information.

setResizable — Set resize behavior of ellipse

See imrect for information.

wait — Block MATLAB command line until ROI creation is finished

vert = wait(h) blocks execution of the MATLAB command line until you finish positioning the ROI object h. You indicate completion by double-clicking on the ROI object. The returned vertices, vert, is of the form returned by the getVertices method.

Remarks

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

Examples

Example 1

Create an ellipse, using callbacks to display the updated position in the title of the figure. The example illustrates using the makeConstrainToRectFcn to keep the ellipse inside the original xlim and ylim ranges.

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

Example 2

Interactively place an ellipse by clicking and dragging. Use wait to block the MATLAB command line. Double-click on the ellipse to resume execution of the MATLAB command line.

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

See Also

imfreehand, imline, impoint, impoly, imrect, imroi, iptgetapi, makeConstrainToRectFcn

imdivide

imerode