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

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.

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

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

Input Arguments

hparent — Handle to parent object

handle

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 — x-coordinates of endpoints

2-element numeric vector

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 — y-coordinates of endpoints

2-element numeric vector

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

Deletable — ROI can be deleted

true (default) | false

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.

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 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.

Object Functions

addNewPositionCallback	Add new-position callback to ROI object
createMask	(Not recommended) Create mask within image
delete	Delete handle object
getAngleFromHorizontal	Return angle between Distance tool and horizontal axis
getColor	Get color used to draw ROI object
getDistance	Return distance between endpoints of Distance tool
getLabelHandle	Return handle to text label of Distance tool
getLabelTextFormatter	Return format of text label of Distance tool
getLabelVisible	Return visibility of text label of Distance tool
getPosition	Return current position of ROI object
getPositionConstraintFcn	Return function handle to current position constraint function
removeNewPositionCallback	Remove 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
setConstrainedPosition	Set ROI object to new position
setLabelTextFormatter	Set format used to display text label of Distance tool
setLabelVisible	Set visibility of text label of Distance tool
setPosition	(Not recommended) Move ROI object to new position
setPositionConstraintFcn	Set position constraint function of ROI object
wait	(Not recommended) Block MATLAB command line until ROI creation is finished

Examples

Insert Distance Tool into an Image

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 Distance Tool

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 Distance Tool with Spatial Referencing

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