# SurfaceFlaw

The SurfaceFlaw 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. is used to detect local intensity variations, which may indicate a flaw, such as a scratch, nick or tear on the object/ part being inspected.

## Overview

The SurfaceFlaw function is designed to detect areas of local intensity and color variations which are flaws in the production process. The function uses two different types of internal filtering operations (Fast, which is used to detect edge-like flaws, or Light Flaws, Dark Flaws or Light and Dark Flaws, which are used to detect blob A blob is a group of pixels on the image that form a distinct pattern, typically used to represent objects, features, or areas of interest in object detection and segmentation tasks.-like flaws) to first highlight edges and areas with sudden color or greyscale variations, before establishing a threshold and applying blob analysis to determine whether or not flaws are present.

SurfaceFlaw is a stand-alone function, and does not require the use of a model, simplifying its setup and improving its execution time. Due to not incorporating a model, the function is able to account for run-time lighting variations and accurately detect flaws. SurfaceFlaw is best suited to applications where a part should have a uniform area to be inspected, such that any sudden change in intensity will be classified as a defect.

Note: The SurfaceFlaw function does accept a Mask data structure output by the Mask function. This allows the function to only inspect specified areas within an image.

### Configuring the SurfaceFlaw function

Setting up the SurfaceFlaw function involves establishing the thresholds that will be used to determine whether or not a flaw exists. Before beginning, collect a database of images of the part to be inspected which contain images of the part in its error-free state, as well as those illustrating common error cases.

To begin, first load an image of the part in its error-free state. Insert the SurfaceFlaw function into the Spreadsheet, and adjust its Region to enclose the area of the image that will be inspected. When configuring the Region, ensure that it does not contain extraneous features, such as labels, the edges of characters or logos, for example. If the inspection will include an edge of a part, the Region must be positioned parallel to the edge (the same applies to circular-shaped Regions, with the circular region arc being parallel to the edge of the part), but not over the edge.

Note:

- If the part will exhibit motion, use a fixture A fixture is a coordinate location on the image that keeps the tool in the place determined by the fixture. to ensure the Region moves accordingly with the part.
- If the part contains areas that should be excluded from inspection, such as labels or alpha-numeric characters, use a Mask data structure output by the Mask function to remove them. This allows the function to only inspect specified areas within an image.

Ensure that the function's parameters are configured such that the function does not identify any flaws. The SurfaceFlaw function contains a Display Image parameter, which provides visual feedback on how parameter adjustments affect the function. Set the Display Image parameter to Flaw Candidates to begin, so that any detected flaws are enclosed within a red bounding box.

When adjusting the parameters, try adjusting the Sampling Factor and Smoothing Factor parameters. Increase the Sampling parameter when trying to detect low gradient flaws, or large flaws with low contrast. Increase the Smoothing Factor parameter to help get rid of small, false defects.

After adjusting those parameters, use the different options of the Detection Type, Detection Size and Detection Axis parameters. The function has two types of flaw detection operations: edge-like flaws or blob-like flaws. When the Detection Type parameter is set to Fast, the function performs an Erosion-Dilation filter to detect edge-like flaws at the edge of "area"-type flaws. Thus, the function will report the size of the flaw as the perimeter of the flaw's bounding box, versus the overall area of the flaw. This setting is useful in detecting flaws such as scratches or tears.

The Light Flaws, Dark Flaws or Light and Dark Flaws Detection Type options use combinations of Bottom-Hat and Top-Hat filters to detect blob-like flaws. This allows the function to detect flaws based on their pixel size. These options are useful in detecting flaws based on their area, such as splotches, smears or stains. However, these three Detection Type options generally require more processing time.

For most applications that require the Detection Type parameter be set to Fast, a Detection Size of 1 is typically appropriate. For applications that require Light Flaws, Dark Flaws or Light and Dark Flaws, the Detection Size parameter must be set to a size that is greater than the radius of the flaw to be detected.

Note: If the Region was configured to be parallel to an edge, the Detection Axis must be set to run parallel to the Region.

