MatchColor

The MatchColor function, referencing a MatchColorLib data structure returned by a TrainMatchColor function, determines which Colors present in the Region of Interest (ROI) match the trained Color(s) in the TrainMatchColor color library. The MatchColor function outputs a Colors data structure, which contains the color distance and match score, in addition to an overall confidence score, for each active Color referenced in the MatchColorLib data structure.

MatchColor Inputs

General Tab

MatchColor(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Region.X,Region.Y,Region.High,Region.Wide,Region.Angle,Region.Curve,External Region,Match Color Library,Color Space,Show)

Note:

In order for a pixel to be counted, it must be completely enclosed within the image region; partially enclosed pixels are not included.
The Fixture and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.

Parameter

Description

Image

Specifies the color image reference. This argument must reference either the valid color Image data structure output by the AcquireImage function, or a Colors data structure output by another MatchColor function. By default, the cell referenced is A0, the cell containing the Image data structure returned by AcquireImage.

Note: This parameter must reference a color image.

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.

Note: 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.

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

Match Color Library

Specifies a reference to a TrainMatchColor function that contains the required Colors. For more information, see TrainMatchColor.

Note: This must be a reference to a TrainMatchColor MatchColorLib data structure. This function cannot reference an ExtractColorLib data structure output by a TrainExtractColor function. The MatchColor function will return #ERR in this condition.

Color Space

Specifies the color space that the function will use to measure color distance.

0 = RGB (default)

The function will operate in RGB color space.

1 = HSI

The function will operate in HSI color space.

Note: The HSI values returned by the ExtractColorHistogram function may differ from the HSI values returned by the MatchColor and TrainMatchColor functions. The MatchColor and TrainMatchColor functions average the pixels before HSI processing while the ExtractColorHistogram function averages the pixels after HSI processing; the divergence will increase with the color randomness found in the image.

Show

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

0 = hide all (default)	All graphics will be hidden, except when the cell containing the MatchColor function is the active cell in the spreadsheet.
2 = input graphics only	The input image region will be displayed at all times.

Colors Tab

Specifies the Colors to be extracted from the referenced TrainMatchColor MatchColorLib data structure; by default, all of the trained Colors in the referenced Library are automatically enabled.

Note: The Colors can also be enabled from the spreadsheet, using the SetMatchClrColorState function. For more information, see Color.

MatchColor Outputs

Returns	A Colors data structure containing the RGB and HSI color distances of the active Colors to the average color in the ROI, or #ERR if any of the input parameters are invalid.
Results	When MatchColor is initially inserted into a cell, a result table is created in the spreadsheet.

MatchColor 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 Color.

Index	GetMatchClrColorByRank(Colors, Rank)	The color index by rank.
MatchColor Color	GetActiveMatchClrColorName(Colors, Index)	The name by index.
Score	GetMatchClrScoreByIndex(Colors, Index)	The color score by index.
Color Distance	GetMatchClrDistByIndex(Colors, Index)	The color distance by index.
Confidence Score	GetConfidenceScore(Colors)	The confidence score for the inspection.