TrainPatMaxPattern

Extracts and trains a pattern from an image for use with the FindPatMaxPatterns function. For more information, see FindPatMaxPatterns.

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.TrainPatMaxPatterntrains 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

Syntax: TrainPatMaxPattern(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Pattern Region.X,Pattern Region.Y,Pattern Region.High,Pattern Region.Wide,Pattern Region.Angle,Pattern Region.Curve,External Region,Pattern Origin.Offset Row,Pattern Origin.Offset Column,Pattern Settings.Algorithm,Pattern Settings.Elasticity,Pattern Settings.Ignore Polarity,Pattern Settings.Sensitivity,Pattern Settings.Coarse Granularity,Pattern Settings.Fine Granularity,Reuse Training Images,Timeout,Show)

Note: The Fixture and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.
Parameter Description

Image

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

Fixture

Defines the Region of Interest (ROI) relative to a Fixture input or the output of a Vision Tool function's image coordinate system. Setting the ROI relative to a Fixture ensures that if the Fixture is rotated or translated, the ROI will be rotated or translated in relation to the Fixture. For more information, see Fixture and Vision Tools Functions.

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

Row (default = 0)

The row offset, in image coordinates.

Column (default = 0)

The column offset, in image coordinates.

Theta (default = 0)

The angle of orientation, in the image coordinate system.

Pattern Region

The Region of Interest (ROI) specifies the region of the image that undergoes analysis and creates a rectangular image region that can be transformed and rotated. For more information, see Interactive Graphics Mode.

Tip: With this parameter selected, you can press the Maximize Region button on the property sheet's toolbar to maximize the region and cover the entire image.

X

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

Y

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

High

The dimension along the region's x-axis.

Wide

The dimension along the region's y-axis.

Angle

The orientation, in fixture coordinates.

Curve

The angular deviation between the region's x-axis and the opposing boundary line.

External Region

This parameter can reference a spreadsheet cell that contains the following functions:

  • Annulus. For more information, see Annulus.
  • Circle. For more information, see Circle.
  • Region. For more information, see Region.
  • EditAnnulus. For more information, see EditAnnulus.
  • EditCircle. For more information, see EditCircle.
  • EditCompositeRegion. For more information, see EditCompositeRegion.
  • EditPolygon. For more information, see EditPolygon.
  • EditRegion. For more information, see 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 function's internal Region, this parameter must be manually set to zero by entering the value 0 in place of the cell reference. Otherwise, the function will continue to reference the external region.
  • In high-precision applications, differences of less than a pixel may be reported if a FindPatMaxPatterns function is constructed to find the patterns returned by a TrainPatMaxPattern function, and the two functions use different external regions for their search and training, respectively. However, if either of the two functions reference an external region that is angled and/or curved, the pixel differences may be much larger. When constructing the job, ensure that the FindPatMaxPatterns and TrainPatMaxPattern function reference the same external region for both searching and training, or use the internal regions of both functions for the searching and training.

Pattern Origin

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

Offset Row

Specifies the row offset from the center of the trained pattern.

Offset Column

Specifies the column 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 are 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 are calculated automatically.
  • The value for Fine Granularity cannot be greater than the value for Coarse granularity.
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) is used to train/re-train the pattern.

1 = On

The image that was initially used to train the pattern is 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 is used to train the pattern and a copy of the image is saved in the job. Any subsequent changes made to the Pattern Settings parameters are made using the stored image.

Note:
  • When loading jobs that were built with In-Sight Explorer firmware prior to release 4.4.1, the pattern must be retrained with In-Sight Explorer firmware 4.4.1 or later to utilize this feature. The function returns #ERR if this parameter is enabled with a pattern that was trained in an earlier release of In-Sight Explorer; the pattern must be retrained to be used with this parameter.
  • When this parameter is enabled, if the Fixture input is modified, the Pattern Region (or External Region) is moved or modified, the function adjusts the training region in the input image, saves the new image and re-trains the pattern.
  • If the Reuse Training Image parameter is turned On (enabled), but a pattern has not already been trained, the function returns #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 searches for a valid pattern before execution is halted and #ERR is returned. Setting the value to 0 disables the setting and a timeout is not applied.

Show

Specifies the display mode for TrainPatMaxPatterngraphics on the image.

0 = hide all

All graphics are hidden, except when the cell containing the TrainPatMaxPatternfunction is highlighted in the spreadsheet.

1 = result graphics only

Trained features of the pattern are displayed at all times.

2 = input and result graphics

The input image region, pattern origin and the trained features are 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 quality. 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 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 are 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. The function is Disabled by default to avoid accidentally training a new pattern on the next acquisition.

Results

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

Note: While in the function's property sheet, supplemental information strings are provided as suggestions for better training a pattern. For a list of possible information strings, click Closedhere.
  • 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.

TrainPatMaxPattern Vision Data Access Functions

One Vision Data Access function 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.

For more information, see Patterns, Pattern Match, or Property Sheet.