F_VN_FindContoursExp

F_VN_FindContoursExp 1:

Search for object contours in a binary image. (expert function)
Can use available TwinCAT Job Tasks for executing parallel code regions.
Can return partial results when canceled by Watchdog.

Syntax

Definition:

FUNCTION F_VN_FindContoursExp : HRESULT
VAR_INPUT
    ipSrcImage           : ITcVnImage;
    ipContours           : Reference To ITcVnContainer;
    eRetrievalMode       : ETcVnContourRetrievalMode;
    eApproximationMethod : ETcVnContourApproximationMethod;
END_VAR
VAR_IN_OUT
    aOffset              : TcVnPoint;
END_VAR
VAR_INPUT
    hrPrev               : HRESULT;
END_VAR

F_VN_FindContoursExp 2: 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.)

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.)

F_VN_FindContoursExp 3: In/Outputs

Name

Type

Description

aOffset

TcVnPoint

Offset by which every contour point is shifted

F_VN_FindContoursExp 4: Return value

HRESULT

Further information

The function F_VN_FindContoursExp is the expert version of F_VN_FindContours. It contains additional parameters.

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.

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.

Application

The finding of all contours in the input image, where the contour points are not approximated, but shifted by 100 px in the x direction and by -50 px in the y direction, looks like this, for example:

VAR
    aOffset :   TcVnPoint   :=  [100, -50];
END_VAR

hr := F_VN_FindContours(
    ipSrcImage              :=  ipImageIn,
    ipContours              :=  ipContours,
    eRetrievalMode          :=  TCVN_CRM_LIST,
    eApproximationMethod    :=  TCVN_CAM_NONE,
    aOffset                 :=  aOffset,

    hrPrev                  :=  hr
);

Samples

Related functions

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