uicaliper

Interactively measure distance in images using a caliper tool

Since R2025a

expand all in page

Description

The uicaliper object displays a caliper tool on an image object that you create using the imageshow function. You can use the caliper tool to interactively detect edges and measure distances in the image.

Note

This functionality requires the Automated Visual Inspection Library for Computer Vision Toolbox™. You can install the Automated Visual Inspection Library for Computer Vision Toolbox from Add-On Explorer. For more information about installing add-ons, see Get and Manage Add-Ons.

Creation

Syntax

hCaliper = uicaliper(hImage)
hCaliper = uicaliper(hImage,PropertyName=Value)

Description

hCaliper = uicaliper(hImage) configures a caliper tool on the displayed image hImage.

example

hCaliper = uicaliper(hImage,PropertyName=Value) sets writable properties using one or more name-value arguments.

For example, Width=10 specifies the width of the profile scan as 10 pixels.

Input Arguments

expand all

Input image object, specified as an images.ui.graphics.Image object. To create this image object, use the imageshow function.

Properties

expand all

Profile center line position, in pixels, specified as a 2-by-2 numeric matrix of the form [x1 y1; x2 y2], where the [x1 , y1] and [x2 ,y2] are the first and last coordinates defining the line, respectively.

You can specify Position programmatically in the MATLAB Command Window, or interactively by clicking a start point in the specified image hImage and dragging to your desired end point.

Profile scan width, specified as a positive scalar. The width is the area within which the uicaliper object computes profile scan lines measurements. The caliper tool scans in lines orthogonal to the profile centerline and using these measurements, computes a mean 1-D profile for gradient detection.

Edge transition type used in edge detection, specified as one of these options:

  • "rising" — Detect darker-to-brighter edge transitions.

  • "falling" — Detect brighter-to-darker edge transitions.

  • "both" — Detect both brighter-to-darker and darker-to brighter-edge transitions.

Tip

When you set the MeasurementMode property to "edge-pairs", specify the edge transition with respect to the first edge in the profile scan line. For example, to detect edge pairs in which the first edge is rising and the second edge is falling, specify EdgeTransition as "rising".

Gradient threshold for a gradient to be considered an edge, specified as a positive scalar in range [0, 1]. The gradient at each scan point is the normalized average gradient across the profile line width, Width. The uicaliper object function evaluates this value at each point along the scan line. Increase the gradient threshold value to detect fewer false positive edges.

Measurement mode used to compute edge data, specified as "edge-pair" or "single-edge". This argument determines how the measurementData argument outputs distance.

ValueEdge Detection Mode
"edge-pair"

Detect edge pairs of the type specified by the EdgeTransition property. When the profile scan line spans multiple edges, the caliper tool pairs each starting edge with the spatially closest ending edge to form a pair.

"single-edge"Detect single edges of the type specified by the EdgeTransition property.

Standard deviation for Gaussian smoothing of the 1-D profile data, specified as a positive scalar. Increase this value to increase the amount of Gaussian smoothing and reduce measurement noise at the possible expense of lower accuracy in detecting edge positions.

Caliper tool color, specified as an RGB triplet, or a long or short color name.

Option to display 1-D profile scan lines, specified as a numeric or logical 1 (true) or 0 (false).

Option to display the distance measurement value as text overlaid on the image, specified as a numeric or logical 1 (true) or 0 (false).

This property is read-only.

Distance from each detected edge profile scan line origin, represented as a row vector.

This property is read-only.

Distance between the start and end of each edge pair, represented as a row vector.

This property is read-only.

Distance between edge pairs, represented as a row vector. The caliper tool measures this distance from the end of each edge pair to the start of the next edge pair.

This property is read-only.

Gradient value corresponding to each detected edge, represented as a row vector or N-by-2 numeric matrix, depending on the value of the MeasurementMode property.

  • "single-edge" — GradientValue is a row vector containing gradient values associated with each detected edge.

  • "edge-pair" — GradientValue is an N-by-2 numeric matrix, where each row contains the gradient values of the start point and the end point of each pair. N is the number of detected edge pairs.

This property is read-only.

1-D profile data that determines detected edges, stored as an M-element numeric vector. M is the integer length of the profile scan, in pixels, and each element of the vector is the mean gradient value at each scan point.

This profile data determines the gradient values for each edge, stored in the GradientValue property.

Note

Specify the amount of Gaussian smoothing of the profile data using the Sigma property.

Examples

collapse all

This example uses:

Open Live Script

Load an image into the workspace.

I = imread("pears.png");

Display the image using the imageshow function.

hIm = imageshow(I);

To interactively measure distances, configure the caliper tool on the displayed image using the uicaliper object. Click a start point in the image and drag the caliper tool to a desired end point. The measurement is displayed on the image.

hCal = uicaliper(hIm)

This GIF shows how to perform multiple measurements by dragging the end points of the caliper tool to different positions on the image.

GIF_Example.gif

Version History

Introduced in R2025a

See Also

Functions