GreyscaleDistance

Available for color In-Sight vision systems 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 two main sets of user-set color parameters:

  • Color representation (red, green and blue, or hue, saturation and intensity)
  • User-entered values for RGB or HSI color and threshold.

The greyscale image is derived from the Euclidean distance of the color of each pixel.

About the Euclidean Distance

Each pixel is made up of three separate color components: RGB or HSI (see the Color Components of a Pixel topic for more information). GreyscaleDistance calculates each pixel's overall RGB or HSI value and finds its nearest greyscale match by using the Euclidean distance. This is defined as the "ordinary" distance between two points that can be measured with a ruler, and is what we mean when talking about "distance" in general. 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 as follows:

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 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. Therefore, you may need to experiment with both to determine the best color-conversion function for your application.

GreyscaleDistance Inputs

Parameter Description
Image

This argument must reference a spreadsheet cell that contains a valid Image data structure; by default, the cell references A0, the cell containing the Image data structure returned by AcquireImage function.
Fixture

Defines the Region of Interest (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.

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

X Specifies the row offset, in image coordinates.
Y Specifies the column offset, in image coordinates.
Theta Specifies the orientation, in image coordinates.
Region

Also known as the Region of Interest (ROI), specifies the region of the image that undergoes image processing; creates a rectangular image region that can be transformed and rotated. With this parameter selected, by pressing the Maximize Region button on the property sheet's toolbar, the region will automatically be stretched 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.
Note: The Fixture and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.
Color Representation

Specifies which color representation to use for the color conversion.

RGB = 0(default) Red, Green, Blue
HSI = 1 Hue, Saturation, Intensity
Color

Specifies which color to use for the color conversion, depending on the type of 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 three thresholds 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 value 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 (between 0–255), 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 setting 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

Parameters Description
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:

Parameters Description
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, which is also used in the example for ColorToGreyscaleFilter. This example uses a simple configuration of GreyscaleDistance that produces a greyscale output image.

  1. Perform random samplings on the image to check its RGB values. To do so, turn off the spreadsheet view with the (Show Grid) button or by pressing Shift + F6, and then start moving the cursor over the sensor. Notice the RGB information in the status bar in the bottom-left corner of the window as you move the cursor to reveal the RGB values of the acquired image.

    In this example, the RGB values are roughly as follows at the colored areas of the vision system:

    205-185-124
    193-177-110
    175-154-39
    133-104-2
    115-91-6
  2. After inserting the function into the In-Sight spreadsheet, you can define the ROI by double-clicking on the Region parameter in the property sheet, which then disappears to reveal the red rectangular image region overlaid on the image. Move and/or resize the box until it is properly placed, and double-click on it to confirm selection and return to the property sheet.
  3. Set the Color Representation property to RGB as the color representation. Then, enter 205-185-124 in the RGB fields in the Color property of the property sheet, accepting the default settings of the other parameters. Finally, click OK in the property sheet to complete the configuration for the example and to apply the function to the input image.

  4. 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 vision system, the vision system 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 vision system is bright in the below image, it lacks the increased contrast of the above image.