# ExtractClearSpot3D

The ExtractClearSpot3D function allows you to extract one or more feature-free areas of a specified size, or clear spots, from the Region of Interest. This function is useful for cases such as finding an appropriate spot on a part for a label of a certain size, or calculating the maximum number of labels that can fit in a specific area.

To use the ExtractClearSpot3D function:

1. Drag and drop the ExtractClearSpot3D function into the Spreadsheet.

2. In the Property Sheet that pops up, set up the Region of Interest using one of the following methods:

   - Double-click the Box3D parameter and adjust the ROI box in the acquisition display.

   - Expand the Box3D parameter and define the box parameters manually.

   - Double-click the External Box parameter and select a Box3D function cell in Spreadsheet.

3. Optionally, double-click the Exclude Region parameter and select a Region3D function cell in Spreadsheet to define an area that is excluded from the search region.

4. Adjust the Spot parameters to define the size and position of the clear spots that you want the function to find.

5. Adjust the Margin parameters to define the margins that you want the function to keep between the spots.

6. Define the Results to Find paremeter to specify the number of clear spots you want the function to find.

7. Adjust the Search Mode and Operation Mode parameters to fine-tune your results.

Inputs

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.
Box3D | Specifies the dimensions, offset and angle for the 3D rectangle of the function. It is offset from the PointCloud origin in the following format with the following arguments: {SizeX, SizeY, X, Y, Z, Rotation, Tilt, TiltDirection}
SizeX | The size of the box along the X-axis of the PointCloud. The value range is 0.001 to inf., and the default value is 100.
SizeY | The size of the box along the Y-axis of the PointCloud. The value range is 0.001 to inf., and the default value is 100.
SizeZ | The size of the box along the Z-axis of the PointCloud. The value range is 0.001 to inf., and the default value is 100.
X | Offset on the X-axis from the PointCloud origin. The value range is -inf. to inf., and the default value is 0.
Y | Offset on the Y-axis from the PointCloud origin. The value range is -inf. to inf., and the default value is 0.
Z | Offset on the Z-axis from the PointCloud origin. The value range is -inf. to inf., and the default value is 0.
Rotation | Specifies the in-plane rotation of the box (in degrees) about the PointCloud Z-axis of the tool. The value range is -360 to 360. External references with values outside the allowed range will be normalized to the allowed range.
Tilt | Specifies the tilt angle of the box (in degrees) from the PointCloud Z-axis of the tool. The value range is 0 - 180. External references with values outside the allowed range will result in an error.
Tilt Direction | Specifies the tilt direction of the box (in degrees) from the rotated PointCloud X-axis of the tool, about the PointCloud Z-axis of the tool. The value range is -360 to 360. External references with values outside the allowed range will be normalized to the allowed range.
Note: This parameter is available only if External Box is set to 0.
External Box3D | 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.
Exclude Region | Specifies a reference to a Region3D structure defined in another cell. The function excludes the referenced Region3D structure from the Region of Interest for the function.
Spot | Specifies the size and position of the clear spots. The following Spot parameters are available:
SizeX | The size of the spot along the X-axis of the spot plane. The value range is 0.001 to inf., and the default value is 100.
SizeY | The size of the spot along the Y-axis of the spot plane. The value range is 0.001 to inf., and the default value is 100.
Minimum Point Coverage | The minimum spot point coverage on the point cloud in percent (0 to 100).
Maximum Overlap Ratio | The maximum allowable overlap ratio between two neighboring spots in percent (0 to 100).
Allow 90 Degree Rotation | If enabled, the function can register clear spots that are rotated by 90 degrees on the XY plane.
Maximum Spot Plane RMS | The maximum allowable root mean square deviation of the clear spots on the observed plane.
Maximum Spot Plane Tilt | The maximum allowable plane tilt for the spot planes.
Margin | Specifies the margin between neighboring spots. The following Margin parameters are available:
SizeX | The size of the margin along the X-axis of the spot plane. The value range is 0.001 to inf., and the default value is 5.
SizeY | The size of the margin along the Y-axis of the spot plane. The value range is 0.001 to inf., and the default value is 5.
Allow Margin Outside Workspace | If enabled, the function can find spots using margins that are outside the defined Region of Interest.
Minimum Point Coverage | The minimum spot point coverage on the point cloud in percent (0 to 100).
Height Tolerance | Specifies the height tolerance for points outside the spot plane when calculating margins.
Minimum Area in Tolerance | Specifies the minimum spot margin area that must meet the height tolerance in percent (0 to 100).
Search Mode | Specifies the search mode. The following Search Mode parameters are available:
Search Mode | Highest (default): prioritize results with higher Z value relative to the bottom plane of the RoI. Closest to Preferred Location: prioritize results that are closest to the preferred location defined with the Preferred Location X and Preferred Location Y parameters. Highest and Closest to Preferred Location: prioritize results with a higher Z value relative to the bottom plane of the RoI, and closest to the preferred location defined with the Preferred Location X and Preferred Location Y parameters. Unspecified: results without specific criteria.
Height Tolerance | Specifies the height tolerance for high spots compared to the highest spot. Note: This parameter is only available when the Search Mode parameter is set to Highest and Closest to Preferred Location.
Preferred Location X | Specifies the relative X coordinate of the preferred location in the top plane of the RoI. Results with a center closest to this location are returned first when using the Closest to Preferred Location or Highest and Closest to Preferred Location search mode.
Preferred Location Y | Specifies the relative Y coordinate of the preferred location in the top plane of the RoI. Results with a center closest to this location are returned first when using the Closest to Preferred Location or Highest and Closest to Preferred Location search mode.
Results to Find | Specifies the number of results to find.
Operation Mode | Specifies the Operation Mode: Speed: this mode is recommended for cases where runtime is a critical consideration. Balanced (default): this mode is recommended for most cases. Accuracy: this mode is recommended for cases where the RoI does not represent a planar surface, and the Balanced mode is not returning acceptable results.
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 ClearSpots3D data structure, or #ERR if any of the input parameters are invalid.
Results |
Output | Description
--- | ---
Num Found | The number of found spots.
Index | The index of each found spot.
Rectangle | A Rectangle3D structure around each found spot.

Vision Data Access functions

For a list of available Vision Data Access functions, see ClearSpots3D Vision Data Access functions.