# ExtractPlane3D

The ExtractPlane3D function is used to extract one or more planes from a point cloud in a user defined region of interest (ROI). The orientation of the extracted planes is determined by the ROI. The tool has two modes for plane extraction:

- Fast mode, using all points to do a least squares fit. This mode extracts a single plane by Orthogonal Distance Regression.
- Robust mode, using random sample consensus (RANSAC).

The extracted planes are returned in an Planes3D structure.

## ExtractPlane3D Inputs

The ExtractHeight3D function has the following syntax:

ExtractPlane3D(PointCloud,Fixture3D,ExternalFixture,Region3D,ExternalRegion,Mode,NumberToExtract,DistanceThreshold,ClutterPercentage,MaxAcceptableTilt,SortKey,SortOrder,SortReference,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.
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 -360 to 360. 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 -360 to 360. The tool normalizes external references with values outside the allowed range to the allowed range.
Note: This parameter is only available if you set External Fixture to 0.
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.
Region3D | Specifies the dimensions, offset and angle for 3D region of interest (ROI) of the function. It is offset from the Fixture3D origin in the following format with the following arguments: {SizeX, SizeY, SizeZ, X, Y, Z, Rotation, Tilt, TiltDirection}
SizeX | The size of the ROI along the Fixture3D X-axis.
SizeY | The size of the ROI along the Fixture3D Y-axis.
SizeZ | The size of the ROI along the Fixture3D Z-axis.
X | Offset on the X-axis from the Fixture3D origin.
Y | Offset on the Y-axis from the Fixture3D origin.
Z | Offset on the Z-axis from the Fixture3D origin.
Rotation | Specifies the in-plane rotation in degrees around the Fixture3D Z-axis of the tool. The value range is -360 to 360. The tool normalizes external references with values outside the allowed range to the allowed range.
Tilt | Specifies the tilt angle in degrees from the Fixture3D Z-axis of the tool 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 Fixture3D X-axis of the tool, around the Fixture3D Z-axis of the tool . The value range is -360 to 360. The tool normalizes external references with values outside the allowed range to the allowed range.
Note: This setting is only available if you set External Region to 0.
External Region | Specifies a reference to 3D region defined in another cell. The function uses the referenced cell as the Region of Interest of the function. Set to 0 (OFF) to use the internal Box3D structure of the function as the ROI.
Mode | Specifies the extraction mode: 0 = Fast mode. In this mode, the function extracts a single plane using all points (including clutter) within the region of interest. If the scene in the function's ROI contains more than one plane, a single compromise plane is fit to the points of the point cloud. This is the function's fastest mode of operation, but it is vulnerable to the presence of outliers in the region. 1 = Robust mode. In this mode, the function can extract multiple planes even in the midst of clutter, and can reject noise and clutter by configuring the Distance Threshold and Clutter Percentage parameters. The Distance Threshold parameter is used to define clutter points, while Clutter Percentage is used to define the amount of clutter within the region of interest. This is the default setting, and is recommended to use if you either want to extract multiple planes, or you need to work with a point cloud acquisition with outlier points in the region.
Number to Extract | Specifies the number of planes to extract. The value range is 1 to inf., and the default value is 1. Note: This setting is restricted to 1 when Fast mode is set, and the function is not in an erroneous state.
Distance Threshold | Specifies the distance from the plane beyond which the points are considered clutter. The value range is 0 to inf., and the default value is 1. Note: This setting is only available in Robust mode, and when the function is not in an erroneous state. Tip: Set the value of this parameter according to how noisy the point cloud is, and consider the order of the amplitude of the random fluctuations in the coordinate values. Depending on the type of vision system, the following value ranges are recommended by default: For In-Sight 3D-L4000 series vision systems, a value of 0.1 – 0.5 mm must suffice. If the point cloud's region of interest contains outlier points, such as spikes, then set this parameter lower than the typical height of the spikes.
Clutter Percentage | Specifies the estimated percentage of clutter points, that is the points that do not belong to any of the desired planes. The value range is 1 to 95 and the default value is 5. Note: This setting is only available in Robust mode, and when the function is not in an erroneous state. Tip: Lower values provide faster performance at the cost of robustness in the presence of clutter.
Max. Acceptable Tilt | Specifies the maximum angular deviation of the normal of the plane from the expected direction. The value range is 0 to 90 and the default value is 90.
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.
Sort Reference | Specifies the origin of the coordinate space in which the positional and rotational values are defined. The available values are the following: Camera: The coordinate space is based off the system in which the point cloud's points are defined. Region: The coordinate space is based off the coordinate system of the working region used in the job. Note: This parameter is enabled only if External Region is set to 0, and Sort Key is set to any of the Center of Rectangle values.
Result Graphic | 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.

## ExtractPlane3D Outputs

Returns | A Planes3D data structure extracted from the point cloud, 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 | Rectangle | Center | X | Y | Z | Tilt | Tilt Direction
❒Planes3D | GetNFound(Planes3D) | 0 | GetScore(Planes3D, 0) | GetRelativeTilt(Planes3D, 0) | GetRectangle(Planes3D, 0) | GetCenter(Rectangle3D) | GetX(Rectangle3D) | GetY(Plane3D) | GetZ(Plane3D) | GetTilt (Plane3D) | GetTiltDirection (Plane3D)
|  | 1 | GetScore(Planes3D, 1) | GetRelativeTilt(Planes3D, 1) | GetRectangle(Planes3D, 1) | GetCenter(Rectangle3D) | GetX(Rectangle3D) | GetY(Plane3D) | GetZ(Plane3D) | GetTilt (Plane3D) | GetTiltDirection (Plane3D)
|  | ... | ... | ... | ... | ... | ... | ... | ... | ... | ...
|  | N-1* | GetScore(Planes3D, N-1) | GetRelativeTilt(Planes3D, N-1) | GetRectangle(Planes3D, N-1) | GetCenter(Rectangle3D) | GetX(Rectangle3D) | GetY(Plane3D) | GetZ(Plane3D) | GetTilt (Plane3D) | GetTiltDirection (Plane3D)
N = min(10, NumToExtract).

## ExtractPlane3D Vision Data Access Functions

The following Planes3D 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(Planes3D) | Returns the number of found planes.
GetPatch(ExtractPlane3D, index) | Returns a finite patch of the extracted plane as a Rectangle3D structure.
GetRelativeTilt(Planes3D, index) | Returns the relative tilt angle of the extracted plane specified with the index number.
GetScore(Planes3D, index) | Returns the score of the extracted plane with the specified index number, as a value between 0 – 100.
GetTilt(Cylinder3D) | Returns the tilt angle of the Cylinder3D structure in degrees on the Z-axis.
GetTiltDirection(Cylinder3D) | Returns the tilt direction angle of the specified Cylinder3D 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.
GetNumInliers(Plane3D, index) | Returns the number of inliers in the specified Plane3D structure. Note: You can only use the GetNumInliers() function when you use the Robust mode, otherwise the function shows an error.