# SortBlob3D

The SortBlob3D function Functions are tools that are available in Spreadsheet for processing and analyzing acquisitions or other results. You can add functions to your Spreadsheet job to create tool chains and produce results for specific applications. is used to return a sorted list of the blobs with the largest volume detected in the point cloud A point cloud is a 3D structure that consists of the data points collected by a 3D vision system during acquisition., by referencing the spreadsheet cell containing the set of extracted large blobs. The function allows you to sort the referenced blobs by specific sort keys and orders. It returns the list of sorted blobs in a Blobs3D structure, which can be referenced with Blobs3D Vision Data Access functions.

Inputs

The SortBlob3D function has the following syntax:

    SortBlob3D(PointCloud A point cloud is a 3D structure that consists of the data points collected by a 3D vision system during acquisition.,Blobs,SortKey,SortOrder,Fixture3D,ExternalFixture,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.
Blobs3D | Specifies a reference to a Blobs3D structure in another spreadsheet cell. The contents of this cell will be used as a basis for sorting.
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 A blob is a group of pixels on the image that form a distinct pattern, typically used to represent objects, features, or areas of interest in object detection and segmentation tasks.'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 (such as grid sorting or appending a sort tool). Note: This parameter is disabled if Sort Key is set to None.
Fixture3D | Specifies the point cloud coordinate system in which the 3D fixture A fixture is a coordinate location on the image that keeps the tool in the place determined by the 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. Note: This parameter is not available if Sort Key is set to None, Volume, Bounding Box Size X, Bounding Box Size Y, Bounding Box Size Z, or Bounding Box Size D.
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. Note: This parameter is not available if Sort Key is set to None, Volume, Bounding Box Size X, Bounding Box Size Y, Bounding Box Size Z, or Bounding Box Size D.
Append Sort | When enabled, the selected the sorting rule will be added to the rules inherited from the reference vision or sorting tool. Otherwise, it will override the inherited rules. This setting is enabled by default.
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 Blobs3D data structure containing the blobs sorted, 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, 0) | GetHeight(Blobs3D, 0) | GetTypeText(Blobs3D, 0) | GetBoundingBox(Blobs3D, 0)
|  | 1 | GetVolume(Blobs3D, 1) | GetHeight(Blobs3D, 1) | GetTypeText(Blobs3D, 1) | GetBoundingBox(Blobs3D, 1)
|  | ... | ... | ... | ... | ...
|  | N-1 | GetVolume(Blobs3D, N-1) | GetHeight(Blobs3D, N-1) | GetTypeText(Blobs3D, N-1) | GetBoundingBox(Blobs3D, N-1)
N = min(10, max(NumFound,1))

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 sorted blob with the specified index.
GetHeight(Blobs3D, index) | Returns the height of the sorted blob with the specified index.
GetNFound(Blobs3D, index) | Returns the number of blobs sorted by the SortBlob3D function.
GetTypeText(Blobs3D, index) | Returns the blob type of the sorted blob with the specified index.
GetVolume(Blobs3D, index) | Returns the volume of the sorted blob with the specified index.