FindPatMaxPatterns

Finds objects in an image based on a trained pattern. FindPatMaxPatterns finds patterns within an image based on a trained pattern from a Patterns structure.

FindPatMaxPatterns Inputs

Syntax: FindPatMaxPatterns(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Find Region.X,Find Region.Y,Find Region.High,Find Region.Wide,Find Region.Angle,Find Region.Curve,External Region,Pattern,Number to Find,Accept,Contrast,Clutter in Score,Outside Region,Find Tolerances.Angle Start,Find Tolerances.Angle End,Find Tolerances.Scale Start,Find Tolerances.Scale End,Find Tolerances.Aspect Ratio,Find Tolerances.Aspect Start,Find Tolerances.Aspect End,Find Overlapping.XY Overlap,Find Overlapping.Angle Overlap,Find Overlapping.Scale Overlap,Find Overlapping.Aspect Overlap,Timeout,Algorithm,Show)

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 Find Region 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 is rotated or translated in relation to the Fixture. For more information, see Fixture or Vision Tools Functions.

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

Row	The row offset, in image coordinates.
Column	The column offset, in image coordinates.
Theta	The angle of orientation, in the image coordinate system.

Find 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

This argument must reference a spreadsheet cell that contains a valid Patterns data structure returned by the TrainPatMaxPattern function. For more information, see TrainPatMaxPattern.

Number to Find

Specifies the maximum number of pattern matches to return (1 to 1024; default = 1).

Specifies the acceptance threshold, which is the lowest score of a valid instance. The score for a potential match must be greater than the value of the acceptance threshold or that match are not returned (0 to 100; default= 50).

Contrast

Specifies the lowest contrast of a valid instance. The contrast for a potential match must be greater than the value of the Contrast Threshold or that instance are not considered (0 to 255; default = 10). A low contrast threshold is used for low-contrast images; a high contrast threshold is used for high-contrast images.

Clutter in Score

Specifies whether missing or occluded pattern features reduce the response score(s).

0 = OFF	Do not include the effect of clutter in score.
1 = ON (default)	Include the effect of clutter in score.

Outside Region

Specifies the percentage of pattern features that may be found outside the Find Region without degrading the pattern response score (0 to 100; default = 0).

Find Tolerances

Specifies the settings for finding patterns that are rotated or scaled with respect to the trained pattern.

Angle Start

Specifies the angle at which to begin searching for matches, in degrees counter-clockwise (-180 to 180; default = -15).

Angle End

Specifies the angle at which to stop searching for matches, in degrees counter-clockwise (-180 to 180; default = 15).

Scale Start

Specifies the scale at which to begin searching for matches (1 to 10000; default= 100).

Scale End

Specifies the scale at which to stop searching for matches (1 to 10000; default= 100).

Aspect Ratio

Limits match-finding to uniform-scale only or allows aspect ratio change in X or Y, in addition to a uniform scale.

Note: The Aspect Start and Aspect End parameters are disabled if Uniform Scale Change is selected.

0 = Uniform Scale Change

1 = Uniform and X Scale Change

2 = Uniform and Y Scale Change

Aspect Start

Specifies the minimum scale change, at which to begin searching for matches, as a percentage of the trained pattern (1 to 10000; default = 100).

Aspect End

Specifies the maximum scale change, at which to stop searching for matches, as a percentage of the trained pattern (1 to 10000; default = 100).

Find Overlapping

Specifies the settings for finding patterns that overlap each other with respect to position, rotation and scale.

XY Overlap	Specifies the expected position difference between multiple overlapping patterns in roughly the same X, Y location, as a percentage of the trained pattern size (0 to 100; default = 80). Note: Increasing this value allows finding multiple overlapping matches of the same pattern.
Angle Overlap	Specifies the expected angle between multiple rotated overlapping patterns in roughly the same X, Y location. A (0 to 360; default = 360). Note: The Angle Overlap parameter is disabled if the values for the Angle Start and Angle End parameters are equal to each other. Increasing this value allows finding multiple overlapping matches of the same pattern.
Scale Overlap	Specifies the expected uniform scale difference between multiple overlapping patterns in roughly the same X, Y location, as a percentage of the trained pattern size (1to 10000; default = 140). Note: The Scale Overlap parameter is disabled if the values for the Scale Start and Scale End parameters are equal to each other. Increasing this value allows finding multiple overlapping matches of the same pattern.
Aspect Overlap	Specifies the expected aspect scale difference between multiple overlapping patterns in roughly the same X, Y location, as a percentage of the trained pattern size (1to 10000; default = 140). Note: The Aspect Overlap parameter is disabled if Uniform Scale Change is selected for the Aspect Ratio parameter or if the if the values for the AspectStart and Aspect End parameters are equal to each other. Increasing this value allows finding multiple overlapping matches of the same pattern.

Timeout

Specifies the amount of time, in milliseconds (0 to 30000), that the function searches for patterns before execution is halted and an #ERR is returned. Setting the value to 0 disables the setting and a timeout is not applied.

Algorithm

Specifies the algorithm to use to process the image for the trained pattern.

0 = PatMax	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.
2 = Trained Pattern (default)	The FindPatMaxPatterns function uses the algorithm (PatMax or PatQuick) specified in the Algorithm parameter of the TrainPatMaxPattern function referenced in the Pattern parameter.

Show

Specifies the display mode for graphical overlays on top of the image.

0 = hide all (default)	All graphics are hidden, except when the cell containing the FindPatMaxPatternsfunction is the active cell in the spreadsheet.
1 = result graphics only	A cross is displayed for each found pattern at all times.
2 = input and result graphics	Both the input image region and a cross for each found pattern are displayed at all times.
3 = show all: input, result, and match features	The input image region, a cross for each found pattern, and the PatMax^® match features are displayed at all times. Note: Match features are not shown when PatQuick is selected for the TrainPatMaxPattern's Algorithm parameter. Green match features = 67 to 100 percent match. Yellow match features = 20 to 66 percent match. Red match features = less than 20 percent match.

FindPatMaxPatterns Outputs

Returns

A Patterns data structure containing a model and a list of pattern responses sorted by score, or #ERR if anyof the input parameters are invalid or no matching patterns could be found.

Results

When FindPatMaxPatternsis initially inserted into a cell, a result table is created in the spreadsheet.

Note: While in the function's property sheet, supplemental information strings are provided as suggestions for better finding patterns. For a list of possible information strings, click

here.

FindPatMaxPatterns Vision Data Access Functions

The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table. For more information, see Patterns.

Row	GetRow(Patterns, Index)	The row coordinate of the pattern position.
Col	GetCol(Patterns, Index)	The column coordinate of the pattern position.
Angle	GetAngle(Patterns, Index)	The orientation of the pattern position.
Scale	GetScale(Patterns, Index)	The size of the pattern found compared tothe trained model, as a percentage of the model size.
Score	GetScore(Patterns, Index)	The pattern response score.