# TrainMatchColor

The TrainMatchColor function extracts and trains Colors from a selected image region for use with the MatchColor function. TrainMatchColor trains Colors within the Library, and then the MatchColor function is used to identify the Color present in the image based on the color distance between the current image and the trained Color(s).

## TrainMatchColor Overview

The TrainMatchColor function is used to build a Color Library (configured with the Train Color button of the TrainMatchColor dialog). The Library may contain up to 100 distinct Colors, which are composed of RGB/HSI values of the object being examined.

Colors are defined by a region of interest (ROI), and they store the average RGB and HSI values contained within the ROI at the time of training. Each individual Color defines a single color in the color space. By adjusting the Color Tolerance controls, a Color may be configured to consider lighter or darker shades of the Color as a match, both in the RGB and HSI color spaces.

- In the RGB color space, the Darker and Lighter limits are based on the color magnitude of the trained Color. The color magnitude can be expressed as the length of a vector starting at the origin and ending at the trained Color. A value of 1 corresponds to the trained Color, while a value of 0.5 corresponds to half of the trained Color.
- In the HSI color space, the Darker and Lighter limits are based solely on the Intensity plane. If the Intensity component of the object being currently examined falls within the Darker and Lighter limits of the trained Color, then the color distance for the object is determined based solely on Hue and Saturation. If the Intensity component falls outside of the Darker and Lighter limits, then the color distance is based on Hue, Saturation and the difference between the current Intensity value and the closest Darker or Lighter limit.

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.

The TrainMatchColor dialog consists of two main parts: the Training tab and the External Training tab.

## TrainMatchColor Training Tab

Note: The parameters in this section are used to configure the training of Colors while the In-Sight color vision system is Online.

The Training tab controls are used to manually train Colors for the Library.

Image | Description
| Library Name: Specifies the name of the Library (the default name is Library).
| Trained Colors: Contains the Colors Table (1) and the Train Controls (2). The Colors Table displays the Color's Name, and its RGB/HSI values. The name of the first trained color is Model_1 by default. The Train Controls contain the following options: Train Color: Specifies the Region of Interest (ROI) used to define a Color in the image. The available ROI types are as follows: Train via Region: Specifies that a rectangular ROI will be used to define the Color. Train via Circle: Specifies that a circular ROI will be used to define the Color. Train via Annulus: Specifies than an annulus ROI will be used to define the Color. Train via Point: Specifies a point in the image that will be used to define the Color. Train via Polygon: Specifies that a polygon ROI will be used to define the Color. Retrain Color: Specifies the ROI used to retrain the color selected in the Colors Table. The available ROIs are the same as in the Train Color option. Remove Color: Removes the Color selected in the Colors Table. Rename Color: Renames the Color selected in the Colors Table.
| Selected Color Tolerance: Specifies the tolerances for the selected Color, adjusting toward either a Darker or Lighter tolerance. Darker: Specifies the Darker Limit (0.0 to 1.0; default = 1.0). When the Color Space is set to RGB, the Darker limit expands the trained Color proportionally lower along a line from (0,0,0) to the trained color's RGB value. When the Color Space is set to HSI, the Darker limit expands the Intensity value of the trained Color lower. Lighter: Specifies the Lighter Limit (1.0 to 10.0; default = 1.0). When the Color Space is set to RGB, the Lighter limit expands the trained Color proportionally higher along a line from (0,0,0) to the trained color's RGB value. When the Color Space is set to HSI, the Lighter limit expands the Intensity value of the trained Color higher. Tip: When configuring the Tolerance controls, position the TrainMatchColor property sheet so that you can easily view the image. As you adjust the controls, the image will update to reflect the changes.

## TrainMatchColor External Training Tab

The External Training tab is used to configure re-training parameters for external training.

Note: The parameters in this section are used to configure the re-training of Colors while the In-Sight color vision system is Online.

Parameter | Description
--- | ---
Image | Specifies the color image reference. This argument must reference either the valid color data structure output by the function, or a data structure output by a MatchColor function. By default, the cell referenced is A0, the cell containing the acquired image. Note: This parameter must reference a color image.
Train Event | Specifies Cell References to a cell containing a color model training event trigger, or a Boolean value. Note: Training occurs when an event trigger, such as a button or other conditionally-enabled cell is non-zero.
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.
Color Name | Specifies the name of the Color, set in the Training tab, to re-train for Online re-training. If the specified Color does not exist, a new Color is created.
Darker Limit | Specifies the Darker Limit for Online training. When the Color Space is set to RGB, the Darker limit expands the trained Color proportionally lower along a line from (0,0,0) to the trained color's RGB value. When the Color Space is set to HSI, the Darker limit expands the Intensity value of the trained Color lower.
Lighter Limit | Specifies the Lighter Limit for Online training. When the Color Space is set to RGB, the Lighter limit expands the trained Color proportionally higher along a line from (0,0,0) to the trained color's RGB value. When the Color Space is set to HSI, the Lighter limit expands the Intensity value of the trained Color higher.

### TrainMatchColor Outputs

Parameter | Description
--- | ---
Returns | A MatchColorLib data structure containing the Colors trained for the MatchColor tool, or #ERR if any of the input parameters are invalid.

### TrainMatchColor Vision Data Access functions

The following data elements can be accessed using Vision Data Access functions:

Parameter | Description
--- | ---
GetNTrainMatchClrColors(MatchColorLib) | Returns the number of Colors in the TrainMatchColor tool generated data structure.
GetTrainMatchClrColorName(MatchColorLib,[Index]) | Returns the name of the indexed Color in the TrainMatchColor tool generated data structure.
GetColorLibraryName(Colors or MatchColorLib) | Returns the name of the color Library from the referenced data structure.