# DetectBlobs

The DetectBlobs function performs a form of blob analysis known as "connectivity analysis" on a Region of Interest (ROI). During "connectivity analysis," the pixels within the ROI are divided into two categories, Blob or Background, based upon a greyscale Threshold value that separates all of the pixels below the threshold into a black category, and all of the pixels above the threshold into a white category.

In this way, pixels with similar values are grouped together based upon their “color” and whether or not they “touch” their neighboring pixels. The Background pixels can be connected to their neighbors if the pixels touch on either side, above and below; while the Blob pixels can be connected to their neighbors if the pixels touch on either side, above, below or diagonally.

Once the image has been processed, it will have been segmented into Blob and Background pixel values. The Blobs found in the ROI will be identified based upon their physical characteristics and assigned values, such as the blob's location in the image (it's Row, Column coordinates), its area, perimeter, spread and elongation. The data from the extracted blobs is stored and reported in a Blobs data structure.

This function is the first step in blob analysis, and both FindBlobs and SortBlobs ultimately uses Cell References to a DetectBlobs function's Blobs data structure, either directly or through Auditing.

## DetectBlobs Inputs

Parameter | Description
Image | This parameter must reference a spreadsheet cell that contains an Image data structure; by default, this parameter references A0, the cell containing the AcquireImage data structure. This parameter can also reference other Image data structures, such as those returned by the Image Vision Data Access Functions or Coordinate Transforms Functions.
Fixture | Defines the Region of Interest (ROI) relative to a Fixture input or the output of a Vision Tools function's image coordinate system. Setting the ROI relative to a Fixture ensures that if the Fixture is rotated or translated, the ROI 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)
Region | Also known as the Region of Interest (ROI), specifies the region of the image that undergoes analysis; creates an Interactive Graphics Mode that can be transformed and rotated. With this parameter selected, by pressing the Maximize Region button on the property sheet's Job Edit toolbar, the region will automatically be stretched to cover the entire image.
X | The x-offset of the origin, in fixture coordinates.
Y | The y-offset of the origin, in fixture coordinates.
Width | The dimension along the region's x-axis.
Height | The dimension along the region's y-axis.
Angle | The orientation, in fixture coordinates.
Curve | The angular deviation between the region's x-axis and the opposing boundary line.
Note: The Fixture and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.
External Region | This parameter uses Cell References to an Annulus, Circle, Region, EditAnnulus, EditCircle, EditCompositeRegion, EditPolygon, EditRegion. When this parameter is used, the function ignores the Region and Fixture settings and inspects the image area specified by referenced region. If an EditCompositeRegion control is referenced, the inspection area can be a mix of shapes. Each shape in the composite region can be assigned as added to or subtracted from (masking) the inspection area. Note: If this parameter has been set as a reference to an external region, to use the function's internal Region, this parameter must be manually set to zero by entering the value 0 in place of the cell reference. Otherwise, the function will continue to reference the external region.
Number to Sort | Specifies the number of blobs to sort.
0 | Returns all blobs that meet the color and size settings specified in the Color Blob/Color Background and Area Limit: Min/Area Limit: Max parameters.
1 to 4096 (default = 1) | Returns up to the specified number of blobs that meet the color and size settings specified in the Color Blob/Color Backgrouond and Area Limit: Min/Area Limit: Max parameters. If more blobs are found, the blobs with the largest area will be selected.
Note: If the value of the Number to Sort parameter is greater than zero, DetectBlobs 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.
Threshold | Specifies the greyscale value that will be used to separate blobs from the background. This value can be determined by utilizing the DetectBlobs function's automatic setting (the default setting), manually configured through trial and error, or set as Cell References to a Histogram function's calculated results.
-1 (default) | The function automatically evaluates and computes a threshold value based on the image's greyscale statistics.
0 to 255 | Specifies a greyscale threshold value, from 0 to 255.
Fill Holes | Specifies one of two methods for processing statistics accumulated in holes.
0 = OFF (default) | Enables the contribution of holes in the overall blob statistics. For example, adding holes to a blob would decrease its area. Note: When set to OFF, blobs that are holes within another blob are reported. In the example below, Blob 1, which is a hole within Blob 0, is reported. In the blob statistics, the value for Blob 0 Area (top row) does not contain Blob 1 Area (bottom row).
1 = ON | Disables the contribution of holes in the overall blob statistics. For example, adding holes to a blob would not affect its area. Note: When set to ON, blobs that are holes within another blob are ignored. In the example below, a hole within Blob 0 is ignored, and only one blob (Blob 0) is reported. In the blob statistics, the value for Blob 0 Area contains the entire blob area, including the hole.
Boundary Blobs | Specifies one of two ways for managing blobs that intersect the ROI boundary.
0 = OFF | Excludes blobs that intersect the ROI boundary; any blobs that intersect the ROI boundary will not be included in the final Blobs data structure.
1 = ON (default) | Includes blobs that intersect the ROI boundary; any blobs that intersect the ROI boundary will be included in the final Blobs data structure (provided that they also meet the specified settings of the Color Blob/Color Background and Area Limit: Min/Area Limit: Maxparameters).
Color: Blob | Specifies the blob's color.
0 = black | Only returns blobs that are below the specified greyscale Threshold value.
1 = white | Only returns blobs that are above the specified greyscale Threshold value.
2 = either (default) | There is no blob color requirement.
Note: When Color: Blob and Color: Background are set to the same color, blobs are not reported. For example, when Color: Blob is set to black and Color: Background is also set to black, blobs are not reported.
Color: Blob = Black Color: Background = Black | Color: Blob = Either or White Color: Background = Black
However, even if Color: Blob and Color: Background are set to the same color, blobs will be reported when it is contained by an area of the opposite color (see the examples below). If any part of the blob is not contained by the opposite color, the blob will not be reported.
Color: Blob = Black Color: Background = Black | Color: Blob = White Color: Background = White
Color: Background | Specifies the background color in the acquired image. 8-way connectivity analysis is performed on the foreground, and 4-way connectivity is performed on the background.
0 = black
1 = white (default)
Area Limit: Min | Specifies a minimum area restriction, in number of pixels, for all returned blobs (default = 100); only blobs whose area is greater than the Area Limit: Min value will be returned. The parameter range is: Lower Limit: 0 Upper Limit: Resolution (width * height) of the connected vision system. For example, when connected to the In-Sight D902 vision system, the parameter range is 0 to 2,304,000 (1920x1200).
Area Limit: Max | Specifies a maximum area restriction, in number of pixels, for all returned blobs (default = 100000); only blobs whose area is less than the Area Limit: Max will be returned. The parameter range is: Lower Limit: 0 Upper Limit: Resolution (width * height) of the connected vision system. For example, when connected to the In-Sight D902 vision system, the parameter range is 0 to 2,304,000 (1920x1200).
Show | Specifies the display mode for DetectBlobs graphical overlays on top of the image.
0 = hide all (default) | All graphics will be hidden, except when the cell containing the DetectBlobs function is highlighted in the spreadsheet.
1 = result graphics only | Blob outlines will be displayed at all times.
2 = input and result graphics | Both the input image region and the outlines of extracted blobs will be displayed at all times.

