TrainPatMaxRedLine

Extracts and trains a pattern from an image for use with the FindPatMaxRedLine function.

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.
Parameter Description

Image

This parameter must reference a spreadsheet cell that contains an Image data structure. By default, this parameter references cell A0 , containing the AcquireImage function. 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

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 as a Fixture, convert the real world units to pixel values using the TransWorldToPixel function.

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 on the Job Edit toolbar of the property sheet 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 Fixture and Region parameters must be defined within the bounds of the image. Otherwise, the function returns #ERR.

External Region

This parameter uses Cell References to spreadsheet cell that contains an Annulus, a Circle, a Region, an EditAnnulus, an EditCircle, an EditCompositeRegion, an EditPolygon, 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. 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.

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.