# ExtractCylinder3D

The ExtractCylinder3D function is used to extract multiple Cylinder3D structures from the point cloud. It returns the extracted 3D cylinders in a Cylinders3D structure.

Inputs

The ExtractCylinder3D function has the following syntax:

ExtractCylinder3D(PointCloud,Fixture3D,ExternalFixture,Region3D,ExternalRegion,NumberToExtract,DistanceThreshold,AcceptThreshold,ClutterPercentage,RadiusMin,RadiusMax,MaxAcceptableTilt,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 -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.
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 a 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.
Number to Extract | Specifies the maximum number of cylinders to extract. The value range is 1 to inf., and the default value is 1.
Distance Threshold | Specifies the distance (in real-world units) from the cylinder beyond which points are considered clutter. 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 In-Sight L38 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.
Accept Threshold | Specifies the minimum percentage score a result must have to be considered found by the function. The vale range is 0 – 100, and the default value is 50.
Clutter Percentage | Specifies the estimated percentage of clutter points, that is the points on edges that do not belong to any of the desired cylinders. The value range is 1 – 97, and the default value is 5). Tip: Lower values provide better performance, at the cost of robustness in the presence of clutter.
Radius Min | Specifies the lower bound on the value of the radius of the extracted cylinders. The value range is 0 to the value of the Maximum Radius attribute. The default value is 0.
Radius Max | Specifies the upper bound on the value of the radius of the extracted cylinders. The value range is from the value of the Minimum Radius attribute to inf., and the default value is 10000.
Max. Acceptable Tilt | Specifies the maximum angular deviation of the normal of the cylinder from the expected direction (in degrees). The value range is 0 to 90, and the default value is 90.
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.

Outputs

Returns | A Cylinders3D data structure containing the 3D cylinders 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 | Cylinder | Axis | Center | Radius | Length | X | Y | Z | Tilt | Tilt Direction
❒Cylinders3D | GetNFound(Cylinders3D) | 0 | GetScore(Cylinders3D, 0) | GetCylinder(Cylinders3D, 0) | GetAxis(Cylinder3D) | GetCenter(Cylinder3D) | GetRadius(Cylinder3D) | GetLength(Cylinder3D) | GetX(Cylinder3D) | GetY(Cylinder3D) | GetY(Cylinder3D) | GetAngleX(Cylinder3D) | GetAngleY(Cylinder3D)
|  | 1 | GetScore(Cylinders3D, 1) | GetCylinder(Cylinders3D, 1) | GetAxis(Cylinder3D) | GetCenter(Cylinder3D) | GetRadius(Cylinder3D) | GetLength(Cylinder3D) | GetX(Cylinder3D) | GetY(Cylinder3D) | GetY(Cylinder3D) | GetAngleX(Cylinder3D) | GetAngleY(Cylinder3D)
|  | ... | ... | ... |  | ... | ... |  | ... | ... | ... | ... | ...
|  | N-1* | GetScore(Cylinders3D, N-1) | GetCylinder(Cylinders3D, N-1) | GetAxis(Cylinder3D) | GetCenter(Cylinder3D) | GetRadius(Cylinder3D) | GetLength(Cylinder3D) | GetX(Cylinder3D) | GetY(Cylinder3D) | GetY(Cylinder3D) | GetAngleX(Cylinder3D) | GetAngleY(Cylinder3D)
*N = min(10, NumToExtract)

Vision Data Access functions

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

Function | Description
GetCylinder(Cylinders3D, index) | Returns the extracted Cylinder3D structure.
GetNFound(Cylinders3D) | Returns the number of found 3D cylinders.
GetNumInliers(Cylinders3D, index) | Returns the number of inliers in the specified Cylinder3D structure.
GetResidualsMax(Cylinders3D, index) | Returns the maximum residual in the specified Cylinder3D structure.
GetResidualsRMS(Cylinders3D, index) | Returns the root mean square residual of the specified Cylinder3D structure.
GetScore(Cylinders3D, index) | Returns the score of the extracted Cylinder3D structure between 0 – 100.