impositionrect (Image Processing Toolbox User's Guide)

Image Processing Toolbox User's Guide

Create draggable position rectangle

Syntax

```
H = impositionrect(hparent,position)
```

Description

H = impositionrect(hparent,position) creates a position rectangle on the object specified by hparent. The function returns H, a handle to the position rectangle, which is an hggroup object. hparent specifies the hggroup's parent, which is typically an axes object, but can also be any other object that can be the parent of an hggroup. position is a four-element position vector that specifies the initial location of the rectangle. position has the form [XMIN YMIN WIDTH HEIGHT]

All measurements are in units specified by the Units property axes object.When you do not specify the position argument, impositionrect uses [0 0 1 1] as the default value.

Remarks

A position rectangle can be dragged interactively using the mouse. When the position rectangle occurpies a small number of screen pixels, its appearance changes to aid visibility.

The position rectangle has a context menu associated with it that you can use to copy the current position to the clipboard and change the color used to display the rectangle.

API Function Syntaxes

A position rectangle contains a structure of function handles, called an API, that can be used to manipulate it. To retrieve this structure from the position rectangle, use the iptgetapi function.

```
API = iptgetapi(H)
```

The following lists the functions in the position rectangle API in the order they appear in the API structure.

Function
Description

setPosition
Sets the position rectangle to a new position.
api.setPosition(new_position)
where new_position is a four-element position vector.

getPosition
Returns the current position of the position rectangle.
position = api.getPosition()
position is a four-element position vector.

delete
Deletes the position rectangle associated with the API.

api.delete()

setColor
Sets the color used to draw the position rectangle.
api.setColor(new_color)
where new_color is a three-element vector specifying an RGB value.

addNewPositionCallback
Adds the function handle fun to the list of new-position callback functions.
id = api.addNewPositionCallback(fun)
Whenever the position rectangle changes its position, each function in the list is called with the syntax:
fun(position)
The return value, id, is used only with removeNewPositionCallback.

removeNewPositionCallback
Removes the corresponding function from the new-position callback list.
api.removeNewPositionCallback(id)
where id is the identifier returned by api.addNewPositionCallback

setDragConstraintCallback
Sets the drag constraint function to be the specified function handle, fcn.
api.setDragConstraintCallback(fcn)
Whenever the position rectangle is moved because of a mouse drag, the constraint function is called using the syntax:
constrained_position = fcn(new_position)
where new_position is a four-element position vector. This allows a client, for example, to control where the position rectangle may be dragged.

Function	Description
`setPosition`	Sets the position rectangle to a new position. `api.setPosition(new_position)` where `new_position` is a four-element position vector.
`getPosition`	Returns the current position of the position rectangle. position = api.getPosition() `position` is a four-element position vector.
`delete`	Deletes the position rectangle associated with the API. api.delete()
`setColor`	Sets the color used to draw the position rectangle. api.setColor(new_color) where `new_color` is a three-element vector specifying an RGB value.
`addNewPositionCallback`	Adds the function handle `fun` to the list of new-position callback functions. id = api.addNewPositionCallback(fun) Whenever the position rectangle changes its position, each function in the list is called with the syntax: fun(position) The return value, `id`, is used only with `removeNewPositionCallback`.
`removeNewPositionCallback`	Removes the corresponding function from the new-position callback list. api.removeNewPositionCallback(id) where `id` is the identifier returned by `api.addNewPositionCallback`
`setDragConstraintCallback`	Sets the drag constraint function to be the specified function handle, `fcn`. api.setDragConstraintCallback(fcn) Whenever the position rectangle is moved because of a mouse drag, the constraint function is called using the syntax: constrained_position = fcn(new_position) where `new_position` is a four-element position vector. This allows a client, for example, to control where the position rectangle may be dragged.

Examples

Display in the command window the updated position of the position rectangle as it moves in the axes.

close all, plot(1:10)
h = impositionrect(gca, [4 4 2 2]);
api = iptgetapi(h);
api.addNewPositionCallback(@(p) disp(p));

Constrain the position rectangle to move only up and down.

close all, plot(1:10)
h = impositionrect(gca, [4 4 2 2]);
api = getappdata(h, 'API');
api.setDragConstraintCallback(@(p) [4 p(2:4)]);

Specify the color of the position rectangle.

close all, plot(1:10)
h = impositionrect(gca, [4 4 2 2]);
api = iptgetapi(h, 'API');
api.setColor([1 0 0]);

When the position rectangle occupies only a few pixels on the screen, the rectangle is drawn in a different style to increase its visibility.

close all, imshow cameraman.tif
h = impositionrect(gca, [100 100 10 10]);

See Also

iptgetapi

impixelregionpanel improfile