F_VN_GradeBarcodeExp
Grades a 1D barcode according to ISO / IEC 15416:2016. Requires uniform illumination, good focus and the image sensor plane parallel to the code plane to achieve meaningful results. (expert function)
Syntax
Definition:
FUNCTION F_VN_GradeBarcodeExp : HRESULT
VAR_INPUT
ipSrcImage : ITcVnImage;
ipDecodedData : Reference To ITcVnContainer;
END_VAR
VAR_IN_OUT
stCodeGrades : TcVnCodeGrades1D;
END_VAR
VAR_INPUT
eBarcodeType : ETcVnBarcodeType;
eSearchDirection : ETcVnBarcodeSearchDirection;
ipResultVisualization : Reference To ITcVnImage;
ipScanLineInfo : Reference To ITcVnContainer;
ipContour : Reference To ITcVnContainer;
hrPrev : HRESULT;
END_VAR
VAR_OUTPUT
fAngleDeg : REAL;
END_VAR
Inputs
Name |
Type |
Description |
---|---|---|
ipSrcImage |
Source image, only containing the horizontally aligned barcode region (USINT, 1 channel, including quiet zones on left and right, excluding Text or empty space on more than 10% total height on top or bottom) | |
ipDecodedData |
Reference To ITcVnContainer |
Returns the decoded data (ContainerType_String_SINT) |
eBarcodeType |
Type of the barcode (supported: CODE39, CODE128, EAN8, EAN13, ITF, UPCA, UPCE) | |
eSearchDirection |
Barcode search direction (BSD_ANY first tries horizontal, then vertical) | |
ipResultVisualization |
Reference To ITcVnImage |
Returns a visualization of the scan lines (optional, set to 0 if not required). Grades are color coded: >= 3 as green, >= 2 as light blue, >= 1 as orange, < 1 as red |
ipScanLineInfo |
Reference To ITcVnContainer |
Returns additional scan line info for further evaluation, e.g. to use PlotIntensityProfile for visualization (optional, set to 0 if not required; ContainerType_Vector_TcVnVector3_REAL, containing [row index, overall grade, threshold]) |
ipContour |
Reference To ITcVnContainer |
Returns the 4 approximate code corner points, including the quiet zone (optional, set to 0 if not required; ContainerType_Vector_TcVnPoint2_DINT) |
hrPrev |
HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.) |
In/Outputs
Name |
Type |
Description |
---|---|---|
stCodeGrades |
Returns the code grades in the range from 0 (very bad) to 4 (very good) |
Outputs
Name |
Type |
Description |
---|---|---|
fAngleDeg |
REAL |
Returns the approximate clockwise rotation angle in degree |
Further information
The function F_VN_GradeBarcodeExp
is an expert variant of F_VN_GradeBarcode. It contains additional parameters.
Parameter
Input image
The input image ipSrcImage
must be an 1-channel image with element type USINT
(8 bits). The input image may only contain the code to be checked, including the corresponding quiet zones. The barcode must be aligned horizontally or vertically and must not have any text or blank space more than 10% of the total height above or below it. The quiet zones are located to the left and right of the code when aligned horizontally.
To achieve meaningful results, uniform illumination, not underexposed or overexposed, good focusing on the code plane and an image sensor plane aligned parallel to it are required. Furthermore, the image resolution must be high enough to match the line width. For barcodes, the minimum bar width should be covered by at least 3 pixels in order to achieve good results.
Read data
The data read from the code are returned as a string in the container ipDecodedData
. The container is of the type ContainerType_String_SINT
. Once the code has been successfully found and decoded, the content can be exported to a string using the function F_VN_ExportContainer_String
.
hr := F_VN_ExportSubContainer_String(ipDecodedData, sText, nMaxLength, hr);
Different decoding results Decoding with the respective reference algorithm can lead to deviating results. It is therefore possible that the code content can be read by other devices or functions, but the reference algorithm fails. |
Return of the quality assessment
The return value stCodeGrades
of type TcVnCodeGrades1D contains the determined individual results and an overall total result fOverall
. The quality grades ranges from 0 (very poor) to 4 (very good). The results are averaged over several scan lines.
Parameter | Description |
---|---|
fDecode | Evaluates whether the code could be decoded with the reference algorithm. |
fSymbolContrast | Evaluates the global symbol contrast, i.e. the difference between the brightest and darkest value on the entire scan line. |
fMinReflectance | Evaluates the ratio of the darkest to the brightest value of the scan lines. |
fMinEdgeContrast | Evaluates the minimum local contrast of neighboring elements of the scan lines. |
fModulation | Evaluates the ratio between the minimum local contrast and the global symbol contrast. |
fDefects | Evaluates irregularities within elements and quiet zones. |
fDecodability | Evaluates how reliably the code can be decoded with the reference algorithm. |
fOverall | The overall score of the code is the lowest score achieved in the individual tests, averaged over all scan lines. If different scan lines lead to different decoded data, the overall score is 0. |
Barcode type
The parameter eBarcodeType
defines the barcode type whose print quality is to be assessed. The following barcode types from the enum ETcVnBarcodeType are supported:
TCVN_BT_CODE39
TCVN_BT_CODE128
TCVN_BT_EAN8
TCVN_BT_EAN13
TCVN_BT_ITF
TCVN_BT_UPCA
TCVN_BT_UPCE
Search direction
The search direction can be specified via eSearchDirection
:
- With
TCVN_BSD_ANY
, the search is first carried out in the horizontal direction and then in the vertical direction. - With
TCVN_BSD_HORIZONTAL
, the search is only carried out in a horizontal direction. - With
TCVN_BSD_VERTICAL
, the search is only carried out in the vertical direction.
Presentation of results
ipResultVisualization
returns an image with the visualization of the scan lines and the respective evaluation results. The lines are color-coded according to the individual grades: >= 3
as green, >= 2
as light blue, >= 1
as orange, < 1
as red. This parameter is optional and can be set to 0 if it is not required.
Scan line information
ipScanLineInfo
returns additional information about the individual scan lines for a more detailed evaluation. The return values are of the type ContainerType_Vector_TcVnVector3_REAL
and specify the index of the image row or image column, the total score and the global threshold determined for each scan line, depending on the orientation. The individual lines can be visualized with F_VN_PlotIntensityProfile, for example. This parameter is optional and can be set to 0 if it is not required.
Position of the code
The parameter ipContour
returns the code corner points, including the quiet zone, as four contour points of the type ContainerType_Vector_TcVnPoint2_DINT
. The calculation is based only on the scan lines that could be decoded. 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.
Rotation angle (return value)
fAngleDeg
returns the clockwise rotation angle in 90° steps.
Application
The print quality of a barcode can be determined in this way, for example:
hr := F_VN_GradeBarcodeExp(
ipSrcImage := ipSrcImage,
ipDecodedData := ipDecodedData,
stCodeGrades := stCodeGrades,
eBarcodeType := eBarcodeType,
eSearchDirection := eSearchDirection,
ipResultVisualization := ipResultVisualization,
ipScanLineInfo := ipScanLineInfo,
ipContour := ipContour,
hrPrev := hr,
fAngleDeg => fAngleDeg);
Required License
TC3 Vision Code Quality
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 |