# ExtractCircle3D

The ExtractCircle3D function extracts one ore more circles from the point cloud. It returns the extracted circles as a Circles3D structure, which can be referenced with Circle3D Vision Data Access functions.

To use the ExtractCircle3D function:

1. Insert the ExtractCircle3D function to the Spreadsheet:

   - Drag and drop the function from the In-Sight Toolbox.

   - Select a cell and use the Insert Function dialog.

   - Select a cell and type the name of the function, followed by the "(" character.

The Property Sheet pops up.

1. Make sure that the PointCloud parameter refers to a cell that contains a point cloud. Adjust the default $A$0 value if needed.

2. Double-click the Region3D parameter to open the interactive display, and adjust the ROI shape projected onto the acquisition display. Alternatively, you can expand the Region3D settings and define the parameters manually.

3. Click OK to finalize the settings.

Inputs

The ExtractCircle3D function has the following syntax:

ExtractCircle3D(PointCloud,Fixture3D,ExternalFixture,Region3D,ExternalRegion,AcceptThreshold,NumberToExtract,DistanceThreshold,MinimumSharpness,MaximumSharpness,MaxAcceptableTilt,TransitionTypes,SortKey,SortOrder,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 Region3D 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 Region3D structure of the function as the ROI.
Accept Threshold | Specifies the minimum score a result has to reach for the function to consider it a found circle. The value range is 0.000 to 100.000. The default setting is 50.000.
Number to Extract | Specifies the maximum number of circles the function extracts. The value range is 1 to inf. The default setting is 1.
Distance Threshold | Specifies the maximum distance in real-world units between an edgelet and a candidate circle for the edgelet to be considered an inlier of the candidate circle.
Minimum Sharpness | Specifies the minimum acceptable sharpness of the circle, that is, the angular measurement between the support surfaces measured along the extraction direction. The value range is 0 to 30 degrees.
Maximum Sharpness | Specifies the maximum acceptable sharpness of the circle, that is, the angular measurement between the support surfaces measured along the extraction direction. The value range is 0 to 150 degrees.
Max Acceptable Tilt | Specifies the maximum angular deviation of the normal of the circle from the expected direction. The value range is 0 to 90 degrees, and the default value is 90.
Transition Types | Specifies whether to extract convex circles (0), concave circles (1), or both (2). By default, the function extracts both circle types.
Sort Key | Specifies the logic by which the extracted circles are sorted. The available values are the following: None: No sorting logic will be applied to the list of circles. Use this setting if you simply want a count of the circles, or want to examine them without the need to order them. Score: Sort the circles by their calculated score values. This is the default setting. Sharpness: Sort the circles by their sharpness. Radius: Sort the circles by their radius. Offset From Axis: Sort the circles by the amount they are offset from the axis.
Sort Order | Specifies whether to sort the results in ascending or descending order. Note: This parameter is disabled if Sort Key is set to None.
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 Circles3D structure containing the circles 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 | Coverage | Axis | Circle | Radius | Center
❒Circles3D | GetNFound(Circles3D) | 0 | GetScore(Circles3D, 0) | GetCoverage(Circles3D, 0) | GetAxis(Circles3D, 0) | GetCircle(Circles3D, 0) | GetRadius(Circles3D) | GetCenter(Circles3D)
| GetNFound(Circles3D) | 1 | GetScore(Circles3D, 1) | GetCoverage(Circles3D, 1) | GetAxis(Circles3D, 1) | GetCircle(Circles3D, 1) | GetRadius(Circles3D) | GetCenter(Circles3D)
| ... | ... | ... | ... | ... | ... | ... | ...
| GetNFound(Circles3D) | N-1* | GetScore(Circles3D, N-1) | GetCoverage(Circles3D, N-1) | GetAxis(Circles3D, N-1) | GetCircle(Circles3D, N-1) | GetRadius(Circles3D) | GetCenter(Circles3D)
*N = min(1, Number To Extract))

Vision Data Access functions

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

Function | Description
GetAxis(Circles3D, index) | Returns the axis of the extracted circle as a Line3D structure.
GetCenter(Circles3D) | Returns the center point of the circle as a Point3D structure.
GetCircle(Circles3D, index) | Returns the extracted Circle3D structure specified with the index.
GetRadius(Circles3D) | Returns the radius of the created 3D circle as an integer.
GetScore(Circles3D, index) | Returns the score of the circle specified with the index as a value between 0 and 100.
GetCoverage(Circles3D, index) | Returns the coverage of the circle specified with the index. Coverage is the percentage of the region perimeter that is covered by the circle.