# SortPatMax3D

The SortPatMax3D function is used to return a sorted list of 3D patterns found by a configured FindPatMax3D function. This function allows you to sort the patterns by specific sort keys and sort orders, and returns the list of sorted patterns in a new Patterns3D structure.

## SortPatMax3D Inputs

The SortPatMax3D function has the following syntax:

    SortPlane3D(PointCloud,Patterns3D,SortKey,SortOrder,SortTolerance,Fixture3D,ExternalFixture,AppendSort,Show)

See the table for a description of the available parameters.

Parameter | Description
PointCloud | Reference to a cell containing a point cloud. The default value is $A$0.
Patterns3D | Specifies a reference to a Patterns3D structure in another spreadsheet cell (created typically by a FindPatMax3D function). The contents of this cell will be used as the basis for sorting.
Sort Key | Specifies the sorting logic for the patterns in the Patterns3D structure. The available values are the following: None: No sorting logic will be applied. Use this setting if you simply want to count the sorted patterns, or want to examine them without the need to order them. Score: Sort the patterns by their calculated score values. Pose Rotation In-Plane Rotation Angle Norm: Sort by the pose rotation's norm in-plane rotation. Pose Rotation In-Plane Rotation Angle Abs: Sort by the pose rotation's absolute in-plane rotation. Pose Rotation Tilt Direction Norm: Sort by the pose rotation's norm tilt direction. Pose Rotation Tilt Direction Abs: Sort by the pose rotation's absolute tilt direction. Pose Rotation Tilt Angle: Sort by the pose rotation's tilt angle. Pose Translation X: Sort by the pose translation's X-component. Pose Translation Y: Sort by the pose translation's Y-component. Pose Translation Z: Sort by the pose translation's Z-component. Pose Translation R: Sort by the pose translation's Euclidean distance. Pose Translation Spoke Angle Norm: Sort by the pose translation's norm spoke angle. Pose Translation Spoke Angle Abs: Sort by the pose translation's absolute spoke angle. Pose Translation Spoke Radius: Sort by the pose translation's spoke radius. Pose Translation X then Y then Z: Sort by the pose translation's Grid X then Y, and then Z. Pose Translation Y then X then Z: Sort by the pose translation's Grid X then Y, and then Z.
Sort Order | Specifies whether to sort the patterns of the referenced Patterns3D structure in ascending or descending order. Note: This parameter is not available if Sort Key is set to None.
Sort Tolerance | Specifies a threshold to determine if 2 or more results are tied. If they are tied, they can be sorted by a subsequent sort. Only takes effect when multiple sorting rules are applied (e.g. grid sorting or appending a sort tool). Note: This parameter is disabled if Sort Key is set to None.
Fixture3D | Specifies the point cloud coordinate system in which the 3D fixture is defined. It is offset from the PointCloud origin in the following format with the following arguments: {X, Y, Z, Rotation, Tilt, TiltDirection}
X | Offset on the X-axis from the PointCloud origin.
Y | Offset on the Y-axis from the PointCloud origin.
Z | Offset on the Z-axis from the PointCloud origin.
Rotation | Specifies the in-plane rotation in degrees around the PointCloud Z-axis. The value range is -180 to 180. The tool normalizes external references with values outside the allowed range to the allowed range.
Tilt | Specifies the tilt angle in degrees from the PointCloud Z-axis after rotation. The value range is 0-180. External references with values outside the allowed range result in an error.
Tilt Direction | Specifies the direction of tilt in degrees from the rotated PointCloud X-axis of the tool, around the PointCloud Z-axis of the tool. The value range is -180 to 180. The tool normalizes external references with values outside the allowed range to the allowed range.
Note: The Fixture3D parameter is only available if you set External Fixture to 0. Note: This parameter is not available if Sort Key is set to None or Score.
External Fixture | Specifies a reference to a Fixture3D structure defined in another cell. The function uses the referenced cell as the fixture of the function. Set to 0 (OFF) to use the internal fixture of the function instead. Note: This parameter is not available if Sort Key is set to None or Score.
Append Sort | When enabled, the selected the sorting rule will be added to the rules inherited from the reference vision or sorting tool. Otherwise, it will override the inherited rules. This setting is enabled by default.
Show | Selects the type of graphics to overlay on the image.
0 = hide all (default) | All graphics are hidden, except when the cell containing the function is highlighted in the spreadsheet.
1 = result graphics only | The result graphics of the function are displayed at all times.
2 = input and result graphics | The region of interest, the input data and the results are displayed at all times.

## SortPatMax3D Outputs

Returns | A Patterns3D data structure containing the sorted planes, or #ERR if any of the input parameters are invalid.
Results | When initially inserted into a cell, the following functions are automatically inserted into the spreadsheet to create a result table.
| Num Found | Index | Score | Relative Tilt | Patch | Center | X | Y | Z | Tilt | Tilt Direction
❒Patterns3D | GetNFound(Patterns3D) | 0 | GetScore(Patterns3D, 0) | GetRelativeTilt(Patterns3D, 0) | GetPatch(Patterns3D, 0) | GetCenter(Patterns3D) | GetX(Patterns3D) | GetY(Plane3D) | GetZ(Plane3D) | GetAngleX(Plane3D) | GetAngleY(Plane3D)
|  | 1 | GetScore(Patterns3D, 1) | GetRelativeTilt(Patterns3D, 1) | GetPatch(Patterns3D, 1) | GetCenter(Patterns3D) | GetX(Patterns3D) | GetY(Plane3D) | GetZ(Plane3D) | GetAngleX(Plane3D) | GetAngleY(Plane3D)
|  | ... | ... | ... | ... | ... | ... | ... | ... | ... | ...
|  | N-1* | GetScore(Patterns3D, N-1) | GetRelativeTilt(Patterns3D, N-1) | GetPatch(Patterns3D, N-1) | GetCenter(Patterns3D) | GetX(Patterns3D) | GetY(Plane3D) | GetZ(Plane3D) | GetAngleX(Plane3D) | GetAngleY(Plane3D)
N = min(10, NumToExtract).

## SortPatMax3D Vision Data Access functions

The following FindPatMax3D Vision Data Access functions are automatically inserted into the spreadsheet to create the result table:

Function | Description
GetFixture(Patterns3D, index) | Returns the Fixture3D structure of the found pattern's fixture.
GetNFound(Patterns3D, index) | Returns the number of found patterns.
GetRotation(Fixture3D) | Returns the rotation of the Z-axis in degrees, also known as the in-plane rotation.
GetScore(Patterns3D, index) | Returns the score of the found pattern specified with the index, as a value between 0 – 100.
GetTilt(Fixture3D) | Returns the tilt angle of the Fixture3D structure in degrees on the Z-axis.
GetTiltDirection(Fixture3D) | Returns the tilt direction angle of the specified Fixture3D structure in degrees. The angle is measured in the X-Y plane of the original reference coordinate system, and specifies the direction for the projection of the tilted Z-axis onto that plane.
GetX(Fixture3D, index) | Returns the X-axis coordinate of the pattern fixture's center point.
GetY(Fixture3D, index) | Returns the Y-axis coordinate of the pattern fixture's center point.
GetZ(Fixture3D, index) | Returns the Z-axis coordinate of the pattern fixture's center point.