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 distance along the x or y-axis, from a fixture origin or a grid, or the angle or angular distance of the blob.

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 distance or angular relationship of the blob 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 is listed first, the next closest second, and so on).

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.

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 centroid of the blob, from closest to furthest, in descending order.
5 = Grid Y	Sort by distance along the y-coordinate of the fixture first, and then by distance along the x-coordinate, from closest to furthest, in descending order. Note: SortBlobs returns #ERR if Grid Y is selected and the function is referencing an image that was calibrated to world coordinate values, such as the output of a CalibrateImage or TransBlobsToWorld function. Grid Y sorting can only be applied to pixel coordinates.
6 = Grid X	Sort by distance along the x-coordinate of the fixture first, and then by distance along the y-axis, from closest to furthest, in descending order. Note: SortBlobs returns #ERR if Grid X is selected and the function is referencing an image that was calibrated to world coordinate values, such as the output of a CalibrateImage or TransBlobsToWorld function. 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 center of mass (centroid) of the referenced blob relative to a Fixture input or the output of the image coordinate system of a Vision Tools function. Setting the center of mass of the referenced blob 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.

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 automatically inserts 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 center of mass (centroid) of the referenced blob.
Y	GetY(Blobs, Blob Index)	Returns the y-coordinate of the center of mass (centroid) of the referenced blob.
Angle	GetAngle(Blobs, Blob Index)	Returns the angle of the center of mass (centroid) of the referenced blob, 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 pixels of the referenced blob are stretched out from the center of mass (centroid). For instance, a circle reports 0 Elongation, while a nail has 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 pixels of the referenced blob are distributed away from the center of mass (centroid). For instance, a circular shaped object has a lower Spread value than an oval shaped object.

See the Blobs Vision Data Access functions for details on the result table.