# SortPlane3D

The SortPlane3D function is used to return a sorted list of planes extracted in the point cloud, by referencing a Planes3D structure (created for example by an ExtractPlane3D function). This function allows you to sort the referenced planes by specific sort keys and sort orders, and returns the list of sorted planes in a new Planes3D structure.

## SortPlane3D Inputs

The SortPlane3D function has the following syntax:

    SortPlane3D(PointCloud,Planes3D,SortKey,SortOrder,Fixture3D,ExternalFixture,ResultGraphic,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.
Planes3D | Specifies a reference to an Planes3D structure in another spreadsheet cell. The contents of this cell will be used as the basis for sorting.
Sort Key | Specifies the sorting logic for the planes in the Planes3D 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 planes, or want to examine them without the need to order them. Score: Sort the planes by their calculated score values. Number of Inliers: Sort the planes by their number of inliers. Residuals RMS: Sort the planes by the root mean square of their residuals. Residuals Max: Sort the planes by their maximum residuals. Inlier Density Over Rectangle: Sort the planes by the density of their inliers over their rectangles. Area of Rectangle: Sort the planes by the area of their finite rectangles. Relative Pitch: Sort the planes by their relative pitches. Center of Rectangle X: Sort the planes by the X-axis distance of their rectangle's center point from the origin of the point cloud space. Center of Rectangle Y: Sort the planes by the Y-axis distance of their rectangle's center point from the origin of the point cloud space. Center of Rectangle Z: Sort the planes by the Z-axis distance of their rectangle's center point from the origin of the point cloud space. Center of Rectangle R: Sort the planes by the radial distance of their rectangle's center point from the origin of the point cloud space. Center of Rectangle Spoke Angle: Sort the planes by their angle from their rectangle's center's X-axis and Y-axis position to their origin. Center of Rectangle Spoke Radius: Sort the planes by the center of their rectangle's distance from their origin to the center of their patch's location on the X-axis and Y-axis (disregarding the Z-axis height).
Sort Order | Specifies whether to sort the planes of the referenced Planes3D structure in ascending or descending order. Note: This parameter is not available if the Sort Key parameter 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 only available if Sort Key is set to Center of Patch X, Center of Patch Y, Center of Patch Z, Center of Patch R, Center of Patch Spoke Angle, or Center of Patch Spoke Radius.
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 only available if Sort Key is set to Center of Patch X, Center of Patch Y, Center of Patch Z, Center of Patch R, Center of Patch Spoke Angle, or Center of Patch Spoke Radius.
Result Graphics | Selects the type of graphics to use for showing the results: 0 = Surface (default) 1 = Plane
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.

## SortPlane3D Outputs

Returns | A Planes3D 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
❒Planes3D | GetNFound(SortPlane3D) | 0 | GetScore(SortPlane3D, 0) | GetRelativeTilt(SortPlane3D, 0) | GetRectangle(SortPlane3D, 0) | GetCenter(Rectangle3D) | GetX(Rectangle3D) | GetY(Rectangle3D) | GetZ(Rectangle3D) | GetAngleX(Rectangle3D) | GetAngleY(Rectangle3D)
|  | 1 | GetScore(SortPlane3D, 1) | GetRelativeTilt(SortPlane3D, 1) | GetRectangle(SortPlane3D, 1) | GetCenter(Rectangle3D) | GetX(Rectangle3D) | GetY(Rectangle3D) | GetZ(Rectangle3D) | GetAngleX(Rectangle3D) | GetAngleY(Rectangle3D)
|  | ... | ... | ... | ... | ... | ... | ... | ... | ... | ...
|  | N-1* | GetScore(SortPlane3D, N-1) | GetRelativeTilt(SortPlane3D, N-1) | GetRectangle(SortPlane3D, N-1) | GetCenter(Rectangle3D) | GetX(Rectangle3D) | GetY(Rectangle3D) | GetZ(Rectangle3D) | GetAngleX(Rectangle3D) | GetAngleY(Rectangle3D)
N = min(10, NumToExtract).

## SortPlane3D Vision Data Access functions

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

Function | Description
GetCenter(Rectangle3D) | Returns the center point of the extracted plane's finite patch (or visually, the center point of the Rectangle3D structure).
GetNFound(SortPlane3D) | Returns the number of found planes.
GetPatch(SortPlane3D, index) | Returns a finite patch of the extracted plane as a Rectangle3D structure.
GetRelativeTilt(SortPlane3D, index) | Returns the relative tilt angle of the extracted plane specified with the index number.
GetScore(SortPlane3D, index) | Returns the score of the extracted plane with the specified index number, as a value between 0 – 100.
GetTilt(Rectangle3D) | Returns the tilt angle of the Rectangle3D structure in degrees on the Z-axis.
GetTiltDirection(Rectangle3D) | Returns the tilt direction angle of the specified Rectangle3D 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(Rectangle3D) | Returns the X-axis coordinate of the specified patch's center point on the Fixture3D X-axis.
GetY(Rectangle3D) | Returns the Y-axis coordinate of the specified patch's center point on the Fixture3D Y-axis.
GetZ(Rectangle3D) | Returns the Z-axis coordinate of the specified patch's center point on the Fixture3D Z-axis.