SortPatterns

Sorts patterns by their position in the image. For each pattern in the input Patterns data structure, SortPatterns computes the position of the pattern's response relative to the specified image fixture coordinate system. Patterns are sorted by one of the following:

X-coordinate
Y-coordinate
Angle
Angle distance
Distance

The sorted patterns are returned as a new Patterns data structure.

SortPatterns Inputs

Syntax: SortPatterns(Patterns,Number to Sort,Sort By,Fixture.Row,Fixture.Column,Fixture.Theta,Sort Tolerance,Show)

Parameter

Description

Patterns

This argument must reference a spreadsheet cell that contains a valid Patterns data structure returned by either the FindPatMaxPatterns or FindPatterns function. For more information, see FindPatMaxPatterns or FindPatterns.

Number to Sort

Specifies the maximum number (1 to 255; default = 1) of patterns to sort.

Sort By

Specifies the sorting method.

0 = X (default)	Sort by distance along the x-axis, from closest to furthest, in descending order. EXAMPLE
1 = Y	Sort by distance along the y-axis, from closest to furthest, in descending order. EXAMPLE
2 = Angle	Sorts by the angle (0 to 360 degrees), as measured from the x-axis of the fixture coordinate system to the line segment defined by the pattern response point and the fixture origin, from closest to furthest, in descending order. For more information, see Offset Row. EXAMPLE
3 = Angular Distance	Sorts by the absolute value of the angle (-180 to 180 degrees), as measured from the x-axis of the fixture coordinate system to a line segment defined by the pattern response point and the fixture origin, from closest to furthest, in descending order. EXAMPLE
4 = Distance	Sorts by the distance from the fixture origin to the pattern's response point, from closest to furthest, in descending order. EXAMPLE
5 = Grid X	Sort by distance along the fixture's x-axis first, and then by distance along the y-axis, from closest to furthest, in descending order. Note: SortPatterns returns #ERR if Grid X is selected and the function is referencing an image that has been calibrated to world coordinate values, such as a CalibrateImage or TransPatternsToWorld function's output. Grid X sorting can only be applied to pixel coordinates. To use the Grid X sorting method using world coordinates, the FindPatMaxPatterns or FindPatterns function being referenced by the SortPatterns function should reference the output of a TransformImage function, with the SortPatterns function sorting in pixel coordinates. The output data can then be transformed to world coordinates using the TransPatternsToWorld function. EXAMPLE
6 = Grid Y	Sort by distance along the fixture's y-axis first, and then by distance along the x-axis, from closest to furthest, in descending order. Note: SortPatterns returns #ERR if Grid Y is selected and the function is referencing an image that has been calibrated to world coordinate values, such as a CalibrateImage or TransPatternsToWorld function's output. Grid Y sorting can only be applied to pixel coordinates. To use the Grid Y sorting method using world coordinates, the FindPatMaxPatterns or FindPatterns function being referenced by the SortPatterns function should reference the output of a TransformImage function, with the SortPatterns function sorting in pixel coordinates. The output data can then be transformed to world coordinates using the TransPatternsToWorld function. EXAMPLE

Fixture

Defines the referenced pattern relative to a Fixture input or the output of a Vision Tool function's image coordinate system. Setting the referenced pattern relative to a Fixture ensures that if the Fixture is rotated or translated, the referenced pattern is rotated or translated in relation to the Fixture. For more information, see Fixture.

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

Row	The row offset, in image coordinates.
Column	The column offset, in image coordinates.
Theta	The angle of orientation, in the image coordinate system.

Sort Tolerance

Specifies the size percentage (1% to 500%; default = 50%) of the trained pattern height a found pattern must be to be included in the group of patterns when sorting by either Grid X or Grid Y.

Note: This parameter is only used when the Sort By parameter is set to either Grid X or Grid Y.

Show

Specifies the display mode for SortPatterns graphics on the image.

0 = hide all (default)	All graphics are hidden, except when the cell containing the SortPatterns function is highlighted in the spreadsheet.
1 = result graphics only	A cross is displayed for each found pattern at all times.
3 = show all: input, result, and match features	The input image region, a cross for each found pattern, and the match features are displayed at all times. Note: Match features are only displayed for PatMax-trained patterns.

SortPatterns Outputs

Returns

A Patterns data structure containing the sorted pattern response points, or #ERR if any of the input parameters are invalid.

Results

When SortPatterns is initially inserted into a cell, a result table is created in the spreadsheet.

Note: If the value of the Number to Sort parameter is greater than zero, SortPatternsautomatically inserts a result table containing a maximum of 10 entries that correspond to the first 10 patterns in the Patterns data structure. If you wish to display more entries, you can expand the table by copying the last row and pasting additional rows at the end. Make sure to increment the index number of any newly-pasted row so that the proper pattern is indexed.

SortPatterns Vision Data Access Functions

The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table. For more information, see Patterns.

Row	GetRow(Patterns, Index)	The row coordinate of the pattern position.
Col	GetCol(Patterns, Index)	The column coordinate of the pattern position.
Angle	GetAngle(Patterns, Index)	The orientation of the pattern position.
Scale	GetScale(Patterns, Index)	The percent size of the original model.
Score	GetScore(Patterns, Index)	The pattern response score.