# ColorToGreyscaleFilter

Available for color In-Sight vision systems and color-enabled emulators only, ColorToGreyscaleFilter converts each pixel in a color image or Region of Interest (ROI) to a greyscale value based on a simple filter of eight available color parameters: "pure" red, green or blue (RGB); hue, saturation or intensity (HSI HSI stands for hue, saturation, and intensity in the RGB color model.); luminance; or interpolation of the weighted average of RGB components.

Note: Although similar to the GreyscaleDistance function Functions are tools that are available in Spreadsheet for processing and analyzing acquisitions or other results. You can add functions to your Spreadsheet job to create tool chains and produce results for specific applications., ColorToGreyscaleFilter offers a more straightforward operation—every output pixel is a function of the selected conversion filter, which focuses on only one component of the pixel (for example, the red value only, not the red, green and blue values together, as with GreyscaleDistance). You may need to experiment with both functions to determine the best color-conversion function for your applications.

## ColorToGreyscaleFilter Inputs

Parameter | Description
--- | ---
Image | This parameter must reference a spreadsheet cell that contains a color Image data structure. By default, this parameter references A0, the cell containing the Image data structure returned by the function. This parameter can also reference other Image data structures, such as those returned by the Vision Tool Image Functions or Coordinate Transforms Functions.
Fixture A fixture is a coordinate location on the image that keeps the tool in the place determined by the 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 A point cloud is a 3D structure that consists of the data points collected by a 3D vision system during acquisition. as a Fixture, convert the real world units to pixel values using the TransWorldToPixel function. Note: Angles must be multiplied by -1, due to image space differences. 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.
Conversion | Specifies the type of the conversion filter. Note: Each color pixel is divided into color components (see the Color Components of a Pixel topic for more information).
Luminance = 0 (default) | Specifies the conversion filter for the luminance of the color. Luminance is closely related to Intensity in concept, and is a measure of the amount of light emitted or reflected from a particular area. In machine-vision applications, luminance is a greyscale value that is computed from the red, green and blue (RGB) components of a pixel using the following formula: RGB Luminance value = 0.299xR + 0.587xG + 0.114xB The result is an output image of the luminance. The more light emitted from a pixel in the input image, the lighter its appearance in the output image.
Red = 1 | Specifies the conversion filter for the red component of the color. The result is to filter out all but the red component of the pixel. The higher a pixel's red value in the input image, the lighter its appearance in the output image.
Green = 2 | Specifies the conversion filter for the green component of the color. The result is to filter out all but the green component of the pixel. The higher a pixel's green value in the input image, the lighter its appearance in the output image.
Blue = 3 | Specifies the conversion filter for the blue component of the color. The result is to filter out all but the blue component of the pixel. The higher a pixel's blue value in the input image, the lighter its appearance in the output image.
Hue = 4 | Specifies the conversion filter for the hue component of the color. The result is to filter out all but the hue component of the pixel. The higher a pixel's hue value in the input image, the lighter its appearance in the output image (for example, a red with a hue value of 0 will appear dark).
Saturation = 5 | Specifies the conversion filter for the saturation component of the color. The result is to filter out all but the saturation component of the pixel. The higher a pixel's saturation value in the input image, the lighter its appearance in the output image (for example, a white with a saturation value of 0 will appear dark).
Intensity = 6 | Specifies the conversion filter for the intensity component of the color. The result is to filter out all but the intensity component of the pixel and to determine the average intensity of the pixel's RGB components. The higher a pixel's intensity value in the input image, the lighter its appearance in the output image (for example, a white with an intensity value of 255 will appear light).
Interpolation = 7 | Specifies the conversion filter for the interpolation of the color. Interpolation is a weighted average of the red, green and blue (RGB) components of a pixel using the following formula: Interpolation value = 0.25xR + 0.50xG + 0.25xB As with the Intensity filter, the result is to filter out all but the intensity component of the pixel. The higher a pixel's intensity value in the input image, the lighter its appearance in the output image (for example, a white with an intensity value of 255 will appear light). However, the Interpolation filter determines the weighted average intensity of the RGB components and is a non-standard conversion filter.
Show | Specifies the display mode for ColorToGreyscaleFilter graphical overlays on top of the image.
Hide all = 0 (default) | All graphics will be hidden, except when the cell containing the ExtractColorHistogram function is the active cell in the spreadsheet.
Result graphics only = 1 | The input image resion and the histogram A histogram is a graphical representation of the distribution of pixel intensity values. A histogram refers to an array of pixels - how many and their individual greyscale values - within a region of interest (ROI). chart will be displayed at all times.
Input graphics only = 2 | The input image region will be displayed at all times.

## ColorToGreyscaleFilter Outputs

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

## ColorToGreyscaleFilter Example

In this example, the object in the input image is a yellow Cognex sensor, which is also used in the example for GreyscaleDistance.

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 sensor:

   | 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. Then, select a conversion filter, accept the default settings of the other parameters, and click OK in the property sheet. This completes the configuration for this example and applies the function to the input image.

4. Below are three output images of the red, green and blue filters applied, respectively. As expected, the yellow parts of the sensor are the brightest in the red-filtered image because red is the strongest color component in the yellow sensor (the maximum red value for the image is 210, the mean is 116 and the median is 127.) The closer the input pixel value is to the filter's value, the brighter the output pixel.

   The yellow of the sensor is slightly darker in the green-filtered image because it contains less green (maximum of 199, mean of 112 and median of 125), compared to the red-filtered image.

   The yellow of the sensor is darkest in the blue-filtered image because it contains little blue (maximum of 197, mean of 101 and median of 121), compared to the red-filtered image.