This topic contains the following sections.
The Color Extractor edit control provides a graphical user interface to the CogColorExtractorTool tool, which you use to extract pixels from a color image in order to create a grey-scale image of light and dark pixels based on the reference colors you specify. The tool also generates a color image that can be used as a diagnostic tool to verify that you are extracting the pixels of a desired color, or set of colors. The following figure shows the Color Extractor tool edit control:
The edit control allows you to perform the following actions:
- Build a collection of color definitions.
- Define whether the color is added to, or extracted from, the output image.
- Define the shape, size and location of the region the tool will use to examine the color contained in each acquired image.
If you add a Color Extractor tool to a QuickBuild Job, it appears with an input terminal for the incoming color image and output terminals for the grey-scale and color images it generates, as shown in the following figure:
See the topic Adding Edit Controls to Visual Studio for details on how to add a Color Extractor edit control to your Visual Studio.NET development environment if you are creating a vision application using the VisionPro application programming interface (API). The QuickBuild development environment supports the Color Extractor edit control automatically.
The following table describes the function of each button:
| Button | Description | Function |
 | Run | Generate the grey-scale and color images based on the reference colors currently defined. |
 | Electric mode | Toggle electric mode, where the Color Extractor tool executes automatically when particular configuration parameters change. In electric mode, a lightning bolt appears next to every electric property. |
 | Local image display | Open or close the local image display window. A Color Extractor tool supports the following image buffers:
Depending on the run parameters and graphic parameters you choose, the tool can generate the last run records for a number of defined color groups:
|
 | Floating image display | Open one or more floating image windows, which support the same image buffers as the local image display window. |
 | Open | Open a VisionPro persistence (.vpp) file that contains a set of saved properties for this vision tool object type. VisionPro reports an error if you try to open a .vpp file for another object type. |
 | Save | Save the current properties of the Color Extractor tool to a VisionPro persistence (.vpp) file. The edit control allows you to choose between saving the Color Extractor tool with or without its image buffers and tool results. |
 | Save As | Save the current properties of the vision tool to a new VisionPro persistence (.vpp) file. |
 | Reset | Reset the vision tool to its default state. The tool gives you a choice between resetting to the default-constructed state, which is appropriate when you are using it in a Visual Studio.NET application, or its template-initialized state, which is appropriate for QuickBuild applications. |
 | Show ToolTips | Enable or disable the display of tooltips for individual items in the edit control. |
 | Help | Open this VisionPro online help file. |
The Colors tab displays a grid of the CogColorExtractorColorModel currently defined for the Color Extractor tool. Use the function buttons shown in the following figure to add, delete and reorder the items in the reference table:
The following table describes what each button does:
| Button | Description |
 | Add a new color by selecting a region of the Current.InputImage. Use the region graphic to define the pixels you want to include in this color and click Accept. The following figure shows a Colors tab with two colors:  See the topic Color Extractor Walkthrough for an example of defining colors to a Color Extractor edit control. |
 | Remove the selected color from the reference table. |
 | IndexOf the selected color up one position in the reference table. |
 | IndexOf the selected color down one position in the reference table. |
