FindPatMaxRedLineColor

Finds objects in a color image based on a trained pattern. FindPatMaxRedLineColor finds patterns within a color image based on a trained pattern from TrainPatMaxRedLineColor's Patterns structure. For more information, see TrainPatMaxRedLineColor.

Note:
  • The TrainPatMaxRedLineColor and FindPatMaxRedLineColor functions are only available on In-Sight 7000 Gen2 series color vision systems and In-Sight 8000 series color vision systems running In-Sight firmware 5.6.0 and later. For a complete list of models and supported firmware versions, see Firmware Versions.
  • When using a greyscale image, the TrainPatMaxRedLine and FindPatMaxRedLine function must be used. When attempting to use the TrainPatMaxRedLineColor and FindPatMaxRedLineColor functions on a greyscale image (for example, ColorToGreyscaleFilter's output), #ERR is returned.
  • The FindPatMaxRedLineColor function must reference the TrainPatMaxRedLineColor function. When referenced a different function (for example, a TrainPatMaxRedLine function), #ERR is returned.

FindPatMaxRedLineColor Inputs

Syntax: FindPatMaxRedLineColor (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 Threshold, Pattern,Accept Threshold, Color,Accuracy Mode,Clutter in Score,Contrast Threshold,Find Tolerances.Angle Start,Find Tolerances.Angle End,Find Tolerances.Scale Start,Find Tolerances.Scale End,XY Overlap,Advanced Settings.Use Coarse Percentage,Advanced Settings.Coarse Accept Percentage,Timeout,Show Graphics)

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.

Note: This parameter must reference a color image.

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.

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.

Find Region

Also known as 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 (default = 320)

The dimension along the region's x-axis.

Wide (default = 440)

The dimension along the region's y-axis.

Angle (default = 0)

The orientation, in fixture coordinates.

Curve (default = 0)

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.
  • Mask: For more information, see Mask

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. For more information, see Cell References - Relative/Absolute.

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.

Pattern

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

Number to Find

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

Accept Threshold, Pattern

Specifies the pattern 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 is not returned (0 to 100; default = 50).

Accept Threshold, Color

Specifies the color 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 is not returned (0 to 100; default = 85).

Increased Lighting Tolerance

When enabled, variations in color caused by differences in lighting are more tolerated.

Note: This parameter is disabled when the TrainPatMaxRedLineColor function's Match Colors parameter is set to No Matching.

0 = Off (default)

1 = On

Color matching is sensitive to non-uniform lighting and uncontrollable lighting changes. When the Increased Lighting Tolerance parameter is enabled, scores colors higher if they differ from the trained color because of lighting. i.e.: the same color, just darker or lighter.

For example, in the package of pills, the lighting is not uniform. The pill in the top left corner is darker than the pills in the center.

When the pill in the upper left is trained, the pills near the center score low without the "Increased lighting tolerance" option enabled. Once the parameter is enabled, the scores improve and finds more matches.

Increased Lighting Tolerance = Off Increased Lighting Tolerance = On

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 will reduce 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 will not be considered (0 to 100; default = 0). The contrast value for FindPatMaxRedLineColor and FindPatMaxRedLine are 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 will be ~100. If the pattern contrast exceeds the feature contrast, the reported Contrast will be <100.

Note: The Contrast for FindPatMaxRedLineColor and FindPatMaxRedLine are different from the 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, i.e. any results that are found outside of the specified Find Tolerances will not be 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

This parameter controls the ability of the tool to find pattern candidates that overlap each other. 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, Pattern 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, Pattern value as a percentage, which is used during the coarse search phase.

Coarse Accept Percentage

Specify the deviation from the Accept Threshold, Pattern 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.

FindPatMaxRedLineColor 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, Pattern value is used to narrow down found instances.

Normal Flow (Use Coarse Percentage = OFF)

While rare, FindPatMaxRedLineColor may not return any matches because only low score instances are found during the coarse search phase. If this happens, the Accept Threshold, Pattern setting can be lowered; however, the lower Accept Threshold, Pattern 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 pattern 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, disabling the timeout), that the function will search for patterns before execution is halted and an #ERR is returned.

Show Graphics

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

Find Region

The Find Region displays at all times.

0 = Off (default)

1 = On

Location

The cross-hair graphic displays indicating where the pattern was found at all times.

0 = Off (default)

1 = On

Trained Pattern

Graphic Overlays

Match Features

Trained edge features display with green lines at all times.

0 = Off (default)

1 = On

Trained Pattern

Graphic Overlays

Match Colors

Display the trained match colors at sampled locations. Samples are displayed as circles where the color and location of the circle indicates the trained color.

Note: This parameter is disabled when the TrainPatMaxRedLineColor function's Match Colors parameter is set to No Matching.

0 = Off (default)

1 = On

Trained Pattern

Graphic Overlays
   

FindPatMaxRedLineColor Output

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 or no matching patterns could be found.

Results

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

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

Name VDA Function Description

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 overall score (0 - 100).
Color Score GetColorScore(Patterns, Index)

The color score value (0 - 100).

Note:

When the referenced TrainPatMaxRedLineColor's Match Colors parameter is set to No Matching, the GetColorScore function returns 100.000.

Match Colors Parameter Selection Behavior
0 = All Colors (default) Returns the computed score, assuming that the tool found a feature match.
1 = Selected Colors
2 = No Matching Returns 100.000 (the tool does not compute the color match score).

Pattern Score and Color Score

The FindPatMaxRedLineColor function automatically inserts two Score values in the spreadsheet: Score and Color Score. The Score returns the "pattern" score, showing how similar the found pattern is to a trained pattern, and it is independent of color. The Color Score shows how similar the found pattern's color is to the trained color.

A poor Color Score value does not impact the Score value. In the following example, the Index 2 pattern shows a low Color Score value, however the Score value is still very high. When either the Score or the Color score falls under its Accept Threshold value (Accept Threshold, Pattern or Accept Threshold, Color), the pattern is not considered as a match, and not returned.

Trained Pattern

Search Result