# 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.

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 the AcquireImage function. This parameter can also reference other Image data structures, such as those returned by the Vision Tool Image Functions Image Functions or Coordinate Transforms 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. 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 as a Fixture, convert the real world units to pixel values using the TransWorldToPixel function. 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 x-axis and the opposing boundary line of the region.
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 returns #ERR.
External Region | This parameter uses Cell References to an Annulus, Circle, Region, EditAnnulus, EditCircle, EditCompositeRegion, EditPolygon, and 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 internal Region of the function, this parameter must be manually set to zero by entering the value 0 in place of the cell reference. Otherwise, the function continues 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 are hidden, except when the cell containing the ExtractHistogram function is the active cell in the spreadsheet.
2 = input graphics only | The input image region is displayed at all times.
3 = show all: input and chart | Both the input image region and the histogram chart are displayed at all times.

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.