# ExtractSphere3D

The ExtractSphere3D function is used to extract one or more spheres from a point cloud in a user defined region of interest (ROI). The tool has two modes for sphere extraction:

- Fast mode, using all points to do a least squares fit. This mode extracts a single sphere by fitting the coefficients of a quadratic equation..
- Robust mode, using random sample consensus (RANSAC).

If no sphere is found by the function with the provided configuration, it returns a result with zero length shape, inliers, and residuals. Typically, radius range, math singularity or shape degeneracy can lead to not finding spheres. For example, if all input points are coincident, then the function cannot extract spheres.

The function returns an Spheres3D structure.

## ExtractSphere3D Inputs

The ExtractSphere3D function has the following syntax:

ExtractSphere3D(PointCloud,Fixture3D,ExternalRegion,Region3D,ExternalRegion,Mode,NumberToExtract,DistanceThreshold,AcceptThreshold,ClutterPercentage,RadiusMin,RadiusMax,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.
Mode | Specifies the extraction mode: 0 = Fast mode. In this mode, the function extracts a single sphere using all points (including clutter) within the region of interest. If the scene in the function's ROI contains more than one sphere, a single compromise sphere is extracted. 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 spheres 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 spheres, or you need to work with a point cloud acquisition with outlier points in the region.
Number to Extract | Specifies the number of spheres 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.
Distance Threshold | Specifies the distance from the sphere 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. 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 acceptance score of the results. The value range is 1 to 100, and the default value is 50.
Clutter Percentage | Specifies the estimated percentage of clutter points, that is the points that do not belong to any of the desired spheres. The value range is 1 to 95 and the default value is 5. Note: This setting is only available in Robust mode. Tip: Lower values provide faster performance at the cost of robustness in the presence of clutter.
Radius Min | Specifies the lower bound on the radius of the extracted spheres. The value range is 0 to the value of the Radius Max property, and the default value is 0.
Radius Max | Specifies the upper bound on the radius of the extracted spheres. The value range is from the value of the Radius Min attribute to inf., and the default value is 1000.
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.

## ExtractSphere3D Outputs

Returns | A Spheres3D 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 | Sphere | Center | Radius | X | Y | Z
❒Spheres3D | GetNFound(Spheres3D) | 0 | GetScore(Spheres3D, index) | GetSphere(Spheres3D, 0) | GetCenter(Sphere3D) | GetRadius(Sphere3D) | GetX(Sphere3D) | GetY(Sphere3D) | GetZ(Sphere3D)
|  | 1 | GetScore(Spheres3D, index) | GetSphere(Spheres3D, 1) | GetCenter(Sphere3D) | GetRadius(Sphere3D) | GetX(Sphere3D) | GetY(Sphere3D) | GetZ(Sphere3D)
|  | ... |  | ... | ... | ... | ... | ... | ...
|  | N-1* | GetScore(Spheres3D, index) | GetSphere(Spheres3D, N-1) | GetCenter(Sphere3D) | GetRadius(Sphere3D) | GetX(Sphere3D) | GetY(Sphere3D) | GetZ(Sphere3D)
N = min(10, NumToExtract).

## ExtractSphere3D Vision Data Access functions

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

Function | Description
GetCenter(Sphere3D) | Returns the center point of the specified Sphere3D structure as a Point3D structure.
GetNFound(Spheres3D) | Returns the number of found spheres.
GetRadius(Sphere3D) | Returns the radius of the specified Sphere3D structure as an integer.
GetScore(Spheres3D, index) | Returns the score of the extracted Sphere3D structure specified with the index number. The value is a number between 0 – 100.
GetSphere(Spheres3D, index) | Returns the extracted Sphere3D structure with the specified index number.
GetX(Sphere3D) | Returns the X-axis coordinate of the specified Sphere3D structure's center point on the Fixture3D X-axis.
GetY(Sphere3D) | Returns the Y-axis coordinate of the specified Sphere3D structure's center point on the Fixture3D Y-axis.
GetZ(Sphere3D) | Returns the Z-axis coordinate of the specified Sphere3D structure's center point on the Fixture3D Z-axis.
GetNumInliers(Sphere3D, index) | Returns the number of inliers in the specified Sphere3D structure. Note: You can only use the GetNumInliers() function when you use the Robust mode, otherwise the function shows an error.