FindPatMaxRedLine

Finds objects in an image based on a trained pattern. (A trained (internal) geometric description of an object you wish to find.) FindPatMaxRedLine finds patterns within an image based on a trained pattern from a Patterns structure.

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 Find Region relative to a Fixture input or the output of the image coordinate system of a Vision Tool 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.

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)

Find 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 (default = 320)

The dimension along the X-axis of the region.

Height (default = 440)

The dimension along the Y-axis of the region.

Angle (default = 0)

The orientation, in fixture coordinates.

Curve (default = 0)

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

External Region

This parameter uses Cell References to spreadsheet cell that contains an Annulus, a Circle, a Region, an EditAnnulus, an EditCircle, an EditCompositeRegion, an EditPolygon, or an 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

This argument must reference a spreadsheet cell that contains a valid Patterns data structure returned by the TrainPatMaxRedLine function.

Number to Find

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

Accept Threshold

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 will not be returned (0 to 100; default = 50).

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

Consider edges that match with opposite polarities.

Ignoring Polarity increases the variety of patterns that PatMax finds. Figure below shows some examples of matched and mismatched polarities. If you configure PatMaxRedLine to ignore polarity, it finds all of the patterns shown in the figure. If you configure PatMaxRedLine to consider polarity, it might not find the pattern in the bottom row, or it might find them but assign them lower scores than the patterns in the upper row.

Accuracy Mode

Specifies the tradeoff between accuracy/reliability and execution speed.

0 = Low

Specifies lower accuracy/reliability and faster execution speed.

1 = High (default)

 Specifies higher accuracy/reliability and slower execution speed.

Clutter in Score

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

0 = OFF (default)

Do not include the effect of clutter in score.

1 = ON

Include the effect of clutter in score.

Contrast Threshold

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 is not be considered (0 to 100; default = 0). FindPatMaxRedLine contrast is the "relative" measure of contrast change between features in the trained pattern versus match features in search image, in percentage. Therefore, if feature contrast is similar or high to pattern contrast, reported Contrast is ~100. If feature contrast is lower than pattern contrast, reported Contrast is <100.

Note: Contrast for FindPatMaxRedLine is different than contrast for FindPatMaxPatterns, which is the "absolute" image contrast of the search ROI, in grey scale level.

Find Tolerances

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

Note: The Find Tolerances are hard limits, meaning that any results that are found outside of the specified Find Tolerances are not returned in the spreadsheet.

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

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 = 70).

Note: Increasing this value allows finding multiple overlapping matches of the same pattern.

Advanced Settings

Use Coarse Percentage

Specify whether or not configure the Coarse Accept Percentage value is used during the coarse search phase.

Note: In most cases, this setting does not need to be enabled.

0 = OFF (default)

Only the Accept Threshold value is used during the coarse search phase (the Coarse Accept Percentage value is ignored).

1 = ON

The Coarse Accept Percentage parameter is enabled to specify the deviation from the Accept Threshold value as a percentage, which is used during the coarse search phase.

Coarse Accept Percentage

Specify the deviation from the Accept Threshold value as a percentage, which is used during the coarse search phase (0 to 100; default = 60). This parameter is useful when the Accept Threshold value cannot narrow down instances effectively, and the function returns no match or too many matches.

How Coarse Accept Percentage Works

FindPatMaxRedLine first uses large features to find an approximate pattern match in a run-time image (coarse search phase), and then uses small features to determine the pattern location precisely (fine search phase). During both phases, the Accept Threshold value is used to narrow down found instances.

Normal Flow (Use Coarse Percentage = OFF)

While rare, FindPatMaxRedLine may not return any matches because only low score instances are found during the coarse search phase. If this happens, the Accept Threshold setting can be lowered. However, the lower Accept Threshold value may result in returning too many matches.

Returns No Match or Too Many Matches
(Use Coarse Percentage = OFF)

In such cases, the Coarse Accept Percentage setting allows you to define the acceptance threshold value just for the coarse search phase. By using different acceptance threshold value for each search phase, the expected results can now be returned.

Returning Expected Results (Use Coarse Percentage = ON)

Timeout

Specifies the amount of time, in milliseconds (0 to 30000; default = 5000), that the function will search 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.

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 FindPatMaxRedLine function 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 RedLine match features are displayed at all times.

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.

Note: FindPatMaxRedLine does not #ERR if a trained pattern is not found. In this case, use the Patterns Vision Data Access functionsGetNFound(Patterns) which returns 0 if no matching patterns were found.

Results

When FindPatMaxRedLine is initially inserted into a cell, a result table is created in the spreadsheet using the following Patterns Vision Data Access functions.

Label Function Description

X

GetX(Patterns, Index)

The X coordinate of the pattern position.

Y

GetY(Patterns, Index)

The Y 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.