F_VN_FindContourHierarchyExp

Syntax

Definition:

FUNCTION F_VN_FindContourHierarchyExp : HRESULT
VAR_INPUT
    ipSrcImage           : ITcVnImage;
    ipContours           : Reference To  ITcVnContainer;
    ipHierarchy          : Reference To  ITcVnContainer;
    eRetrievalMode       : ETcVnContourRetrievalMode;
    eApproximationMethod : ETcVnContourApproximationMethod;
END_VAR
VAR_IN_OUT
    aOffset              : TcVnPoint;
END_VAR
VAR_INPUT
    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.)
ipHierarchy	Reference To ITcVnContainer	Returns a container which is filled with information on the found contours' hierarchy (ContainerType_Vector_TcVnVector4_DINT; The elements of this container are four-dimensional vectors containing the 0-based indices of the next [0] and the previous contour [1] at the same level, the first child [2], and the parent [3]. Non-zero interface pointers are reused.)
eRetrievalMode	ETcVnContourRetrievalMode	Specifies which contours are retrieved and how their relationship is encoded
eApproximationMethod	ETcVnContourApproximationMethod	Contour encoding
hrPrev	HRESULT	HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.)

In/Outputs

Name	Type	Description
aOffset	TcVnPoint	Offset by which every contour point is shifted

Return value

HRESULT

Further information

The function F_VN_FindContourHierarchyExp is an extension of the function F_VN_FindContoursExp by the return of the contour hierarchy.

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.

Hierarchy ^{(Expert, return value)}

The parameter ipHierarchy returns the hierarchy of the contours found in a container of the type TcVnVector4_DINT. The vectors of the container have the following elements:

[0] – NEXT - Index of the next contour on the same level
[1] – PREVIOUS - Index of the previous contour on the same level
[2] – CHILD - Index of the first child contour
[3] – PARENT - Index of parent contour

Search mode ^(Expert)

The search mode eRetrievalMode of the type ETcVnContourRetrievalMode defines which contours are to be sought:

TCVN_CRM_LIST: All contours
TCVN_CRM_EXTERNAL: Only outer contours (as with F_VN_FindContours)
TCVN_CRM_CONNECTED_COMPONENTS: Contours with a two-layer hierarchy
TCVN_CRM_TREE: All contours; used in interaction with the function F_VN_FindContourHierarchyExp in order to determine the hierarchy of the contours
TCVN_CRM_FLOODFILL: Returns the contours found with the help of a floodfill algorithm (available only for DINT images)

Approximation method ^(Expert)

The approximation method eApproximationMethod of the type ETcVnContourApproximationMethod specifies whether the contours are to be described on the basis of all surrounding points (TCVN_CAM_NONE) or whether the number of describing points are to be reduced with the help of approximation.

Offset ^(Expert)

The offset aOffset defines constant X/Y values by which all contour points are shifted. This can be helpful when contours are sought in an ROI and their positions should be referenced to the original image.

Examples of contour hierarchies

Via eRetrievalMode, not only is it possible to specify whether all contours or just the outer contours are to be found, but also how contours are to be sorted and how they are hierarchically related to one another. This can be read from the parameter ipHierarchy:

TCVN_CRM_EXTERNAL
Only the outer contours are returned as a sorted list. The Child [2] and Parent [3] relationships are not determined and are invalid with -1.

F_VN_FindContourHierarchyExp 5:

TCVN_CRM_LIST
All contours are returned as a sorted list. The Child [2] and Parent [3] relationships are not determined and are invalid with -1.

F_VN_FindContourHierarchyExp 6:

TCVN_CRM_CONNECTED_COMPONENTS
All contours are sorted according to a 2-step hierarchy. The outer contours are considered first, then in the second step the contour lying directly within them. If there are further contours within the second step, they are set to the first step like outer contours
In this sample, this means that the inner Child [2] contours (green in the image) cannot be Parent [3] contours (red in the image) at the same time. Therefore, contours that would lie in a tree structure at Level 3 are regarded again as outer contours and set to Level 1 (Parent [3] = -1), in this case contours 1 and 2.

F_VN_FindContourHierarchyExp 7:

TCVN_CRM_TREE
All contours are set according to a tree structure. It is possible for contours to be both Child [2] and Parent [3] contours, depending on how they are nested within one another.

F_VN_FindContourHierarchyExp 8:

Samples

Find Contour - Hierarchy & Retrieval Mode, for the parameter ETcVnContourRetrievalMode
Find Contour - Approximation Method, for parameter ETcVnContourApproximationMethod
Find contour instead of Blob Detection, for comparison with function F_VN_DetectBlobs

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