imfreehand

(Not recommended) Create draggable freehand region

imfreehand is not recommended. Use the new Freehand 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.

Description

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

Creation

Syntax

h = imfreehand

h = imfreehand(hparent)

h = imfreehand(___,Name,Value)

Description

h = imfreehand begins interactive placement of a freehand region on the current axes, and returns an imfreehand object.

h = imfreehand(hparent) begins interactive placement of a freehand region on the object specified by hparent.

h = imfreehand(___,Name,Value) specifies name-value pairs that control the behavior of the freehand region.

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.

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

Freehand region is closed, specified as true or false. When set to true (the default), imfreehand draws a straight line to connect the endpoints of the freehand line to create a closed region. If set to false, imfreehand leaves the region open.

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

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

Interactive Behavior	Description
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. imfreehand copies an n-by-2 array of coordinates on the boundary of the ROI to the clipboard.
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 Deletable property to false: h = imfreehand(); h.Deletable = false;

Object Functions

Each imfreehand object supports a number of methods. Type methods imfreehand 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
setPositionConstraintFcn	Set position constraint function of ROI object
wait	(Not recommended) Block MATLAB command line until ROI creation is finished

Examples

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 wait function to block the MATLAB^® command line. Double-click on the freehand region to resume execution of the MATLAB command line.

position = wait(h);

Tips

• If you use imfreehand with 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 plot function, the axes limits automatically expand to accommodate the movement of the freehand region.

• To cancel the interactive placement, press the Esc key. imfreehand returns an empty object.

Version History

Introduced in R2007b

R2018b: imfreehand 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 imfreehand ROI object with the Freehand or AssistedFreehand object. You can also use the ROI convenience functions drawfreehand or drawassisted.

Update ROI Creation Code

Update all instances of imfreehand.

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

Other ROI Code Updates

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 getColor or setColor with use of the Color property. In some cases, you must replace the imfreehand object function with an object function of the new Freehand ROI. Each of the individual imfreehand ROI object functions include information about migrating to the new Freehand ROI object. For a migration overview, see ROI Migration.