ExtractBlobFromCylinder3D

The ExtractBlobFromCylinder3D function is used to extract 3D blobs relative to a reference Cylinder3D structure. The function returns the extracted blob(s) in a Blobs3D structure on the Spreadsheet.

ExtractBlobFromCylinder3D Inputs

The ExtractBlobFromCylinder3D function has the following syntax:

ExtractBlobFromCylinder3D(PointCloud,Fixture3D,ExternalFixture,Region3D,ExternalRegion,Cylinder3D,ExternalCylinder,AutoConnectivityDist,ConnectivityDist,AutoNoiseThreshold,NoiseThreshold,KernelSize,NumberToExtract,MinimumVolume,MaximumVolume,MinimumHeight,MaximumHeight,BlobTypes,SortKey,SortOrder,SortTolerance,SortReference,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) about the PointCloud Z-axis. 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 (in degrees) from the PointCloud Z-axis after rotation. The value range is 0-180. External references with values outside the allowed range will result in an error.
Tilt Direction Specifies the direction of tilt (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 Fixture is set to 0.
External Fixture

Specifies a reference to a Fixture3D structure defined in another cell to be used as the function's fixture. Set to 0 (OFF) to use the function's internal fixture instead.

Region3D

Specifies the dimensions, offset and angle of the function's 3D region of interest (ROI). 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 ROI's size along the Fixture3D X-axis.
SizeY The ROI's size along the Fixture3D Y-axis.
SizeZ The ROI's size 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) about the tool's Fixture3D Z-axis. 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 (in degrees) from the tool's Fixture3D Z-axis after rotation. The value range is 0-180. External references with values outside the allowed range will result in an error.
Tilt Direction Specifies the direction of tilt (in degrees) from the tool's rotated Fixture3D X-axis, about the tool's Fixture3D Z-axis. The value range is -360 to 360. External references with values outside the allowed range will be normalized to the allowed range.
Note: This setting is available only if External Region is set to 0.
Note: This parameter is available only if External Region is set to 0.

External Region

Specifies a reference to 3D region defined in another cell to be used as the function's Region of Interest (ROI). Set to 0 (OFF) to use the function's internal Box3D structure as the ROI.
Cylinder3D

Specifies the dimensions, offset and angle of the function's 3D cylinder. It is offset from the PointCloud origin in the following format with the following arguments:

{Radius, Length, X, Y, Z, Tilt, TiltDirection}

Radius The radius of the cylinder.
Length The length (or "height") of the cylinder..
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.
Tilt Specifies the cylinder's tilt angle (in degrees) from the tool's PointCloud Z-axis. The value range is 0 - 180. External references with values outside the allowed range will result in an error.
Tilt Direction Specifies the cylinder's direction of tilt (in degrees) from the tool's rotated PointCloud X-axis, about the tool's Fixture3D Z-axis. 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 enabled only if External Cylinder is set to 0.
Note: This parameter is available only if External Cylinder is set to 0.
External Cylinder

Specifies a reference to a Cylinder3D structure defined in another cell to be used by the function. Set to 0 (OFF) to use the function's internal Cylinder3D structure instead.
Auto Connectivity Dist

When checked, the function automatically tries to estimate the smallest distance that two points can be apart, but still be considered to belong to the same blob result. This is achieved by using the known point cloud and sensor sampling distance. This parameter is enabled by default.

Note: If the computed distance turns out to be smaller than the distance required for your specific inspection, regions in multiple blobs may become broken. In such cases, disable this setting and increase the connectivity distance manually with the Connectivity Distance parameter.

Disable this setting to configure the connectivity distance manually.
Connectivity Distance

Specifies the maximum distance (in real-world units) between two points at which they are still considered to be part of the same blob. The value range is between 0.010 – inf., and default value is 1.0.

Tip: Higher values connect points further apart. For example, if you see a region split in two blobs when you expected just one, increase the value of this attribute so that points further away are connected into same blob.
Note: This parameter is enabled only if Auto Connectivity Dist is disabled.
Auto Noise Threshold

When checked, the function automatically sets the noise threshold of the blobs to be detected, based on the detected point cloud sampling distance. This parameter is enabled by default.

Note: If the configured noise threshold turns out to be incorrect for your inspection, uncheck this attribute and configure the noise threshold manually with the following attribute.
Noise Threshold

Specifies the noise threshold of the blobs to be detected (in real-world units). This parameter creates a margin above and below the reference shape, and all points within this region are considered overlapping the reference shape. These points will not be part of any Positive or Negative blob types: only Unchanged blobs will contain them. Configuring this parameter properly helps you to deal with noisy points near the reference shape without affecting blob height and volume measurements.

Tip: For most scenarios, Cognex recommends to set the Noise Threshold to the same value (or double that) of the Separation Distance Z-value. Larger values may also work for your inspection depending on the circumstances, as long as they do not exceed the minimum expected blob height.

The value range is from 0 to inf., and the default value is 0.

Note: This parameter is enabled only if Auto Noise Threshold is disabled.
Kernel Size

Specifies the approximate size of the smallest tolerable deformations from the reference shape. The value range is 0 to inf., and the default value is 1.
Number to Extract Specifies the maximum number of blobs to extract. The value range is 1 to 65535, and the default value is 1.
Minimum Volume

Specifies the minimum volume (in real-world units) that the blobs must have to be detected and included, allowing you to skip very small blobs that are probably caused by noise. The value range is from 0 to the configured value of the Maximum Volume property. The default value is 20).

