This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

imdistline

Distance tool

Description

An imdistline object is a type of imline that 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

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.

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
createMaskCreate 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
resumeResume execution of MATLAB command line
setColorSet 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
setPositionMove ROI object to new position
setPositionConstraintFcnSet position constraint function of ROI object
waitBlock MATLAB command line until ROI creation is finished

Note

Each function that accepts an imline also accepts an imdistline. These objects define position in the same way.

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

Introduced before R2006a