The edit control also contains the following parameters for defining a color definition:
| Parameter | Description |
| Dilation | Use a Dilation value between 1 and 10 to set the range of color pixels you want to include in this color definition. Higher values allow the tool to consider pixels with approximate RGB values to be included in the analysis, while lower values force the tool to consider only pixels closer to the exact range of RGB values this color defines. |
| Softness | Use a Softness value when you want to generate a grey scale output image with grey values that indicate how closely a pixel in the input image matches the defined color. Increasing this value does not cause the tool to consider more pixels to be included in the definition, but allows the tool to indicate how removed any particular pixel is from the definition itself. A low value generates a grey scale output image where pixels that are close to the color definition receive a medium grey value, while a high value generates a grey scale output image where pixels that are close to the color definition receive bright grey values and pixels that are further from the definition receive dark grey values. The higher the value of Softness, the more individual grey levels will be present in the output image. |
| MinimumPixelCount | Use this value to define the minimum amount of pixels in the input image that match the color definition for inclusion in the grey-scale and color output images. For example, if the minimum value you specify is 20, there must be at least 20 pixels in the input image that match the color definition before they are represented in the grey-scale and color output images. |
| MatteLineLimitLow and MatteLineLimitHigh | Enable and use the Matte Line values to allow the tool to extract pixel values that are darker (low) or brighter (high) than the hues defined by the color definition. |
| Dilation | Enable and use this value to allow the tool to include pixels that range from the defined color into pure white. This can be useful when the objects in your input images display specular highlights from one or more light sources. |
Use the Train button in the Colors tab to train the tool with the current set of defined colors. If you choose to enable the AutoTrain feature on the Run Params tab, the tool can redefine the set of enabled colors based on the latest training parameters and the previously cached color definition image.
Use the Groups tab to manage and organize the individual color groups you want to use in this Color Extractor tool. The following figure shows a sample Groups tab:
The tab contains a button bar for adding, deleting and organizing the color groups. For each group, the tab provides the following options:
| Parameter | Description |
| CombineColorsSequentially | When enabled, the grey-scale and color output images are generated based on the order of the colors within each group. If not enabled, then the tool combines all the colors that are to be added to the output images first, combines all the colors that are subtracted from the output images next, and then combines these two separate groups to produce the resulting output images. |
| Enabled | Determines whether or not this color group should be considered part of the containing color model. |
Use the Region tab to specify the type of region you want to use to examine the run-time image. By default, the region of interest is configured to encompass the entire input image, but some applications might examine just a portion of each acquired image. For example, the following figure shows the Region tab configured to use a rectangular region of interest:
Use the following controls to determine the region of interest:
| Feature | Description |
Select the shape of the input region. Selecting "None=Use entire image" means that the tool uses the entire input image. A Color Extractor tool supports the following input region shapes:
The set of region-defining parameters that appear depend on the region shape you use. | |
| SelectedSpaceName | The coordinate space in which the region is interpreted. For more information, see Coordinate Space Names. |
| Select Mode | Available when Region Shape is CogRectangle or CogRectangleAffine. Selects the set of parameters that define the rectangle. If cogRectangleAffine is chosen, note that the angles of rotation and skew can be specified in degrees or radians, although the underlying tool keeps the measurements in radians. |
| FitToImage | Centers the copy region within Current.InputImage. |
Defines how the tool interprets the region you specify.
|
Use the Run Params tab to determine what results a Color Extractor tool generates. The following figure shows the Run Params tab:
| Parameter | Description |
| SoftnessThreshold | The Color Extractor produces a count for the number of pixels in each image that represent matched colors. By defining a Softness value on the Colors tab, you can generate a grey-scale output image with grey values to indicate how closely any particular pixel matches a defined color. By default, the tool only counts output pixels with a grey value of 255 as pixels that fell within a defined color, but you can lower this default value and have the tool count pixels with a color similar to a defined color as object pixels. For example, lowering this value to 200 would result in the tool counting any grey-scale pixel in the output image with a value above 200 as an object pixel. |
| AutoTrain | When enabled, allows the tool to automatically train before each execution if any run-time parameters have been modified. |
| Overall Results | Generate an overall OverallPixelCountEnabled, a OverallGreyscaleImageEnabled and a OverallColorImageEnabled for all the enabled color groups and their contained colors. |
| Group Results | Generate an individual GroupPixelCountsEnabled, GroupGreyscaleImagesEnabled and GroupGreyscaleImagesEnabled for each enabled color group. |
Use the Graphics tab to control what graphics and images the tool can display. Enabling more options can affect the time the tool requires to execute. The following figure shows a sample Graphics tab:
The tab contains a number of options:
| Parameter | Description |
| Inputs | Show a graphic representing the run-time mask, if you supplied one. The graphic is shown on the Current.InputImage display. |
| Results | Enable the image options you want the edit control to display. |
Diagnostics | For Show Input Image, determine whether or not the input image is recorded as part of the diagnostic record, and whether the image is copied to the record or saved in the record as a reference. Check Show Region to enable a graphic on the LastRun.InputImage corresponding to the region of interest. Check Show Diagnostic Input Image Mask to show a graphic representing the run-time mask, if you supplied one. The graphic is shown on the LastRun.InputImage display. |
Use the Results tab to view the overall PixelCount and group pixel counts for individual color groups. The following figure shows a Results tab:
