# TrainFlawModel

The TrainFlawModel 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 create the model of the "golden" or perfect part /object that will be compared against acquired images. This function defines what will be inspected; the Region of Interest (set either through the Region or External Region or Path parameter) defines the area of the image that is trained, as well as where the DetectFlaw and FlexFlawModel functions which reference it, perform their search.

On each image acquisition Acquisition is the process or result of the vision system acquiring a new image., the ROI is adjusted based on the current Fixture A fixture is a coordinate location on the image that keeps the tool in the place determined by the fixture. values; the ROI coordinates, and updated Scale value, are passed to any DetectFlaw or FlexFlawModel functions that reference it. The TrainFlawModel will retain the model.

Note: The TrainFlawModel function passes updated Region, Fixture and Scale data to the DetectFlaw and FlexFlawModel functions which reference it, therefore this function should not be disabled unless all of the functions referencing it are disabled, as well. Otherwise, the functions referencing it will be processing data based on the state of the function prior to being disabled.

## TrainFlawModelInputs

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 or Coordinate Transforms Functions. Note: The TrainFlawModel function does not support calibrated results; the function only operates in pixel coordinates. The TrainFlawModel function supports both greyscale and color images. When referencing a color image, defects in any of the three color planes, Red, Green and Blue (RGB), are identified.
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 | 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 under Edit in the property sheet toolbar to automatically stretch the region to cover the entire image. Note: Use the External Region or Path parameter instead of setting cell references to the region coordinates if attempting to define the ROI relative to the output of another Vision Tool function or Graphics Functions]. The External Region or Path 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 or Path | Specifies Cell References to a spreadsheet cell that contains an Annulus, a Region, an EditAnnulus, an EditMaskedRegion, an EditPolylinePath or an EditRegion function. 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 an external region or path is being used to define the model, and the external region or path is modified, you must enable the Force Train parameter to initiate a re-train of the model. Opening and closing the property sheet will not initiate a re-train when an external region or path is being referenced. 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.
Scale | Specifies the expected scaled size of the modeled part/object at run-time (80 to 120; default = 100), as a percentage, compared to the trained model. Note: If, for instance, a FindPatMaxRedLine function is being used to supply the Fixture input value, the TrainFlawModel function's Scale parameter may be set as a cell reference to the Scale value output by a FindPatMaxRedLine function.
Edge Mask Size | Specifies the tolerance amount (0 to 5; default = 0) near edges to build into the mask image.
Minimum Edge Strength | Specifies the minimum change in intensity (10 to 255; default = 30)across an edge to be included in the model.
Minimum Edge Length | Specifies the minimum edge length (10 to 1000; default = 20) to be included in the model; edges shorter than this length will be excluded from the model. This value represents the minimum number of edge pixels that are connected into an edge. When this parameter is set to a higher value, fewer edges will be detected, while setting this parameter to a lower value will cause more edges to be detected. This setting helps to filter out noisy edge pixels, which are generally short.
Force Train | Specifies whether or not automatic model retraining will be performed on spreadsheet updates. Irrespective of the Force Train parameter, the model will be retrained when the property sheet for the function is open and the following parameters are changed and confirmed by pressing the OK button: The Image parameter is modified. The Fixture parameter is modified. The Region parameter is modified. The External Region or Path parameter is modified. The Scale parameter is modified. The Edge Mask Size parameter is modified. The Minimum Edge Strength parameter is modified. The Minimum Edge Length parameter is modified. During run-time operation, the model will be retrained if any of the following actions occur: The Image parameter is modified. The Region parameter is modified. The External Region or Path parameter is modified. The Minimum Edge Strength parameter is modified. The Minimum Edge Length parameter is modified.
0 = OFF (default) | The function will only retrain if the property sheet is open, one of the parameters mentioned above is changed and the change is confirmed by pressing the OK button of the property sheet. Note: If parameters are placed in the spreadsheet, and those parameters are modified without the property sheet of the TrainFlawModel function being open, the model will not be re-trained. The property sheet must be open, or the Force Train parameter must be set to ON to initiate a re-train of the model.
1 = ON | The function will train a new model every time the spreadsheet executes.
Display Resolution | Specifies the resolution used to display the model image and the edge model. Specifying either Medium or Coarse downsamples the image, removing fine details and noise.
0 = Fine (default) | Specifies that the function will train the model at full image resolution.
1 = Medium | Specifies that the function will train the model at half image resolution.
2 = Coarse | Specifies that the function will train the model at one quarter image resolution.
Draw Edge Markings | Specifies whether or not the edges in the model will be drawn on the image. Trained edges are drawn in green, masked edges are drawn in blue.
0 = ON (default) | The function will draw the edge markings on the image.
1 = OFF | The function will not draw the edge markings on the image.
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 = Live Image | Specifies that the currently acquired image will be displayed.
1 = Edge Image | Specifies that the trained edges in the image will be displayed.
2 = Model Image (default) | Specifies that the trained model will be displayed.
3 = Mask Image | Specifies that the currently trained mask image will be displayed.
Timeout (ms) | Specifies the amount of time, in milliseconds (0 to 30000; default = 5000), that the function will search for a valid model before execution is halted an #ERR is returned. Setting the value to 0 will disable the setting and a timeout will not be applied.
Show | Specifies the display mode for TrainFlawModel graphical overlays on top of the image. Pixels that match those in the trained model will be colored green; pixels that do not match will be colored yellow; pixels that are missing from the Mask Image will be colored blue; extra pixels in the Mask Image will be colored dark magenta; extra edge defects will be colored magenta; and missing edge and area defect pixels will be colored in red.
0 = hide all (default) | All graphics will be hidden, except when the cell containing the TrainFlawModel 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 input image region, the Model Image and Mask Image will be displayed at all times.

## TrainFlawModel Outputs

Returns | A TrainFlawModel data structure containing, for each resolution, a Model Image, Edge Model Image and a Mask Image; or #ERR if any of the input parameters are invalid.
Results | When TrainFlawModel is initially inserted into a cell, the following Flaw Detection Vision Data Access Function is inserted into the spreadsheet.
GetTrained(TrainFlawModel) | Returns 1 if a model has been successfully trained, and 0 if a model cannot be trained.