GreyscaleDistance

Available for color In-Sight sensors and color-enabled emulators only, GreyscaleDistance converts each pixel of a color image or region of interest (ROI) to a greyscale value or to black and white based on a variety of user-set color parameters: color representation (red, green and blue, or hue, saturation and intensity) and user-entered values for RGB or HSI color and threshold. For more information, see Color Components of a Pixel. The greyscale image is derived from the Euclidean distance of the color of each pixel.

ClosedMore information on Euclidean distance

Each pixel is made up of three separate color components: RGB or HSI. GreyscaleDistance calculates each pixel's overall RGB or HSI value and finds its nearest greyscale match by using Euclidean distance. Euclidean distance, which is defined as the "ordinary" distance between two points that can be measured with a ruler, is what most people mean when they talk about "distance." The Euclidean distance is calculated by taking the square root of the sum of the squares of the differences of the color components of a pixel. The mathematical formula is:

Where:

x0 = The user-specified red/hue value in the Color section of the property sheet.

x1 = The actual red/hue value of an input pixel.

y0 = The user-specified green/saturation value in the Color section of the property sheet.

y1 = The actual green/saturation value of an input pixel.

z0 = The user-specified blue/intensity value in the Color section of the property sheet.

z1 = The actual blue/intensity value of an input pixel. 

The D value can range from 0 to 442, with 0 representing an exact match and 442 indicating no match. Each D value is then divided by 3, which is the square root of the number of components, and inverted to the greyscale spectrum, where 0 is black (no match) and 255 is white (exact match).

Note: Although similar to the ColorToGreyscaleFilter function, GreyscaleDistance provides users with more control and flexibility. One consequence is that "impure" colors (that is, those containing grey or white) will convert better with GreyscaleDistance than with ColorToGreyscaleFilter, which contains filters of only "pure" colors. Users might need to experiment with both to determine the best color-conversion function for their applications. For more information, see ColorToGreyscaleFilter.

GreyscaleDistance Inputs

GreyscaleDistance(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Region.X,Region.Y,Region.High,Region.Wide,Region.Angle,Color Representation,Color.Red/Hue,Color.Green/Saturation,Color.Blue/Intensity,Threshold.Red/Hue,Threshold.Green/Saturation,Threshold.Blue/Intensity,Show)

Note: The Fixture and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.
Parameter Description

Image

This argument must reference a spreadsheet cell that contains a valid color Image data structure. By default, the cell referenced is A0, which contains the Image data structure returned by AcquireImage.

Note: AcquireImage is the only function that returns a valid color Image data structure.

Fixture

Defines the ROI relative to a Fixture input or the output of a Vision Tool 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.

Note: The default setting is (0,0,0), the top leftmost corner of the image.

Row

Specifies the row offset, in image coordinates.

Column

Specifies the column offset, in image coordinates.

Theta

Specifies the orientation, in image coordinates.

Region

Also known as the region of interest or ROI, specifies the region of the image that undergoes image processing; creates a rectangular image region that can be transformed and rotated. For more information, see Interactive Graphics Mode.

Tip: With this parameter selected, clicking the Maximize Region button will automatically stretch the region to cover the entire image.

X

Specifies the x-offset of the origin, in fixture coordinates.

Y

Specifies the y-offset of the origin, in fixture coordinates.

High

Specifies the dimension along the region's x-axis.

Wide

Specifies the dimension along the region's y-axis.

Angle

Specifies the orientation, in fixture coordinates.

Color Representation

Specifies which color representation to use for the color conversion.

0 = RGB (default)

Red, Green, Blue

1 = HSI

Hue, Saturation, Intensity

Color

Specifies which color to use for the color conversion, depending on the color representation chosen. All three color values (and threshold levels) will affect the appearance of a pixel in the output image. For example, an RGB of 255-0-0 with all threethresholds set at -1 will display all "pure" red pixels as white in the output image, and all other colors as darker greyscale values, depending on their Euclidean distance from 255-0-0 (for example, white will appear dark).

Red/Hue

 0 - 255 (default = 0): Specifies the red/hue component of the color.

