ExtractBlobs

The ExtractBlobs function performs a form of blob analysis known as "connectivity analysis" on a Region of Interest (ROI). For more information, see 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 reference an ExtractBlobs function's Blobs data structure, either directly or in a chain of cell dependencies. For more information, see FindBlobs, SortBlobs, Cell References - Relative/Absolute, or Job Auditing.

ExtractBlobs Inputs

Syntax: ExtractBlobs(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Region.X,Region.Y,Region.High,Region.Wide,Region.Angle,Region.Curve,External Region,Number to Sort,Threshold,Fill Holes,Boundary Blobs,Color Blob,Color Background,Area Limit: Min,Area Limit: Max,Show)

Note: The Fixture and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.

Parameter

Description

Image

Specifies a reference to a spreadsheet cell that contains an Image data structure; by default, this parameter references A0, the cell containing the AcquireImage Image data structure. This parameter can also reference other Image data structures, such as those returned by the Vision Tool Image functions or Coordinate Transforms Functions.

Fixture

Defines the Region of Interest (ROI) relative to a Fixture input or the output of a Vision Tool 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. For more information, see Fixture and Vision Tools.

Note: The default setting is (0,0,0), the top leftmost corner of the image.

Row (default = 0)	The row offset, in image coordinates.
Column (default = 0)	The column offset, in image coordinates.
Theta (default = 0)	The angle of orientation, in the image coordinate system.

Region

Also known as the Region of Interest (ROI), specifies the region of the image that undergoes analysis and creates a rectangular image region that can be transformed and rotated. For more information, see Interactive Graphics Mode.

Tip: With this parameter selected, you can press the Maximize Region button on the property sheet's toolbar to maximize the region and cover the entire image.

X	The x-offset of the origin, in fixture coordinates.
Y	The y-offset of the origin, in fixture coordinates.
High	The dimension along the region's x-axis.
Wide	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.

External Region

This parameter can reference a spreadsheet cell that contains the following functions:

Annulus. For more information, see Annulus.
Circle. For more information, see Circle.
Region. For more information, see Region.
EditAnnulus. For more information, see EditAnnulus.
EditCircle. For more information, see EditCircle.
EditCompositeRegion. For more information, see EditCompositeRegion.
EditPolygon. For more information, see EditPolygon.
EditRegion. For more information, see 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 return.

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 Background 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, ExtractBlobs 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 ExtractBlobs function's automatic setting (the default setting), manually configured through trial and error, or set as a reference 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.

EXAMPLE

0 = OFF (default)	Enables the contribution of holes in the overall blob statistics. For example, adding holes to a blob would decrease its area.
1 = ON	Disables the contribution of holes in the overall blob statistics. For example, adding holes to a blob would not affect its area.

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: Max parameters).

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.

Color Background

Specifies the background color in the acquired image. When the background color differs from the blob color, 8-way connectivity analysis is performed; when the background color matches the blob color, 4-way connectivity analysis is performed.

0 = black
1 = white (default)

Area Limit: Min

Specifies a minimum area restriction, in number of pixels, (0 to 900000; default = 100) for all returned blobs; only blobs whose area is greater than the Area Limit: Min value will be returned.

Area Limit: Max

Specifies a maximum area restriction, in number of pixels, (0 to 900000; default = 100000) for all returned blobs; only blobs whose area is less than the Area Limit: Max will be returned.

Show

Specifies the display mode for ExtractBlobs graphical overlays on top of the image.

0 = hide all (default)	All graphics will be hidden, except when the cell containing the ExtractBlobs 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.

ExtractBlobs 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 ExtractBlobs is initially inserted into a cell, a result table is created in the spreadsheet. If Number to Sort is equal to 0, the table is comprised solely of the GetNFound function. If Number to Sort is greater than zero, multiple functions will be inserted to create a table of blob results with a maximum of Number to Sort rows.

ExtractBlobs Vision Data Access Functions

These functions provide important statistical information about the blobs found in the image. The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table. For more information, see Blobs.

Spreadsheet Name	Function Name	Description
Index	N/A	Returns the indexed blobs, sorted from largest to smallest in area.
Row	GetRow(Blobs, Blob Index)	Returns the y-coordinate (Row) of a blob's center of mass (centroid). EXAMPLE
Col	GetCol(Blobs, Blob Index)	Returns the x-coordinate (Column) of a blob's center of mass (centroid). EXAMPLE
Angle	GetAngle(Blobs, Blob Index)	Returns the angle of a blob's center of mass, relative to the center of the ROI. EXAMPLE
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). EXAMPLE 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. EXAMPLE
Holes	GetHoles(Blobs, Blob Index)	Returns the number of holes contained within the blob.
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. EXAMPLE
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. EXAMPLE

Additional data elements can be accessed using the following Vision Data Access functions:

Thresh	GetThresh(Blobs)	Returns the Threshold value that was used to segment the image.
NFound	GetNFound(Blobs)	Returns the number of blobs found.
High	GetHigh(Blobs, Blob Index)	Returns the height of the indexed blob.
Wide	GetWide(Blobs, Blob Index)	Returns the width of the indexed blob.
MinRow	GetMinRow(Blobs, Blob Index)	Returns the topmost row coordinate for a square bounding box around the blob, oriented to the image coordinate frame. Note: For an alternative bounding box, with a varied orientation, please refer to the BoundingRectangle.
MinCol	GetMinCol(Blobs, Blob Index)	Returns the leftmost column coordinate for a square bounding box around the blob, oriented to the image coordinate frame. Note: For an alternative bounding box, with a varied orientation, please refer to the BoundingRectangle.
MaxRow	GetMaxRow(Blobs, Blob Index)	Returns the bottommost row coordinate for a square bounding box around the blob, oriented to the image coordinate frame. Note: For an alternative bounding box, with a varied orientation, please refer to the BoundingRectangle .
MaxCol	GetMaxCol(Blobs, Blob Index)	Returns the leftmost column coordinate for a square bounding box around the blob, oriented to the image coordinate frame. Note: For an alternative bounding box, with a varied orientation, please refer to the BoundingRectangle.

ExtractBlobs Example

The ExtractBlobs 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 ExtractBlobs 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 ExtractBlobs function's result table:

An ExtractBlobs function was inserted into a blank cell in the spreadsheet. Based upon the shapes, the ExtractBlobs 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 NeighborFilter function, which processes the image to remove excess image noise before inspecting it for blobs. For more information, see NeighborFilter.

Fixture: The default setting was used because the image is stationary and will not be rotated or moved. However, when using the ExtractBlobs function on images that undergo movement, it is advisable to assign the image region to a Fixture. For more information, see 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: There were six shapes, so the Number to Sort was set to six. This parameter could have also been set to 0, and the tool would have automatically extracted the six shapes.

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. For more information, see Histogram, HistHead, or HistTail.

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, 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 circle and dumb-bell 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 ExtractBlobs property sheet, a Blobs data structure and result data table are produced.

Looking at the results, all of the shapes are comprised of nearly the same area, while the other values, such as Angle, Elongation and Perimeter, show a much greater variance. 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 ExtractBlobs 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.