F_VN_DetectBlobs

Detects blob-contours. Applies a threshold, a contour search and offers several options for filtering the found contours. Provides easy setup for multiple thresholds and combination of results.
Can use available TwinCAT Job Tasks for executing parallel code regions.
Can return partial results when canceled by Watchdog.

Syntax

Definition:

FUNCTION F_VN_DetectBlobs : HRESULT
VAR_INPUT
    ipSrcImage     : ITcVnImage;
    ipBlobContours : Reference To  ITcVnContainer;
END_VAR
VAR_IN_OUT
    stParams       : TcVnParamsBlobDetection;
END_VAR
VAR_INPUT
    hrPrev         : HRESULT;
END_VAR

Inputs

Name	Type	Description
ipSrcImage	ITcVnImage	Source image (USINT or REAL, 1 channel or 3 channel (3 channel input is expected to be RGB and internally converted to Gray))
ipBlobContours	Reference To ITcVnContainer	Returns a container which is filled with the found contours (ContainerType_Vector_Vector_TcVnPoint2_DINT; The elements of this container are single contours. Non-zero interface pointers are reused.)
hrPrev	HRESULT	HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.)

In/Outputs

Name	Type	Description
stParams	TcVnParamsBlobDetection	Parameters to filter the detected contours.

Return value

HRESULT

Further information

The function F_VN_DetectBlobs detects blob contours on the basis of definable features in the input image. Internally, this takes place through contour finding analogous to F_VN_FindContours and subsequent filtering of the contours found on the basis of contour features.

Parameter

Input image

The input image ipSrcImage must be a 1-channel or 3-channel image of the type USINT or REAL. 3-channel images are interpreted as RGB and converted internally into grayscale images.

List of contours found ^{(Return value)}

All contours found in the input image are returned in the container ipBlobContours.

Parameters for blob detection

The parameters stParams of the structure TcVnParamsBlobDetection define which features a contour in the input image must have in order to be found and returned.

Expert parameters

The expert version F_VN_DetectBlobsExp contains additional parameters.

Blobs parameters

Threshold value

In the first step, a contour search is carried out internally using one or more binary images. For this purpose, the input image is converted into binary images using one or more threshold values and the threshold value type.

Setting a single threshold value corresponds to calling F_VN_Threshold. To do this, fThresholdStep must be set to 0. Only the value of fMinThreshold is used.

Alternatively, several threshold values can be taken into account. The first threshold value is fMinThreshold. Starting from this value, fThresholdStep is added for the next threshold value until the threshold value is greater than fMaxThreshold. If, for example, the three threshold values 100, 150 and 200 are to be taken into account, the parameterization is as follows:

stBlobParams.fMinThreshold     := 100;
stBlobParams.fMaxThreshold     := 200;
stBlobParams.fThresholdStep    := 50;

Same contours with different threshold values

It may happen that the same contour is found at different threshold values. Identical contours are identified by means of a center point comparison. In this case fMinBlobDistance specifies the minimum center distance of different contours. If the distance is not reached, the contour is selected according to eBlobCombination (ETcVnBlobCombination).

In addition, multiple finding of a contour at different threshold values can be a filter criterion. How often a contour has to be found in order to be considered is specified via nMinRepeatability.

Filter

In the second step, the contours found are filtered according to the defined parameters. The individual filter criteria can be activated via a Boolean variable.

Area in pixels

Parameter: bFilterByArea, fMinArea, fMaxArea
Alternatively, the area of a contour can be determined via F_VN_ContourArea.

Circularity

Parameter: bFilterByCircularity, fMinCicularity, fMaxCircularity
Value range from 0 to 1; a perfect circle has a circularity of 1.
Alternatively, the circularity of a contour can be determined via F_VN_ContourCircularity.

Convexity

Parameter: bFilterByConvexity, fMinConvexity, fMaxConvexity
The value range is from 0 to 1. A perfectly convex shape has a convexity of 1.

Eccentricity

Parameter: bFilterByEccentricity, fMinEccentricity, fMaxEccentricity
Value range from 0 to 1; a perfect circle has an eccentricity of 0.
Alternatively, the eccentricity of a contour can be determined via F_VN_ContourEccentricity.

Inertia ratio

Parameter: bFilterByInertiaRatio, fMinInertiaRatio, fMaxInertiaRatio
Value range from 0 to 1; shapes with the same height and width have an inertia ratio of 1.

Application

VAR
    stBlobParams    :   TcVnParamsBlobDetection;
END_VAR

stBlobParams.bFilterByArea  :=  TRUE;
stBlobParams.fMinArea       :=  100;
stBlobParams.fMaxArea       :=  100_000;

hr := F_VN_DetectBlobs(
    ipSrcImage      :=  ipImageIn,
    ipBlobContours  :=  ipContours,
    stParams        :=  stBlobsParams,
    hrPrev          :=  hr
);

Sample

Blob Detection with watchdog monitoring

Related functions

F_VN_FindContours(Exp) for general contour finding
F_VN_FindContourHierarchyExp with return of the hierarchy
F_VN_DetectBlobs with integrated filtering of the contours

Required License

TC3 Vision Base

System Requirements

Development environment	Target platform	PLC libraries to include
TwinCAT V3.1.4024.54 or later	PC or CX (x64) with PL50, e.g. Intel 4-core Atom CPU	Tc3_Vision