# ExtractHistogram

Extracts a Histogram array from an image region.

## ExtractHistogram Overview

The Histogram function returns a one-dimensional representation of pixel values in a region of interest. A histogram is represented by an array of integers, where each element of the array, called a bin, stores a count of the number of pixels in the region, where the value in bin n is the number of pixels in the region of pixel value n. The total of all bin counts in the array is equal to the number of pixels in the region.

## ExtractHistogram Inputs

Parameter | Description
Image | This parameter must use Cell References in a spreadsheet cell that contains an Image data structure; by default, this parameter references A0, the cell containing the Image data structure returned by GetGreyscalefunction. This parameter can also reference other Image data structures, such as those returned by the Vision Tool Image Functions.
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. 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 on the Job Edit toolbar of the property sheet 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 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.
External Region | This parameter uses Cell References to an Annulus, Circle, Region, EditAnnulus, EditCircle, EditCompositeRegion, EditPolygon, 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.
Show | Specifies the display mode for ExtractHistogram graphical overlays on top of the image.
0 = hide all (default) | All graphics will be hidden, except when the cell containing the ExtractHistogram 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. Note: The histogram chart is a dockable window. For more information, see the Charts topic.

## ExtractHistogram Outputs

Returns | A Hist data structure containing the greyscale frequency distribution, or #ERR if any of the input parameters are invalid.
Results | When ExtractHistogram is initially inserted into a cell, a result table is created in the spreadsheet. The following Hist Vision Data Access Functions are automatically inserted into the spreadsheet to create the result table:
Label | Function | Description
Thresh | HistThresh(Hist, 0, 255) | The binary threshold.
Contrast | HistContrast(Hist, 0, 255) | The greyscale image contrast.
DarkCount | HistCount(Hist, 0, Thresh-1) | The number of pixels below Thresh.
BrightCount | HistCount(Hist, Thresh, 255) | The number of pixels above Thresh.
Average | HistMean(Hist, 0, 255) | The mean greyscale value.