Tip: Cognex recommends setting this property as tight as possible to remove all unwanted blobs from the inspection.
Maximum Volume Specifies the maximum volume (in real-world units) that the blobs can have to be detected and included, allowing you to keep large blobs that must be part of the inspection. The value range is from the configured value of the Minimum Volume property to inf. The default value is 100,000,000).
Minimum Height

Specifies the minimum height (in real-world units) that the blobs must have to be detected and included, allowing you to skip very small blobs that are probably caused by noise. The value range is from 0 to the configured value of the Maximum Height property. The default value is 1).
Maximum Height Specifies the maximum height (in real-world units) that the blobs can have to be detected and included. The value range is from the configured value of the Minimum Height property to inf. The default value is 10000).
Blob Types

Specifies the blob types to detect or ignore by checking or unchecking their respective properties. The available types are the following:

  • Positive: Specifies a positive volume with respect to the reference shape (that is a blob above the reference shape). This is the default setting.
  • Negative: Specifies a negative volume with respect to the reference shape (that is a blob below the reference shape).
  • Unchanged: Specifies an unchanged volume with respect to the reference (that is, a blob that overlaps the reference shape, and as such, indicates no change).
Sort Key

Specifies the logic by which the blobs of the referenced Blobs3D structure will be sorted. The available values are the following:

  • None: No sorting logic will be applied to the list of blobs. Use this setting if you simply want a count of the blobs, or want to examine them without the need to order them.
  • Volume: Sort the blobs by their volume. Use this setting if you want to examine the blobs sorted by their volume (e.g. from the largest volume to the smallest, or the opposite). This is the default setting.
  • Bounding Box Size: Sort the blobs by the length of their bounding boxes on the specified axis. Use this setting if you want to examine the blobs sorted by their size (e.g., from the largest to the smallest, or the opposite), with the size specified by the bounding box dimensions of the blobs. This sorting key has four sub-types:
    • Bounding Box Size X: Sort the blobs by the X-axis length of their bounding boxes.
    • Bounding Box Size Y: Sort the blobs by the Y-axis length of their bounding boxes.
    • Bounding Box Size Z: Sort the blobs by the Z-axis length of their bounding boxes.
    • Bounding Box Size D: Sort the blobs by the diagonal length of their bounding boxes.
  • Center of Mass: Sort the blobs by their 3D positions in the 3D point cloud. The blob's 3D position is specified by the location of its center of mass in the point cloud in the specified direction (that is, their X, Y, Z or radial distance from the origin of the specified Sort Reference space). This sorting key has four sub-types:
    • Center of Mass X: Sort the blobs by the X-axis distance of their center of mass from the origin of the Sort Reference space.
    • Center of Mass Y: Sort the blobs by the Y-axis distance of their center of mass from the origin of the Sort Reference space.
    • Center of Mass Z: Sort the blobs by the Z-axis distance of their center of mass from the origin of the Sort Reference space.
    • Center of Mass R: Sort the blobs by the Euclidean distance of their center of mass from the origin of the Sort Reference space.
  • Center of Mass Spoke: Sort the blobs by their 2D positions. Use these sort keys, for example, if the objects are arranged in a circular fashion on a plane surface. The "2D position" refers to the blob's center of mass as projected onto the X/Y plane of the Sort Reference's space. This sorting key has two sub-types:
    • Center of Mass Spoke Angle Norm: Sort the blobs by the normalized spoke angle of their center of mass.
    • Center of Mass Spoke Angle Abs: Sort the blobs by the absolute spoke angle of their center of mass.
    • Center of Mass Spoke Radius: Sort the blobs by their center of mass distance from their origin to the center of mass location on the X-axis and Y-axis (disregarding the Z-axis height).
  • Center of Mass Grid X then Y then Z: Sort by the center-of-mass' X-axis position, then Y-axis position, and finally Z-axis position.
  • Center of Mass Grid Y then X then Z: Sort by the center-of-mass' Y-axis position, then X-axis position, and finally Z-axis position.
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.
Sort Tolerance

