Main Content


(Not recommended) Create draggable ellipse

imellipse is not recommended. Use the Ellipse ROI object instead. You can also use the ROI creation convenience function drawellipse. If you used imellipse to create a circular ROI, use the Circle ROI object instead. For more information, see Compatibility Considerations.


An imellipse object encapsulates an interactive ellipse over an image.

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



h = imellipse begins interactive placement of an ellipse on the current axes, and returns an imellipse object.

h = imellipse(hparent) begins interactive placement of an ellipse on the object specified by hparent.


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

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

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 ellipse as defined by a bounding rectangle, specified as a 4-element vector of the form [xmin ymin width height]. The initial size of the bounding 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 ellipse can be dragged. See the help for the setPositionConstraintFcn function for information about valid function handles.


expand all

ROI can be deleted, specified as true or false.

Data Types: logical


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. Right-click on the ellipse to access this context menu.

The table lists the interactive behavior supported by imellipse.

Interactive BehaviorDescription
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.
Deleting the ellipseMove the pointer inside the ellipse. Right-click and select Delete from the context menu. To remove this option from the context menu, set the Deletable property to false: h = imellipse(); h.Deletable = false;

Object Functions

Each imellipse object supports a number of methods. Type methods imellipse 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
getVerticesReturn vertices on perimeter of ellipse ROI object
removeNewPositionCallbackRemove 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
setConstrainedPositionSet ROI object to new position
setFixedAspectRatioModePreserve aspect ratio when resizing ROI object
setPosition(Not recommended) Move 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


Update Title when Ellipse Moves

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.

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

Click and Drag to Place Ellipse

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.

h = imellipse;
position = wait(h);


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.

Compatibility Considerations

expand all

Not recommended starting in R2018b

Introduced in R2007b