Image Processing Toolbox™

imdistline - Distance tool

Syntax

h = imdistline h = imdistline(hparent) h = imdistline(..., x, y)

Description

h = imdistline creates a Distance tool on the current axes. The function returns h, a handle to the Distance tool, which is an hggroup object.

The Distance tool is a draggable, resizable line, superimposed on an axes, that measures the distance between the two endpoints of the line. The Distance tool displays the distance in a text label superimposed over the line. The tools specifies the distance in data units determined by the XData and YData properties, which is pixels, by default. The following figure shows a Distance tool on an axes.

To move the Distance tool, position the pointer over the line, the shape changes to the fleur, . Click and drag the line using the mouse. To resize the Distance tool, move the pointer over either of the endpoints of the line, the shape changes to the pointing finger, . Click and drag the endpoint of the line using the mouse. The line also supports a context menu that allows you to control various aspects of its functioning and appearance. See Context Menu for more information. Right-click the line to access the context menu.

h = imdistline(hparent) creates a Distance tool on the object specified by hparent. hparent specifies the Distance tool's parent, which is typically an axes object, but can also be any other object that can be the parent of an hggroup object.

h = imdistline(..., x, y) creates a Distance tool with endpoints located at the locations specified by the vectors x and y, where x = [x1 x2] and y =[y1 y2].

Context Menu

Distance Tool Behavior	Context Menu Item
Export endpoint and distance data to the workspace	Select Export to Workspace from the context menu.
Toggle the distance label on/off.	Select Show Distance Label from the context menu.
Specify horizontal and vertical drag constraints	Select Constrain Drag from the context menu.
Change the color used to display the line.	Select Set Color from the context menu.
Delete the Distance tool object	Select Delete from the context menu.

API Functions

The Distance tool contains a structure of function handles, called an API, that can be used to retrieve distance information and control other aspects of Distance tool behavior. To retrieve this structure from the Distance tool, use the iptgetapi function, where h is a handle to the Distance tool.

api = iptgetapi(h)

The following table lists the functions in the API, with their syntax and brief descriptions.

Function	Description
`getDistance`	Returns the distance between the endpoints of the Distance tool. dist = getDistance() The value returned is in data units determined by the `XData` and `YData` properties, which is pixels, by default.
`getAngleFromHorizontal`	Returns the angle in degrees between the line defined by the Distance tool and the horizontal axis. The angle returned is between 0 and 180 degrees. (For information about how this angle is calculated, see Remarks.) angle = getAngleFromHorizontal()
`setLabelTextFormatter`	Sets the format string used in displaying the distance label. `setLabelTextFormatter(str)` `str` is a character array specifying a format string in the form expected by `sprintf`.
`getLabelTextFormatter`	Returns a character array specifying the format string used to display the distance label. str = getLabelTextFormatter() `str` is a character array specifying a format string in the form expected by `sprintf`.
`setPosition`	Sets the endpoint positions of the Distance tool. setPosition(X,Y) setPosition([X1 Y1; X2 Y2])
`getPosition`	Returns the endpoint positions of the Distance tool. pos = getPosition() `pos` is a 2-by-2 array `[X1 Y1; X2 Y2]`.
`delete`	Deletes the Distance tool associated with the API. delete()
`setColor`	Sets the color used to draw the Distance tool. setColor(new_color) `new_color` can be a three-element vector specifying an RGB triplet, or a text string specifying the long or short names of a predefined color, such as `'white'` or `'w'`. For a complete list of these predefined colors and their short names, see `ColorSpec`.
`addNewPositionCallback`	Adds the function handle `fcn` to the list of new-position callback functions. id = addNewPositionCallback(fcn) Whenever the Distance tool changes its position, each function in the list is called with the following syntax. fcn(pos) `pos` is a 2-by-2 array `[X1 Y1; X2 Y2]`. The return value, `id`, is used only with `removeNewPositionCallback`.
`removeNewPositionCallback`	Removes the corresponding function from the new-position callback list. removeNewPositionCallback(id) `id` is the identifier returned by `addNewPositionCallback`.
`setPositionConstraintFcn`	Sets the position constraint function to be the specified function handle, `fcn`. Use this function to control where the Distance tool can be moved and resized. setPositionConstraintFcn(fcn) Whenever the Distance tool is moved or resized because of a mouse drag, the constraint function is called using the following syntax. constrained_position = fcn(new_position) `new_position` is a 2-by-2 array `[X1 Y1; X2 Y2]`.
`getPositionConstraintFcn`	Returns the function handle of the current drag constraint function. fcn = getDragConstraintFcn()

Remarks

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

To understand how imdistline calculates the angle returned by getAngleToHorizontal, draw an imaginary horizontal vector from the bottom endpoint of the distance line, extending to the right. The value returned by getAngleToHorizontal is the angle from this horizontal vector to the distance line, which can range from 0 to 180 degrees.

Examples

Example 1

Insert a Distance tool into an image. Use makeConstrainToRectFcn to specify a drag constraint function that prevents the Distance tool from being dragged outside the extent of the image. Right-click the Distance tool and explore the context menu options.

figure, imshow('pout.tif');
h = imdistline(gca);
api = iptgetapi(h);
fcn = makeConstrainToRectFcn('imline',...
                              get(gca,'XLim'),get(gca,'YLim'));
api.setDragConstraintFcn(fcn);

Example 2

Position endpoints of the Distance tool at the specified locations.

close all, imshow('pout.tif');
h = imdistline(gca,[10 100],[10 100]);

Delete the Distance tool.

api = iptgetapi(h);
api.delete();

Example 3

Use the Distance tool with XData and YData of associated image in non-pixel units. This example requires the boston.tif image from the Mapping Toolbox software, which includes material copyrighted by GeoEye™, all rights reserved.

start_row = 1478;
end_row = 2246;
meters_per_pixel = 1;
rows = [start_row meters_per_pixel end_row];
start_col = 349;
end_col = 1117;
cols = [start_col meters_per_pixel end_col];
img  = imread('boston.tif','PixelRegion',{rows,cols});
figure; 
hImg = imshow(img);
title('1 meter per pixel');
 
% Specify initial position of distance tool on Harvard Bridge.
hline = imdistline(gca,[271 471],[108 650]);
api = iptgetapi(hline);
api.setLabelTextFormatter('%02.0f meters');
 
% Repeat process but work with a 2 meter per pixel sampled image. Verify
% that the same distance is obtained.
meters_per_pixel = 2;
rows = [start_row meters_per_pixel end_row];
cols = [start_col meters_per_pixel end_col];
img  = imread('boston.tif','PixelRegion',{rows,cols});
figure;    
hImg = imshow(img);
title('2 meters per pixel');    
     
% Convert XData and YData to meters using conversion factor.
XDataInMeters = get(hImg,'XData')*meters_per_pixel; 
YDataInMeters = get(hImg,'YData')*meters_per_pixel;
     
% Set XData and YData of image to reflect desired units.    
set(hImg,'XData',XDataInMeters,'YData',YDataInMeters);    
set(gca,'XLim',XDataInMeters,'YLim',YDataInMeters);
     
% Specify initial position of distance tool on Harvard Bridge.
hline = imdistline(gca,[271 471],[108 650]);
api = iptgetapi(hline);
api.setLabelTextFormatter('%02.0f meters');