Mask

The Mask function is used to create an irregularly shaped binary image mask, which is used to highlight certain areas of the image ("care pixels" which are assigned a value of 255), while also excluding other areas from being inspected ("don't care pixels" which are assigned a value of 0). This function can be used as an input with the SurfaceFlaw and the Flaw Detection functions.

Overview

The image mask is used to remove certain features from the inspection, while highlighting other areas. The mask is created through an internal two-step process. The first step involves edge detection and segmentation, during which the input image is smoothed based on the Smoothing Factor parameter setting. Using the smoothed image, an edge magnitude image is internally constructed.

Note: For color images, the edge magnitude image is computed based on all three color channels (R,G,B).

Next, the image is segmented based upon edge transitions, using blob analysis. This is performed on the edge magnitude image, with dark blobs being extracted into segments, which are indexed and labeled. The Mask Generation parameters, Maximum Small Hole Fill Size, Median Kernel Size and Erode Mask Count, can be used to fill holes, smooth borders and / or remove narrow strips in the image mask, respectively. The Median Kernel Size parameter is particularly useful in helping to smooth edges and remove stripes.

The second step of the process involves selecting the edges or segments that will be used to generate the image mask. By default, edges are used (the Mask Method parameter is set to Edge Mask by default) to generate an image mask based on edge magnitude. With this image mask, only edge pixels are masked, and all other pixels are to be shown. This type of mask is helpful when attempting to exclude things like labels, text or logos.

Segments may also be used, by setting the Mask Method parameter to either Largest Segment or Selected Segments. The background is indexed as 0, and the next largest segment is 1, with the rest of the segments being sorted based on their size (they are color-coded and indexed in the image). This type of mask is helpful when attempting to block out the background, or other larger areas in the image.

When setting up the function, the Display Image parameter can be used to display the segments. The segments will be displayed with a numerical index and color-coded (black pixels are not a part of a segment, and white pixels are part of the largest segment).

Once the mask has been properly configured, it will be trained and retain the mask internally as a model. While the function's property sheet is open, if any parameter is changed, the mask will be retrained to the new parameter settings.

Note:

If the part the mask is covering will exhibit motion from image to image, ensure that the mask has a fixture.
If any of the following parameters are placed in the spreadsheet as absolute references to allow for external control of the parameters and the parameters are changed, they will automatically cause the mask model to be retrained: Mask Method, Smoothing Factor, Minimum Edge Contrast, Minimum Segment Size, Maximum Small Hole Fill Size, Erode Mask Count, Invert, Median Kernel Size, and/or Segment(s).
If the Region parameter has been placed in the spreadsheet as an absolute reference to allow for external control of the parameter, and the parameter is changed, the Train Mask button should be pressed to retrain the mask model. If the Region parameter is modified while in the function's property sheet, the mask model will automatically be retrained.

Mask Inputs

Parameter

Description

Image

This argument must reference a spreadsheet cell that contains a valid Image data structure. By default, the cell referenced is $A$0, which contains the image data structure returned by AcquireImage.

Fixture

Defines the region of interest or ROI relative to a Fixture input or the output of a Vision Tools 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	The x-offset from the image.
Y	The y-offset from the image.
Theta	Rotation from image x-axis

Region

Also known as the region of interest or ROI, specifies the region of the image that undergoes image processing; creates a region that can be transformed and rotated. With this parameter selected, clicking the Maximize Region button will automatically stretch the region to cover the entire image.

Note: If the Region parameter has been placed in the spreadsheet as an absolute reference to allow for external control of the parameter, and the parameter is changed, the Train Mask button should be pressed to retrain the mask model. If the Region parameter is modified while in the function's property sheet, the mask model will automatically be retrained.

X	The x-offset from the fixture origin.
Y	The y-offset from the fixture origin.
Width	Width
Height	Height
Angle	Rotation from fixture x-axis
Curve	Specifies the angular deviation between the region's x-axis and the opposing boundary line.

Note: The Fixture and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.

Scale

Specifies the size (80 to 120; default = 100)of the mask, relative to the trained fixture size, as a percentage.

Note: To view the effect of changing the Scale parameter, drag-and-drop the control to the spreadsheet. This will create an EditInt that is automatically classified as an absolute reference to the Scale parameter. Modifying the value of the Scale parameter while in the function's property sheet will automatically re-train the mask at the new scale value, which obscures the effect of the parameter change.

