caliper

Measure distance in image data using caliper tool

Since R2025a

Syntax

measurementData = caliper(I,linePosition)

measurementData = caliper(I,linePosition,Name=Value)

Description

measurementData = caliper(I,linePosition) measures distance in a grayscale or RGB input image, I, using a caliper tool by positioning a profile scan line at the position linePosition.

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.

measurementData = caliper(I,linePosition,Name=Value) specifies options using one or more name-value arguments. For example, Width=10 specifies the width of the profile scan as 10 pixels.

Examples

Measure Distance Between Object Edges Using Caliper

Load an image into the workspace.

I = imread("coins.png");

Display the image using the imageshow function.

imageshow(I)

Measure the distance between the edges of the darkest nickel coin using the caliper function. Specify the start and end point of the profile scan line as [171 89; 218 131]. To detect the coin edges, specify a gradient threshold lower than the maximum intensity gradient across the scan length using the GradientThreshold name-value argument. Since the coin contains two edge pairs, the function returns the distance between them, or the coin width, as IntraEdgeDistance value.

measureOut = caliper(I,[158 89; 218 131],GradientThreshold=0.04)

measureOut = struct with fields:
    InterEdgeDistance: [1×0 double]
    IntraEdgeDistance: 56.4544
        GradientValue: [0.0520 -0.0579]
             Distance: [3.4186 59.8729]
          ProfileData: [146×1 double]

Display the intensity gradient value along the profile scan line.

figure
plot(measureOut.ProfileData)

Input Arguments

I — Input image

H-by-W numeric matrix | H-by-W-by-3 numeric array

Input image for which to perform caliper measurement, specified as one of these values:

Image Type	Data Format
Grayscale	H-by-W numeric matrix
RGB	H-by-W-by-3 numeric array

linePosition — Profile line position

2-by-2 numeric matrix

Profile line position, in pixels, specified as a 2-by-2 numeric matrix of the form [x₁ y₁; x₂ y₂], where the [x₁ , y₁] and [x₂ ,y₂] are coordinates of the start point and end point of the line, respectively.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: caliper(I,linePosition,Width=10) specifies the width of the profile scan as 10 pixels.

Width — Profile scan width

50 (default) | positive scalar

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

EdgeTransition — Edge transition type

"both" (default) | "rising" | "falling"

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.

The edge transition is relative to the direction of the scan line, from start point to end point.

GradientThreshold — Gradient threshold selection

0.1 (default) | positive scalar in range [0, 1]

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 caliper function evaluates this value at each point along the scan line. Increase the gradient threshold value to detect fewer false positive edges.

MeasurementMode — Measurement mode

"edge-pair" (default) | "single-edge"

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

Value	Edge Detection Mode	measurementData Distance Output
"edge-pair"	Detect edge pairs of the type specified by the EdgeTransition name-value argument. 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.	measurementData populates the InterEdgeDistance and IntraEdgeDistance fields with distance information. InterEdgeDistance is the distance between the end of an edge pair and the start of the next edge pair. IntraEdgeDistance is the distance between the start and end of each edge pair.
"single-edge"	Detect single edges of the type specified by the EdgeTransition name-value argument.	measurementData populates the Distance field with distance information. Distance is the distance from the start point of the profile line to the position where the function detects the gradients.

Sigma — Standard deviation for Gaussian smoothing of 1-D profile data

1.0 (default) | positive scalar

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.

Transformation — Geometric transformation for input image data

affinetform2d object (default) | imref2d object | rigidtform2d object | simtform2d object | transltform2d object

Geometric transformation for the input image data that defines a 2-D world coordinate system, specified as an affinetform2d object, an imref2d object, a rigidtform2d object, a simtform2d object, or a transltform2d object.

Output Arguments

measurementData — Caliper measurement data

structure

Caliper measurement data, returned as a structure with these fields:

MeasurementData Field	Description
Distance	Distance between the first point of the profile line to the position of each detected edge, stored as a numeric array.
IntraEdgeDistance	Distance between the start and end of each edge pair, stored as a numeric array.
InterEdgeDistance	Distance between the end of an edge pair and the start of the next edge pair, stored as a numeric array.
ProfileData	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.
GradientValue	Gradient values corresponding to each edge detection, stored as a row vector or N-by-2 numeric matrix, depending on the value of the measurementMode name-value argument. "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 the corresponding edge pair. N is the number of detected edge pairs.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The EdgeTransition and MeasurementMode name-value arguments must be compile-time constants. Code generation does not support cell arrays for these name-value arguments.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• The EdgeTransition and MeasurementMode name-value arguments must be compile-time constants. Code generation does not support cell arrays for these name-value arguments.

Version History

Introduced in R2025a