Image Processing Toolbox™

impoly - Create draggable, resizable polygon

Syntax

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

Description

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

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

h = impoly(hparent, position) creates a draggable, resizable polygon on the object specified by hparent. position is an n-by-2 array that specifies the initial position of the vertices of the polygon. position has the form [X1,Y1;...;XN,YN].

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

Interactive Behavior

When you call impoly with an interactive syntax, the pointer changes to a cross hairs when over the image. Click and drag the mouse to define the vertices of the polygon and adjust the size, shape, and position of the polygon. The polygon also supports a context menu that you can use to control aspects of its appearance and behavior. The choices in the context menu vary whether you position the pointer on an edge of the polygon (or anywhere inside the region) or on one of the vertices. The following figure shows a polygon being created.

The following table lists the interactive behaviors supported by impoly.

Interactive Behavior	Description
Closing the polygon.	Use any of the following mechanisms: Move the pointer over the initial vertex of the polygon that you selected. The pointer changes to a circle . Click either mouse button. Double-click the left mouse button. This action creates a vertex at the point under the mouse and draws a straight line connecting this vertex with the initial vertex. Click the right mouse button. This action draws a line connecting the last vertex selected with the initial vertex; it does not create a new vertex.
Adding a new vertex.	Move the pointer over an edge of the polygon and press the A key. The shape of the pointer changes . Click the left mouse button to create a new vertex at that position on the line.
Moving a vertex. (Reshaping the polygon.)	Move the pointer over a vertex. The pointer changes to a circle . Click and drag the vertex to its new position.
Deleting a vertex.	Move the pointer over a vertex. The shape changes to a circle . Right-click and select Delete Vertex from the vertex context menu. This action deletes the vertex and adjusts the shape of the polygon, drawing a new straight line between the two vertices that were neighbors of the deleted vertex.
Moving the polygon.	Move the pointer inside the polygon. The pointer changes to a fleur shape . Click and drag the mouse to move the polygon.
Changing the color of the polygon	Move the pointer inside the polygon. Right-click and select Set Color from the context menu.
Retrieving the coordinates of the vertices	Move the pointer inside the polygon. Right-click and select Copy Position from the context menu. impoly copies an n-by-2 array containing the x- and y-coordinates of each vertex to the clipboard. n is the number of vertices you specified.

Methods

Each impoly object supports a number of methods, listed below. Methods inherited from the base class are links to that class.

addNewPositionCallback — Add new-position callback to ROI object

See imroi for information.

delete — Delete ROI object

See imroi for information.

getPosition — Return current position of polygon

pos = getPosition(h) returns the current position of the polygon h. The returned position, pos, is an N-by-2 array [X1 Y1;...;XN YN].

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.

setClosed — Set geometry of polygon

setClosed(TF) sets the geometry of the polygon. TF is a logical scalar. true means that the polygon is closed. false means that the polygon is an open polyline.

setColor — Set color used to draw ROI object

See imroi for information.

setConstrainedPosition — Set ROI object to new position

See imroi for information.

setPosition — Set polygon to new position

setPosition(h,pos) sets the polygon h to a new position. The new position, pos, is an n-by-2 array, [x1 y1; ..; xn yn] where each row specifies the position of a vertex of the polygon.

setPositionConstraintFcn — Set position constraint function of ROI object.

See imroi for information.

setVerticesDraggable — Control whether vertices may be dragged

setVerticesDraggable(h,TF) sets the interactive behavior of the vertices of the polygon h. TF is a logical scalar. True means that the vertices of the polygon are draggable. False means that the vertices of the polygon are not draggable.

wait — Block MATLAB command line until ROI creation is finished

See imroi for information.

Remarks

If you use impoly with an axes that contains an image object, and do not specify a position constraint function, users can drag the polygon outside the extent of the image and lose the polygon. When used with an axes created by the plot function, the axes limits automatically expand when the polygon is dragged outside the extent of the axes.

Examples

Example 1

Display updated position in the title. Specify a position constraint function using makeConstainToRectFcn to keep the polygon inside the original xlim and ylim ranges.

figure, imshow('gantrycrane.png');
h = impoly(gca, [188,30; 189,142; 93,141; 13,41; 14,29]);
setColor(h,'yellow');
addNewPositionCallback(h,@(p) title(mat2str(p,3)));
fcn = makeConstrainToRectFcn('impoly',get(gca,'XLim'),get(gca,'YLim'));
setPositionConstraintFcn(h,fcn);

Example 2

Interactively place a polygon by clicking to specify vertex locations. Double-click or right-click to finish positioning the polygon. Use wait to block the MATLAB command line. Double-click on the polygon to resume execution of the MATLAB command line.

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

See also

imellipse, imfreehand, imline, impoint, imrect, imroi, makeConstrainToRectFcn

impoint

impositionrect