Filter

Produces a color or greyscale output image where every pixel is the result of an image-enhancement technique in the input image or ROI.

Note: This function is only available on In-Sight vision systems running In-Sight firmware 5.1.0 and later. For a complete list of models and supported firmware versions, see Firmware Versions.

A multipurpose function, Filter produces a color or greyscale output image that is used to enhance low contrast images and/or expose features in an image. This function helps to accentuate the desired features, and minimize the undesired features, for most parts. When used effectively, this function makes inspection applications more reliable and repeatable.

The Filter function offers a full range of both local and global image-enhancement techniques; the image-enhancement technique is defined by selecting a Filter Type. For more information, see When Image Processing Is Used?.

Use the Filter Function

Setting up the Filter function involves identifying the image-enhancement technique by selecting a Filter Type to be used to enhance the image.

To begin, first load an image. Insert the Filter function into the Spreadsheet, and adjust its Region to enclose the area of the image that will be enhanced. When configuring the Region, ensure that it does only encompasses areas of the image that need to be enhanced. Encompassing areas that do not require enhancement will affect both how the image-enhancement technique is applied, and the execution time of the function.

Next, select the appropriate Filter Type. Depending on the selected Filter Type, additional parameters will be enabled to further define how the technique is applied. Adjust the enabled parameters to achieve the desired image-enhancement effect.

Note:
  • If the area of the image that requires enhancement will exhibit motion, use a fixture to ensure the Region moves accordingly with the area. For more information, see Fixtures or Region.
  • Before beginning, collect a database of images of the inspection; the images may be loaded using the Record/Playback Options dialog.
  • After configuring the function, load additional images, and adjust parameters, as necessary, to ensure that the image-enhancement technique is being applied correctly across the entire range of images.

Filter Inputs

