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.

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.

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.