Green/Saturation

 0 - 255 (default = 0): Specifies the green/saturation component of the color.

Blue/Intensity

 0 - 255 (default = 0): Specifies the blue/intensity component of the color.

Threshold

Specifies black-and-white ("binary") thresholds for each color coordinate, depending on the color representation chosen.

Note:
  • The default is -1 for all three threshold values, which will produce a greyscale output image based on the Euclidean distance.
  • If any Threshold parameter is set to an integer greater than -1, then the output will be a black-and-white image based on the threshold value that is specified.
  • The Threshold parameter represents a "±" value: The thresholds are subtracted from and added to the color values specified in the Color section above, creating minimum and maximum thresholds for the RGB or HSI components. For example, if the user specifies RGB or HSI values of 200-100-50 and threshold values of 20-10-5, the maximum and minimum thresholds will be 220-110-55 and 180-90-45. Pixels with RGB or HSI values equal to or within the thresholds will display as white; those that are outside the thresholds will display as black.

Red/Hue
  • -1 = auto (default): Enables an automatic conversion routine based on the Euclidean distance.
  • 0 - 255: Directly specifies the binary threshold for the red/hue component of the color.

Green/Saturation
  • -1 = auto (default): Enables an automatic conversion routine based on the Euclidean distance.
  • 0 - 255: Directly specifies the binary threshold for the green/saturation component of the color.

Blue/Intensity
  • -1 = auto (default): Enables an automatic conversion routine based on the Euclidean distance.
  • 0 - 255: Directly specifies the binary threshold for the blue/intensity component of the color.

Show

Specifies which graphical overlays are displayed on top of the image.

0 = hide all

The input image region will be hidden, except when the cell containing the GreyscaleDistance function is highlighted in the spreadsheet.

1 = result graphics only

The processed image will be displayed at all times.

2 = input graphics only

The input image region will be displayed at all times.

GreyscaleDistance Outputs

Returns

An Image data structure containing the processed image, or #ERR if any of the input parameters are invalid.

Results

When GreyscaleDistance is initially inserted into a cell, a result table is created in the spreadsheet.

GreyscaleDistance Vision Data Access Functions

The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.

DarkCount

GetDarkPixelCount(Image)

The number of pixels below the binary threshold level.

BrightCount

GetBrightPixelCount(Image)

The number of pixels equal to or above the binary threshold level.
Note: If all three threshold values are set to -1 (default), the two preceding functions will return #ERR.

GreyscaleDistance Example

In this example, the object in the input image is a yellow Cognex vision system. Random samplings of the image (achieved by toggling off the Overlay view by clicking Overlay on the View menu, moving the cursor over the sensor and viewing the RGB information in the status bar in the bottom-left corner of the window) reveal RGB values of 205-185-124, 193-177-110, 175-154-39, 133-104-2 and 115-91-6 for the sensor.

This example uses a simple configuration of GreyscaleDistance that produces a greyscale output image.

After inserting the function into the In-Sight spreadsheet, the user defines the ROI by double-clicking on the word "Region" in the property sheet, which disappears to reveal the red ROI box overlaid on the image. The user moves or resizes the box using the cursor, and clicks the OK button on the Job Edit toolbar to confirm the selection and return to the property sheet. (The selection can also be confirmed by pressing the Enter key or by double-clicking within the ROI.)

Selecting RGB as the color representation, entering 205-185-124 in the RGB fields in the Color section of the property sheet, accepting the default settings of the other parameters and clicking OK in the property sheet completes the configuration for this example and applies the function to the input image.

Below is the output image produced by GreyscaleDistance. Because the RGB values of 205-185-124 are an exact match of some areas of the sensor, the sensor is represented by very bright pixels.

Compare the image above with the image below, which was produced by using the red filter in ColorToGreyscaleFilter. Although the sensor is bright in the below image, it lacks the increased contrast of the above image.

Copyright © 1999 - 2019  |  Cognex Corporation  |  All Rights Reserved.

In-Sight® Explorer Help  |  2019 May 07  |  Revision: 5.7.2.5