# ExtractColorHistogram

The ExtractColorHistogram 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. extracts a color histogram A histogram is a graphical representation of the distribution of pixel intensity values. A histogram refers to an array of pixels - how many and their individual greyscale values - within a region of interest (ROI). array from an image region.

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 section for more information. The components are represented as combinations of either RGB or HSI HSI stands for hue, saturation, and intensity in the RGB color model.. For both RGB and HSI, each component of a pixel is converted to a value from 0 to 255. Therefore, the accumulated histogram contains 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 increases with the color randomness found in the image.
Inputs

Parameter | Description
--- | ---
Image | This argument must reference a spreadsheet cell that contains a valid Image data structure. By default, the cell references A0, containing the Image data structure returned by the AcquireImage function.
Fixture A fixture is a coordinate location on the image that keeps the tool in the place determined by the 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. The default setting is (0,0,0), the top leftmost corner of the image.
X | The X-offset, in image coordinates.
Y | The Y-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.
X | The X-offset of the origin, in fixture coordinates.
Note: In order for the histogram to count a pixel, the image region must completely enclose the pixel. The histogram does not include partially-enclosed pixels. The Fixture and Region parameters must be defined within the bounds of the image, or the function returns #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 increases 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.

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)

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.