F_VN_TrainImageColorExp2

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

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

Return value

HRESULT

Further information

The function F_VN_TrainImageColorExp2 is the extended expert version of F_VN_TrainImageColorExp. It contains further parameters. If the trained color model is to be saved to disk, the F_VN_TrainImageColorExp2_ITcVnMlModel with the type ITcVnMlModel must be used.

Parameter

Reference image

The reference image ipSrcImage must have 3 channels in RGB format and the element type USINT (8-bit).

Color model

The parameter ipColorModel returns the trained color model. This is an interface pointer of the type ITcVnColorModel.

Number of colors to be distinguished

The number nDifferentColors defines the number of colors to be trained. Note that the image background, for example, can also have its own color.

Clustering algorithm

When selecting the clustering algorithm, KMeans++ (fixed number of clusters) and LBG (dynamic number of clusters) are available.

Maximum cluster radius

Used only with the LBG cluster algorithm. This can be used to influence the distribution of the individual clusters.

Global optimization

Used only with the LBG cluster algorithm. This allows a choice between shorter execution time (bSingleSplitSteps = FALSE) and improved results (bSingleSplitSteps = TRUE).

Less frequent use of global optimization is faster, but may lead to less optimal results.

Application

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

Related functions

There are three ways to pass the reference color to the corresponding F_VN_ReferenceColorSimilarity function:

As a trained color model of the type ITcVnColorModel
As a trained color model of the type ITcVnMlModel
Directly with values in a TcVnVector3_LREAL

For the color models there are corresponding functions for training and for all three data types one function each for execution:

F_VN_TrainImageColor for the training of a color model
F_VN_ReferenceColorSimilarity for segmentation by means of a color model

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