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 function, as well as flexed by the FlexFlawModel function of the Flaw Detection functions. For more information, see SurfaceFlaw, FlexFlawModel, or Flaw Detection.

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.

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.

Mask Inputs

Syntax: Mask(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Region.X,Region.Y,Region.High,Region.Wide,Region.Angle,Region.Curve,Scale,External Region,Flex Flaw Reference,Segmentation.Smoothing Factor,Segmentation.Minimum Edge Contrast,Segmentation.Minimum Segment Area,Mask Generation.Mask Method,Mask Generation.Segment(s),Mask Generation.Maximum Small Hole Fill Size,Mask Generation.Median Kernel Size,Mask Generation.Erode Mask Count,Mask Generation.Invert,Mask Generation.Train Mask,Timeout,Display Image,Show)

Parameter	Description
Image	This argument must reference a spreadsheet cell that contains a valid Image data structure. By default, the cell referenced is A0, which contains the Image data structure returned by AcquireImage.
Fixture	Defines the Region (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 or Vision Tools Functions. Note: The default setting is (0,0,0), the top leftmost corner of the image. Row Specifies the row offset, in image coordinates. Column Specifies the column offset, in image coordinates. Theta Specifies the orientation, in image coordinates.
Region	Also known as the region of interest or 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, 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 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. Curve Specifies the angular deviation between the region's x-axis and the opposing boundary line.
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. For more information, see EditInt.
External Region	Specifies a reference to a spreadsheet cell that contains a Controls function. 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. For more information, see Controls Functions. 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.
Flex Flaw Reference	Specifies a reference to a cell containing a FlexFlawModel data structure containing the Flex algorithm modified model data, output by a FlexFlawModel function. This allows the mask to be flexed by the FlexFlawModel function's Flex algorithms, to account for process variations.
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 Specifies that the mask will be trained to the currently configured parameter settings. Note: This parameter may be inserted into the spreadsheet to allow external control of the re-training operation. Placing the parameter in the spreadsheet allows an external device, through the use of a Custom View, to re-train the mask during run-time. For more information, see Custom View Settings Dialog.
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.
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

A Mask data structure containing a binary mask, 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.

For more information, see Structures.