# SortBlobs

SortBlobs is used to sort the blobs referenced in a Blobs data structure in relation to a fixture.

## SortBlobs Overview

By computing the position of the referenced blob's center of mass (centroid) relative to the specified image fixture coordinate system, SortBlobs sorts the referenced blobs based upon one of their measurement characteristics, such as the blob's distance along the x or y-axis, from a fixture origin or a grid, or the blob's angle or angular distance.

Each blob in the referenced Blobs data structure is examined, and depending upon the Sort By parameter setting, the blob is identified and its position is calculated by measuring either the blob's distance or angular relationship to a fixed location.

Once SortBlobs has sorted the referenced blobs, a new Blobs data structure and accompanying result table will be automatically inserted into the spreadsheet. The result table is sorted by how close the blob is to the chosen fixture, in descending order (the closest blob will be listed first, the next closest second, etc.).

SortBlobs is an extremely helpful function in instances where there are multiple blobs and the position of each blob in relation to the other blobs needs to be determined.

## SortBlobs Inputs

Parameter | Description
Blobs | This parameter uses Cell References to a spreadsheet cell containing the Blobs data structure that is to be sorted.
Number to Sort | Specifies the maximum number of blobs (1 to 4096; default = 3) to return. Note: If the value of this parameter is greater than zero, SortBlobs will automatically insert a result table containing a maximum of 10 entries that correspond to the first 10 blobs in the Blobs data structure. If you wish to display more entries, you can expand the table by copying the last row and pasting additional rows at the end; make sure to increment the index number of any newly-pasted row so that the proper blob is indexed.
Sort By | Specifies how the referenced blobs will be measured and sorted.
0 = Y (default) | Sort by distance along the fixture y-coordinate, from small to large.
1 = X | Sort by distance along the fixture x-coordinate, from small to large.
2 = Angle | Sort by the angle (0 to 360 degrees), as measured counter-clockwise from the y-axis of the fixture coordinate system to the line segment defined by the blob's centroid (center of mass) and the fixture origin, from closest to furthest, in descending order.
3 = Angular Distance | Sort by the absolute value of the angle (-180 to 180 degrees), as measured from the x-axis of the fixture coordinate system to a line segment defined by the blob centroid and the fixture origin, from closest to furthest, in descending order.
4 = Distance | Sort by the distance from the fixture origin to the blob's centroid, from closest to furthest, in descending order.
5 = Grid Y | Sort by distance along the fixture's y-coordinate first, and then by distance along the x-coordinate, from closest to furthest, in descending order. Note: SortBlobs will return #ERR if Grid Y is selected and the function is referencing an image that has been calibrated to world coordinate values, such as a CalibrateImage or TransBlobsToWorld function's output. Grid Y sorting can only be applied to pixel coordinates.
6 = Grid X | Sort by distance along the fixture's x-coordinate first, and then by distance along the y-axis, from closest to furthest, in descending order. Note: SortBlobs will return #ERR if Grid X is selected and the function is referencing an image that has been calibrated to world coordinate values, such as a CalibrateImage or TransBlobsToWorld function's output. Grid X sorting can only be applied to pixel coordinates.
7 = Width | Sorts by width values, from the largest to the smallest.
8 = Height | Sorts by height values, from the largest to the smallest.
Fixture | Defines the referenced blob's center of mass (centroid) relative to a Fixture input or the output of a Vision Tools function's image coordinate system. Setting the referenced blob's center of mass relative to a Fixture ensures that if the Fixture is rotated or translated, the referenced blob will be rotated or translated in relation to the Fixture. The default setting is (0,0,0), the top leftmost corner of the image.
X | The X offset, in image coordinates.
Y | The Y offset, in image coordinates.
Theta | The rotation from the image X axis, in the image coordinate system. (+/-360 degrees clockwise)
Show | Specifies the display mode for SortBlobs graphical overlays on top of the image.
0 = hide all (default) | All graphics will be hidden, except when the cell containing the SortBlobs function is highlighted in the spreadsheet.
1 = result graphics only | Blob outlines will be displayed at all times.

## SortBlobs Outputs

Returns | A Blobs data structure containing the sorted blobs, or #ERR if any of the input parameters are invalid.
Results | When SortBlobs is initially inserted into a cell, a results table is created in the spreadsheet. Note: If the value of the Number to Sortparameter is greater than zero, SortBlobs will automatically insert a result table containing a maximum of 10 entries that correspond to the first 10 blobs in the Blobs data structure. If you wish to display more entries, you can expand the table by copying the last row and pasting additional rows at the end; make sure to increment the index number of any newly-pasted row so that the proper blob is indexed. The following Blobs Vision Data Access Functions are automatically inserted into the spreadsheet to create the SortBlobs data structure result table:
Label | Function | Description
Index |  | A Blobs index
X | GetX(Blobs, Blob Index) | Returns the x-coordinate of the referenced blob's center of mass (centroid).
Y | GetY(Blobs, Blob Index) | Returns the y-coordinate of the referenced blob's center of mass (centroid).
Angle | GetAngle(Blobs, Blob Index) | Returns the angle of the referenced blob's center of mass, relative to the center of the ROI.
Color | GetColor(Blobs, Blob Index) | Returns the color value (0 = black, 1 = white) of the referenced blob.
Score | GetScore(Blobs, Blob Index) | A measure of how closely the blob matches the criteria of a FindBlobs function.
Area | GetArea(Blobs, Blob Index) | Returns the area of the referenced blob (measured in pixels). Note: If there are holes in the blob, the Area value will vary depending on whether or not the Fill Holes checkbox is enabled or disabled.
Elongation | GetElongation(Blobs, Blob Index) | Returns a value that represents how the referenced blob's pixels are stretched out from the blob's center of mass (centroid). For instance, a circle would report 0 Elongation, while a nail would have a high Elongation value.
Holes | GetHoles(Blobs, Blob Index) | Returns the number of holes contained within the referenced blob.
Perimeter | GetPerimeter(Blobs, Blob Index) | Returns the length of the boundary around the referenced blob; the perimeter is calculated by counting the external edges of the pixels that form the boundary of the blob.
Spread | GetSpread(Blobs, Blob Index) | Returns a value that represents how the referenced blob's pixels are distributed away from the blob's center of mass (centroid). For instance, a circular shaped object would have a lower Spread value than an oval shaped object.