Quantcast

Documentation Center

  • Trial Software
  • Product Updates

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 an imdistline 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 draggable 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 BehaviorContext Menu Item
Export endpoint and distance data to the workspaceSelect 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 constraintsSelect 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 objectSelect 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 Tips.)

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.

setLabelVisible

Sets visibility of Distance tool text label.

 setLabelVisible(h,TF) 

h is the Distance tool. TF is a logical scalar. When the distance label is visible, TF is true. When the distance label is invisible, TF is false.

getLabelVisible

Gets visibility of Distance tool text label.

TF = getLabelVisible(h)

h is the Distance tool. TF is a logical scalar. When TF is true, the distance label is visible. When TF is false, the distance label is invisible.

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.

getColor

Gets the color used to draw the ROI object h.

color = getColor(h)

color is a three-element vector that specifies an RGB triplet.

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

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');        

More About

expand all

Tips

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.

See Also

|

Was this topic helpful?