impoint

(Not recommended) Create draggable point

impoint is not recommended. Use the new Point ROI object instead. You can also use the new ROI creation convenience function drawpoint. For more information, see Compatibility Considerations.

Description

An impoint object encapsulates an interactive point over an image.

You can adjust the position of the point by using the mouse. The point also has a context menu that controls aspects of its appearance and behavior. For more information, see Usage.

Creation

Syntax

h = impoint

h = impoint(hparent)

h = impoint(hparent,position)

h = impoint(hparent,x,y)

h = impoint(___,Name,Value)

Description

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

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

h = impoint(hparent,position) creates a draggable point with coordinates defined by position.

example

h = impoint(hparent,x,y) creates a draggable point with (x, y) coordinates defined by x and y.

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

Input Arguments

expand all

`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 point
2-element vector

Position of point, specified as a 2-element vector of the form [x y].

`x` — x-coordinate of point
numeric scalar

x-coordinate of the point, specified as a numeric scalar.

`y` — y-coordinate of point
numeric scalar

y-coordinate of the point, specified as a numeric scalar.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

`'PositionConstraintFcn'` — Position constraint function
function handle

Position constraint function, specified as the comma-separated pair consisting of 'PositionConstraintFcn' and a function handle. fcn is called whenever the mouse is dragged. You can use this function to control where the point can be dragged. See the help for the setPositionConstraintFcn function for information about valid function handles.

Properties

expand all

`Deletable` — ROI can be deleted
`true` (default) | `false`

ROI can be deleted, specified as true or false.

Data Types: logical

Usage

When you call impoint with an interactive syntax, the pointer changes to a cross hairs when over the image. Click and drag the mouse to specify the position of the point. The point supports a context menu that you can use to control aspects of its appearance and behavior.

The table describes the interactive behavior supported by impoint.

Interactive Behavior	Description
Moving the point.	Move the mouse pointer over the point. The mouse pointer changes to a fleur shape . Click and drag the mouse to move the point.
Changing the color used to display the point.	Move the mouse pointer over the point. Right-click and select Set Color from the context menu and specify the color you want to use.
Retrieving the coordinates of the point.	Move the mouse pointer over the point. Right-click and select Copy Position from the context menu to copy a 1-by-2 array to the clipboard specifying the coordinates of the point `[X Y]`.
Deleting the point	Move the pointer on top of the point. Right-click and select Delete from the context menu. To remove this option from the context menu, set the `Deletable` property to false: `h = impoint(); h.Deletable = false;`

Object Functions

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

`addNewPositionCallback`	Add new-position callback to ROI object
`createMask`	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
`setColor`	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
`setString`	Set text label for point ROI object
`wait`	(Not recommended) Block MATLAB command line until ROI creation is finished

Examples

Enforce Boundary Constraint when Point Moves

Use impoint functions to set custom color, set a label, enforce a boundary constraint, and update position in title as point moves.

imshow('rice.png')
h = impoint(gca,100,200);

Update the title with the new position by using addNewPositionCallback.

addNewPositionCallback(h,@(h) title(sprintf('(%1.0f,%1.0f)',h(1),h(2))));

Construct a boundary constraint function by using makeConstrainToRectFcn.

fcn = makeConstrainToRectFcn('impoint',get(gca,'XLim'),get(gca,'YLim'));

Enforce the boundary constraint function using setPositionConstraintFcn.

setPositionConstraintFcn(h,fcn);
setColor(h,'r');
setString(h,'Point label');

Click and Drag to Move Point

Interactively place a point. Use wait to block the MATLAB^® command line. Double-click on the point to resume execution of the MATLAB command line

imshow('pout.tif')
h = impoint(gca,[]);
position = wait(h);

Tips

If you use impoint with an axes that contains an image object, and do not specify a drag constraint function, then users can drag the point outside the extent of the image and lose the point. When used with an axes created by the plot function, the axes limits automatically expand to accommodate the movement of the point.

Compatibility Considerations

expand all

`impoint` 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 ROI Creation Overview.

Replace use of the impoint ROI object with the new Point ROI object. You can also use the ROI creation convenience function drawpoint.

Update ROI Creation Code

Update all instances of impoint.

Discouraged Usage	Recommended Replacement
This example creates a point ROI. imshow('cameraman.tif'); h = impoint(gca,[25 50]);	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 size and position information as a name,value pair imshow('cameraman.tif'); h = drawpoint(gca,'Position',[25 50]);

Other ROI Code Updates

Update code that uses any of the object functions of the impoint ROI object. In many cases, you can replace the call to an impoint object function by simply accessing or setting the value of an Point ROI object property. For example, replace calls to getColor or setColor with use of the Color property. In some cases, you must replace the impoint object function with an object function of the new Point ROI. Each of the individual impoint ROI object functions include information about migrating to the new Point ROI object. For a migration overview, see ROI Migration.

Documentation

impoint

Description

Creation

Syntax

Description

Input Arguments

`hparent` — Handle to parent object
handle

`position` — Position of point
2-element vector

`x` — x-coordinate of point
numeric scalar

`y` — y-coordinate of point
numeric scalar

`'PositionConstraintFcn'` — Position constraint function
function handle

Properties

`Deletable` — ROI can be deleted
`true` (default) | `false`

Usage

Object Functions

Examples

Enforce Boundary Constraint when Point Moves

Click and Drag to Move Point

Tips

Compatibility Considerations

`impoint` is not recommended

See Also

Topics

Image Processing Toolbox Documentation

Support

Documentation

impoint

Description

Creation

Syntax

Description

Input Arguments

hparent — Handle to parent object handle

position — Position of point 2-element vector

x — x-coordinate of point numeric scalar

y — y-coordinate of point numeric scalar

'PositionConstraintFcn' — Position constraint function function handle

Properties

Deletable — ROI can be deleted true (default) | false

Usage

Object Functions

Examples

Enforce Boundary Constraint when Point Moves

Click and Drag to Move Point

Tips

Compatibility Considerations

impoint is not recommended

See Also

Topics

Image Processing Toolbox Documentation

Support

`hparent` — Handle to parent object
handle

`position` — Position of point
2-element vector

`x` — x-coordinate of point
numeric scalar

`y` — y-coordinate of point
numeric scalar

`'PositionConstraintFcn'` — Position constraint function
function handle

`Deletable` — ROI can be deleted
`true` (default) | `false`

`impoint` is not recommended