# SortPatterns

Sorts patterns by their position in the image. For each pattern in the input Patterns data structure, SortPatterns computes the position of the response of the pattern relative to the specified image fixture coordinate system. Patterns are sorted by one of the following: X coordinate, Y coordinate, angle, angle distance, distance, or grid. The sorted patterns are returned as a new Patterns data structure.

Inputs

Parameter | Description
Patterns | This argument must reference a spreadsheet cell that contains a valid Patterns data structure returned by the function.
Number to Sort | Specifies the maximum number (1 to 255; default = 1) of patterns to sort.
Sort By | Specifies the sorting method.
0 = Y (default) | Sort by distance along the fixture Y coordinate, from small to large.
1 = X | Sort by distance along the fixture X coordinate, from small to large.
2 = Angle | Sorts by the angle (0 to 360 degrees), as measured counter-clockwise from the Y 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.
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.
4 = Distance | Sorts by the distance from the fixture origin to the response point of the pattern, from closest to furthest, in descending order.
5 = Grid Y | Sort by distance along the Y coordinate of the fixture first, and then by distance along the X coordinate, 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 the output of a CalibrateImage or TransPatternsToWorld function. Grid Y sorting can only be applied to pixel coordinates.
6 = Grid X | Sort by distance along the X coordinate of the fixture first, and then by distance along the Y coordinate, 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 the output of a CalibrateImage or TransPatternsToWorld function. Grid Y sorting can only be applied to pixel coordinates.
Fixture | Defines the referenced pattern relative to a Fixture input or the output of the image coordinate system of a Vision Tools function. 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. The default setting is (0,0,0), the top leftmost corner of the image.
X | The X-offset, in image coordinates.
Y | The Y-offset, in image coordinates.
Theta | The rotation from the image X-axis, in the image coordinate system. (+/-360 degrees clockwise)
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.

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 using the following Patterns Vision Data Access functions:
Label | Function | Description
X | GetX(Patterns, Index) | The X coordinate of the pattern position.
Y | GetY(Patterns, Index) | The Y 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.
Note: If the value of the Number to Sort parameter is greater than zero, SortPatterns automatically 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.