# ExtractColor

The ExtractColor function Functions are tools that are available in Spreadsheet for processing and analyzing acquisitions or other results. You can add functions to your Spreadsheet job to create tool chains and produce results for specific applications. finds all pixels in an image region whose value matches a color model in a color library returned by a TrainExtractColor function. When you set the reference to the color library, you can select which color models to consider. By default, all color models are selected.

The ExtractColor function outputs a Colors data structure, which contains the pixel count of the extracted color model and an output image. This image can be further processed by other functions.

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

ExtraColor Inputs

## General Tab

Note: The Fixture A fixture is a coordinate location on the image that keeps the tool in the place determined by the fixture. and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.

Parameter | Description
--- | ---
Image | This argument must reference a color image. By default, the cell referenced is A0, the cell containing the Image data structure returned by AcquireImage.
Fixture | Defines the Region of Interest (ROI) relative to a Fixture input or the output of the image coordinate system for the Vision Tools function. Setting the ROI relative to a Fixture ensures that if the Fixture is rotated or translated, the ROI is rotated or translated in relation to the Fixture. Note: 2D projections use real world units but fixturing with 2D tools requires input in pixel values. When using a 2D projection from a 3D point cloud A point cloud is a 3D structure that consists of the data points collected by a 3D vision system during acquisition. as a Fixture, convert the real world units to pixel values using the TransWorldToPixel function. Note: Angles must be multiplied by -1, due to image space differences. Note: The default setting is (0,0,0), the top leftmost corner of the image.
X | The row offset, in image coordinates.
Y | The column offset, in image coordinates.
Theta | The rotation from the image X-axis, in the image coordinate system. (+/-360 degrees clockwise)
Region | Also known as the Region of Interest (ROI), specifies the region of the image that undergoes analysis. Double-click on the Region parameter to create an Interactive Graphics Mode that you can transform and rotate. Select this parameter and press the Maximize Region button under Edit in the property sheet toolbar to automatically stretch the region to cover the entire image.
X | The X-offset of the origin, in fixture coordinates.
Y | The Y-offset of the origin, in fixture coordinates.
Width | The dimension along the X-axis of the region.
Height | The dimension along the Y-axis of the region.
Angle | The orientation, in fixture coordinates.
Curve | The angular deviation between the x-axis and the opposing boundary line of the region.
Note: In order for a pixel to be counted, it must be completely enclosed within the image region; partially enclosed pixels are not included.
External Region | Note: This parameter uses Cell References to an Annulus, Circle, Region, EditAnnulus, EditCircle, EditCompositeRegion, EditPolygon, EditMaskedRegion, 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.
Extract Color Library | Specifies a reference to an ExtractColorLib data structure, which is the output of the TrainExtractColor function.
Count Pixels | Turns on pixel counting if you check the checkbox. By default, pixel counting is turned off. Note: If pixel counting is not required, turn the parameter off to save processing time. If only pixel counting is required, turn this parameter on and set the Output Image parameter to No Image for the fastest processing time and the least impact on memory.
Output Image | Indicates the type of image to be output. Other In-Sight vision tools can reference the output image in the Image parameter. All graphics are hidden in the output image, except when the cell containing the ExtractColor function is the active cell in the spreadsheet.
Marked Image (default) | Specifies that a marked image will be output. In this output image, any pixel that matches an active color model is set to the marked color, which is the color opposite the peak of the first color present in the color model. Note: While providing useful user feedback information, this output image requires the longest processing time.
Binary Image | Specifies that a binary, greyscale image will be output. In this output image, any pixel that matches an active color model is set to white(255), while all other pixels are set to black(0). Other In-Sight vision tools can use this output image, such as the ExtractBlobs function. Note: This output image is the fastest of the image outputs and has the least impact on memory.
Color Image | Specifies that a color image will be output. In this output image, any pixel that matches an active color model retains its original value, while all other pixels are set to 0,0,0 (RGB). Other In-Sight vision tools can use this output image. Note: This output image is 4 times the size of the Binary Image, as it contains RGB and Intensity data.
None | Specifies that no image will be output. Note: This setting is applicable in jobs that require the fastest execution time. If only pixel counting is required, enable the Count Pixels parameter and set the Output Image parameter to No Image for the fastest processing time and the least impact to memory.
Show | Specifies the display mode for ExtractColor graphical overlays on top of the image.
hide all (default) | All graphics are hidden, except when the cell containing the ExtractColor function is the active cell in the spreadsheet.
result graphics only | The input image region is displayed at all times.
input and result graphics | Both the input image region and the outlines of extracted colors are displayed at all times.

## Color Models Tab

Specifies the color models to be extracted from the referenced TrainExtractColor ExtractColorLib data structure. By default, all of the trained color models in the referenced library are enabled.

Note: The Color Models can also be enabled from the spreadsheet, using the SetExtClrColorModelState function. For more information, see Color Vision Data Access functions.
ExtractColor Outputs

Returns | A Colors data structure containing the pixel count and an output image (unless No Image was specified in the Output Image parameter); or #ERR if any of the input parameters are invalid.
Results | When the ExtractColor function is initially inserted into a cell, a result table is created in the spreadsheet.

ExtractColor Vision Data Access Functions

The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.

Index | GetExtClrModelByRank(Color, Rank) | The color model index by rank.
Extract Model Color | GetActiveExtClrModelName(Color, Index) | The color model name by index.
Pixel Count | GetPixelCountByIndex(Color, Index) | The pixel count by index.
Overall Pixel Count | GetOverallPixelCount(Color) | The pixel count for all active color models.