FindPatterns

FindPatterns consists of two functions: one function extracts area or edge-based patterns or models, while the second function searches an image for a previously trained model.

Whether the function is training or finding, its execution depends on which of the parameters are forcing the update. Updating any of the model parameters causes the model to be returned. Updating the Image, the Fixture, the Find Region, or any of the search parameters causes the f unction to execute a search.

Tip: To avoid accidentally training new models, insert two separate FindPatterns functions. One function is used to train a model and becomes Disabled, while the second function searches by referencing the first function in the Patterns parameter.

FindPatterns Inputs

Syntax: FindPatterns(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Model Region.X,Model Region.Y,Model Region.High,Model Region.Wide,Model Region.Angle,Model Settings.Model Type,Model Settings.Coarseness,Model Settings.Accuracy,Model Settings.Offset Row,Model Settings.Offset Column,Model Settings.ForceTrain,Model Settings.Patterns,Find Region.X,Find Region.Y,Find Region.High,Find Region.Wide,Find Region.Angle,Number to Find,Angle Range,Scale Tolerance,Thresh: Accept,Thresh: Confuse,Timeout,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 Model and Find Regions 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 are rotated or translated in relation to the Fixture. For more information, see ROI, 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.

Model Region

Specifies the rectangular image region that are used to extract the model pattern. For more information, see Interactive Graphics Mode.

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.

Model Settings

Specifies model training parameters.

Model Type

Specifies area model or edge model training.

0 = Area model	Area model training creates patterns based on a uniform sampling of greyscale pixel values from the Model Region. The area model similarity metric is based on the normalized greyscale correlation coefficient.
1 = Edge model (default)	Edge model training creates patterns based on a sampling of points biased to the immediate vicinity of the greyscale discontinuities typically found on objects' boundaries. The edge model similarity metric is based on the normalized comparison of greyscale derivatives. Note: The maximum number of points that may be used to define a model is 4096.

Coarseness

Specifies the size of the smallest features in the trained model.

0 = Fine	Smallest features approximately 4 pixels in size.
1 = Medium (default)	Smallest features approximately 4 to 8 pixels in size.
2 = Coarse	Smallest features larger than 8 pixels in size.

Accuracy

Specifies the tradeoff between accuracy/reliability and execution speed.

0 = Accurate	Specifies higher accuracy/reliability and slower execution speed.
1 = Medium (default)
2 = Fast	Specifies lower accuracy/reliability and faster execution speed.

Offset Row

Specifies the row offset (-479 to 479; default = 0) from the model's center to the response point, as measured in the model's local coordinate system.

Offset Column

Specifies the column offset (-639 to 639; default = 0) from the model's center to the response point, as measured in the model's local coordinate system.

Force Train

Enables/disables automatic model training on spreadsheet updates. When Force Train is OFF, the model is trained only when the Model Region or Model Settings are changed. When ON, the model are re-trained every time the spreadsheet executes.

0 = OFF (default)
1 = ON

Patterns

Specifies whether the FindPatterns function searches using its own model, or a model contained in another FindPatterns function. The default value is 0, which means the current FindPatterns function uses its own model. Patterns can also be referenced to a Patterns data structure, which specifies that searching uses the local model trained by another FindPatterns function. This alternative behavior allows a single model to be shared by multiple instances of PatFind searches in the spreadsheet.

Note: This behavior does not chain. It is invalid to reference a PatFind model that, in turn, references another PatFind model.

Find Region

Specifies the region of the image that is used to define where the search for the pattern is performed. A rectangular image region is created, that can be transformed and rotated. With this parameter selected, optionally press the Maximize Region button on the property sheet's toolbar 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.
High	The dimension along the region's x-axis.
Wide	The dimension along the region's y-axis.
Angle	The orientation, in fixture coordinates.

Number to Find

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

Note: Although the maximum number of patterns that can be returned is 255, when the Model Settings parameter is set to Edge model, other settings, especially Coarseness, Accuracy and Scale Tolerance, can drastically reduce the number of patterns returned. If more patterns need to be found, it is recommended to use the FindPatMaxPatterns function. For more information, see FindPatMaxPatterns.

Angle Range

Specifies the function's +/- tolerance to pattern rotation (0 to 180; default =15). The function still finds patterns that are outside of the specified range, but the accuracy may be somewhat compromised. An Angle Range setting greater than 0 reduces the speed at which patterns are located.

Scale Tolerance

Specifies the function's tolerance to changes in pattern scale.

0 = OFF (default)	Disables scale searching. When scale searching is disabled, the function still find patterns that are within about 10% of the original model size, but the response is degraded as the discrepancy increases.
1 = ON	Enables scale searching. When scale searching is enabled, the function performs limited scale adjustments in the range of plus and minus 10% of the original model size.

Thresh: Accept

Specifies the minimum acceptable pattern response score (0 to 100; default = 50). The function returns the Number to Find pattern responses that exceed the Thresh: Accept limit.

Thresh: Confuse

Specifies the maximum expected pattern response score (0 to 100; default = 70)for a pattern in the image that is not a true instance of the model. Setting this search parameter helps the function know which pattern responses to investigate and which can be safely ignored. This parameter is also known as a confusion threshold.

Timeout

Specifies the amount of time, in milliseconds (0 to 30000; default = 5000), that the function searches for patterns 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 FindPatterns graphics on the image.

0 = hide all	All graphics are hidden, except when the cell containing the FindPatterns function is highlighted in the spreadsheet.
1 = result graphics only	A cross is displayed at the offset coordinate of the found model at all times.
2 = input and result graphics	Both the input image region and the cross are displayed at all times.

FindPatterns Outputs

Returns	A Patterns data structure containing a model and a list of pattern responses sorted by score, or #ERR if any of the input parameters are invalid.
Results	When FindPatterns is initially inserted into a cell, a result table is created in the spreadsheet.

FindPatterns 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 to the trained model, as a percentage of the model size.
Score	GetScore(Patterns, Index)	The pattern response score.