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 AcquireImage function. 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 a Vision Tools 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 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 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.

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 Spreadsheet Editor – 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.