F_VN_FindContourHierarchyExp

F_VN_FindContourHierarchyExp 1:

Search for object contours in a binary image and determine their hierarchical relationship. (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_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

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

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

F_VN_FindContourHierarchyExp 3: In/Outputs

Name

Type

Description

aOffset

TcVnPoint

Offset by which every contour point is shifted

F_VN_FindContourHierarchyExp 4: Return value

HRESULT

Weiterführende Informationen

Die Funktion F_VN_FindContourHierarchyExp ist eine Erweiterung der Funktion F_VN_FindContoursExp um die Rückgabe der Konturhierarchie.

Parameter

Eingangsbild

Das Eingangsbild ipSrcImage muss genau 1 Kanal haben und sollte ein Binärbild sein.

Falls das Eingangsbild kein Binärbild ist, wird es intern mittels eines Schwellwerts von 1 in eins umgewandelt. Daher sollte das Eingangsbild manuell mit einem Schwellwert oder einer binären Segmentierung vorverarbeitet werden.

Liste an gefundenen Konturen (Rückgabewert)

Alle im Eingangsbild gefundenen Konturen werden in dem Container ipContours zurückgegeben. Der Container ist ein zweidimensionales Array von Punkten und hat daher den Typ ContainerType_Vector_Vector_TcVnPoint2_DINT.

Zurückgegeben werden die gefundenen Konturen in ipContours. Dabei setzt sich jede Kontur aus einer Summe von Punkten zusammen, welche in einem Container zusammengefasst werden. Ein weiterer übergeordneter Container fasst dann nochmal alle Konturen zusammen.

Hierarchie (Expert, Rückgabewert)

Der Parameter ipHierarchy gibt die Hierarchie der gefundenen Konturen in einem Container vom Typ TcVnVector4_DINT zurück. Die Vektoren des Containers haben folgende Elemente:

[0] – NEXT – Index der nächsten Kontur auf gleicher Ebene (gleichem Level)
[1] – PREVIOUS – Index der vorherigen Kontur auf gleicher Ebene (gleichem Level)
[2] – CHILD – Index der ersten Kind-Kontur
[3] – PARENT – Index der Eltern-Kontur

Suchmodus (Expert)

Der Suchmodus eRetrievalMode vom Typ ETcVnContourRetrievalMode legt fest, nach welchen Konturen gesucht wird:

  • TCVN_CRM_LIST: Alle Konturen
  • TCVN_CRM_EXTERNAL: Nur Außenkonturen (wie bei F_VN_FindContours)
  • TCVN_CRM_CONNECTED_COMPONENTS: Konturen mit einer zweischichtigen Hierarchie
  • TCVN_CRM_TREE: Alle Konturen; wird verwendet im Zusammenspiel mit der Funktion F_VN_FindContourHierarchyExp, um die Hierarchie der Konturen zu bestimmen
  • TCVN_CRM_FLOODFILL: Gibt die gefundenen Konturen mit Hilfe eines Floodfill-Algorithmus zurück (nur für DINT-Bilder verfügbar)

Approximationsart (Expert)

Die Approximationsart eApproximationMethod vom Typ ETcVnContourApproximationMethod legt fest, ob die Konturen anhand aller umschließender Punkte beschrieben werden sollen (TCVN_CAM_NONE) oder ob die Anzahl der beschreibenden Punkte mit Hilfe von Approximation reduziert werden soll.

Offset (Expert)

Das Offset aOffset legt konstante X-/Y-Werte fest, um die alle Konturpunkte verschoben werden. Dies kann hilfreich sein, wenn Konturen in einer ROI gesucht werden und ihre Positionen sich auf das Originalbild beziehen sollen.

Beispiele von Konturhierarchien

Über eRetrievalMode kann nicht nur unterschieden werden ob alle Konturen oder nur die äußeren gefunden werden sollen, sondern auch wie Konturen sortiert werden sollen und wie sie hierarchisch in Beziehung stehen. Dies kann am Parameter ipHierarchy abgelesen werden:

F_VN_FindContourHierarchyExp 5:

F_VN_FindContourHierarchyExp 6:

F_VN_FindContourHierarchyExp 7:

F_VN_FindContourHierarchyExp 8:

Beispiele

Verwandte Funktionen

Required License

TC3 Vision Base

System Requirements

Development environment

Target platform

PLC libraries to include

TwinCAT V3.1. 4024.44 or later

PC or CX (x64) with PL50, e.g. Intel 4-core Atom CPU

Tc3_Vision