F_VN_FindContours

Search for object contours in a binary image. Returns only external contours.
Can use available TwinCAT Job Tasks for executing parallel code regions.
Can return partial results when canceled by Watchdog.

Syntax

Definition:

FUNCTION F_VN_FindContours : HRESULT
VAR_INPUT
    ipSrcImage : ITcVnImage;
    ipContours : Reference To  ITcVnContainer;
    hrPrev     : HRESULT;
END_VAR

Inputs

Name	Type	Description
ipSrcImage	ITcVnImage	Source image (1 channel, binary)
ipContours	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.)

Return value

HRESULT

Further information

The function F_VN_FindContours detects outer contours in the input image.

Parameter

Input image

The input image ipSrcImage must have precisely 1 channel and should be a binary image.

If the input is not a binary image, it will be converted internally to one by means of a threshold value of 1. Therefore, the input image should be manually pre-processed with a threshold value or a binary segmentation.

List of contours found ^{(Return value)}

All contours found in the input image are returned in the container ipContours. The container is a two-dimensional array of points and therefore has the type ContainerType_Vector_Vector_TcVnPoint2_DINT.

The contours that are found are returned in ipContours. Each contour consists of a sum of points which are combined into a container. Another higher-level container then consolidates all contours.

Expert parameters

The expert version F_VN_FindContoursExp contains additional parameters. This enables inner contours to be found too, for example.

Application

The finding and processing of contours looks like this, for example:

Pre-processing

As a binary image is to be used for the input image ipSrcImage, a threshold value or binary segmentation should be applied to the image prior to the function call, e.g. using the function F_VN_Threshold:

hr := F_VN_Threshold(ipImageIn, ipImageWork, 128, 255, TCVN_TT_BINARY, hr);

Function call

Nothing further needs to be observed with regard to the function call. Parameter settings are only necessary with the expert version F_VN_FindContoursExp.

hr := F_VN_FindContours(
    ipSrcImage  :=  ipImageIn,
    ipContours  :=  ipContours,
    hrPrev      :=  hr
);

Further processing

F_VN_GetForwardIterator can be used to apply an iterator to the higher-level container, which makes it possible to retrieve the containers of the individual contours one after the other via F_VN_GetContainer in order to analyze them with the Contour Analysis functions, for example. Remember to increment the iterator with F_VN_IncrementIterator.

hr := F_VN_GetForwardIterator(ipContours, ipIterator, hr);
WHILE SUCCEEDED(hr) AND_THEN ipIterator.CheckIfEnd() <> S_OK DO
    hr := F_VN_GetContainer( ipIterator, ipContour, hr);
    hr := F_VN_IncrementIterator(ipIterator, hr);

    // Analyse the single contour in ipContours with the contour analysis functions

END_WHILE

Alternatively you can also retrieve a single contour from the container of all contours with F_VN_GetAt_ITcVnContainer.

The number of contours found can be queried with F_VN_GetNumberOfElements.

Visualization

Use the function F_VN_DrawContours(Exp) to draw the contours found.

hr := F_VN_DrawContours(
    ipContours      :=  ipContours,
    nContourIndex   :=  -1,
    ipDestImage     :=  ipImageRes,
    aColor          :=  aColorRed,
    nThickness      :=  5,
    hrPrev          :=  hr
);

All contours in the contour list ipContours are drawn by setting nContoursIndex to -1.

Samples

Find contour instead of Blob Detection

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.59 or later	PC or CX (x64) with min. PL50, e.g. Intel 4-core Atom CPU	Tc3_Vision