F_VN_ReadDataMatrixCodeRoiExp

Detect and interpret a data matrix code (ECC200) within the provided image. The code should be in the image center. (expert function)
Can use available TwinCAT Job Tasks for executing parallel code regions.

Syntax

Definition:

FUNCTION F_VN_ReadDataMatrixCodeRoiExp : HRESULT
VAR_INPUT
    ipSrcImage       : ITcVnImage;
    ipDecodedData    : Reference To  ITcVnContainer;
    fModuleWidth     : REAL;
    ipContour        : Reference To  ITcVnContainer;
    eOptions         : ULINT;
    nRows            : USINT;
    nCols            : USINT;
    bExtensiveSearch : BOOL;
    hrPrev           : HRESULT;
END_VAR
VAR_OUTPUT
    fAngleDeg        : REAL;
END_VAR

Inputs

Name	Type	Description
ipSrcImage	ITcVnImage	Source image (USINT elements, 1 channel)
ipDecodedData	Reference To ITcVnContainer	Returns the decoded code (ContainerType_String_SINT)
fModuleWidth	REAL	Minimum module width of the code in the image (in pixels). Must be at least 3, preferably 5 - 8.
ipContour	Reference To ITcVnContainer	Returns the contour of the detected code (ContainerType_Vector_TcVnPoint2_DINT; optional, set to 0 if not required)
eOptions	ULINT	Specifies a combination of one or more ETcVnDataMatrixOptions
nRows	USINT	Specifies the number of code module rows, including the finder and clock pattern, excluding the quiet zone (8 - 144; set to 0 to search for any size)
nCols	USINT	Specifies the number of code module columns, including the finder and clock pattern, excluding the quiet zone (10 - 144; set to 0 to search for any size)
bExtensiveSearch	BOOL	If true, tries different approaches if the specified options fail
hrPrev	HRESULT	HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.)

Outputs

Name	Type	Description
fAngleDeg	REAL	Returns the clockwise rotation angle in degree

Return value

HRESULT

Required License

TC3 Vision Code Reading

Further information

The F_VN_ReadDataMatrixCodeRoiExp function is the expert variant of F_VN_ReadDataMatrixCodeRoi and contains additional parameters.

ipContour

The ipContour parameter returns the code corner points as four contour points of the type ContainerType_Vector_TcVnPoint2_DINT. The corner points are at the edge of the outer modules. The contour can be drawn directly with F_VN_DrawContours, for example, or further analyzed with the Contour Analysis functions. This parameter is optional and can be set to 0 if it is not required.

eOptions

The eOptions parameter defines which detection strategies are to be used. There are three groups with mutually exclusive options, of which only one option per group can be selected:

Image pre-processing:

TCVN_DMO_BINARY_INPUT
TCVN_DMO_GLOBAL_THRESHOLD

Grid detection:

TCVN_DMO_BINARY_GRID
TCVN_DMO_STATIC_GRID

Code color mode:

TCVN_DMO_REGULAR_COLOR
TCVN_DMO_INVERTED_COLOR

Each group can be configured individually, e.g. TCVN_DMO_GLOBAL_THRESHOLD OR TCVN_DMO_STATIC_GRID OR TCVN_DMO_REGULAR_COLOR. Invalid combinations such as TCVN_DMO_BINARY_GRID OR TCVN_DMO_STATIC_GRID lead to the error ADS_E_INVALIDPARM.

The default setting TCVN_DMO_DEFAULT uses an adaptive local threshold, a dynamic grid (based on a grayscale image) and detects both color modes. To optimize the computing time, it is recommended to always specify the colour mode explicitly.

A description of the recognition strategies can be found under ETcVnDataMatrixOptions.

nRows and nCols

The parameters nRows and nCols fix the expected number of modules in the vertical (height) or horizontal (width) direction, based on a non-rotated code with the corner point of the L-pattern at the bottom left. Both the finder pattern and the clock pattern of the Data Matrix code must be included in the count. It is recommended that you always set these values in order to reduce the maximum computing time required.

bExtensiveSearch

The bExtensiveSearch parameter activates an advanced search routine that automatically applies alternative decoding strategies if the initial analysis fails.

System Requirements

Development environment	Target platform	PLC libraries to include
TwinCAT V3.1.4024.59 or later	PC or CX (x64) with min. PL50, e.g. Intel 4-core Atom CPU	Tc3_Vision