impoly() - Image Processing
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.ParameterDescription
'Closed'Scalar logical that controls whether the polygon is closed.
When set to true (the default), impoly creates
a closed polygon, that is, it draws a straight line between the last
vertex specified and the first vertex specified to create a closed
region. When Closed is false, impoly does
not connect the last vertex with the first vertex, creating an open
polygon (or polyline).
'PositionConstraintFcn'Function handle fcn that is called
whenever the object is dragged using the mouse. You can use this function
to control where the line can be dragged. See the help for the setPositionConstraintFcn method for information
about valid function handles.
Interactive BehaviorWhen 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 the context
menu when the pointer is on the polygon, not on a vertex.
The following table lists the interactive behaviors supported
by impoly.Interactive BehaviorDescription
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.
Deleting the polygonMove the pointer inside the polygon or on one of the lines
that define the polygon, not on a vertex. Right-click and select Delete from
the context menu. To remove this option from the context menu, set
the Deletable property to false: h = impoly();
h.Deletable = false;
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 polygonMove 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.
MethodsEach 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 objectSee imroi for information.createMask — Create mask within imageSee imroi for information.delete — Delete ROI objectSee imroi for information.getColor — Get color used to draw ROI objectSee imroi for information.getPosition — Return current position of polygonpos = 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 functionSee imroi for information.removeNewPositionCallback — Remove new-position callback
from ROI object.See imroi for information.resume — Resume execution of MATLAB command lineSee imroi for information.setClosed — Set geometry of polygonsetClosed(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 objectSee imroi for information.setConstrainedPosition — Set ROI object to new positionSee imroi for information.setPosition — Set polygon to new positionsetPosition(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 draggedsetVerticesDraggable(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 finishedSee imroi for information.
Syntax
<![CDATA[h = impolyh = impoly(hparent)h = impoly(hparent, position)h = impoly(..., param1, val1, ...)]]>
Example
<![CDATA[Draw Polygon on Image and Specify Position Constraint Function
Draw a polygon on an image and specify a position
constraint function using makeConstrainToRectFcn to
keep the polygon inside the original xlim and ylim ranges.
Display updated position of the polygon in the title.
Display image.figure
imshow('gantrycrane.png');
Draw polygon on the image, specifying location of vertices.h = impoly(gca, [188,30; 189,142; 93,141; 13,41; 14,29]);
Get the API associated with the polygon so that you can
modify properties of the polygon.api = iptgetapi(h);Set the color of the polygon to yellow.api.setColor('yellow');
Define a function for the new position callback. This
function displays the current position of the polygon whenever it
is moved.api.addNewPositionCallback(@(p) title(mat2str(p,3)));
Create the function that constrains the movement of the
polygon, specifying the boundary of the image as the limits, and then
set the value of the setPositionConstraintFcn property.fcn = makeConstrainToRectFcn('impoly',get(gca,'XLim'),get(gca,'YLim'));
api.setPositionConstraintFcn(fcn);
Interactively Create a Polygon by Clicking to Specify Vertex LocationsDisplay image.figure
imshow('gantrycrane.png');
Create a polygon, specifying several vertices, but leave
it unfinished so that you can finish it interactively. The example
sets Closed to false so that
the polygon is left open. When you move the cursor over one of the
endpoints of the polygon, the cursor shape changes to a circle.h = impoly(gca,[203,30; 202,142; 294,142],'Closed',false);
Complete the polygon. Grab one of the ends of the existing
lines. Extend the line by dragging it to another corner of the shape
you want to create. Then, while positioning the cursor over the line,
press the A key to add a vertex to the line.
Once you create the vertex you can drag it anywhere you want to create
the shape you want. Continue dragging the line and adding vertices
as you want. For more information, see Interactive Behavior.]]>
Output / Return Value
Limitations
Alternatives / See Also
Reference