imline

Create draggable, resizable line

Syntax

h = imline
h = imline(hparent)
h = imline(hparent, position)
h = imline(hparent, x, y)
h = imline(..., param1, val1,...)

Description

h = imline begins interactive placement of a line on the current axes. The function returns h, a handle to an imline object. The line has a context menu associated with it that controls aspects of its appearance and behavior—see Interactive Behavior. Right-click on the line to access this context menu.

h = imline(hparent) begins interactive placement of a line on the object specified by hparent. hparent specifies the HG parent of the line graphics, which is typically an axes but can also be any other object that can be the parent of an hggroup

h = imline(hparent, position) creates a draggable, resizable line on the object specified by hparent. position is a 2-by-2 array that specifies the initial endpoint positions of the line in the form [X1 Y1; X2 Y2].

h = imline(hparent, x, y) creates a line on the object specified by hparent. x and y are two-element vectors that specify the initial endpoint positions of the line in the form x = [X1 X2], y = [Y1 Y2].

h = imline(..., param1, val1,...) creates a draggable, resizable line, specifying parameters and corresponding values that control the behavior of the line. The following tables lists the parameter available. Parameter names can be abbreviated, and case does not matter.

ParameterDescription

'PositionConstraintFcn'

Function handle fcn that is called whenever the object is dragged using the mouse. You can use this function to control where the line can be dragged. See the help for the setPositionConstraintFcn method for information about valid function handles.

Interactive Behavior

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

The following table lists the interactive behavior supported by imline.

Interactive BehaviorDescription
Moving the lineMove the pointer over the line. The pointer changes to a fleur shape . Click and drag the mouse to move the line.
Moving the endpoints of the lineMove the pointer over either end of the line. The pointer changes to the pointing finger, . Click and drag the mouse to resize the line.
Changing the color used to display the lineMove the pointer over the line. Right-click and select Set Color from the context menu.
Retrieving the coordinates of the endpoints of the lineMove the pointer over the line. Right-click and select Copy Position from the context menu. imline copies a 2-by-2 array to the clipboard specifying the coordinates of the endpoints of the line in the form [X1 Y1; X2 Y2].
Deleting the lineMove the pointer on top of the line. Right-click and select Delete from the context menu. To remove this option from the context menu, set the Deletable property to false: h = imline(); h.Deletable = false;

Methods

Each imline object supports a number of methods. Type methods imline to see a list of the methods.

addNewPositionCallback — Add new-position callback to ROI object

See imroi for information.

delete — Delete ROI object

See imroi for information.

getColor — Get color used to draw ROI object.

See imroi for information.

getPosition — Return current position of line

Returns the endpoint positions of the line.

pos = api.getPosition()

pos is a 2-by-2 array [X1 Y1; X2 Y2].

getPositionConstraintFcn — Return function handle to current position constraint function

See imroi for information.

removeNewPositionCallback — Remove new-position callback from ROI object.

See imroi for information.

resume — Resume execution of MATLAB command line

See imroi for information.

setColor — Set color used to draw ROI object

See imroi for information.

setConstrainedPosition — Set ROI object to new position

See imroi for information.

setPosition — Set line to new position

setPosition(h,pos) sets the line h to a new position. The new position, pos, has the form, [X1 Y1; X2 Y2].

setPosition(h,x,y) sets the line h to a new position. x and y specify the endpoint positions of the line in the form x = [x1 x2], y = [y1 y2].

setPositionConstraintFcn — Set position constraint function of ROI object.

See imroi for information.

wait — Block MATLAB command line until ROI creation is finished

See imroi for information.

Examples

Example 1

Use a custom color for displaying the line. Use addNewPositionCallback method. Move the line, note that the 2-by-2 position vector of the line is displayed in the title above the image. Explore the context menu of the line by right clicking on the line.

figure, imshow('pout.tif');
h = imline(gca,[10 100], [100 100]);
setColor(h,[0 1 0]);
id = addNewPositionCallback(h,@(pos) title(mat2str(pos,3)));
 
% After observing the callback behavior, remove the callback.
% using the removeNewPositionCallback API function.     
removeNewPositionCallback(h,id);

Example 2

Interactively place a line by clicking and dragging. Use wait to block the MATLAB command line. Double-click on the line to resume execution of the MATLAB command line

figure, imshow('pout.tif');
h = imline;
position = wait(h);

More About

expand all

Tips

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

Was this topic helpful?