TrainExtractColor

Extracts and trains Color Models from an image region for use with the ExtractColor function. TrainExtractColor trains Colors within the Color Models, and then the ExtractColor function is used to identify the Color Model present in the image. For more information, see ExtractColor.

The TrainExtractColor function is used to build a color Library (configured in the Training tab of the ExtractColor Training dialog). The Library may contain up to 100 distinct Color Models, which are composed of individual Colors.

A Color Model defines an aggregate 3D distribution of RGB values, and is constructed by sequentially adding and/or subtracting individual Color distributions.

A Color defines the 3D distribution of RGB values based on the peak RGB value present within the region of interest (ROI) at the time the Color was trained. The distribution can be expanded or contracted, based on the individual Color Tolerances settings, and added to or subtracted from the aggregate distribution defined in the Color Model.

When defining a Color during the training phase, the TrainExtractColor function internally generates a 3D color histogram of the colors present within the ROI. The function then determines the Peak Color within the ROI. Figure 1 shows the 3D color histogram of an image of a washer. The data in the histogram illustrates that instead of being composed of a single color, the washer's color occupies a three dimensional distribution of many colors within the RGB space.

The 3D histogram represents a dichromatic reflection, which is composed of the light that is reflected from the material surface and the light reflected from the material body.

The Peak Color area represents the location in the histogram with the highest concentration of matching pixels.
The Darker/Lighter Line corresponds to the light reflected from the body of the object, and is represented as a line that connects the origin (Black; 0,0,0) to the Peak Color, and then extends beyond to the limits of the histogram.
The Highlight Line represents the surface reflection component, and extends from the Peak Color to the limits of the histogram along the illumination vector (White; 255,255,255).

Peak Color and Hues

When a Color is first trained, the function performs a statistical analysis of the individual colors present in the ROI. The Peak Color is determined, and the standard deviation from the Red, Green and Blue channels is calculated. This calculation is referred to as the sigma factor, and adjusting the Hues control will set the number of standard deviations from the Peak Color that a Color must be within to be considered part of the trained Color, creating upper and lower limits on the RGB color channels. For example, if the Hues control was set to a sigma factor of 3, any pixel whose RGB values are within 3 standard deviations from the Peak Color will be counted as a match for that Color.

Darker/Lighter Line

Adjusting the Darker/Lighter controls allows you to expand the model beyond the bounds of the Peak Color and sigma factor to include more variations of the Color along the Darker/Lighter Line. These controls allows you to include/exclude RGB values that maintain the proportionality of the Peak Color, but have greater or lesser intensity. These colors are contained within a volume that extends from the apex, located at the origin, to the limits of the histogram, and encompasses the Peak Color. Figure 2 illustrates the 3D histogram from Figure 1, but with the Darker/Lighter Limits in place. The Darker/Lighter Line of the Color is limited by the Darker/Lighter Limit values, which are set as a percentage of the color magnitude (the Euclidian distance from the Peak Color to the origin). A separate percentage is calculated for the range values of the Darker and Lighter Limits.

Highlight Line

Adjusting the Highlights controls expands the number of colors that are considered to belong to the Color. The additional colors are contained within a volume that starts at the Peak Color, has a width equal to the that of the Darker/Lighter volume, and encompasses the Highlight line, as illustrated in Figure 3. The Highlight Line's upper limit is the only adjustable limit, and it is set as a percentage of the color magnitude.

TrainExtractColor Training Tab

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

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

Color Models Controls

Library Directory Structure

The Library directory structure displays the Color Models in the Library.

New Model: Adds a new Color Model to the Library.
Rename: Allows the default Color Model name (Model_1) to be modified.
Delete Model: Removes the selected Color Model from the Library.

Colors Table

The Colors table displays the Colors of the selected Color Model in the Library window, and the Color's Name, RGB values and Operation.

Rename Color: Allows the default Color name (Color_1) to be modified.
Include Color: Specifies an additive Operation of the Color within the Color Model.
Exclude Color: Specifies a subtractive Operation of the Color within the Color Model.
Move Color Down: Moves the selected Color down in the list of Colors within the Color Model.
Move Color Up: Moves the selected Color up in the list of Colors within the Color Model.
Delete Color: Removes the selected Color from the list of Colors within the Color Model.

