TrainPatMaxRedLine

Extracts and trains a pattern from an image for use with the FindPatMaxRedLine function. For more information, see FindPatMaxRedLine.

Note:

From In-Sight firmware 5.5.0 and later, the function's algorithm has been changed to return more accurate results and decrease the execution time in some circumstances.
Due to this change, when attempting to load a job containing this function configured on the In-Sight firmware 5.5.0 or later to an In-Sight vision system running firmware version 5.4.x or earlier, an error message is displayed and any cells that contains this function will result in #ERR.
This function is only available on In-Sight vision systems running In-Sight firmware 5.1.0 and later. For a complete list of models and supported firmware versions, see Firmware Versions.
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

Syntax: TrainPatMaxRedLine (Image,Fixture.Row,Fixture.Column,Fixture.Theta,Pattern Region.X,Pattern Region.Y,Pattern Region.High,Pattern Region.Wide,Pattern Region.Angle,Pattern Region.Curve,External Region,Pattern Origin.Offset Row,Pattern Origin.Offset Column,Auto Select Coarse,Auto Select Fine,Coarse Granularity,Fine Granularity,Feature Threshold,Reuse Training Image,Timeout,Show)

Note: The Fixture and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.

Parameter

Description

Image

Specifies a reference to a spreadsheet cell that contains an Image data structure; by default, this parameter references A0, the cell containing the AcquireImage 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.

Fixture

Defines the Region of Interest (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 and Vision Tools.

Note: The default setting is (0,0,0), the top leftmost corner of the image.

Row (default = 0)	The row offset, in image coordinates.
Column (default = 0)	The column offset, in image coordinates.
Theta (default = 0)	The angle of orientation, in the image coordinate system.

Pattern Region

Also known as the Region of Interest (ROI), specifies the region of the image that undergoes analysis and creates a rectangular image region that can be transformed and rotated. For more information, see Interactive Graphics Mode.

Tip: With this parameter selected, you can press the Maximize Region button on the property sheet's toolbar to maximize the region and cover the entire image.

X	The x-offset of the origin, in fixture coordinates.
Y	The y-offset of the origin, in fixture coordinates.
High (default = 320)	The dimension along the region's x-axis.
Wide (default = 440)	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.

External Region

This parameter can reference a spreadsheet cell that contains the following functions:

Annulus. For more information, see Annulus.
Circle. For more information, see Circle.
Region. For more information, see Region.
EditAnnulus. For more information, see EditAnnulus.
EditCircle. For more information, see EditCircle.
EditCompositeRegion. For more information, see EditCompositeRegion.
EditPolygon. For more information, see EditPolygon.
EditRegion. For more information, see EditRegion.
Mask: For more information, see Mask

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. For more information, see Cell References - Relative/Absolute.

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 row and column of the training pattern's origin, as offsets from the center of the training region.

Offset Row (default = 0)	Specifies the row offset from the center of the trained pattern.
Offset Column (default = 0)	Specifies the column offset from the center of the trained pattern.

Auto Select Coarse

Specifies whether or not automatically specify the image granularity to use for the coarse search phase. Coarse granularity is used to find large features to find an approximate pattern match in a run-time image quickly.

0 = Off
1 = On (default)

Auto Select Fine

Specifies whether or not automatically specifies the image granularity to use for the fine search phase. Fine granularity is used to find small features to determine the pattern location precisely.

0 = Off
1 = On (default)

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).

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) is 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 and/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 are made using the stored image.

Note:

When this parameter is enabled, if the Fixture parameter is modified, the Pattern Region parameter (or External Region parameter) 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; default = 0, disabling the timeout), that the function will search for a valid pattern before execution is halted and an #ERR is returned.

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.

TrainPatMaxRedLine Outputs

Returns	A Patterns data structure containing a trained pattern, or #ERR if any of the input parameters are invalid. The function is Disabled by default to avoid accidentally training a new pattern on the next acquisition. For more information, see Cell State Dialog.
Results	When TrainPatMaxRedLine is initially inserted into a cell, the Trained parameter status automatically appears in the adjacent cell to the right. If a pattern cannot be trained, then #ERR is inserted.

TrainPatMaxRedLine Vision Data Access Functions

One Vision Data Access function is automatically inserted into the spreadsheet. For more information, see Patterns.

Name	VDA Function	Description
Trained	GetTrained(Pattern)	Returns 1 if a pattern has been successfully trained, and 0 if a pattern cannot be trained.