# Filter

Produces an output image where every pixel is the result of an image-enhancement technique in the input image or the specified Region of Interest (ROI).

## Filter Overview

A multipurpose function, Filter produces an image that is used to enhance low contrast images 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.

### Using 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.

1. Load an image.
2. Insert the Filter function into the Spreadsheet.
3. Adjust its Region to enclose the area of the image to 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.
4. Select the appropriate Filter Type. Depending on the selected Filter Type, additional parameters are 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.
- 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.

Inputs

Parameter | Description
Image | This parameter must use Cell References in a spreadsheet cell that contains an Image data structure. By default, this parameter references A1, the cell containing the Image data structure. This parameter can also reference other Image data structures, such as those returned by the Vision Tool Image Functions Image 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.
Note: The Fixture and Region parameters must be defined within the bounds of the image. Otherwise, the function returns #ERR.
External Region | Specifies Cell References to a spreadsheet cell that contains a Controls Functions data structure. When this parameter is used, the function ignores the Region and Fixture settings and inspects the image area specified by the referenced region. 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.
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 is in greyscale.
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 , 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 scale Output 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 have are dependent upon the image content and the resolution. The Low Smoothness and High Smoothness parameters are used to identify the edges by creating Gaussian kernels. The range defined by the two parameters should enclose the size of the feature being enhanced. By default, the Low Smoothness parameter is set to 0, so the edges of features of any size are enhanced equally. The Smoothness parameter is used to identify the edges by creating a Gaussian kernel. The Gain parameter dictates the strength of the sharpening, and the Threshold parameter is used to reduce noise, 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 (1–25; default = 3) 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 the neighbors of a pixel defines the greyscale value for that pixel location in the output image. Note: 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. This parameter Filter Type is enabled when the is set to one of the following: Bottom Hat Close Dilate Edge Magnitude Erode Erode Minus Dilate High Pass Local Mean Normalization Local Median Local Median Normalization Low Pass Max (Top Hat/Bottom Hat) Open Top Hat
Kernel Columns | Specifies the number of columns (1–25; default = 3) 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 the neighbors of a pixel defines the greyscale value for that pixel location in the output image. Note: 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. This parameter Filter Type is enabled when the Filter Type is set to one of the following: Bottom Hat Close Dilate Edge Magnitude Erode Erode Minus Dilate High Pass Local Mean Normalization Local Median Local Median Normalization Low Pass Max (Top Hat/Bottom Hat) Open Top Hat
Auto Threshold | Specifies whether or not the function automatically determines 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 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 automatically computes 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 are set to background. If the pixel values are within the Min and Max parameter settings, the pixel values are set to foreground.
Threshold | Specifies the threshold levels (0 to 255; default = 128) when the Filter Type is set to Binarize, Greyscale Distance, Sharpen, or Threshold Range. Note: The Auto Threshold parameter is enabled by default. Disable it to enable this parameter. If the Filter Type is set to Sharpen, this parameter is used as a noise-reduction setting, and instructs the function to ignore a certain amount of difference between pixels when sharpening, so that lightly textured areas are not over-sharpened.
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.

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. Additional information about the values returned by the function can be accessed through the Image Vision Data Access functions functions.