impoly

(Not recommended) Create draggable, resizable polygon

impoly is not recommended. Use the new Polygon object instead. You can also use the new ROI creation convenience function drawpolygon. Another option is the Polyline object, which enables you to create an open polygon, or polyline shape. For more information, see Compatibility Considerations.

Description

An impoly object encapsulates an interactive polygon over an image.

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.

Creation

Syntax

h = impoly

h = impoly(hparent)

h = impoly(hparent,position)

h = impoly(___,Name,Value)

Description

h = impoly begins interactive placement of a polygon on the current axes, and returns an impoly object.

h = impoly(hparent) begins interactive placement of a polygon on the object specified by hparent.

h = impoly(hparent,position) creates a draggable, resizeable polygon with vertices at coordinates defined by position.

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

Input Arguments

hparent — Handle to parent object

handle

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 — Position of polygon vertices

n-by-2 matrix

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.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is 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

function handle

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) | false

Polygon is closed, specified as true or false. 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).

Data Types: logical

Properties

Deletable — ROI can be deleted

true (default) | false

ROI can be deleted, specified as true or false.

Data Types: logical

Usage

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 Closed parameter.

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 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. 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 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 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.

Object Functions

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

addNewPositionCallback	Add new-position callback to ROI object
createMask	(Not recommended) Create mask within image
delete	Delete handle object
getColor	Get color used to draw ROI object
getPosition	Return current position of ROI object
getPositionConstraintFcn	Return function handle to current position constraint function
removeNewPositionCallback	Remove new-position callback from ROI object
resume	(Not recommended) Resume execution of MATLAB command line
setClosed	Set closure behavior of ROI object
setColor	(Not recommended) Set color used to draw ROI object
setConstrainedPosition	Set ROI object to new position
setPosition	(Not recommended) Move ROI object to new position
setPositionConstraintFcn	Set position constraint function of ROI object
setVerticesDraggable	Set vertex behavior of ROI object
wait	(Not recommended) Block MATLAB command line until ROI creation is finished

Examples

Draw Polygon on Image and Specify Position Constraint Function

Display an image.

imshow("gantrycrane.png")

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.

setColor(h,"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 makeConstrainToRectFcn, specifying the boundary of the image as the limits. Enforce the boundary constraint function using setPositionConstraintFcn.

fcn = makeConstrainToRectFcn("impoly",get(gca,"XLim"),get(gca,"YLim"));
setPositionConstraintFcn(h,fcn);

Interactively Create a Polygon by Clicking to Specify Vertex Locations

Display 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 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.

Tips

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 History

Introduced in R2007b

R2018b: 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 Polygon or Polyline object. You can also use the drawpolygon or drawpolyline function to create an these objects.

Update ROI Creation Code

Update all instances of impoly.

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]);

Other ROI Code Updates

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 getColor or setColor with use of the Color property. In some case, you must replace the impoly object 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.