# TrainExtractColor

The TrainExtractColor function extracts and trains color models from an image region. You can use these models to create a color library for the ExtractColor function. The ExtractColor function identifies the pixels that match the colors trained in the color library.

For an example of extracting colors with the TrainExtractColor and ExtractColor functions, see Extract Colors.

## TrainExtractColor Overview

Use the Training tab of the TrainExtractColor property sheet to create a color library. A color library includes one or more color models. You create the color models selecting and combining color samples. The order of the colors in the color model is important because different orders can result in different pixel counts. See Extract Colors for an example.

Each color sample includes:

- An RGB value

  The most dominant RGB value in the training region determines the RGB value of the color sample.

  Note: Color variation in the training region affects the Hue tolerance. For best results, place the ROI over a uniform color when training.

- Color tolerances

  The color tolerances you set in the property sheet determine which pixel values close to the trained pixel value the function includes in the color sample. You can set how selectively the function includes different hues, darker or lighter values, and highlights that are close to the trained pixel.

- Operation

  The operation setting indicates whether the function adds pixels that match the selected color to the result or removes them.

  - Additive: If the image pixel value matches this color, the function includes the pixel in the result as a matching pixel.

  - Subtractive: If the image pixel value matches this color, the pixel will be removed as a matching pixel.

## TrainExtractColor Training Tab

The Training tab parameters are used to manually train colors and color models for the color library while the vision system is Offline.

Number | Description
1 | In this section, you can specify the name of the color library and the color models the library contains. Use the buttons next to the Model Name field to: Rename a color model. Add a new color model to the library. Remove a color model from the library. Use the Optimized For setting to optimize the model for either Accuracy or Speed.
2 | Use the Add New Color and the Subtract New Color buttons to add new colors to the color model. The terms "add" and "subtract" refer to whether pixels matching the color are added to or removed from the result. This is referred to as the operation of the color. Note: You can change the operation mode after training. To add a color to the color library: Click the Add New Color or Subtract New Color depending on the desired operation mode. Select a ROI type from the drop-down menu: region, circle, or annulus. Place the ROI over the desired part of the image to extract the color. For best results, select a uniform color. Use the Train mode options to specify either Single color or Multiple color mode. Multiple color training has the following two parameters: Minimum Color Area (%): Specifies the minimum number of pixels (1 to 80; default = 2) within the ROI that the Color must occupy to be trained, as a percentage of the total number of pixels within the ROI. Smoothing: Specifies the image smoothing factor (0-10; default = 1), which reduces image noise and is applied prior to training. Note: The Multiple color mode specifies that the function automatically populates the Color Model with Colors, according to the RGB data present in the ROI. It assigns an additive or subtractive operation depending on which button is pressed (Add New Color/Subtract New Color) to the newly created Colors. You can then configure the properties of the individual Colors.
3 | This section displays the colors of the selected color model, the operation, and the RGB values. You can change the operation of the color with the drop-down menu in the Operation column. Use the buttons next to the colors to: Move the selected color up in the list. Move the selected color down in the list. Remove the selected color.
4 | Specify the tolerances for the selected color(s). When configuring the tolerance controls, move the TrainExtractColor property sheet so that you can easily view the image. As you adjust the controls, the image updates to reflect the changes. Darker: Specifies the lower limit (0 to 1.0; default = 1.0). This setting expands the color distribution proportionally lower along a line passing through 0,0.0 and the peak color. Lighter: Specifies the upper limit (1.0 to 10.0; default = 1.0). This setting expands the color distribution proportionally higher along a line passing through 0,0.0 and the peak color. Highlights: Specifies the highlight limit (1.0 to 10.0; default = 1.0) for training. This setting, beginning at the peak color, expands the color distribution higher and towards saturation (255,255,255). Hues: Specifies the sigma factor (0.0 to 10.0; default = 2.0), which refers to the standard deviation calculation that is performed internally at the time of training for each color plane. This setting allows you to set how strict the function is when deciding if a color is part of the trained color. The Hues setting sets the number of standard deviations from the peak color that a color must be within to be considered part of the trained color. For example, if you set the hue control to a sigma factor of three, the tool will count any pixel whose RGB values are within three standard deviations from the peak color as a match.The Hue control sets the number of standard deviations about the peak color in each of the three color planes. A Hue control of 2.0, for example, sets a box around the peak color of ±1 standard deviation for each color plane.

## TrainExtractColor External Training Tab

The External Training tab is used to configure re-training parameters for external training. The parameters in this section are used to configure the re-training of color models while the vision system is Online.

TrainExtractColor Inputs

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 an ExtractColor function. Note: This parameter must reference a color image.
External Region | This parameter uses Cell References to an Annulus, Circle, Region, EditAnnulus, EditCircle, EditCompositeRegion, EditPolygon, and 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.
Event | Specifies the update event on which to train a color model. This parameter must be a reference to one of the following: The Image data structure in cell A0, containing the AcquireImage function. A cell containing an Event function. A cell containing a Button function.
Train Procedure | Specifies the method used to add new colors to the color model.
0 = Append to existing colors (default) | Add the new color to the existing colors in the color model.
1 = Delete existing colors and append | Delete all the previous colors and add the new color to the color model.
Color Model Name | Specifies the name of the color model, set in the Training tab, to re-train for Online re-training. If the color model does not exist, a new color model is created.
Color Name | Specifies the name to assign to the newly trained color. If empty, the default name is assigned automatically.
Color Operation | Specifies the operation of the color within the color model.
0 = Add | The newly trained color will have an Add Operation in the color model.
1 = Subtract | The newly trained color will have a Subtract Operation in the color model.
Darker Limit | Specifies the lower limit (0 to 1.0; default = 1.0) for Online training. This setting expands the color distribution proportionally lower along a line passing through 0,0.0 and the peak color.
Lighter Limit | Specifies the upper limit (1.0 to 10.0; default = 1.0) for Online training. This setting expands the color distribution proportionally higher along a line passing through 0,0.0 and the peak color.
Highlight Limit | Specifies the highlight limit (1.0 to 10.0; default = 1.0) for Online training. This setting, beginning at the peak color, expands the color distribution higher and towards saturation (255,255,255).
Hue Limit | Specifies the sigma factor (0.0 to 10.0; default = 2.0) for single color Online training. This setting expands the color distribution to allow colors that are similar to the peak color to be included. The sigma factor refers to the standard deviation calculation that is performed internally at the time of training for each color plane. This setting allows you to set how strict the function is when deciding if a color is part of the trained color. The Hues setting sets the number of standard deviations from the peak color that a color must be within to be considered part of the trained color. For example, if you set the hue control to a sigma factor of three, the tool will count any pixel whose RGB values are within three standard deviations from the peak color as a match.The Hue control sets the number of standard deviations about the peak color in each of the three color planes. A Hue control of 2.0, for example, sets a box around the peak color of ±1 standard deviation for each color plane.

TrainExtractColor Outputs

Returns | An ExtractColorLib data structure containing the Color Model(s) trained for the ExtractColor tool, or #ERR if any of the input parameters are invalid.

TrainExtractColor Vision Data Access Functions

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

GetNTrainExtClrModels(ExtractColorLib) | Returns the number of Color Models in the TrainExtractColor tool generated ExtractColorLib data structure.
GetTrainExtClrModelName(ExtractColorLib,[Index]) | Returns the name of the indexed Color Model in the TrainExtractColor tool generated ExtractColorLib data structure.
GetColorLibraryName(ExtractColorLib) | Returns the name of the color Library from the referenced ExtractColorLib data structure.