TrainPatMaxRedLineColor

Extracts and trains a pattern (a trained, internal geometric description of an object you wish to find) from a color image for use with the FindPatMaxRedLineColor function. For more information, see FindPatMaxRedLineColor.

Note:

The TrainPatMaxRedLineColor and FindPatMaxRedLineColor functions are only available on In-Sight 7000 Gen2 series color vision systems and In-Sight 8000 series color vision systems running In-Sight firmware 5.6.0 and later. For a complete list of models and supported firmware versions, see Firmware Versions.
When using a greyscale image, the TrainPatMaxRedLine and FindPatMaxRedLine function must be used. When attempting to use the TrainPatMaxRedLineColor and FindPatMaxRedLineColor functions on a greyscale image (for example, ColorToGreyscaleFilter's output), #ERR is returned.
The FindPatMaxRedLineColor function must reference the TrainPatMaxRedLineColor function. When referenced a different function (for example, a TrainPatMaxRedLine function), #ERR is returned.

TrainPatMaxRedLineColor Inputs

Sytanx: TrainPatMaxRedLineColor(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,Match Colors,Select Colors,Auto Select Coarse,Auto Select Fine,Coarse Granularity,Fine Granularity,Feature Threshold,Reuse Training Image,Timeout,Show Graphics)

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.

Note: This parameter must reference a color image.

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

Match Colors

Specify which colors to train in the Pattern Region.

0 =All Colors (default)

Specify to match all colors in the Pattern Region. For example, in the following image, both the blue (object) and grey (background) colors are trained.

As a result, the FindPatMaxRedLineColor function that references this function finds blue patterns on grey background. For more information, see FindPatMaxRedLineColor.

1 = Selected Colors

Specifies colors to train using the Select Colors parameter. For example, in the following image, you can select only the blue color (object) to train.

As a result, the FindPatMaxRedLineColor function that references this function finds all blue patterns on any background.

2 = No Matching

No color is trained. As a result, the FindPatMaxRedLineColor function that references this function finds all matched patterns regardless of any color, or any background.

Select Colors

Specifies colors to train by using the Select Colors dialog. You may reference a button or a numeric value in the job; non-zero values are treated as a pressed button and will trigger the Select Colors dialog. For more information, see Selecting Colors.

0 = The Select Color button is not pressed (default).
1 = The Select Color button is pressed.

Note: The Select Colors parameter is enabled only when the Match Colors parameter is set to Selected Colors.

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

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 the Pattern Origin, Auto Select Coarse, Auto Select Fine, Coarse Granularity and/or Fine Granularity 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, or Fine Granularity parameter 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; default = 0, disabling the timeout), that the function will search for a valid pattern before execution is halted and an #ERR is returned.

Show Graphics

Specifies the display mode for TrainPatMaxRedLineColor graphics on the image.

Pattern Region	The Pattern Region and the Pattern Origin display. 0 = Off (default) 1 = On
Trained Image	The trained image displays. 0 = Off (default) 1 = On
Trained Features	The trained edge features display with green lines. 0 = Off (default) 1 = On
Match Colors	Display the trained match colors at sampled locations. Samples are displayed as circles where the color and location of the circle indicates the trained color. 0 = Off (default) 1 = On

TrainPatMaxRedLineColor 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 TrainPatMaxRedLineColor is initially inserted into a cell, the Trained status automatically appears in the adjacent cell to the right. If a pattern cannot be trained, then #ERR is inserted.

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

Selecting Colors

When the Match Colors parameter is set to Selected Colors, you need to select colors to train in the Pattern Region using the Select Colors dialog.

Click the Select Colors button in the TrainPatMaxRedLineColor property sheet. The Select Colors dialog and the magic wand cursor display.
Click the areas where you want to train colors in the Pattern Region. Once selected, the selected areas are colored in and surrounded by a moving border.
Note:
- When selecting multiple areas, enable the icon in the Select Colors dialog or hold down the CTRL key, and click the areas.
- When deselecting areas, enable the icon in the Select Colors dialog and click the areas.
- If you click the outside of the Pattern Region, the selected areas are all deselected.
Specify the tolerance using the Select Colors dialog. To adjust the value, you can click within the bar, or drag the bar. The tolerance is applied once you release the mouse button.

Note:
The tool examines all the pixels that were clicked (= input pixel), and performs a basic diff operation. If the diff result is less than or equal to the tolerance value, the pixels are selected. If you increase the tolerance towards to 100%, all pixels within the Pattern Region are selected. If you decrease the tolerance to 0%, the only pixels that are the exact RBG value of the input pixel are selected.
To accept the selected colors and the tolerance, press the OK button. To cancel, click the Cancel button.

Tip: You can also click the or button in the Job Edit Toolbar to accept or cancel.
The TrainPatMaxRedLineColor property sheet displays again.