TrainPatMaxPattern

Extracts and trains a pattern from an image for use with the FindPatMaxPatterns function.

TrainPatMaxPattern Overview

A PatMax® pattern is a collection of geometric features where each feature is a point on the boundary between two regions of dissimilar pixel values. TrainPatMaxPattern trains a pattern, then FindPatMaxPatterns is used to locate one or more instances of that pattern in an image. PatMax offers three key features that distinguish it from other pattern-location technologies available in machine vision:

  • High-speed location of objects whose appearance is rotated, scaled, and/or stretched
  • Location technology that is based on object shape, not on greyscale values
  • Very high accuracy

PatMax differs from other pattern-location technologies in that it is not based on pixel grid representations that cannot be efficiently and accurately rotated or scaled. Instead, PatMax uses a feature-based representation that can be transformed quickly and accurately for pattern matching.

Note: When a cell containing a trained PatMax pattern is highlighted the pattern's features are displayed. This allows the user to see the pattern that is trained without entering the TrainPatMaxPattern's Property sheet, which would retrain the pattern.

TrainPatMaxPattern Inputs

Parameter Description

Image

This parameter must reference a spreadsheet cell that contains an Image data structure. By default, this parameter references cell A0 , containing the AcquireImage function. This parameter can also reference other Image data structures, such as those returned by the Image Vision Data Access functions or Coordinate Transforms Functions.

Fixture

Defines the Region of Interest (ROI) relative to a Fixture input or the output of the image coordinate system for the Vision Tools function. Setting the ROI relative to a Fixture ensures that if the Fixture is rotated or translated, the ROI is rotated or translated in relation to the Fixture.

Note: 2D projections use real world units but fixturing with 2D tools requires input in pixel values. When using a 2D projection from a 3D point cloud as a Fixture, convert the real world units to pixel values using the TransWorldToPixel function.

The default setting is (0,0,0), the top leftmost corner of the image.

X (default = 0)

The X-offset, in image coordinates.

Y (default = 0)

The Y-offset, in image coordinates.

Theta (default = 0)

The rotation from the image X-axis, in the image coordinate system. (+/-360 degrees clockwise)

Pattern Region

Also known as the Region of Interest (ROI), specifies the region of the image that undergoes analysis. Double-click on the Region parameter to create an Interactive Graphics Mode that you can transform and rotate. Select this parameter and press the Maximize Region button on the Job Edit toolbar of the property sheet to automatically stretch the region to cover the entire image.

X

The X-offset of the origin, in fixture coordinates.

Y

The Y-offset of the origin, in fixture coordinates.

Width

The dimension along the X-axis of the region.

Height

The dimension along the Y-axis of the region.

Angle

The orientation, in fixture coordinates.

Curve

The angular deviation between the x-axis and the opposing boundary line of the region.
Note: The Fixture and Region parameters must be defined within the bounds of the image. Otherwise, the function returns #ERR.

External Region

This parameter uses Cell References to an Annulus, Circle, Region, EditAnnulus, EditCircle, EditCompositeRegion, EditPolygon, and EditRegion. When this parameter is used, the function ignores the Region and Fixture settings and inspects the image area specified by referenced region. If an EditCompositeRegion control is referenced, the inspection area can be a mix of shapes. Each shape in the composite region can be assigned as added to or subtracted from (masking) the inspection area.

Note: If this parameter has been set as a reference to an external region, to use the internal Region of the function, this parameter must be manually set to zero by entering the value 0 in place of the cell reference. Otherwise, the function continues to reference the external region.

Pattern Origin

Specifies the X and Y of the training pattern's origin, as offsets from the center of the training region.

Offset X

Specifies the x-offset from the center of the trained pattern.

Offset Y

Specifies the y-offset from the center of the trained pattern.

Pattern Settings

Specifies the settings for training the pattern.

Algorithm

Specifies which algorithm to use for training the pattern.

0 = PatMax (default)

The PatMax algorithm offers higher accuracy than PatQuick, but requires more time to execute.

1 = PatQuick

The PatQuick algorithm offers lower accuracy than PatMax, but requires less time to execute.

Elasticity

Specifies the amount of perimeter deviation (0 to 10; 0 = default).

