Operator Library: Blob
The BlobDetector1D operator detects objects in binary images that have an unlimited height and determines their properties. The outputs of the operator are several streams of data representing the properties for each object.
The functionality of the operator can be fully simulated in VisualApplets.
![[Important]](../common/images/admon/important.png) |
Availability |
|---|---|
|
To use the BlobDetector1D operator, you need either a Segmentation and Classification Library license, or the VisualApplets 4 license. |
Read also the introduction to the Library Blob.
The BlobDetector1D provides the BoundingBox, Area, and Center of Gravity X and Y features.
![[Note]](../common/images/admon/note.png) |
The Center of Gravity X and Y Are No Direct Outputs of the Operator |
|---|---|
|
The output ports CenterX and CenterY actually provide the image moments M10 (CenterX) and M01 (CenterY). To extract the center of gravity of an object, you must divide the moments by the extracted area:
|
The BlobDetector1D operator is designed for endless one-dimensional images. In general, for a 1D blob analysis, the Bounding Box and Center of Gravity Y object features are related to the position of the object with the origin in the top left corner of an image. Since indexing an endless amount of lines is impossible, at some point of operation an overflow for the Y-coordinate will occur. The line in which the Y-coordinate overflow occurs, is controlled by the parameter LineCountBits. Every 2^LineCountBits lines, the Y-coordinate is reset to 0. For example, if LineCountBits = 10, the maximum Y-coordinate is 1023 (= 2^10-1). The following line is assigned to the Y-coordinate = 0. While this restriction is no issue for the Bounding Box, the Area, and the Center of Gravity X features, the Center of Gravity Y value is affected by an Y-coordinate overflow: If an object extends beyond the limit of the overflow, the Center of Gravity Y value becomes corrupted, as shown in the graphic below. In this graphic, the foreground is colored.
|
The Corrupted Center of Gravity Y Value Isn't Detected Automatically |
|---|---|
|
The corrupted Center of Gravity Y value isn't detected automatically for objects which span across the Y-coordinate border. |
The incoming image is processed line by line by the operator. Since the operator can't predict the future, regions that are connected later may appear as independent at first. Therefore, connected pixels within a single line in this text are named object artifacts. The BlobDetector1D operator checks whether those object artifacts overlap with other object artifacts of the following line. This is to determine whether the objects are really independent or whether they are part of a larger object. The maximum number of object artifacts that can be handled by the operator is defined by the LabelCount parameter. If the number of object artifacts exceed the value of LabelCount, data will be lost and the integrity of the object results is no longer given. This is called a context corruption. The line, in which the data is lost, is marked with a Line Error dummy object discernible by an ErrorFlag. All following objects within the corrupted context are flagged as such. The context corruption ends once the context is reset by flushing an applet or by restarting the applet. All error flags are listed in the section 'Output Ports'.
In most cases, the number of required labels to prevent a context corruption is equal to the maximum number of object artifacts within a line. For neighborhood = 4 and neighborhood = 8, the precise number of labels required is slightly different:
-
For neighborhood = 4, the number of labels to prevent a context corruption is equal to the maximum number of object artifacts between any pixel at position X of line N and the pixel at position X of line N+1.
-
For neighborhood = 8, the number of labels to prevent a context corruption is equal to the maximum number of object artifacts between any pixel at position X of line N and the pixel at position X+1 of line N+1.
If you are not sure whether the selected amount of labels is sufficient for your use case, check it in the simulation.
When instantiating the BlobDetector1D module, you can define which output ports shall be created. By enabling/disabling the ports, the corresponding features are also automatically enabled/disabled. After confirming these ports, you can't change them anymore. If you need other output ports, you must instantiate another BlobDetector1D module.
While the 2D image format has a built-in maximum latency for outputting objects due to the frame end, it is possible for objects in a 1D image to never reach their end. Since it might be necessary to react to an object within a certain amount of time, you can define a maximum bounding box height as well as the premature output of feature data, if the bounding box height or other feature data reaches an overflow. These outputs are called overflow events and are indicated by the ErrorFlagsO link. You can enable or disable the overflow events in the operator properties. If a feature overflows (and its OverflowEvent parameter is enabled), the objects are output in their intermediate state. The object is still processed and continued internally; the output is just an intermediate result of the object that has been given as output.
The figure below visualized the handling of overflow events: The foreground is colored blue, the '>' symbol indicates at which position the overflow event is detected. Since the grayscale is triggered in the moment when the maximum BoundingBox height is exceeded, the actual height of intermediate object is MaxBoundingBoxHeight + 1. This is why the bounding boxes are displayed to have a height of 7, while the feature value of the object gives the output 1.
The blob detector operators belong to the few operators whose processing speed, i.e., bandwidth, depends on the image content. The operators work best on images with few changes between foreground and background pixels within cohesive lines. Therefore, noise or a high number of object artifacts within multiple lines slow down the data throughput noticeably. However, this applies only for images containing very strong noise.
The operator works with minimum latency by processing the input images line by line. Once the end of an object becomes unambiguous, the object features are immediately provided as output by the operator. Therefore, the output of the object takes place in the same line in which it ends. This enables the post-processing of completed object features while the following context is still being processed by the operator.
Note that the DMA and some other operators wait for a frame end signal before they report completion.
The resource consumption of the operator depends on the enabled features, the number of bits used for the features and the selected number of labels. Therefore, Basler recommends to disable not required features as well as to be cautious when setting the LabelCount parameter.
|
Partially Disabling Bounding Box Ports Doesn't Save Resources |
|---|---|
|
The bounding box has several output ports, therefore the feature is only disabled if all of its ports are disabled. Partially disabling bounding box ports doesn't save resources. |
|
Setting the Maximum Values Manually Saves Resource |
|---|---|
|
To save resource and to improve the handling of the design, Basler recommends to set the bit widths for the links manually, if you know the maximum values for the objects to be detected. |
The ImageI input of the blob detector expects a binary (pixel bit width of 1) 1D image. The operator supports the input of different line lengths during operation time as well as empty lines.
The operator assumes foreground values to have the value ONE, and background values to have the value ZERO. Make sure you match this requirement in the preliminary binarization process.
The BlobDetector1D operator has an additional input link FlushI synchronous to ImageI. FlushI terminates the active context, meaning it acts like a virtual End of Frame. This termination is triggered, if any of the incoming pixels at the FlushI port is '1' and will take place at the end of the line. The flush restarts the blob detection, beginning in the following line, which also resets the Y-coordinate to 0. All objects that are output due to the Flush command are unmistakably flagged with bit 14 of the ErrorFlagsO link. In addition to that, a ContextTermination object is output as the very last object of the line, in which the flush has been issued (flagged by bit 15 of the ErrorFlagsO link). The ContextTermination is a dummy object that doesn't hold any useful feature data.
The behavior of the BlobDetector1D operator is demonstrated in the figure below. Foreground pixels ('1') are colored in blue. The '>' indicates in which line the objects are output. The naming of the objects corresponds to their set tags that are present at the output link ErrorFlagsO.
The output is represented in form of the VALT_LINE1D image format. Each of the output ports represents one object feature / object property. They are synchronous and together they describe one single object. Each output pixel provides the value of either a completed object or of an error status object. Whether this output is an extracted object or an error status object is indicated by the ErrorFlagsO output port. The pixel that represents an object appears in the same line in which the object has been completed. They are output in the order of their completion. For example, two objects end in line 10. The last pixel of object A has the X-coordinate 42, the last pixel of object B has the X-coordinate 97. Therefore, object A is the first pixel and object B is the second pixel at the operator's output ports. Lines, in which no objects are completed and no errors occurred, are empty.
The output port's widths either adapt automatically, based on the given input format to prevent an overflow of the feature data. Alternatively you can manually configure the output port's widths. Manual configurations of link bit widths are available for Area/ CenterX/ CenterY, if you have enabled them in the operator properties.
The port ErrorFlagsO outputs several error flags for overflows or additional info tags. Each bit is reserved for a specific flag. You can see these error flags either in the runtime environment of your hardware or in the simulation. To see these error flags in the simulation:
-
Add a simulation probe to the ErrorFlagsO port of the BlobDetector1D.
-
Add an image that causes an overflow to the simulation.
-
Run the simulation.
-
Open the of your output port.
-
Scroll to the pixel you want to examine, zoom in to see the pixel
values and set the pixel values to :
-
The active bits within your hex value indicate different errors or status information regarding your blob object. For details check the table blow.
You find a detailed explanation of the error flags in the parameter description below. A summary is given in the following table:
| Bit # | Description | Notes |
|---|---|---|
| 0 | Area Overflow |
The Area value of the object exceeded the provided output bit width at some point in its processing history. |
| 1 | Area OverflowEvent |
The Area value of the object exceeded the provided output bit width during its processing. The generated object marks in which line the overflow occurred. |
| 2 | CenterX Overflow |
The CenterX value (image moment M10) of the object exceeded the provided output bit width at some point in its processing history. |
| 3 | CenterX OverflowEvent |
The CenterX value (image moment M10) of the object exceeded the provided output bit width during its processing. The generated object marks in which line the overflow occurred. |
| 4 | CenterY Overflow |
The CenterY value (image moment M01) of the object exceeded the provided output bit width at some point in its processing history. |
| 5 | CenterY OverflowEvent |
The CenterY value (image moment M01) of the object exceeded the provided output bit width during its processing. The generated object marks in which line the overflow occurred. |
| 6 | BoundingBox HeightViolation |
The height of the BoundingBox exceeded the parameter value MaxBoundingBoxHeight you have configured for objects at some point in its processing history. |
| 7 | BoundingBox HeightViolationEvent |
The height of the BoundingBox exceeded the parameter value MaxBoundingBoxHeight you have configured for objects during its processing. The generated object marks in which line the height violation has been detected. |
| 8-11 | Reserved |
Reserved for future extensions. |
| 12 | Line Error |
Indicates a dummy object, which marks a line in which more object artifacts occurred than can be handled by the selected number of labels. The available memory is insufficient to process further incoming data. Since this is a dummy object, the feature data values at the other ports don't contain any useful data. While the feature values are displayed as 0 in the simulation, they can be any value in hardware. Due to the lower ErrorBits 7-0 being tied to the enabled features and their values, these flags also might differ in hardware from the simulation. If this error flag exists, it is always the first object output of a line. |
| 13 | ContextCorruption |
More object artifacts occurred than could be handled by the selected number of labels. The available memory is not sufficient to process all incoming data. The integrity of the flagged object can't be guaranteed. The operator returns to the correct functionality with the end of context (i.e. triggered by a flush) or by a restart of the application in which you open the HAP file you built from your design. With the following line the context is then processed without any impact of a previous context corruption. |
| 14 | FlushedLine |
The flagged objects are output due to the forced context termination by a flush. |
| 15 | ContextTermination |
Indicates a dummy object, which marks the end of the context in the line, in which a flush has been triggered. Since this is a dummy object, the feature data at the other ports don't contain any useful data. While the feature values are displayed as 0 in the simulation, they can be any value in hardware. Due to the lower ErrorBits 7-0 being tied to the enabled features and their values, these flags also might differ in hardware from the simulation. Any object output after this dummy object is part of a new context. |
Table 34. Explanation of Blob Error Flags
| Property | Value |
|---|---|
| Operator Type | M |
| Input Links | ImageI, data input FlushI, data input |
| Output Links | BoundingX0O, data output BoundingX1O, data output BoundingY1O, data output BoundingHeightO, data output AreaO, data output CenterXO, data output CenterYO, data output ErrorFlagsO, data output |
|
|
The bit width is based on the incoming maximum image width of the ImageI
link. It is calculated as |
|
|
The bit width is defined by the parameter LineCountBits. |
|
|
The bit width is derived from the parameter
MaxBoundingBoxHeight. It is calculated as
|
|
|
Via the parameters AreaBitWidthMode, CenterXBitWidthMode, and CenterYBitWidthMode, you can select whether you either configure the link manually or use the automatic mode. If you edit the links manually, the allowed range is [1, 48]. |
|
|
The maximum image width equals the parameter LabelCount + 2. |
| LabelCount | |
|---|---|
| Type | static parameter |
| Default | 100 |
| Range | [1, (max. Img Width(Input Link I) / 2 + 2] |
|
To track partial objects internally, this parameter sets the number of available labels. It also influences the maximum number of objects which may be output in a line. Note that the required resources for the Blob_Detector_1D operator depend on the number of labels. A good value range for this parameter is between 100 and 500, which should be sufficient for most applications. If more partial objects than selected labels occur, data is lost and the context of the frame becomes corrupted. In this case, bit 13 of the output link ErrorFlagsO is '1' to indicate that the provided data is no longer reliable. The error bit is set when detecting the data loss and is reset by a flush or a restart of the acquisition. |
|
| Neighborhood | |
|---|---|
| Type | static parameter |
| Default | EightConnected |
| Range | {FourConnected, EightConnected} |
|
This parameter selects the required neighborhood for object detection. See 'Definition' for a detailed explanation of pixel neighborhoods. |
|
| LineCountBits | |
|---|---|
| Type | static parameter |
| Default | 10 |
| Range | [1, 24] |
|
This parameter defines the number of bits used for the internal indexing of
incoming lines. The Y-coordinate resets at index
|
|
| MaxBoundingBoxHeight | |
|---|---|
| Type | static parameter |
| Default | 256 |
| Range | [1, 2^24] |
|
This parameter defines the maximum allowed height of the bounding box of an object, i.e. the maximum number of lines spanned by the bounding box. When the height of the bounding box exceeded the MaxBoundingBoxHeight value, the height starts over at 1 and the corresponding object is flagged with the HeightViolation tag (i.e. bit 6 of ErrorFlagsO). |
|
| GenerateBoundingBoxHeightViolationEvents | |
|---|---|
| Type | static parameter |
| Default | true |
| Range | {true, false} |
|
When the height of the bounding box of an object exceeds the value of the MaxBoundingBoxHeight parameter, the object is output in its intermediate state. The object is still internally processed and continued, but the result is just an intermediate result of the object that has been output. Objects output due to an HeightViolation event are tagged with bit 7 of ErrorFlagsO. |
|
| AreaBitWidthMode | |
|---|---|
| Type | static parameter |
| Default | AutomaticContextMaximum |
| Range | {AutomaticContextMaximum, LinkManuallyEditable} |
|
The area of an object is defined by the sum of all object foreground pixels. If AutomaticContextMaximum is selected,
the operator automatically sets the bits for the maximum size of an object.
Since there is no real maximum height for a 1D image, a maximum height of
If the maximum possible size of objects is known, or only objects of a specific size are of interest, Basler recommends to use the mode LinkManuallyEditable. This saves resources and improves the build time of the entire design. In the LinkManuallyEditable mode, you can edit the bit width property of the link within the allowed range of [1, 48]. The bit width of the link directly translates to the bit width used internally for calculating the Area feature and therefore impacts the overall resource consumption. If the bit width is not sufficient for the Area value of an object, it is indicated by the ErrorFlagO link (bit 0). |
|
| GenerateAreaOverflowEvents | |
|---|---|
| Type | static parameter |
| Default | false |
| Range | {true, false} |
|
When the Area value of the object exceeds the bit width of the AreaO link, the object is output in its intermediate state. The object is still internally processed and continued, but it is an intermediate result of the object that has been output. Objects output due to an AreaOverflowEvent are tagged with bit 1 of ErrorFlagsO. |
|
| CenterXBitWidthMode | |
|---|---|
| Type | static parameter |
| Default | AutomaticContextMaximum |
| Range | {AutomaticContextMaximum, LinkManuallyEditable} |
|
See 'Center of Gravity' for an explanation of the Center of Gravity feature. Note that the output is the image moment M10. To receive a pixel coordinate for the Center of Gravity X, either use the DIV operator or divide the value by the area on the target host. If you set AutomaticContextMaximum, the
operator automatically sets the bits for the maximum size of an object. Since
there is no real maximum height for a 1D image, a maximum height of
Note that even in automatic mode, the maximum value is limited to 48 bits. This means that just because it's set to AutomaticContextMaximum, the value won't automatically be sufficient to prevent overflows. If the maximum possible CenterX (image moment M10) value is known, or only objects of a specific X-coordinate are of interest, Basler recommends to use the mode LinkManuallyEditable. This saves resources and improves the build time of the entire design. In the LinkManuallyEditable mode, you can edit the bit width property of the link within the allowed range of [1, 48]. The bit width of the link directly translates to the bit width used internally for calculating the CenterX feature and therefore impacts the overall resource consumption. If the bit width is not sufficient for the CenterX value of an object, it is indicated by the ErrorFlagO link (bit 2). |
|
| GenerateCenterXOverflowEvents | |
|---|---|
| Type | static parameter |
| Default | false |
| Range | {true, false} |
|
When the CenterX value of the object exceeds the bit width of the CenterX link, the object is output in its intermediate state. The object is still internally processed and continued, but it is an intermediate result of the object that has been output. Objects output due to an CenterX OverflowEvent are tagged with bit 3 of ErrorFlagsO. |
|
| CenterYBitWidthMode | |
|---|---|
| Type | static parameter |
| Default | AutomaticContextMaximum |
| Range | {AutomaticContextMaximum, LinkManuallyEditable} |
|
See 'Center of Gravity' for an explanation of the Center of Gravity feature. Note that the output is the image moment M10. To receive a pixel coordinate for the Center of Gravity Y, either use the DIV operator or divide the value by the area on the host PC. If you set AutomaticContextMaximum, the
operator automatically sets the bits for the maximum size of an object. Since
there is no real maximum height for a 1D image, a maximum height of
Note that even in automatic mode, the maximum value is limited to 48 bits. This means that just because it's set to AutomaticContextMaximum, the value won't automatically be sufficient to prevent overflows. If the maximum possible CenterY (image moment M10) value is known, or only objects of a specific Y-coordinate are of interest, Basler recommends to use the mode LinkManuallyEditable. This saves resources and improves the build time of the entire design. In the LinkManuallyEditable mode, you can edit the bit width property of the link within the allowed range of [1, 48]. The bit width of the link directly translates to the bit width used internally for calculating the Area feature and therefore impacts the overall resource consumption. If the bit width is not sufficient for the CenterY value of an object, it is indicated by the ErrorFlagO link (bit 4). |
|
| GenerateCenterYOverflowEvents | |
|---|---|
| Type | static parameter |
| Default | false |
| Range | {true, false} |
|
When the CenterY value of the object exceeds the bit width of the CenterY link, the object is output in its intermediate state. The object is still internally processed and continued, but it is an intermediate result of the object that has been output. Objects output due to an CenterY OverflowEvent are tagged with bit 5 of ErrorFlagsO. |
|
The use of operator BlobDetector1D is shown in the following examples:
-
Examples - Shows the usage of operator BlobDetector1D in line scan applications.
Prev
