Skip to content

Circle Measurements Pro vTool#

The Circle Measurements Pro vTool allows you to measure the position and size of a circle in images.

The Circle Measurements Pro vTool accepts an image via the Image input pin and outputs information about the circle found via its output pins.

If you use the Calibration vTool before measuring and connect the Transformation output/input pins of both vTools, the transformation data supplied by the Calibration vTool allows the Circle Measurements Pro vTool to output the results of the measurement in world coordinates in meters (outpin pins with the suffix _m become available).

If you use a Matching vTool and the Image Alignment vTool before measuring, you can measure objects that appear at positions that are different from your reference image. The transformation supplied via the InverseTf input pin allows the vTool to output the measurement results for the original input image.

Circle Measurements Pro vTool

How It Works#

By defining a measurement object and fitting it to the shape you want to measure in your input image, you can gather the following information:

  • Region with a visualization of the shape
  • Measurements of the circle
  • Score of the shape fit

Shape Settings#

The measurement object defines the area in which the vTool detects the edges of the shape to measure. After loading an image, a default measurement object in the shape of a circle with an inner and an outer frame is displayed. The distance between these two frames is the shape tolerance value multiplied by 2.

The outline of the target shape in the input image must lie within these two frames. If you specify a greater tolerance, you can allow for variations in size of the target shape.

You can move, resize, and rotate the measurement object by using the handles of the circle or by entering the desired values manually in the respective input boxes or using the sliders provided. The Shape tolerance value can only be entered manually.

Sample Settings#

Apart from the size and position of the measurement object, you can specify the number and width of the sample segments. Inside these sample segments, the vTool detects possible edge candidates and fits them to the geometric shape. The more segments you use, the more robust your measurement result will be. The downside is that a high number of segments slows down processing.

By default, the segments are distributed evenly with minimum gaps and overlaps and the Number of sample segments and Sample segment width options are linked. If you change one of them, the other is adjusted accordingly. If you disable this link, you can freely adjust number and width. In that case, the only limit is the size of the measurement object.

  • Options linked: Chain Icon
  • Options unlinked: Chain Broken Icon

By specifying an appropriate Sample tolerance value, you can account for waviness or size of potential shape deformations. Sampled edge points must lie within this tolerance to support the shape fit.

With the Minimum score option, you can specify the expected ratio of inliers, i.e., how many of the samples must support the shape fit.

Detection Settings#

An edge is defined as the position of the locally strongest absolute magnitude of the gradient. Commonly, the profile signal is smoothed by a low-pass filter. Use the Smoothing option to set the strength of the filter.

The local extrema of the gradient must be stronger than the Threshold value specified to be accepted as an edge. Try different threshold values to find the optimum setting. The optimum is somewhere between an upper value where all target edges are just detected and a lower value where unwanted edges are not detected anymore.

Edges have a positive or a negative gradient. If the edge gradient is positive, the transition is dark to light. If the edge gradient is negative, the transition is light to dark. If you expect to only find transitions of one type with your application, set the Transition option accordingly. With the Uniform transition option, you can ensure that only edges of identical transitions are selected.

In combination with the transition, the Select option allows you to specify which edges to choose to fit the measurement object to the shape. To make the application more robust, only select the desired type instead of setting the option to All. This can be the first, the last, or the strongest (in terms of gradient magnitude) edge.


The vTool reads the gray value profiles of the sample segments from the inside to the outside of the shape.

Using Calibration#

The resulting positions and distances can also be output in world coordinates in meters. To achieve this, connect the Transformation output pin of the Calibration vTool to the Measurements vTool's Transformation input pin.


The measurement plane is the plane in which the edges to be measured lie in the 3-dimensional world. In every image to process, the edges have different positions within the measurement plane. Register this measurement plane by placing the calibration plate's surface in this measurement plane.

You have to use the same calibration configuration for setting up the Measurements vTool as for the actual processing.

Using Image Alignment#

The Circle Measurements Pro vTool requires that the shape to be measured is always in the same position, i.e., within the shape tolerance defined. Otherwise, detection will fail. To give you more flexibility, you can add a Matching vTool and the Image Alignment vTool to your recipe.

Matching is able to detect the desired shape at different positions in the input image compared to the reference image. It computes and outputs the alignment transformation data that the Image Alignment vTool then uses to provide an aligend input image to the Circle Measurements Pro vTool where the shape is in the same position as in the reference image. Now, the shape can be measured.

The Circle Measurements Pro vTool also receives inverse transformation data with which it can output correct position data for the input image instead of the aligned image.


If the InverseTf input pin is not connected, the parameters of the shape are output relative to the aligned image.
If the InverseTf input pin is connected, the parameters of the shape are output relative to the input image of the Image Alignment vTool.
The applies regardless of whether you're using the Calibration vTool or not.

Configuring the vTool#

To configure the Circle Measurements Pro vTool:

Circle Measurements Pro vTool Settings

  1. In the Recipe Management pane in the vTool Settings area, click Open Settings or double-click the vTool.
    The Circle Measurements Pro dialog opens.
  2. Capture or open an image.
  3. In the Shape Settings area, define the measurement object by entering the values manually.
    Alternatively, you can use the handles of the circle to move, resize, and rotate it so that it fits the target shape you want to measure in the image.
    A horizontal measurement object has an angle of 0.
  4. In the Sample Settings area, specify the number and width of the sample segments as well as the sample tolerance and the desired minimum score.
  5. Click the Show/Hide Details button to display the sample segments and sample points in the image.
  6. In the Detection Settings area, set Smoothing and Threshold to detect the edges in a robust and precise manner.
  7. Set Transition and Select such that only the target edges are selected.

You can view the result of the measurement in a pin data view. Here, you can select which outputs to display.



Accepts images directly from a Camera vTool or from a vTool that outputs images, e.g., the Image Format Converter vTool.

  • Data type: Image
  • Image format: 8-bit to 16-bit mono or color images. Color images are converted internally to mono images.


Accepts the inverse transformation data of the alignment transformation. With this, the vTool can output correct position data for the input image instead of the aligned image.

  • Data type: Transformation Data


Accepts transformation data from the Calibration vTool.

  • Data type: Transformation Data



Returns the region of the shape.

  • Data type: Region


Returns the measurements of the shape in image pixel coordinates (row/column).

  • Data type: Circle


Returns the measurements of the shape in world coordinates in meters (x/y).

  • Data type: Circle


Returns the score of the shape fit.

  • Data type: Float

Typical Predecessors#