## DetectBlobs Outputs

Returns | A Blobs data structure containing the blobs extracted from the image, or #ERR if any of the input parameters are invalid.
Results | When DetectBlobs is initially inserted into a cell, a result table is created in the spreadsheet using the following Blobs Vision Data Access Functions Note: If Number to Sort is equal to 0, the table is comprised solely of the GetNFound function. If the value of the Number to Sort parameter is greater than zero, DetectBlobs 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.
Label | Function Name | Description
X | GetX(Blobs, Blob Index) | Returns the x-coordinate of a blob's center of mass (centroid).
Y | GetY(Blobs, Blob Index) | Returns the y-coordinate of a blob's center of mass (centroid).
Angle | GetAngle(Blobs, Blob Index) | Returns the angle of a blob’s principal (major) axis with respect to the Y-axis.
Color | GetColor(Blobs, Blob Index) | Returns the color value (0 = black, 1 = white) of a 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 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 a 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 blob. Note: Only holes whose area is greater than the Area Limit: Min value will be returned.
Perimeter | GetPerimeter(Blobs, Blob Index) | Returns the length of the boundary around the 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 a 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.

## DetectBlobs Example

The DetectBlobs function is used to identify and locate blobs of connected pixels, which can be comprised of various shapes and sizes. This example illustrates how the information returned in the DetectBlobs data structure result table relates to the found blobs, and how that information can be used to later sort and filter the blobs based upon their characteristics.

For this example, the following image has been used to help illustrate the meaning of the values that are returned in the DetectBlobs function's result table:

A DetectBlobs function was inserted into a blank cell in the spreadsheet. Based upon the shapes, the DetectBlobs property sheet's parameters were configured as follows:

- Image: The default setting was used for this example, but this parameter can reference any Image data structure, such as an Image data structure produced by a Filter function, which processes the image to remove excess image noise before inspecting it for blobs.
- Fixture: The default setting was used because the image is stationary and will not be rotated or moved. However, when using the DetectBlobs function on images that undergo movement, it is advisable to assign the image region to a Fixture.
- Region: The image region was maximized to include all of the shapes in the analysis. By clicking on the Region parameter and then pressing the Maximize Region button on the property sheet's toolbar, the region will automatically be stretched to cover the entire image.
- Number to Sort: The Number to Sort was set to six. This parameter could have also been set to 0, and the tool would have automatically extracted all blobs that meet the color and size settings specified in the Color Blob/Color Background and Area Limit: Min/Area Limit: Max parameters.
- Threshold: The default setting was used, which automatically calculates the greyscale Threshold value. In this image, the greyscale value differences are very pronounced and it is very clear which pixels are the dark pixels and which are the light. In applications where there is a more subtle gradation and the automatic threshold setting does not separate the values very well, using Histogram functions, such as the HistHead or HistTail functions, to determine the greyscale intensities in different regions of the image can be very helpful.
- Fill Holes: The default setting was used, enabling the contribution of the holes found in the blobs, thus decreasing the overall area of those blob shapes with holes in them. Had the Fill Holes checkbox been checked, holes within blobs are reported and the area within the holes would have been added, thus increasing the area of the blobs with holes.
- Boundary Blobs: The default setting was used, which includes any blobs that intersect the image region's boundary. With this setting, if the image had been moved to the left, and the biggest circle and the smallest square shape intersected the left-most boundary of the image region, the parts of those shapes that still fell within the region's boundary would be extracted as blobs. If the checkbox had been unchecked, though, those blobs would not have been processed.
- Area Limit: Min/Max: The default settings were used. These settings filter through the blobs in the region during the extraction phase, evaluating the blobs based upon the minimum and maximum area limit settings to determine whether or not the area of the blob allows it to be classified as a blob.
- Show: The default setting was used, which only allows the result graphics to be displayed when the cell containing the Blobs data structure is selected, as in the example below.

After configuring the DetectBlobs property sheet, a Blobs data structure and result data table are produced.

The values returned in the result table can be used to filter and sort the blobs, using the FindBlobs and SortBlobs functions. For example, a FindBlobs function could be inserted into the spreadsheet and reference the DetectBlobs function. The FindBlobs function would then be used to filter the blobs based upon their Spread. Then a SortBlobs function could be inserted into the spreadsheet and it could reference the recently created FindBlobs function to sort the list of blobs based upon their X, Y position.