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.

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

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.