Syntax: Filter(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Region.X,Region.Y,Region.High,Region.Wide,Region.Angle,Filter Type,Kernel Rows,Kernel Columns,Auto Threshold,Threshold,Min,Max,Gain,Smoothness,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 parameter must reference a spreadsheet cell that contains an Image data structure. By default, this parameter references A0, the cell containing the AcquireImage Image data structure. This parameter can also reference other Image data structures, such as those returned by the Vision Tool Image functions. For more information, see AcquireImage and Image.

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. For more information, see Fixture and Vision Tools.

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

Row

The row offset, in image coordinates.

Column

The column offset, in image coordinates.

Theta

The angle of orientation, in the image coordinate system.

Region

Also known as the Region of Interest (ROI), specifies the region of the image that undergoes analysis and creates a rectangular image region that can be transformed and rotated. For more information, see Interactive Graphics Mode.

Tip: With this parameter selected, you can press the Maximize Region button on the property sheet's toolbar to maximize the region and cover the entire image.

X

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

Y

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

High

The dimension along the region's x-axis.

Wide

The dimension along the region's y-axis.

Angle

The orientation, in fixture coordinates.

Filter Type

Specifies the type of image-enhancement technique to perform; the result is displayed in a greyscale output image.

0 = Binarize (default)

Specifies a black-and-white ("binary") threshold operation that compares each input pixel with the threshold level to determine whether the output pixel is white or black. Input pixel values equal to or above the Threshold parameter value are white; values below the threshold are black.

Note: When a color input image is used, the output image will be a greyscale image.

1 = Bottom Hat

Specifies a "bottom hat" filtering operation that filters out everything except dark features that are smaller than the size of the kernel neighborhood. The result is an output image that displays these dark features as bright pixels on an otherwise dark background.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

2 = Clip

Specifies a "clipping" operation that eliminates the extreme ends of the greyscale spectrum so that the features in the output image are more uniform. This operation compares the greyscale value of each input pixel to the Min and Max parameter values:

  • If the input pixel value is equal to or exceeds the minimum or the maximum, the output pixel is assigned ("clipped" to) the minimum or maximum value, respectively.
  • If the input pixel value is within the minimum and maximum, the output pixel is assigned the value of the input pixel.

3 = Close

Specifies a "closing" operation that performs a dilation followed by an erosion to filter out dark features that are smaller than the size of the kernel neighborhood. Closing an image reduces or completely removes dark areas of the image.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

4 = Dilate

Specifies a "dilation" operation that enhances the bright features of the image while suppressing the darker features. The result is an output image with larger areas of bright pixels. Useful for removing dark specks.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

5 = Edge Magnitude

Specifies an operation that displays the difference between a dilation and an erosion of the input image. The result is an output image where edges are represented by bright pixels. Though similar to Gradient Full, this operation is more complex (and slower), allowing diagonally oriented edges to be represented.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

6 = Equalize

Specifies a histogram equalization operation that extracts the histogram of the input image and spreads out the most frequent greyscale values to create a more even distribution. The result is an output image with increased contrast. This type of filter is useful in environments where the lighting can vary slightly from one image to the next, or when some aspects of the object being inspected can slightly vary.

7 = Erode

Specifies an "erosion" operation that reduces the bright features of the image. The result is an output image with larger areas of dark pixels. Useful for removing light specks, noisy pixels and/or small defects.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

8 = Fill Dark Holes

Specifies a "pixel-filling" operation, where dark pixels surrounded by light pixels are converted to light pixels. The result is an output image where dark holes are filled.

9 = Fill Light Holes

Specifies a "pixel-filling" operation, where light pixels surrounded by dark pixels are converted to dark pixels. The result is an output image where light holes are filled.

10 = Gradient Full

Specifies a "vertical and horizontal gradient" operation that results in an output image where both vertically and horizontally oriented edges are represented by bright pixels. Though similar to Edge Magnitude, this operation is simpler (and faster) and does not represent diagonally oriented edges.

11 = Gradient Horizontal

Specifies a "horizontal gradient" operation that results in an output image where horizontally oriented edges are represented by bright pixels.

12 = Gradient Vertical

Specifies a "vertical gradient" operation that results in an output image where vertically oriented edges are represented by bright pixels.

13 = Greyscale Distance

Specifies the greyscale value of each output pixel as the difference between the greyscale value of each input pixel and the threshold level (for example, if the input pixel value is 100 and the threshold is 25, then the output pixel value will be 75), which is determined by the Threshold parameter.

14 = High Pass

Specifies a "high-pass" operation that results in an output image where edges are enhanced relative to areas with more consistent greyscale gradient. This type of filter is useful in accentuating fine features.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

15 = Invert

Specifies an inversion of pixel values based on the 256-step greyscale that results in an output image that is a "negative" of the input image (for example, inverting an input pixel value of 10 results in an output pixel value of 245).

17 = Local Median

Specifies an operation that computes the median pixel value of the pixel values in the kernel neighborhood, then uses this result as the output image pixel value.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

18 = Local Median Normalization

Specifies a means to subtract the background from an image; this operation subtracts the local median of the input image from the input image, shifts the result right by one, and then adds 128 to produce the output pixel value.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

19 = Low Pass

Specifies a "low-pass" operation that results in an output image in which edges are smoothed or blurred.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

20 = Max (Top Hat/Bottom Hat)

Specifies an operation that uses the maximum of Top Hat and Bottom Hat operations.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

21 = Open

Specifies an "opening" operation that performs an erosion followed by a dilation to filter out bright features that are smaller than the size of the kernel neighborhood. The result is an output image with slightly decreased overall brightness; removing small amounts of bright pixels and enhancing the remaining bright features.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

22 = Optical Density

Specifies an inversion of pixel values based on a logarithmic scaleOutput pixel value = 100 * log (255) - 100 * log (input pixel value). The result is an output image that reveals the density of objects and features in the input image by measuring the amount of light that passes through them. Denser objects and features are represented by lighter pixels in the output image.

23 = Sharpen

Specifies a "sharpness" operation that is used to enhance edges. The operation evaluates the contrast between adjacent pixels, and increases the contrast when the contrast is high. A large contrast difference between adjacent pixels usually represents an edge; however, this operation should not be used to locate edges. The effects that the operation will have are dependent upon the image content and the resolution.

  • The Smoothness parameter is used to identify the edges by creating a Gaussian kernel.
  • The Gain parameter dictates the strength of the sharpening, instructing the filter to ignore a certain amount of difference between pixels when sharpening so that lightly textured areas will not be over-sharpened.

24 = Stretch

Specifies a greyscale stretching operation that linearly "scales up" or "stretches" the greyscale values (based on the Min and Max parameter settings) in the input image to the full 256-step greyscale, resulting in an output image with increased contrast. If the input pixel value is equal to or exceeds the minimum or maximum, the output pixel is assigned to 0 or 255, respectively. For input pixel values within the minimum and maximum, they will be linearly stretched to the 0 to 255 range. For example, if the Min is 50 and the Max is 180, the operation subtracts 50 from each pixel's intensity, making the range 0 to 130. Then each pixel intensity is multiplied by 255/130, creating the range of 0 to 255.

25 = Threshold Range

Specifies a black-and-white ("binary") threshold operation that compares each input pixel with two threshold values (Min and Max) to determine whether the output pixel is background or foreground. If the input pixel value is within the minimum and maximum, the output pixel retains its value, otherwise, the output pixel is set to the background level.

Note: If the minimum value is greater than the maximum value, the background is inverted.

26 = Top Hat

Specifies the "top hat" filtering operation, which filters out everything except bright features that are smaller than the size of the kernel neighborhood. The result is an output image that displays these bright features as bright pixels on an otherwise dark background.

Note: This operation enables the Kernel Rows and Kernel Columns parameters. The kernel must be constructed from odd integer values.

Kernel Rows

Specifies the number of rows of the kernel. A kernel is a rectangular array of numbers that defines the processing neighborhood for operations performed on each pixel location of an image. The greyscale values of a pixel's neighbors defines the greyscale value for that pixel location in the output image.

Filter Type Parameter Range Default Value
Bottom Hat, Close, Dilate, Edge Magnitude, Erode, High Pass, Local Median, Low Pass, Max (Top Hat/Bottom Hat), Open, and Top Hat. 1 - 25 3
Local Median Normalization 1 - 99 3
Note:
  • This parameter is enabled when the Filter Type is set to Bottom Hat, Close, Dilate, Edge Magnitude, Erode, High Pass, Local Median, Local Median Normalization, Low Pass, Max (Top Hat/Bottom Hat), Open, or Top Hat.
  • The kernel is unweighted.
  • The kernel must be constructed from odd integer values. A typical kernel is 3 x 3, but the size is arbitrary.

Kernel Columns

Specifies the number of columns of the kernel. A kernel is a rectangular array of numbers that defines the processing neighborhood for operations performed on each pixel location of an image. The greyscale values of a pixel's neighbors defines the greyscale value for that pixel location in the output image.

Filter Type Parameter Range Default Value
Bottom Hat, Close, Dilate, Edge Magnitude, Erode, High Pass, Local Median, Low Pass, Max (Top Hat/Bottom Hat), Open, and Top Hat. 1 - 25 3
Local Median Normalization 1 - 99 3
Note:
  • This parameter is enabled when the Filter Type is set to Bottom Hat, Close, Dilate, Edge Magnitude, Erode, High Pass, Local Median, Local Median Normalization, Low Pass, Max (Top Hat/Bottom Hat), Open, or Top Hat.
  • The kernel is unweighted.
  • The kernel must be constructed from odd integer values. A typical kernel is 3 x 3, but the size is arbitrary.

Auto Threshold

Specifies whether or not the function will automatically determine a threshold level  when the Filter Type is set to Binarize, Greyscale Distance, or Threshold Range.

Note: This parameter is enabled by default. To use the Threshold parameter, disable this parameter.
  • When enabled, and the Filter Type is set to Binarize, the function automatically computes a threshold level based on the greyscale values within the specified region.
  • When enabled, and the Filter Type is set to Greyscale Distance, the function will automatically compute a threshold value based on the mean greyscale value within the specified region.
  • When enabled, and the Filter Type is set to Threshold Range, the following is automatically applied:
    • If the pixel values are less than the Min parameter setting, or the pixel values are greater than the Max parameter setting, the pixel values will be set to background.
    • If the pixel values are within the Min and Max parameter settings, the pixel values will be set to foreground.

Threshold

Specifies the threshold levels (0 to 255; default = 128) when the Filter Type is set to Binarize, Greyscale Distance, or Threshold Range.

Note:
  • The Auto Threshold parameter is enabled by default; disable it to enable this parameter.

Min

Specifies the minimum greyscale value (0–255; default = 128) when the Filter Type is set to Clip, Stretch or Threshold Range.

Max

Specifies the maximum greyscale value (0–255; default = 128) when the Filter Type is set to Clip, Stretch or Threshold Range.

Gain

Specifies a gain value (0 to 10; default = 1) when the Filter Type is set to Sharpen. This parameter dictates the strength of the sharpening that will be performed by controlling the amount of edge contrast enhancement. Pixels around an edge are driven to their minimum or maximum values to create a sharper appearance of the edge.

Smoothness

Specifies the smoothness value (1 to 4; default = 1) for the Gaussian kernel when the Filter Type is set to Sharpen. Smoothness controls the standard deviation of the Gaussian kernel; higher smoothness values result in a wider "aperture" for the smoothing operation, helping to sharpen features.

Note: Gaussian refers to a bell-shaped curve that is applied as a weighted average to the pixels in the ROI.

Show

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

0 = hide all (default)

The input image region will be hidden, except when the cell containing the Filter 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.

Filter Outputs

Returns

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

Note:
  • The contents of the processed image region in the Image data structure are not saved with the job.
  • For more information about the values returned by the function, see Image.