Finally, adjust the Minimum Flaw Area, Maximum Flaw Area and Minimum Contrast parameters to ensure that the flaws are being properly detected and highlighted, respectively.

Once the function is correctly inspecting the part in its error-free state, load an image of the part containing a flaw. Again, go through the process of adjusting the parameters until the function correctly identifies the desired flaws. After the flaws have been identified, re-load an image of the part in its error-free state and ensure it is still being correctly inspected as not containing flaws. The function will be ready for run-time inspections once all of the database images have been properly configured.

## SurfaceFlaw Inputs

Parameter | Description
Image | This parameter must reference a spreadsheet cell that contains an Image data structure. By default, this parameter references cell A1 . This parameter can also reference other Image data structures, such as those returned by the Image Vision Data Access functions or Coordinate Transforms Functions. Note: The SurfaceFlaw function operates in pixel coordinates.
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 (default = 0) | The X-offset, in image coordinates.
Y (default = 0) | The Y-offset, in image coordinates.
Theta (default = 0) | 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 under Edit in the property sheet toolbar to automatically stretch the region to cover the entire image. Note: Use the External Region parameter instead of setting Cell References to the region coordinates if attempting to define the ROI relative to the output of another 2D Vision Tools function or Controls Functions function. The External Region parameter will properly account for fixture movement, while the cell references may not function correctly and may cause any functions that reference it to result in #ERR.
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.
Curve | The angular deviation between the x-axis and the opposing boundary line of the region.
Note: The Region parameter must be defined within the bounds of the image. Otherwise, the function returns #ERR. The Fixture parameter does not need to be within the bounds of the image.
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.
Straighten Images | Specifies whether or not the function will straighten a curved or angled region of interest (ROI), prior to further image processing. Enabling this parameter is helpful in situations where flaws are only being detected along a particular axis (X or Y); the detection kernel always processes along the image's X and Y axis, independent of the ROI orientation or shape. In order to detect a flaw along a straight edge that is "diagonal" in the image, the image should first be straightened. Note: This parameter is necessary if the internal Region or the External Region parameters have an angle or are curved.
0 = OFF (default) | Specifies that the function will not straighten a curved or angled ROI.
1 = ON | Specifies that the function will straighten a curved or angled ROI.
Sampling Factor | Specifies the amount by which to sample (1 to 99999; default = 1) the input image, thus reducing its resolution. Sampling is used to help reduce the function's execution time, however, at the expense of accuracy. Sub-sampling the image is helpful in instances where the contrast of the flaws is low and they gradually move; sub-sampling brings the pixels closer together so the transitions are shorter and steeper. When determining the proper sampling value, a value of 1 denotes no sampling, i.e. that the input image will be used at full resolution. Higher values denote less resolution and accuracy, but faster execution times.
Automatic Smoothing | Specifies whether or not the function will determine the optimal smoothing factor by which to smooth the image. Allowing the function to select the optimal smoothing factor generally enables better performance. Note: The Automatic Smoothing parameter checkbox is disabled by default. To enable the parameter, the Sampling Factor parameter must be set to a value greater than 1. If the Sampling Factor parameter is set to a value greater than 1 and Automatic Smoothing is not desired, turn off the parameter and set the appropriate value using the Smoothing Factor parameter, instead.
0 = OFF | Specifies that a manual smoothing factor will be applied using the Smoothing Factor parameter.
1 = ON (default) | Specifies that the function will determine the optimal smoothing factor.
Smoothing Factor | Specifies the factor (0 to 99999; default = 0) by which to smooth the image. When determining the optimal value, begin with a similar value as specified in the Sampling Factor parameter. To specify no smoothing, set the value to 0. Note: The Smoothing Factor parameter is disabled if the Automatic Smoothing parameter is enabled and On.
Detection Type | Specifies the type of image processing to apply to the image to determine if flaws are present. Note: If Light Flaws, Dark Flaws or Light and Dark Flaws is the selected type of image processing, the Detection Size parameter must be set to the size of the largest flaw to be detected.
0 = Fast (default) | This option is ideally suited for detecting "edge-like" intensity transitions on a surface, such as streaks or scratches. It applies an erode-dilation operation, which highlights the edge of a flaw. It has the best execution time, however, when reporting flaws, it only reports the perimeter of the flaw, not its area.
1 = Light Flaws | This option is ideally suited for detecting light "blob-like" flaws on a dark background, and detecting flaws based on their area pixel size. It applies a "top hat" filtering operation, which filters out everything except bright features that are smaller than the size of the Detection Size parameter, to detect potential flaws.
2 = Dark Flaws | This option is ideally suited for detecting dark "blob-like" flaws on a light background, and detecting flaws based on their area pixel size. It applies a "bottom hat" filtering operation, which filters out everything except dark features that are smaller than the size of the Detection Size parameter.
3 = Both | This option is ideally suited for detecting "blob-like" flaws where the flaw could be either dark or light, and detecting flaws based on their area pixel size. It applies both "bottom hat" and "top hat" operations and utilizes the maximum result of the two operations.
Detection Size | Specifies the detection neighborhood size (1 to 99999; default = 1), in pixels. This parameter is used to construct the processing neighborhood, or kernel, for use with the Detection Type parameter. Note: For all the Detection Type operations other than Fast, the size value must be set to a value that is at least as large as the length or width of the flaws to be detected.
Detection Axis | Specifies the axis in which to detect potential flaws. This parameter also determines the height of the kernel. For example, if this parameter is set to X and Y, with a Detection Size of 1, the kernel will be a 3 x 3 grid. If this parameter were set to X, with a Detection Size of 1, the kernel will be 1 x 3, in the X direction.
0 = Y | The function will attempt to detect flaws along the Y axis.
1 = X | The function will attempt to detect flaws along the X axis.
2 = X and Y (default) | The function will attempt to detect flaws along both the X and Y axis.
Calculate Flaw Data | Specifies whether or not the function will calculate the area, intensity and bounding box for each detected flaw. Note: Disabling this parameter will decrease the function's execution time. When this parameter is disabled, the internal blob analysis will not be performed. This will cause the function to only return the total area of "flaw " pixels, and no graphical information will denote where the flaws are located in the image. The function's auto-generated results table will return #ERR for the individual results; to extract the data, use the GetTotalFlawArea Flaw Detection Vision Data Access functions, which returns the total area of all of the flaws, combined. Setting the Display Image parameter to Flaw Image (its default setting) will implicitly enable Calculate Flaw Data (i.e, the function will override the state of the Calculate Flaw Data checkbox, running the calculations regardless of the state of the checkbox). If disabling Calculate Flaw Data, set the Display Image parameter to Input Image for the fastest tool execution.
0 = OFF | Specifies that the function will not calculate the area, intensity and bounding box for each detected flaw.
1 = ON (default) | Specifies that the function will calculate the area, intensity and bounding box for each detected flaw.
Calculate Flaw Shapes | Specifies whether or not the function will also calculate the perimeter and roundedness of each flaw. Roundedness is a unit-less number that represents how circular a flaw is; a perfect circle has a roundedness value of 1.0. Elongated flaws will have values greater than 1, with values larger than that representing even further elongation. Point-like flaws may have values closer to 0. Note: The Calculate Flaw Data parameter must be enabled to activate this parameter.
0 = OFF | Specifies that the function will not also calculate the perimeter and roundedness of each flaw.
1 = ON (default) | Specifies that the function will also calculate the perimeter and roundedness of each flaw.
Minimum Flaw Area | Specifies the minimum size (1 to 99999; default = 30), in pixels, of the flaws to detect.
Maximum Flaw Area | Specifies the maximum size (1 to 99999; default = 99999), in pixels, of the flaws to detect. A value of 0 specifies that there is no maximum size.
Minimum Contrast | Specifies the intensity threshold (1 to 255; default = 20) used to detect flaws. For a flaw to be detected, its intensity must differ by this value from the background.
Timeout (ms) | Specifies the amount of time, in milliseconds (0 to 30000; default = 0/No Timeout), that the function will search for flaws before execution is halted and #ERR is returned. Setting the value to 0 will disable the setting and a timeout will not be applied.
Display Image | Specifies the output image to display. Note: This image is for display purposes only, and may not be used as an input to another function.
0 = Input Image | Specifies that the currently acquired image will be displayed.
1 = Straightened Image | Specifies that a transformed and straightened image will be displayed, when an angled or curved ROI is used as an input.
2 = Sampled Image | Specifies that the smoothed and sampled image will be displayed. If an angled or curved ROI was used as an input, the transformed and straightened version will be displayed in addition to the smoothed and sampled affects.
3 = Flaw Candidates | Specifies that the potential flaws will be displayed. Potential flaws are highlighted in contrast to the background, and surrounded by a red bounding box. This display option will include flaws that fall outside the limits of defined flaws (Minimum Flaw Area and Maximum Flaw Area).
4 = Flaw Image (default) | Specifies that flaws will be displayed. Flaws will be drawn in white, while all other areas are drawn in black.
Display X | Specifies the x-coordinate (default = 0) where the display image will be displayed, relative to the upper left-hand corner. This parameter is enabled under the following conditions: The Display Image parameter is set to either Sampled Image, Flaw Candidates or Flaw Image, and the Sampling Factor parameter is set to a value greater than 1. The Display Image parameter is set to Straightened Image, Sampled Image, Flaw Candidates or Flaw Image, the Straighten Images parameter is enabled, and the Region, Angle and/or Curve parameter settings do not equal 0.
Display Y | Specifies the y-coordinate (default = 0) where the display image will be displayed, relative to the upper left-hand corner. This parameter is enabled under the following conditions: The Display Image parameter is set to either Sampled Image, Flaw Candidates or Flaw Image, and the Sampling Factor parameter is set to a value greater than 1. The Display Image parameter is set to Straightened Image, Sampled Image, Flaw Candidates or Flaw Image, the Straighten Images parameter is enabled, and the Region, Angle and/or Curve parameter settings do not equal 0.
Show | Specifies the display mode for SurfaceFlaw graphical overlays on top of the image.
0 = hide all (default) | All graphics will be hidden, except when the cell containing the SurfaceFlaw function is highlighted in the spreadsheet.
1 = result graphics only | The specified Display Image will be shown at all times.
2 = input and result graphics | The specified Display Image and result graphics (red rectangles will be drawn around detected flaws) will be displayed at all times. Note: If the External Region parameter is set as a reference to a Mask data structure, no input image will be displayed.