Train Controls

Specifies how the Color will be trained, the ROI used to define the Color and the Operation of the Color within the Color Model.

Most Dominant Color: Specifies that one Color within the defined Color Model is trained, and will be added or subtracted from the Color Model, depending on which button is pressed (Add New Color/Subtract New Color).
Multiple Colors: Specifies that the function will automatically populate the Color Model with Colors, according to the RGB data present in the ROI, and assigns an additive or subtractive operation depending on which button is pressed (Add New Color/Subtract New Color) to the newly created Colors. The properties of the individual Colors may then be configured.

Note: This parameter enables the Minimum Color Area and Smooth Image First parameters.
Smooth Image First: Specifies the image smoothing factor (0-10; default = 1), reducing image noise, to be applied prior to training.

Note: This control is only enabled when Multiple Colors is selected.
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.

Note: This control is only enabled when Multiple Colors is selected.
Select Region: Specifies that a rectangular ROI will be used to define the Color(s).
Select Circle: Specifies that a circular ROI will be used to define the Color(s).
Select Annulus: Specifies than an annulus ROI will be used to define the Color(s).
Select Polygon: Specifies that a polygon ROI will be used to define the Color(s).
Draw Freehand: Specifies that a free-hand shape ROI will be used to define the Color(s).
Add New Color: Specifies an Add Operation for the Color(s).
Subtract New Color: Specifies a Subtract Operation for the Color(s).

Color Tolerance Controls

Specifies the tolerances for the selected Color(s).

Tip: When configuring the Color Tolerance controls, position the TrainExtractColor property sheet so that you can easily view the image. As you adjust the controls, the image will update to reflect the changes, depending on the type of Image Marking selected.

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) for Single Color 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. The Hue Limit sets the number of standard deviations about the peak color in each of the three color planes. A Hue Limit of 2.0, for example, sets a box around the peak color of ±1 standard deviation for each color plane.

Image Marking Controls

Specifies the display of the Color(s) in the image.

Mark Results for Entire Group: Specifies that all of the Colors in the Color Model are marked in the image.
Mark Results up to Selected Color: If you select the second Color in a list of three, the first and second Colors are marked in the image.
Mark Selected Colors Only: Only the selected Color is marked in the image.

TrainExtractColor Image Tab

The Image tab is used to specify the image that will be used to train the Color Models 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.

TrainExtractColor 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 color models while the In-Sight color vision system is Online.

TrainExtractColor Inputs

Syntax: TrainExtractColor(Image,Event,External Region,Retrain Operation,Retrain Procedure,Retrain Mode,Color Model Name,Darker Limit,Lighter Limit,Highlight Limit,Hue Limit,Minimum Color Area,Smoothing)

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.

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

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.

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

Retrain 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	All previous Colors will be deleted and the new Color will be added to the Color Model.

Retrain Mode

Specifies the training mode.

0 = Single Color (default)	One Color within the defined Color Model is trained, and will be added or subtracted from the Color Model, depending on the Retrain Operation parameter setting.
1 = Multi Color	The function will automatically populate the Color Model with Colors, according to the RGB data present in the ROI, and assigns the property set in the Retrain Operation parameter (Add/Subtract) to the newly created Colors. The properties of the individual Colors may then be configured. Note: This parameter enables the Minimum Color Area and Smoothing parameters.

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.

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. The Hue Limit sets the number of standard deviations about the peak color in each of the three color planes. A Hue Limit of 2.0, for example, sets a box around the peak color of ±1 standard deviation for each color plane.

Note: This parameter is only enabled when the Retrain Mode parameter is set to Single Color.

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.

Note: This parameter is only enabled when the Retrain Mode parameter is set to Multi Color.

Smoothing

Specifies the image smoothing factor (0-10; default = 1), reducing image noise, to be applied prior to training.

Note: This parameter is only enabled when the Retrain Mode parameter is set to Multi Color.

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

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.