caliper

Measure distance in image data using caliper tool

Since R2025a

collapse all in page

    Syntax

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

    Description

    Add-On Required: This feature requires the Automated Visual Inspection Library for Computer Vision Toolbox add-on.

    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.

    example

    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

    collapse all

    This example uses:

    Open Live Script

    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)

    Figure contains an axes object. The axes object contains an object of type line.

    Input Arguments

    collapse all

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

    Image TypeData Format
    GrayscaleH-by-W numeric matrix
    RGBH-by-W-by-3 numeric array

    Profile 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 coordinates of the start point and end point of the line, respectively.

    Name-Value Arguments

    collapse all

    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.

    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.

    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.

    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.

    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.

    ValueEdge Detection ModemeasurementData 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.

    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.

    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

    collapse all

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

    MeasurementData FieldDescription
    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

    expand all

    Version History

    Introduced in R2025a

    See Also

    | | | | |