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.

TrainPatMaxRedLine Inputs

Parameter

Description

Image

This parameter must reference a spreadsheet cell that contains an Image data structure; by default, this parameter references A0, the cell containing the AcquireImage data structure. 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 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 (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; creates an Interactive Graphics Mode that can be transformed and rotated. With this parameter selected, by pressing the Maximize Region button on the property sheet's Job Edit toolbar, the region will automatically be stretched 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 region's x-axis.
Height (default = 320)	The dimension along the region's y-axis.
Angle (default = 0)	The orientation, in fixture coordinates.
Curve (default = 0)	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.

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, a Mask, 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 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.

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 will be 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 will be 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 (i.e. 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 will be used to re-train the pattern in the event that Pattern Origin, Auto Select Coarse, Auto Select Fine, Coarse Granularity, Fine Granularity and/or Noise Threshold parameters are modified. When first enabled, the image identified by the Image parameter will be used to train the pattern and a copy of the image will be 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 will be made using the stored image.

Note:

When this parameter is enabled, if the Fixture input is modified, the Pattern Region (or External Region) is moved or modified, the function will adjust 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 will return #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 will search 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 will be hidden, except when the cell containing the TrainPatMaxRedLine function is highlighted in the spreadsheet.
1 = result graphics only	Trained features of the pattern will be displayed at all times.
2 = input and result graphics	The input image region, pattern origin and the trained features will be 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 will be displayed at all times.

TrainPatMaxRedLine 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 will be inserted.

One Patterns Vision Data Access Functions is automatically inserted into the spreadsheet:

Trained

GetTrained(Pattern)

Returns 1 if a pattern has been successfully trained, and 0 if a pattern cannot be trained.