# ExtractColorHistogram

The ExtractColorHistogram function extracts a color histogram array from an image region.

## 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 (see the Color Components of a Pixel topic for more information). These components are represented as combinations of either red, green and blue (RGB) and/or hue, saturation and intensity (HSI). 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

Parameter | Description
--- | ---
Image | This argument must reference a spreadsheet cell that contains a valid Image data structure. By default, the cell references , containing the Image data structure returned by the AcquireImage function.
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. 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 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; creates a rectangular image region that can be transformed and rotated. With this parameter selected, by pressing the Maximize Region button on the property sheet's toolbar, the region will automatically be stretched 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 region's X-axis.
Height | 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 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.
Color Mode | Specifies whether the type of color representation to calculate and display within the histogram should be RGB, HSI or both. RGB: The tool 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. RGB+HSI: When selected, the tool calculates the red, green and blue (RGB) components and the hue, saturation and intensity (HSI) components of every input pixel. However, 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. HSI: When selected, the tool 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. 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.
Show | Specifies the display mode for ExtractColorHistogram graphical overlays on top of the image.
Hide all = 0 (default) | All graphics will be hidden, except when the cell containing the ExtractColorHistogram function is the active cell in the spreadsheet.
Input graphics only = 2 | The input image region will be displayed at all times.
Show all = 3: input and chart | Both the input image region and the histogram chart will be displayed at all times.

## ExtractColorHistogram Outputs

Parameter | Description
--- | ---
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, the following result table is created in the spreadsheet:
| Red | Green | Blue | Hue | Saturation | Intensity
❒ColorHist | HistMean(ColorHist, 0, 255, 0) | HistMean(ColorHist, 0, 255, 1) | HistMean(ColorHist, 0, 255, 2) | HistMean(ColorHist, 0, 255, 3) | HistMean(ColorHist, 0, 255, 4) | HistMean(ColorHist, 0, 255, 5)

## ExtractColorHistogram Vision Data Access functions

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

Note: These Vision Data Access functions are automatically inserted into the spreadsheet, regardless of the Color Mode parameter value. Therefore, if RGB mode is selected, the Hue, Saturation and Intensity columns return #ERR. At the same time, if HSI mode is seleted the Red, Green and Blue columns return #ERR.

Color | Function | Description
--- | --- | ---
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.