Skip to content

Geometric Pattern Matching Pro vTool#

The Geometric Pattern Matching Pro vTool allows you to detect objects in images based on their shape using a taught pattern.

The Geometric Pattern Matching Pro vTool accepts an image via the Image input pin and outputs information about the matches found via its output pins.

If you use the Calibration vTool before matching and connect the Transformation output/input pins of both vTools, the transformation data supplied by the Calibration vTool allows the Geometric Pattern Matching vTool to output the positions of the matches in world coordinates in meters (the Positions_m outpin pin becomes available).

Geometric Pattern Matching Pro vTool

How It Works#

By defining a pattern and applying it to your input image, you can gather the following information about the matches:

  • Matching scores
  • Positions
  • Orientations
  • Vertical and horizontal scaling factors
  • Regions with visualizations of the matches

Pattern Definition#

The first step of pattern matching is the teaching of a model based on a representative image of the object to be detected by your application. In this teaching image, mark the desired pattern and teach it. Your application uses this model to detect this pattern in your production environment. Patterns are formed by edges.


Choose a representative image as a template.

Mark the edges of the desired pattern in the template image. Choose edges that are prominent and that are generally present in the search images.

Using The Reference Point#

You can decide to display a reference point in the pattern you've marked. By default, the software determines the center of gravity of your pattern and places the reference point there. For most applications, this works well.

If required, however, you can move the reference point to a different position. An example would be a robotic picking application. In such a scenario, the vision system has to determine the gripping position for the robot taking into account the gripper of the robot and the shape of the objects to pick. Here, you could place the reference point accordingly to accomodate both these aspects.

To display the reference point, you have to mark a pattern in the teaching image first.


The Contrast setting refers to the contrast of the edges of a pattern. On the one hand, set the contrast so low that all relevant model edges are detected. On the other hand, set the contrast high enough to exclude noisy or unwanted edges. In most situations, enabling the Contrast Auto provides good results. In this case, the software determines a suitable contrast.

The contrast is included in the model. If you make changes here, you have to re-teach the model.


Three different scaling options are available: no scaling, isotropic scaling, or anisotropic scaling.

  • No scaling: If the distance between camera to object or the object size itself is constant, choose this option.
  • Isotropic scaling: Isotropic scaling can compensate for changes in the distance between camera and object or a varying object size.
  • Anisotropic scaling: Anisotropic scaling means that scaling takes place in two directions: vertical and horizontal. Therefore, objects may vary to different degrees in length and width. This option is useful, for example, to detect rectangles with different lengths and widths.


Always choose the simplest scaling option to reduce processing time and increase the vTool's robustness. If the scale of an object remains the same in the application, use No scaling. If the object size varies, choose Isotropic scaling. Only in cases of varying shapes, use Anisotropic scaling.

If the application requires scaling, set the scaling range as low as possible. This also reduces processing time and increases the vTool's robustness.

The scaling settings are included in the model. If you make changes here, you have to re-teach the model.

Execution Settings#

  • Matches: If the application is such that only a limited number of objects can occur, you may want to restrict the possible number of matches to exactly this number. This will increase processing speed and robustness.
  • Score: A score value is calculated for every match. This score indicates how closely the actual object in the image resembles the model of the pattern. For example, a score value of 0.9 says that 90 % of all model points could be matched to edges in the search image.
    To find the optimum Score setting, start with a moderate value and run some test images. Observe the output values of the Scores pin. Allow for some tolerance and choose a score value between 50–80 % of the lowest score output values determined on the test image. In case the score is set too low, some unwanted matches may be detected as well. In that case, readjust the score value until only the intended patterns are found in the test images.
  • Timeout: For time-critical applications you can specify a timeout. A timeout helps in cases where the processing time varies or can't be foreseen, for example, if the image doesn't contain the pattern taught. By specifying a timeout, the detection process stops after the specified timeout and moves on to the next image.
    Basler recommends setting the timeout a bit lower than the desired time limit. This is because the vTool doesn't stop the detection process immediately. Therefore, set the timeout to 70–80 % of the desired time limit.

Using Calibration#

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

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


The contours of the objects in the three-dimensional world space producing the two dimensional edges in the image must lie, at least more or less, on the same plane. If this is the case, the effect of perspective distortion due to different positions of the object in the world and the edges in the image is negligible.

For wide-angle lenses, that introduce significant perspective distortion due to the optical setup, the objects of inspection should be low in height relative to the object-to-camera distance. Alternatively, if the object height can't be neglected, choose model edges at the same height level.

Register the plane of object contours by placing the calibration plate's surface in this plane during calibration setup.

Common Use Cases#

  • Counting objects: In this case, only the number of elements at the Scores output pin is relevant.
  • Locating objects in image coordinates: Use the Positions_px and Angles_rad output pins for subsequent processing.
  • Locating objects in world coordinates: Use the Positions_m and Angles_rad output pins to transmit the positions of objects, e.g., to a robot to grasp the objects.
  • Size determination: Use the VScalingFactors and HScalingFactors output pins to measure size or object distance variations.

A typical example of a pattern matching result is shown below:

Geometric Pattern Matching Pro vTool Result

Configuring the vTool#

To configure the Geometric Pattern Matching Pro vTool:

Geometric Pattern Matching Pro vTool Settings

  1. In the Recipe Management pane in the vTool Settings area, click Open Settings or double-click the vTool.
    The Geometric Pattern Matching Pro vTool dialog opens.
  2. Take a teaching image.
    You can either use the Single Shot button to grab a live image or click the Open Image button to open an existing image.
  3. Use the pens to mark the desired pattern in the image. To correct the drawing, you can use the eraser or delete it completely.
  4. In the Model Settings: Contrast area, adjust the Contrast to detect the relevant edges of the model.
    The model edges are visualized in the teaching image with the color selected in Edge visualization.
  5. In the Model Settings: Scaling area, select the desired scaling option and adjust the scaling range according to the application.
  6. Teach the matching model by clicking the Teach button in the toolbar.
  7. If required, display the reference point by clicking Show Reference Point.
    The reference point is displayed at the center of the pattern and the Set Reference Point Manually button becomes available. You can now drag the reference point to the desired position. If you click Set Reference Point Manually again, the reference point snaps back to its default position.
  8. If desired, adjust the Matches setting in the Execution Settings area to limit the number of matches to a maximum.
  9. If necessary, adjust the Score setting so that only the target objects are found.
  10. If you want to specify a timeout, clear the No timeout check box and enter the desired timeout in the input field.

You can view the result of the pattern matching 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 transformation data from the Calibration vTool.

  • Data type: Transformation Data



Returns the scores of the matches.

  • Data type: Float Array


Returns the positions of the matches in image coordinates (row/column).

  • Data type: PointF Array


Returns the positions of the matches in world coordinates in meters (x/y).

  • Data type: PointF Array


Returns the orientations of the matches in radian.

  • Data type: Float Array


Returns the vertical scaling factors of the matches.

  • Data type: Float Array


Returns the horizontal scaling factors of the matches.

  • Data type: Float Array


Returns a region for every match found.

  • Data type: Region Array

Typical Predecessors#