# 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 data structure.

## MatchColor Inputs

The MatchColor dialog consists of two main parts: the General tab and the Colors tab.

### General Tab

Parameter | Description
--- | ---
Image | Specifies the color image reference. This argument must reference either the valid Image data structure output of the function, or a data structure output by another MatchColor function. By default, the cell referenced is A0, the cell containing the Image data structure returned by . Note: This parameter must reference a color image.
Fixture | Defines the Region of Interest (ROI) relative to a Fixture input or the output of the image coordinate system for the Vision Tools 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. Note: 2D projections use real world units but fixturing with 2D tools requires input in pixel values. When using a 2D projection from a 3D point cloud as a Fixture, convert the real world units to pixel values using the TransWorldToPixel function. The default setting is (0,0,0), the top leftmost corner of the image.
X | The row offset, in image coordinates.
Y | 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), the Region specifies the region of the image that undergoes analysis; it creates a rectangular image region that can be transformed and rotated. With this parameter selected, by pressing the Maximize Region button on the property sheet's toolbar, the region will automatically be stretched 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 | The dimension along the region's X-axis.
Height | 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.
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.
External Region | This parameter can reference a spreadsheet cell that contains an Annulus, a Circle, a Region, an EditAnnulus, an EditCircle, an EditCompositeRegion, an EditPolygon, or an EditRegion control function. When this parameter is used, the function ignores the Region and Fixture settings and inspects the image area specified by the 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. Note: This must be a reference to a MatchColorLib data structure, outputted by a TrainMatchColor function.
Color Space | Specifies the color space that the function will use to measure color distance.
RGB = 0 (default) | The function will operate in RGB color space.
HSI = 1 | 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.
Hide all = 0 (default) | All graphics will be hidden, except when the cell containing the MatchColor function is the active cell in the spreadsheet.
Input graphics only = 2 | The input image region will be displayed at all times.

### Colors Tab

Specifies the Colors to be extracted from the referenced TrainMatchColor 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. See Color Vision Data Access functions for more information on this function.

## Match Color Outputs

Returns | Results
--- | ---
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. | When MatchColor is initially inserted into a cell, the following result table is created in the spreadsheet.
| Rank | Index | Color Name | Score | Color Distance | Confidence Score
❒Colors | 0 | GetMatchClrColorByRank(Colors, Rank) | GetActiveMatchClrColorName(Colors, Index) | GetMatchClrScoreByIndex(Colors, Index) | GetMatchClrDistByIndex(Colors, Index) | GetConfidenceScore(Colors)
| 1 | GetMatchClrColorByRank(Colors, Rank) | GetActiveMatchClrColorName(Colors, Index) | GetMatchClrScoreByIndex(Colors, Index) | GetMatchClrDistByIndex(Colors, Index) | GetConfidenceScore(Colors)
| ... | ... | ... | ... | ... | ...
| N-1 | GetMatchClrColorByRank(Colors, N-1) | GetActiveMatchClrColorName(Colors, Index) | GetMatchClrScoreByIndex(Colors, Index) | GetMatchClrDistByIndex(Colors, Index) | GetConfidenceScore(Colors)

## Match Color Vision Data Access functions

The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table:

Label | Function | Description
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.