F_VN_TrainImageColorExp2

F_VN_TrainImageColorExp2 1:

Create a new color model, describing the image color. (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_TrainImageColorExp2 : HRESULT
VAR_INPUT
    ipSrcImage           : ITcVnImage;
    ipColorModel         : Reference To  ITcVnColorModel;
    nDifferentColors     : UDINT;
    eMethod              : ETcVnColorTrainingMethod;
    ipMask               : ITcVnImage;
    nSkipPixels          : UDINT;
    eClusteringAlgorithm : ETcVnClusteringAlgorithm;
    nMaxClusterRadius    : DINT;
    bSingleSplitSteps    : BOOL;
    hrPrev               : HRESULT;
END_VAR

F_VN_TrainImageColorExp2 2: Inputs

Name

Type

Description

ipSrcImage

ITcVnImage

Source image (3 channels (RGB) of type USINT)

ipColorModel

Reference To ITcVnColorModel

Returns the color model

nDifferentColors

UDINT

Maximum number of different colors to distinguish (if LBG is used as a clustering algorithm, the result might have less different colors, depending on nMaxClusterRadius)

eMethod

ETcVnColorTrainingMethod

Color training method

ipMask

ITcVnImage

Optional image mask (1 channel of type USINT, set to 0 if not required)

nSkipPixels

UDINT

Number of pixels to skip between each evaluated color sample (to achieve a better performance). 0 takes every pixel into account and tends to be more accurate.

eClusteringAlgorithm

ETcVnClusteringAlgorithm

Clustering algorithm

nMaxClusterRadius

DINT

Only used for the LBG clustering algorithm. Maximum allowed radius (> 0) of a single cluster, i.e. clusters with a higher radius will be split into smaller ones, until a global number of nDifferentColors is reached.

bSingleSplitSteps

BOOL

Only used for the LBG clustering algorithm. If true, the global optimization is always run after a single cluster has been split. If false, several clusters are split within the same step before applying the global optimization. Applying the global optimization less often is faster, but can lead to less optimal results, especially having 2 nearby clusters that could be represented by 1)

hrPrev

HRESULT

HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.)

F_VN_TrainImageColorExp2 3: Return value

HRESULT

Weiterführende Informationen

Die Funktion F_VN_TrainImageColorExp2 ist die erweiterte Expert-Variante von F_VN_TrainImageColorExp. Sie enthält weitere Parameter. Wenn das Trainierte Farbmodell auf der Festplatte gespeichert werden soll, muss die F_VN_TrainImageColorExp2_ITcVnMlModel mit dem Typ ITcVnMlModel verwendet werden.

Parameter

Referenzbild

Das Referenzbild ipSrcImage muss 3 Kanäle im RGB-Format und den Element-Typ USINT (8 Bit) haben.

Farbmodell

Der Parameter ipColorModel gibt das trainierte Farbmodell zurück. Dieses ist ein Interface Pointer vom Typ ITcVnColorModel.

Anzahl zu unterscheidender Farben

Die Anzahl nDifferentColors definiert die Anzahl an zu trainierenden Farben. Achten Sie darauf, der Bildhintergrund z. B. auch eine eigene Farbe sein kann.

Clustering-Algorithmus

Bei der Auswahl des Clustering-Algorithmus stehen KMeans++ (feste Anzahl von Clustern) und LBG (dynamische Anzahl von Clustern) zur Verfügung.

Maximaler Cluster-Radius

Wird nur beim LBG-Clusteralgorithmus verwendet. Damit kann die Aufteilung der einzelnen Cluster beeinflusst werden.

Globale Optimierung

Wird nur beim LBG-Clusteralgorithmus verwendet. Damit kann zwischen kürzerer Ausführungszeit (bSingleSplitSteps = FALSE) und verbesserten Ergebnissen (bSingleSplitSteps = TRUE) gewählt werden.

Eine seltenere Anwendung der globalen Optimierung ist schneller, kann aber zu weniger optimalen Ergebnissen führen.

Anwendung

VAR
    ipColorModel    :   ITcVnColorModel;
END_VAR

hr := F_VN_TrainImageColorExp2(
            ipSrcImage          := ipImageRef,
            ipColorModel        := ipColorModel,
            nDifferentColors    := 5, // 4 colors + 1 background = 5
            eMethod             := TCVN_CTM_LAB,
            ipMask              := 0,
            nSkipPixels         := 3,
            eClusteringAlgorithm:= TCVN_CA_KMEANSPP,
            nMaxClusterRadius   := 0,
            bSingleSplitSteps   := FALSE,
            hrPrev              := hr);

Verwandte Funktionen

Es gibt drei Möglichkeiten die Referenzfarbe an die entsprechende F_VN_ReferenceColorSimilarity Funktion zu übergeben:

  • Als trainiertes Farbmodell vom Typ ITcVnColorModel
  • Als trainiertes Farbmodell vom Typ ITcVnMlModel
  • Direkt mit Werten in einem TcVnVector3_LREAL

Für die Farbmodelle gibt es entsprechende Funktionen zum Trainieren und für alle drei Datentypen jeweils eine Funktion zur Ausführung:

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 PL50, e.g. Intel 4-core Atom CPU

Tc3_Vision