ExtractColor

The ExtractColor function, referencing a ExtractColorLib data structure returned by a TrainExtractColor function, determines the number of pixels present in the Region of Interest (ROI) that match the selected trained Color Models in the TrainExtractColor color Library. For more information, see TrainExtractColor. The extracted Color Model corresponds to the Color Model with the highest pixel count.

The ExtractColor function outputs a Colors data structure, which contains the pixel count of the extracted Color Model and an output image that can be referenced by other In-Sight Vision Tools. For more information, see Vision Tools.

ExtractColor Inputs

Syntax: ExtractColor(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Region.X,Region.Y,Region.High,Region.Wide,Region.Angle,Region.Curve,External Region,Extract Color Library,Count Pixels,Output Image,Show)

General Tab

Note: 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 either a valid color Image data structure output by the AcquireImage function, or a Colors data structure output by another ExtractColor function. By default, the cell referenced is A0, the cell containing the Image data structure returned by AcquireImage. For more information, see AcquireImage.

Note: This parameter must reference a color image.

Fixture

Defines the Region of Interest (ROI) relative to a Fixture input or the output of a Vision Tool function's image coordinate system. Setting the ROI relative to a Fixture ensures that if the Fixture is rotated or translated, the ROI will be rotated or translated in relation to the Fixture. For more information, see Fixture and Vision Tools.

Note: The default setting is (0,0,0), the top leftmost corner of the image.

Row	The row offset, in image coordinates.
Column	The column offset, in image coordinates.
Theta	The angle of orientation, in the image coordinate system.

Region

Also known as the Region of Interest (ROI), specifies the region of the image that undergoes analysis and creates a rectangular image region that can be transformed and rotated. For more information, see Interactive Graphics Mode.

Tip: With this parameter selected, you can press the Maximize Region button on the property sheet's toolbar to maximize the region and cover the entire image.

X	The x-offset of the origin, in fixture coordinates.
Y	The y-offset of the origin, in fixture coordinates.
High	The dimension along the region's x-axis.
Wide	The dimension along the region's y-axis.
Angle	The orientation, in fixture coordinates.
Curve	The angular deviation between the region's x-axis and the opposing boundary line.

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

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.

Extract Color Library

Specifies a reference to a TrainExtractColor function that contains the desired color Library and Color Models.

Note: This must be a reference to a TrainExtractColor ExtractColorLib data structure. This function cannot reference a MatchColorLib data structure output by a TrainMatchColor function; the ExtractColor function will return #ERR in this condition.

Count Pixels

Specifies if pixel counting is turned on or 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 to memory.

0 = OFF	Pixel counting is turned off.
1 = ON (default)	Pixel counting is turned on.

Output Image

Indicates the type of image to be output. The output image may be referenced by other In-Sight Vision Tools in the Image parameter.

All graphics will be hidden, except when the cell containing the ExtractColor function is the active cell in the spreadsheet.

0 = Marked Image	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 highly useful user feedback information, this output image requires the largest amount of processing time.
1 = Binary Image (default)	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). This image may be used by other In-Sight Vision Tools, such as the ExtractBlobs function. For more information, see ExtractBlobs. Note: This output image is the fastest of the image outputs and presents the least impact to memory.
2 = Color Image	Specifies that a color image will be output. In this output image, any pixel that matches an active Color Model will retain its original value, while all other pixels are set to 0,0,0 (RGB). This image may be used by other In-Sight Vision Tools. Note: This output image is 4 times the size of the Binary Image, as it contains RGB and Intensity data.
3 = No Image	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, turn the Count Pixels parameter On 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.

0 = hide all (default)	All graphics will be hidden, except when the cell containing the ExtractColor function is the active cell in the spreadsheet.
2 = result graphics only	The input image region will be displayed at all times.
3 = input and result graphics	Both the input image region and the outlines of extracted colors will be 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 automatically enabled.

Note: The Color Models can also be enabled from the spreadsheet, using the SetExtClrColorModelState function. For more information, see SetExtClrColorModelState(Colors, Enable, ColorModelName1, [ColorModelName2,...]).

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

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.