# ExtractBlob3D

The ExtractBlob3D function is used to extract the blob(s) relative to a reference Plane3D structure. It returns the extracted blob(s) as a Blobs3D structure.

## ExtractBlob3D Inputs

The ExtractBlob3D function has the following syntax:

ExtractBlob3D(PointCloud,Fixture3D,ExternalFixture,Region3D,ExternalRegion,PlaneFromRegion,Plane3D,ExternalPlane,AutoConnectivityDist,ConnectivityDist,AutoNoiseThreshold,NoiseThreshold,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 around the PointCloud Z-axis. 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 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 -360 to 360. The tool normalizes external references with values outside the allowed range to the allowed range.
Note: This 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 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.
Plane From Region | When checked, the function uses a plane derived from the configured Region3D region or External Region This is useful if you need only just a rough reference shape or surface, and you do not want to extract or explicitly define a plane. The setting is disabled (unchecked) by default. Note: Enabling this setting disables the Plane3D setting.
Plane3D | Specifies the offset and the angle of the plane to use. It is offset from the PointCloud origin in the following format with the following arguments: {X, Y, Z, 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.
Tilt | Specifies the tilt angle (in degrees) from the 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 direction of tilt (in degrees) from the plane's rotated PointCloud X-axis, about the tool's PointCloud Z-axis. The value range is -360 - 360. External references with values outside the allowed range will be normalized to the allowed range.
Note: This parameter is available only if External Plane is set to 0. Note: This parameter is available only if the Plane from Region parameter is disabled, and the External Plane parameter is set to a value other than 0.
External Plane | Specifies a reference to a Rectangle3D or Circle3D structure defined in another cell to be used by the function. Set to 0 (OFF) to use the function's internal Plane3D structure instead. Note: This parameter is available only if the Plane from Region parameter is disabled.
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.
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 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.

## ExtractBlob3D 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)

## ExtractBlob3D 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.