## SurfaceFlaw Outputs

Returns | A SurfaceFlaw data structure containing the display image data and detected flaws; or #ERR if any of the input parameters are invalid.
Results | When the function is initially inserted into a cell, a results table is created in the spreadsheet using the following Flaw Detection Vision Data Access functions: Note: If the Calculate Flaw Data parameter is disabled, the function will only return the total area of all of the detected flaws; use the GetTotalFlawArea Vision Data Access functions, which returns the total area of all of the flaws, combined.
Label | Function | Description
Total Flaw Area | GetTotalFlawArea(SurfaceFlaw) | Returns the total area of all of the flaws, combined.
Index | N/A | Returns the indexed flaws, sorted from largest to smallest in area.
X | GetX(Structure, [Index1], [Index2]) | Returns a x-coordinate.
Y | GetY(Structure, [Index1], [Index2]) | Returns a y-coordinate.
Width | GetWidth(SurfaceFlaw, [Index]) | Returns the width value, in pixels, of the bounding box surrounding the flaw.
Height | GetHeight(SurfaceFlaw, Index) | Returns height value, in pixels, of the bounding box surrounding the flaw.
Area | GetArea(SurfaceFlaw, Index) | Returns the area, in pixels, of the flaw.
Perimeter | GetPerimeter(SurfaceFlaw, Index) | Returns the perimeter, in pixels, of the flaw.
Intensity | GetAverageIntensity(SurfaceFlaw, Index) | Returns the average pixel intensity value of the flaw.
Roundedness | GetRoundedness(SurfaceFlaw, Index) | Returns the roundedness, in pixels, of the flaw.