(Not recommended) Create draggable, resizable polygon
impoly is not recommended. Use the new
object instead. You can also use the new ROI creation convenience function
drawpolygon. Another option is the
object, which enables you to create an open polygon, or polyline
shape. For more information, see Compatibility Considerations.
impoly object encapsulates an interactive polygon over
You can add vertices and adjust the size and position of the polygon by using the mouse. The polygon also has a context menu that controls aspects of its appearance and behavior. For more information, see Usage.
h = impoly begins interactive placement of a polygon on
the current axes, and returns an
h = impoly( begins
interactive placement of a polygon on the object specified by
h = impoly(___,
specifies name-value pairs that control the behavior of the polygon.
hparent — Handle to parent object
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
position — Position of polygon vertices
Position of polygon vertices, specified as an n-by-2 matrix. The two columns define the x- and y-coordinate, respectively, of each of the n vertices.
Specify optional pairs of arguments as
the argument name and
Value is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name in quotes.
PositionConstraintFcn — Position constraint function
Position constraint function, specified as a function handle.
fcn is called whenever the mouse is dragged.
You can use this function to control where the polygon can be
dragged. See the help for the
setPositionConstraintFcn function for information
about valid function handles.
Closed — Polygon is closed
true (default) |
Polygon is closed, specified as
false. When set to
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
impoly does not connect the last vertex with
the first vertex, creating an open polygon (or polyline).
Deletable — ROI can be deleted
true (default) |
ROI can be deleted, specified as
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. By default,
impoly draws a straight line connecting the last
point you drew with the first point, but you can control this behavior using the
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 figure shows the context menu when the pointer is on the polygon but not on a vertex.
The table lists the interactive behaviors supported by
|Closing the polygon.|
Use any of the following mechanisms:
|Adding a new vertex.||Move the pointer over an edge of the polygon. Press and hold 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 polygon||Move 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 |
|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 object supports a number of methods. Type
methods impoly to see a complete list.
|Add new-position callback to ROI object|
|(Not recommended) Create mask within image|
|Delete handle object|
|Get color used to draw ROI object|
|Return current position of ROI object|
|Return function handle to current position constraint function|
|Remove new-position callback from ROI object|
|(Not recommended) Resume execution of MATLAB command line|
|Set closure behavior of ROI object|
|(Not recommended) Set color used to draw ROI object|
|Set ROI object to new position|
|(Not recommended) Move ROI object to new position|
|Set position constraint function of ROI object|
|Set vertex behavior of ROI object|
|(Not recommended) Block MATLAB command line until ROI creation is finished|
Draw Polygon on Image and Specify Position Constraint Function
Display an image.
Draw a polygon on the image, specifying the location of five vertices.
h = impoly(gca,[188,30; 189,142; 93,141; 13,41; 14,29]);
Set the color of the polygon to yellow.
Define a function for the new position callback. This function displays the current position of the polygon whenever it is moved.
addNewPositionCallback(h, @(p) title(mat2str(p,3)));
Create the function that constrains the movement of the polygon by using
specifying the boundary of the image as the limits. Enforce the boundary
constraint function using
fcn = makeConstrainToRectFcn("impoly",get(gca,"XLim"),get(gca,"YLim")); setPositionConstraintFcn(h,fcn);
Interactively Create a Polygon by Clicking to Specify Vertex Locations
Create a polygon, specifying several vertices, but leave it unfinished so
that you can finish it interactively. The example sets
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 and hold 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 Usage.
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.
Version HistoryIntroduced in R2007b
impoly is not recommended
Starting in R2018b, a new set of ROI objects replaces the existing set of ROI objects. The new objects provide more functional capabilities, such as face color transparency. The new classes also support events that you can use to respond to changes in your ROI such as moving or being clicked. Although there are no plans to remove the old ROI objects at this time, switch to the new ROIs to take advantage of the additional capabilities and flexibility. For more information on creating ROIs using the new ROI functions, see Create ROI Shapes.
Replace use of the
impoly object with the
Polyline object. You can also use the
drawpolyline function to create an these objects.
Update all instances of
|Discouraged Usage||Recommended Replacement|
This example creates a closed polygonal ROI.
imshow("cameraman.tif"); h = impoly(gca,[10 10; 10 100; 80 100]);
Here is equivalent code, replacing the old ROI object with the new ROI object. This example uses the ROI creation convenience function. Note that you must specify the position information as a name-value argument.
imshow("cameraman.tif"); h = drawpolygon(gca,"Position",[10 10; 10 100; 80 100]);
Update code that uses any of the object methods of the
impoly ROI object. In many cases, you can replace the
call to an
impoly object method by simply accessing or
setting the value of a
Polygon ROI object property. For
example, replace calls to
setColor with use of the
property. In some case, you must replace the
method with an object method of the new ROI. The documentation for each
impoly ROI object method includes information about
migrating to the new ROI object. For a migration overview, see ROI Migration.