Specifies a threshold to determine if 2 or more results are tied. If they are tied, they can be sorted by a subsequent sort. Only takes effect when multiple sorting rules are applied (e.g. grid sorting or appending a sort tool).

Note: This parameter is disabled if Sort Key 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 region of interest (ROI) used in the job.
Note: This parameter is enabled only if External Region is set to 0, and Sort Key is set to Center of Mass X, Center of Mass Y, Center of Mass Z, Center of Mass R, Center of Mass Spoke Angle Norm/Abs, Center of Mass Spoke Radius, Center of Mass X then Y then Z, or Center of Mass Y then X then Z.

Show

Selects the type of graphics to overlay on the image.

0 = hide all (default)

All graphics will be hidden, except when the cell containing the function is highlighted in the spreadsheet.
1 = result graphics only The result graphics of the function will be displayed at all times.

2 = input and result graphics

The region of interest, the input data and the results will be displayed at all times.

ExtractBlobFromCylinder3D Outputs

Returns

A Blobs3D data structure containing the extracted 3D blob(s), 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 Volume Height Type Bounding Box
❒Blobs3D GetNFound(Blobs3D) 0 GetVolume(Blobs3D, index) GetHeight(Blobs3D, index) GetTypeText(Blobs3D, index) GetBoundingBox(Blobs3D)

ExtractBlobFromCylinder3D Vision Data Access Functions

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

Function Description
GetBoundingBox(Blobs3D, index) Returns the bounding box of the blob as a Box3D structure.
GetCenterOfMass(Blobs3D, index) Returns the center of mass of the blob as a Point3D structure
GetHeight(Blobs3D,index) Returns the height of the blob.
GetHeightHistogram(Blobs3D, index, binSize, minValue, maxValue) Returns the height histogram of the blob as a Histogram3D structure
GetNFound(Blobs3D) Returns the number of blobs extracted by the function.
GetNPoints(Blobs3D, index) Returns the number of points in the blob.
GetType(Blobs3D, index) Returns the blob type of the blob as an integer value.
GetTypeText(Blobs3D, index) Returns the blob type of the blob as text.
GetVolume(Blobs3D, index) Returns the volume of the blob.