ExtractColorHistogram

Extracts a color histogram array from an image region. For more information, see Histogram.

ExtractColorHistogram Overview

ExtractColorHistogram accesses every whole pixel in an image region to accumulate a color histogram. Each color pixel is composed of three separate color components; these components are represented as combinations of either red, green and blue (RGB) and/or hue, saturation and intensity (HSI). For more information, see Color Components of a Pixel. For both RGB and HSI, each component of a pixel is converted to a value from 0 to 255; therefore, the accumulated histogram will contain 256 elements for each color component, where each element contains a value representing the count of the number of pixels with values equal to the index number of the array element.

Note: The HSI values returned by the ExtractColorHistogram function may differ from the HSI values returned by the MatchColor and TrainMatchColor functions. The MatchColor and TrainMatchColor functions average the pixels before HSI processing while the ExtractColorHistogram function averages the pixels after HSI processing; the divergence will increase with the color randomness found in the image.

ExtractColorHistogram Inputs

Syntax: ExtractColorHistogram(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Region.X,Region.Y,Region.High,Region.Wide,Region.Angle,Region.Curve,ColorMode,Show)

Note:

In order for a pixel to be counted in the histogram, it must be completely enclosed within the image region; partially enclosed pixels are not included.
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 spreadsheet cell that contains a valid color Image data structure. By default, the cell referenced is A0, the cell containing the Image data structure returned by AcquireImage. For more information, see AcquireImage.

Note: AcquireImage is the only function that returns a valid color Image data structure.

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.

Color Mode

Specifies the type of color representation to calculate and display within the histogram.

0 = RGB (default)	Calculates the red, green and blue (RGB) components of every input pixel. Within the histogram, the red component is shown as a red line, the green component as a green line, and the blue component as a blue line.
1 = RGB+HSI	Calculates the red, green and blue (RGB) components and the hue, saturation and intensity (HSI) components of every input pixel. The histogram only displays the HSI, with the hue component shown as a red line, the saturation component as a green line, and the intensity component as a blue line.
2 = HSI	Calculates the hue, saturation and intensity (HSI) components of every input pixel, with optimal HSI processing. Within the histogram, the hue component is shown as a red line, the saturation component as a green line, and the intensity component as a blue line.

Show

Specifies the display mode for ExtractColorHistogram graphical overlays on top of the image.

0 = hide all (default)	All graphics will be hidden, except when the cell containing the ExtractColorHistogram function is the active cell in the spreadsheet.
2 = input graphics only	The input image region will be displayed at all times.
3 = show all: input and chart	Both the input image region and the histogram chart will be displayed at all times.

ExtractColorHistogram Outputs

Returns	A ColorHist data structure containing the RGB and/or HSI frequency distribution, or #ERR if any of the input parameters are invalid.
Results	When ExtractColorHistogram is initially inserted into a cell, a result table is created in the spreadsheet.

ExtractColorHistogram 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 or ColorHist.

Note: These Vision Data Access functions are automatically inserted into the spreadsheet, regardless of the Color Mode parameter value. If RGB (Color Mode = 0) is specified, #ERR is returned for Hue, Saturation and Intensity. If HSI (Color Mode = 2) is specified, #ERR is returned for Red, Green and Blue.

Red	HistMean(ColorHist, 0, 255, 0)	The mean red channel value.
Green	HistMean(ColorHist, 0, 255, 1)	The mean green channel value.
Blue	HistMean(ColorHist, 0, 255, 2)	The mean blue channel value.
Hue	HistMean(ColorHist, 0, 255, 3)	The mean hue level value.
Saturation	HistMean(ColorHist, 0, 255, 4)	The mean saturation level value.
Intensity	HistMean(ColorHist, 0, 255, 5)	The mean intensity level value.