External Region

Specifies a spreadsheet Cell References that contains aControls Functions. When this parameter is used, the Mask function will ignore 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 function's internal region, this parameter must be manually set to zero by entering the value 0 in place of the cell reference. Otherwise, the function will continue to reference the external region.

Segmentation

Specifies how the function will perform the segmentation analysis.

Smoothing Factor	Specifies the amount of smoothing (0 to 31; default = 1) to apply before performing edge detection. Smoothing is applied to average the greyscale values and diminish the affect of sharp transitions.
Minimum Edge Contrast	Specifies the minimum contrast (1 to 100; default = 10) used to detect edges. Note: This parameter is only enabled if the Mask Method parameter is set to Edge Mask.
Minimum Segment Area	Specifies the minimum area (1 to 50000; default = 1000), in pixels, a segment must be in order to be extracted. This parameter is helpful in removing noise from the segments. Note: This parameter is used when the Mask Method parameter is set to either Largest Segment or Selected Segments.

Mask Generation

Specifies how the function will construct the mask.

Mask Method

Specifies what will be the basis for building the mask: edges or segments.

0 = Largest Segment	Specifies that the largest segment should be used to generate the mask.
1 = Edge Mask (default)	Specifies that edge magnitude should be used to generate the mask. Use the Minimum Edge Contrast to determine which edges are used.
2 = Selected Segments	Specifies that user-selected segments will be used to generate the mask. Use the Segment(s) parameter to specify which segments will be used.

Segment(s)

Specifies which specific segments should be used to generate the mask. Select the specific segments by entering a comma-delimited string (e.g. 1,2,5,7).

Note:

The Mask Method parameter must be set to Selected Segments to enable this parameter.
When the Display Image parameter is set to Segmented Image, a string containing the number of segments found will be displayed beside the Information icon. The first number displayed in the list is the selected segment, followed by the found and available segments.

Maximum Small Hole Fill Size

Specifies the maximum size (0 to 10000; default = 0) a small hole must be in order to be filled (not counted as a hole).

Note: This parameter should be set to 0 when the Mask Method parameter is set to Edge Mask.

Median Kernel Size

Specifies the median kernel size (0 to 10; default = 0) which will be used to smooth the edges in the mask image. The kernel is constructed based on (2N + 1), such that the kernel will always be constructed from an odd value. Setting the parameter to 0 specifies that the kernel will not be used.

Erode Mask Count

Specifies the number of times (-100 to 100; default = 0) the generated image will be eroded or dilated. This value can be either negative or positive; negative values dilate the image. Setting the parameter to 0 specifies that no erosion or dilation will occur.

Invert

Specifies whether or not to invert the mask, i.e. white for black, black for white.

0 = Off (default)	The mask will not be inverted.
1 = On	The mask will be inverted.

Train Mask

Select to enable training of the generated mask image, using the segmentation and mask parameters.

Note: Parameter changes result in mask re-generation.

Timeout

Specifies the amount of time, in milliseconds (0 to 30000; default = 0), that the function will attempt to calculate the mask before execution is halted and #ERR is returned. 0 = no timeout

Display Image

Specifies the type of output image the function will generate.

0 = Input Image	The input image will be displayed.
1 = Edge Image	The edge magnitude image will be displayed.
2 = Segmented Image	The color-coded and numerically indexed segment image will be displayed.
3 = Mask Image (default)	The binary mask image, after accounting for the fixture input, which is created after the segmentation and mask generation process. Pixel values of 255 = Care About Pixels; pixel values of 0 = Don't Care About Pixels.

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 Mask function is highlighted in the spreadsheet.
1 = result graphics only	The processed image will be displayed at all times.
2 = input and result graphics only	Both the input image region and the mask will be displayed at all times.

Mask Outputs

Returns

Returns a Mask data structure that contains an image mask based on either edge or segment data, or #ERR if any of the input parameters are invalid.

Note:

The image is not saved in the function's data structure.
The Mask function may produce an incorrect output mask, and not result in the function returning a #ERR condition, under the following condition: First, the mask has been trained using the mask method of Selected Segments, using specific segments. Next, the region is moved to an area of the image that does not contain the selected segments. Once the function is re-trained, the function will display the new Region location and the formerly trained mask. The function will be in an error state, but it will not return a #ERR. To resolve the issue, re-open the function's property sheet and specify segments that exist in the new region, and re-train the mask.