# TrainPatMaxRedLine

Extracts and trains a pattern from an image for use with the FindPatMaxRedLine 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..

Note: A trained pattern consumes approximately 1MB when using the default Pattern Region (320 x 440), although the pattern size varies greatly depending on the size of the trained pattern.
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.
Fixture A fixture is a coordinate location on the image that keeps the tool in the place determined by the 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)
Pattern 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.
X | The X-offset of the origin, in fixture coordinates.
Y | The Y-offset of the origin, in fixture coordinates.
Width (default = 440) | The dimension along the X-axis of the region.
Height (default = 320) | The dimension along the Y-axis of the region.
Angle (default = 0) | The orientation, in fixture coordinates.
Curve (default = 0) | 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 | This parameter uses Cell References to spreadsheet cell that contains an Annulus, a Circle, a Region, a Polygon, an EditAnnulus, an EditCircle, an EditCompositeRegion, an EditPolygon, an EditMaskedRegion, or an EditRegion. When this parameter is used, the function ignores the Region and Fixture settings and inspects the image area specified by referenced region. If an EditCompositeRegion control is referenced, the inspection area can be a mix of shapes. Each shape in the composite region can be assigned as added to or subtracted from (masking) the inspection area. 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.
Pattern Origin | Specifies the X and Y of the training pattern's origin, as offsets from the center of the training region.
Offset X (default = 0) | Specifies the X offset from the center of the trained pattern.
Offset Y (default = 0) | Specifies the Y offset from the center of the trained pattern.
Auto Select Coarse | When enabled, automatically selects the pattern granularity size to be used during the course search phase. Coarse granularity is used to find large features to find an approximate pattern match in a run-time image quickly.
0 = OFF | Course granularity is used.
1 = ON (default) | Pattern granularity size is automatically selected.
Auto Select Fine | When enabled, automatically selects the pattern granularity to be used during the fine search phase. Fine granularity is used to find small features to determine the pattern location precisely.
0 = OFF | Fine granularity is used.
1 = ON (default) | Pattern granularity size is automatically selected.
Coarse Granularity | Specifies the coarse granularity, as a pixel value. Coarse granularity is used to find large features to find an approximate pattern match in a run-time image quickly (1 to 30; 4 = default). Note: The Auto Select Coarse parameter is enabled by default. Disable it to enable this parameter.
Fine Granularity | Specifies the fine granularity, as a pixel value. Fine granularity is used to find small features to determine the pattern location precisely (1 to 10; 1 = default). Note: The Auto Select Fine parameter is enabled by default. Disable it to enable this parameter. The value for Fine Granularity cannot be greater than the value for Coarse Granularity.
Feature Threshold | Specifies the minimum contrast of trained features. Decrease the value to train additional low contrast features, or increase it to ignore them (1 to 100; 20 = default).
Train Event | Specifies Cell References to a cell containing a model training event trigger. Note: Training occurs when either the property sheet is open or when an event trigger such as a button or other conditionally enabled cell is non-zero.
Reuse Training Image | Specifies whether or not the image used to train the pattern is saved and used when modifying the Pattern settings parameters (Pattern Origin, Auto Select Coarse, Auto Select Fine, Coarse Granularity, Fine Granularity, or Noise Threshold).
0 = OFF (default) | The current image (meaning the image specified in the Image parameter) will be used to train/ re-train the pattern.
1 = ON | The image that was initially used to train the pattern is used to re-train the pattern in the event that Pattern Origin, Auto Select Coarse, Auto Select Fine, Coarse Granularity, Fine Granularity, or Noise Threshold parameters are modified. When first enabled, the image identified by the Image parameter is used to train the pattern and a copy of the image is saved in the job A job is a user-configured program in In-Sight 3D Spreadsheet consisting of functions and designed for specific applications. You can create and edit jobs using the In-Sight 3D Spreadsheet interface, and load them on a vision system for deployment in a live environment.. Any subsequent changes made to the Pattern Origin, Auto Select Coarse, Auto Select Fine, Coarse Granularity, Fine Granularity, or Noise Threshold parameters is made using the stored image. Note: When this parameter is enabled, if the Fixture input is modified or the Pattern Region (or External Region) is moved or modified, the function adjusts the training region in the input image. Save the new image and re-train the pattern. If the Reuse Training Image parameter is turned ON (enabled), but a pattern has not already been trained, the function returns #ERR until the parameter has been turned OFF (disabled) and a new pattern trained.
Timeout | Specifies the amount of time, in milliseconds (0 to 30000; 0 = default), that the function searches for a valid pattern before execution is halted and an #ERR is returned. When set to 0, the setting is disabled and no timeout is applied.
Show | Specifies the display mode for TrainPatMaxRedLine graphics on the image.
0 = hide all (default) | All graphics are hidden, except when the cell containing the TrainPatMaxRedLine function is highlighted in the spreadsheet.
1 = result graphics only | Trained features of the pattern are displayed at all times.
2 = input and result graphics | The input image region, pattern origin, and the trained features are displayed at all times.
3 = show all: input, result and training image | The input image region, pattern origin, the trained features, and the training image are displayed at all times.

Outputs

Returns | A Patterns data structure containing a trained pattern, or #ERR if any of the input parameters are invalid.
Results | When TrainPatMaxRedLine is initially inserted into a cell, the Trained status will automatically appear in the adjacent cell to the right. If a pattern cannot be trained, then #ERR is inserted. One Patterns Vision Data Access functions is automatically inserted into the spreadsheet:
Label | Function | Description
--- | --- | ---
Trained | GetTrained(Pattern) | Returns 1 if a pattern has been successfully trained, and 0 if a pattern cannot be trained.