Main Content

imdistline

Distance tool

Description

An imdistline object encapsulates a Distance tool, which consists of an interactive line over an image, paired with a text label that displays the distance between the line endpoints.

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

Creation

Description

example

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

h = imdistline(hparent) creates a draggable Distance tool on the object specified by hparent.

example

h = imdistline(___,x,y) creates a Distance tool with endpoints at the positions specified by x and y.

Input Arguments

expand all

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.

x-coordinates of endpoints, specified as a 2-element numeric vector.

Example: h = imdistline(gca,[10 100],[20 40]); sets the first endpoint at the (x, y) coordinate (10, 20) and the second endpoint at the coordinate (100, 40).

y-coordinates of endpoints, specified as a 2-element numeric vector.

Example: h = imdistline(gca,[10 100],[20 40]); sets the first endpoint at the (x, y) coordinate (10, 20) and the second endpoint at the coordinate (100, 40).

Properties

expand all

ROI can be deleted, specified as true or false.

Data Types: logical

Usage

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.

Distance tool displaying a blue line over an image, with a label that indicates that the length of the line is 120.0 pixels.

The line also supports a context menu that allows you to control various aspects of its functioning and appearance. Right-click the line to access the 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.

Object Functions

addNewPositionCallbackAdd new-position callback to ROI object
createMask(Not recommended) Create mask within image
deleteDelete handle object
getAngleFromHorizontalReturn angle between Distance tool and horizontal axis
getColorGet color used to draw ROI object
getDistanceReturn distance between endpoints of Distance tool
getLabelHandleReturn handle to text label of Distance tool
getLabelTextFormatterReturn format of text label of Distance tool
getLabelVisibleReturn visibility of text label of Distance tool
getPositionReturn current position of ROI object
getPositionConstraintFcnReturn function handle to current position constraint function
removeNewPositionCallbackRemove new-position callback from ROI object
resume(Not recommended) Resume execution of MATLAB command line
setColor(Not recommended) Set color used to draw ROI object
setConstrainedPositionSet ROI object to new position
setLabelTextFormatterSet format used to display text label of Distance tool
setLabelVisibleSet visibility of text label of Distance tool
setPosition(Not recommended) Move ROI object to new position
setPositionConstraintFcnSet position constraint function of ROI object
wait(Not recommended) Block MATLAB command line until ROI creation is finished

Examples

collapse all

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.

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

Position endpoints of the Distance tool at the specified locations.

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

Delete the Distance tool.

delete(h)

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 the initial position of distance tool on Harvard Bridge.

hline = imdistline(gca,[271 471],[108 650]);
setLabelTextFormatter(hline,'%02.0f meters');

Repeat the 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 the image to reflect desired units.

set(hImg,'XData',XDataInMeters,'YData',YDataInMeters);    
set(gca,'XLim',XDataInMeters,'YLim',YDataInMeters);

Specify the initial position of distance tool on Harvard Bridge.

hline = imdistline(gca,[271 471],[108 650]);
setLabelTextFormatter(hline,'%02.0f meters');

Tips

  • If you use imdistline with an axes that contains an image object, and do not specify a drag constraint function, then you 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.

  • You can also use the Line ROI object to create an interactive customizable distance tool. For an example, see Measure Distances in an Image.

Version History

Introduced before R2006a

See Also

|