0 = No Tolerance

1 or Greater = Flexible Boundary

Ignore Polarity

Specifies whether matches can be found that contain color-inverted match features with respect to the trained pattern.

0 = OFF (default)

Do not match color-inverted features.

1 = ON

Allow color-inverted match features.

Sensitivity

0 = Not Implemented

Coarse Granularity

Specifies the coarse granularity, as a pixel value. Coarse granularity is used to find large features to find an approximate pattern match in a run-time image quickly (0 to 10; 0 = default).

Note: If a value of less than 1.0 is specified, both Coarse Granularity and Fine Granularity parameter values will be calculated automatically.

Fine Granularity

Specifies the fine granularity, as a pixel value. Fine granularity is used to find small features to determine the pattern location precisely (0 to 10; 0 = default).

Note:
  • If a value of less than 1.0 is specified, both Coarse Granularity and Fine Granularity parameter values will be calculated automatically.
  • The value for Fine Granularity cannot be greater than the value for Coarse granularity.
Train Event

Specifies Cell References to a cell containing a model training event trigger.

Note: Training occurs when either the property sheet is open or when an event trigger such as a button or other conditionally enabled cell is non-zero.
Reuse Training Image

Specifies whether or not the image used to train the pattern is saved and used when modifying the Pattern Settings parameters.

0 = OFF (default)

The current image (i.e. the image specified in the Image parameter) will be used to train/re-train the pattern.

1 = ON

The image that was initially used to train the pattern will be used to re-train the pattern in the event that one or more of the Pattern Settings parameters is modified. When first enabled, the image identified by the Image parameter will be used to train the pattern and a copy of the image will be saved in the job. Any subsequent changes made to the Pattern Settings parameters will be made using the stored image.

Note:
  • When this parameter is enabled, if the Fixture input is modified, the Pattern Region (or External Region) is moved or modified, the function will adjust the training region in the input image, save the new image and re-train the pattern.
  • If the Reuse Training Image parameter is turned ON (enabled), but a pattern has not already been trained, the function will return #ERR until the parameter has been turned OFF (disabled) and a new pattern trained.

Timeout

Specifies the amount of time, in milliseconds (0 to 30000), that the function will search for a valid pattern before execution is halted and an #ERR is returned. Setting the value to 0 will disable the setting and a timeout will not be applied.

Show

Specifies the display mode for TrainPatMaxPattern graphics on the image.

0 = hide all

All graphics will be hidden, except when the cell containing the TrainPatMaxPattern function is highlighted in the spreadsheet.

1 = result graphics only

Trained features of the pattern will be displayed at all times.

2 = input and result graphics

The input image region, pattern origin and the trained features will be displayed at all times.

Note: The color of a trained feature (Green, Yellow and Red) represents the quality of the feature candidate for matching. Green represents high quality; red represents low. The Granularity parameters should be adjusted until all trained features are green or choose a better image to train. Distinct features (edges) and good image contrast will yield the best results.
3 = show all: input, result and training image The input image region, pattern origin, the trained features and the training image will be displayed at all times.

TrainPatMaxPattern Outputs

Returns

A Patterns data structure containing a trained pattern, or #ERR if any of the input parameters are invalid.

 

Results

When TrainPatMaxPattern is initially inserted into a cell, the Trained status will automatically appear in the adjacent cell to the right. If a pattern cannot be trained, then #ERR will be inserted.

One Patterns Vision Data Access functions is automatically inserted into the spreadsheet:

Trained

GetTrained(Pattern)

Returns 1 if a pattern has been successfully trained, and 0 if a pattern cannot be trained.
Note: While in the function's property sheet, supplemental information strings are provided as suggestions for better training a pattern. Possible information strings include:
  • Pattern may contain too few match features.
  • Difficult to automatically set feature granularity; manually set Granularity.
  • Pattern may be less accurate than expected because the training image appears blurry.
  • The pattern results may be unstable because the coarse features have the same direction.
  • Execution time may increase because of numerous fine features; manually set Granularity.
  • Pattern may contain insufficient information to measure Angle or Scale reliably.

To insert information strings into the spreadsheet, use the GetInfoString Vision Data Access function.