(Not recommended) Create draggable freehand region
imfreehand is not recommended. Use the new
ROI object instead. You can also use the new ROI creation convenience function
drawfreehand. Another option is the
AssistedFreehand object, which enables you to hand-draw a shape that
automatically follows the edges in the underlying image. For more information, see Compatibility Considerations.
imfreehand object encapsulates an interactive freehand
region 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.
h = imfreehand begins interactive placement of a freehand
region on the current axes, and returns an
h = imfreehand( begins
interactive placement of a freehand region on the object specified by
h = imfreehand(___,
specifies name-value pairs that control the behavior of the freehand
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
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 freehand region can
be dragged. See the help for the
setPositionConstraintFcn function for information
about valid function handles.
Closed — Freehand region is closed
true (default) |
Freehand region is closed, specified as
false. When set to
imfreehand draws a straight line
to connect the endpoints of the freehand line to create a closed
region. If set to
imfreehand leaves the region open.
Deletable — ROI can be deleted
true (default) |
ROI can be deleted, specified as
When you call
imfreehand with an interactive syntax, the pointer
changes to a cross hairs when positioned over an image. Click and drag the
mouse to draw the freehand region and adjust the position of the region. By default,
imfreehand draws a straight line connecting the last point you
drew with the first point, but you can control this behavior using the
The freehand region also supports a context menu that you can use to control aspects of its appearance and behavior.
The table lists the interactive features supported by
|Moving the region.||Move the pointer inside the freehand region. The pointer changes to a fleur shape . Click and hold the left mouse button to move the region.|
|Changing the color used to draw the region.||Move the pointer inside the freehand region. Right-click and select Set Color from the context menu.|
|Retrieving the current position of the freehand region.||Move the pointer inside the freehand region. Right-click and select
Copy Position from the context menu.
|Deleting the region||Move the pointer inside the region. Right-click and select
Delete from the context menu. To remove
this option from the context menu, set the |
imfreehand object supports a number of methods. Type
methods imfreehand 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|
|Set position constraint function of ROI object|
|(Not recommended) Block MATLAB command line until ROI creation is finished|
Click and Drag to Place Freehand Region
Interactively place a closed freehand region of interest by clicking and dragging over an image.
imshow("pout.tif") h = imfreehand;
Interactively move the freehand region by clicking and dragging. Use the
function to block the MATLAB® command line. Double-click on the freehand region to resume
execution of the MATLAB command line.
position = wait(h);
If you use
imfreehandwith an axes that contains an image object, and do not specify a position constraint function, users can drag the freehand region outside the extent of the image and lose the freehand region. When used with an axes created by the
plotfunction, the axes limits automatically expand to accommodate the movement of the freehand region.
To cancel the interactive placement, press the Esc key.
imfreehandreturns an empty object.
Version HistoryIntroduced in R2007b
imfreehand is not recommended
Not recommended starting in R2018b
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.
Update all instances of
|Discouraged Usage||Recommended Replacement|
This example enables drawing of a free-hand ROI.
imshow("cameraman.tif"); h = imfreehand
Here is equivalent code, replacing the old ROI object with the new ROI object. This example uses the ROI creation convenience function.
imshow("cameraman.tif"); h = drawfreehand
Update code that uses any of the object functions of the
imfreehand ROI object. In many cases, you can replace the
call to an
imfreehand object function by simply accessing or
setting the value of a
Freehand ROI object property. For
example, replace calls to
setColor with use of the
property. In some cases, you must replace the
object function with an object function of the new
ROI. Each of the individual
imfreehand ROI object functions
include information about migrating to the new
object. For a migration overview, see ROI Migration.