TrainMatchColor

Extracts and trains Colors from an 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). For more information, see MatchColor.

The TrainMatchColor function is used to build a Color Library (configured in the Training tab of the MatchColor Training 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.

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.

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

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

Library Name

Library Name: Specifies the name of the Library (the default name is "Library").

Colors Table

The Colors table displays the Colors of the Library. The table displays the Color's name, RGB and HSI values.

Rename Color: Allows the default Color name (Color_1) to be modified.
Delete Color: Removes the selected Color from the Library.

Train Controls

The Train controls are used to add and retrain Colors and specifies the ROI used to define the Color.

Select Region: Specifies that a rectangular ROI will be used to define the Color.
Select Circle: Specifies that a circular ROI will be used to define the Color.
Select Annulus: Specifies than an annulus ROI will be used to define the Color.
Select Polygon: Specifies that a polygon ROI will be used to define the Color.
Draw Freehand: Specifies that a free-hand shape ROI will be used to define the Color.
Select Point: Specifies a point in the image that will be used to define the Color.
Add New Color: Specifies that a new Color will be added to the Library.
Retrain Color: Specifies that the selected Color will be retrained.

Color Tolerance Controls

Specifies the tolerances for the selected Color.

Tip: When configuring the Color 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.

Darker: Specifies the Darker Limit (0 to 1.0; default = 1.0). When the MatchColor function's Color Space parameter 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 MatchColor function's Color Space parameter 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 Image Tab

The Image tab is used to specify the image that will be used to train the Colors in the Library.

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

Start Live: Places the vision system into Live Video mode to display a real-time image.
Open Image...: Loads an image from any networked vision system, local PC or networked PC.

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.

TrainMatchColor Inputs

Syntax: TrainMatchColor(Image,Event,External Region,Color Name,Darker Limit,Lighter Limit)

Parameter	Description
Image	Specifies the color image reference. This argument must reference either: The valid color Image data structure output by the AcquireImage function. By default, the cell referenced is A0, the cell containing the Image data structure returned by AcquireImage. A Color data structure output by a MatchColor function. Note: This parameter must reference a color image.
Event	Specifies the update event on which to train a Color Model.This parameter must be a reference to one of the following: TheImage data structurein cell A0, containing the AcquireImagefunction.For more information, see AcquireImage. Acell containing an Event function.For more information, see Event. Acell containing a Button function.For more information, see Button.
External Region	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.
Color Name	Specifies the name of the Color, set in the Training tab, to re-train for Online re-training. If the Color does not exist, a new Color is created.
Darker Limit	Specifies the Darker Limit for Online training. When the MatchColor function's Color Space parameter 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 MatchColor function's Color Space parameter 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

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. For more information, see Color.

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