Barcode (CVCBarcode.dll) 15.0
Decoding

Functions

short CvcBcDecodeBarcode (IMG image, long plane, RECT *prc, CVC_BC_DIRECTION direction, CVC_BC_CONFIG config, char code[], short max_num_codechar, CVC_BC_INFO *pinfo, short size_of_info)
 This function initiates the decoding of barcodes. More...
 
void CvcBcGetReadout (CVC_BC_CONFIG config, short *num_angle, short *num_stripe, short *range)
 This function reads the current readout parameters for a given configuration, which determines the actual scanning pattern. More...
 
short CvcBcSetReadout (CVC_BC_CONFIG config, short num_angle, short num_stripe, short range)
 This function sets the parameters for profile generation. More...
 
short CvcBcTeachDottedDataMatrix (IMG image, long plane, RECT *prc, CVC_BC_DIRECTION direction, CVC_BC_CONFIG config, char code[], short max_num_codechar, CVC_BC_INFO *pinfo, short size_of_info)
 This function teach the parameters for decoding a unknown two-dimensional dotted Data Matrix barcode. The invocation is the same as CvcBcDecodeBarcode. More...
 

Detailed Description

Function Documentation

◆ CvcBcDecodeBarcode()

short CvcBcDecodeBarcode ( IMG  image,
long  plane,
RECT *  prc,
CVC_BC_DIRECTION  direction,
CVC_BC_CONFIG  config,
char  code[],
short  max_num_codechar,
CVC_BC_INFO pinfo,
short  size_of_info 
)

This function initiates the decoding of barcodes.

This function is the key function for the decoding of barcodes. In general, you pass the function image handle of a Common Vision image object and a code pointer to this data area to which the decoded barcode should be written. The individual parameters are described below.

Attention
To a great extent, the function runtime depends on the computer used. Experience shows that it is at its lowest on PCs with PCI bus and MMX-Pentium processors. In the case of slow systems, you can restrict the runtime (see CvcBcSetTimeLimit).
Parameters
[in]imageHandle of the image object in which the barcode is searched.

The image parameter contains the handle of the Common Vision image object in which barcodes are to be read. Such an object can be created, for example, with the LoadImageFile function from the Common Vision Blox Image DLL. A Common Vision image object can be a file, for example in Windows bitmap format, or a Common Vision Blox hardware driver used to address an image processing board. In the simplest case, such an object may be created using the call LoadImageFile("image.bmp", image).

The image object may consist of any number of planes, also known as frames or colour channels. However, all the planes must be 8 bits deep and are considered to be unsigned. The maximum possible extension of the image object in the X and Y direction is specified by the constant CVC_BC_MAX_LINE_LENGTH. If the image object is larger, the search area is automatically restricted to the maximum permitted area.
[in]planeThe plane (the colour separation) in which the barcode is searched, or null if only one plane is present.

The plane parameter specifies the plane in which the barcode is to be searched for. Image processing hardware for black-and-white cameras usually has only one plane. Since, under Common Vision Blox, planes are numbered from zero onwards, it is also possible to pass the value zero. However, multi camera systems or colour cameras may contain multiple planes, with the result that values greater than zero may also be required.
[in]prcPointer to a RECT structure which specifies the area in the image in which the barcode is searched.

The prc parameter is a pointer to a Windows RECT structure which is used to restrict the barcode search to a rectangular area within the image object. In this way it is possible to read two or more different barcodes in an image by restricting the search to the area occupied by the barcode. If the entire image were to be specified, the search would terminate when the first barcode is found. You can also pass NULL for the prc parameter; the entire image area is then searched automatically.
[in]directionOrientation of the barcode.

The direction parameter specifies the orientation in which a barcode is expected to occur. This specification is only of use in one-dimensional and stacked two-dimensional barcodes (such as PDF 417). Matrix codes, such as Data Matrix, are always read irrespective of orientation in which they occur.

Please refer to CVC_BC_DIRECTION for possible values.
[in]configConfiguration handle created with CvcBcCreateConfiguration.

The config parameter is a handle to a so-called configuration. A configuration specifies all the conditions which need to be taken into consideration when acquiring barcodes. I.e., which barcodes are to be recognised and what restrictions apply.

A configuration is generated with the function CvcBcCreateConfiguration and specified in more detail with the CvcBcSet...() functions (see chapter Configurations).

You can also pass the NULL value for the config parameter if you want to use the default configuration. This configuration initially permits all barcodes. However, you can subsequently modify this by calling the CvcBcSet...() functions.
[in]codePointer to a memory area in which the decoded data is stored.

The code parameter is a pointer to a memory area in which the CvcBcDecodeBarcode function stores the decoded information. The function automatically adds a Null character at the end of the data information or sets a null character at the first code position if no barcode was found. Thus code always points to a null-terminated or void string.

However, some barcodes do allow you to encode binary data, such as null characters. In such cases it is not sufficient simply to append an additional null character in order to indicate the end of the decoded data. For this reason the CvcBcDecodeBarcode function also returns the number of decoded characters without the terminating null character as the function result.
[in]max_num_codecharSize of the memory area.

The max_num_codechar parameter specifies the number of bytes present in the memory area to which code points. If code is a field of char and not a pointer, you can simply specify sizeof(code) here.

If the decoded information is greater than max_num_codechar characters, the remainder of the information is truncated and the number of truncated characters counted.

Here is an example. The code pointer points to a field of 10 characters. max_num_codechar therefore has the value 10. If a barcode with precisely 10 characters is now decoded, the first 9 characters of the barcode and the
terminating null character are present in the
code field after the CvcBcDecodeBarcode call.
The number of truncated characters in this
example is 1 and this value is entered in the
char_truncated element of the pinfo structure.

A barcode decoded using this library may comprise
a maximum of CVC_BC_MAX_NUM_CODECHAR
characters including the terminating null
character. Thus a field of this size is always
large enough.
[out]pinfoPointer to a CVC_BC_INFO structure in which
information about the decoded barcode is stored.

The pinfo parameter is a pointer to a structure of type CVC_BC_INFO. It stores information
related to the encoded barcode. The structure
element type specifies which barcode symbology
was found. This is indicated by one of the
constants from CVC_BC_TYPE. The char_read
element contains the number of decoded characters
excluding the terminating null character and
therefore corresponds to the return value of the
function following error-free processing.

As described above, the char_truncated
structure element contains the number of
characters which do not fit into the specified
memory area.

The num_digits structure element specifies
the number of code words which formed the decoded
barcode. This specification has a different
meaning for different symbologies (see chapter Fundamentals of barcode acquisition).

Attention: If you don't need the pinfo parameter you can pass the value NULL in its place.
[in]size_of_infoSize of the CVC_BC_INFO structure.
Returns
The return value of the function is normally the number of read characters or Null, if no barcode was found in the image. If an error occurs during function execution, the return value is negative and described by one the following error constants:
CVC_BC_NO_IMAGE, CVC_BC_NOT_8BIT, CVC_BC_INVALID_PLANE, CVC_BC_INVALID_RECT, CVC_BC_NO_MEMORY, or CVC_BC_NO_FREE_CONFIGURATION.
Supported platforms:
Win32
Win64

◆ CvcBcGetReadout()

void CvcBcGetReadout ( CVC_BC_CONFIG  config,
short *  num_angle,
short *  num_stripe,
short *  range 
)

This function reads the current readout parameters for a given configuration, which determines the actual scanning pattern.

Please read Readout Modes for a more precise description.

Parameters
[in]configHandle to the configuration or NULL to use the default configuration.
[in]num_anglePointer to the number of profile rotations.
[in]num_stripePointer to the number of profile lines.
[in]rangePointer to the number of pixels between profile lines.
Supported platforms:
Win32
Win64
Related Topics:
CVC_BC_DIRECTION
CvcBcSetReadout

◆ CvcBcSetReadout()

short CvcBcSetReadout ( CVC_BC_CONFIG  config,
short  num_angle,
short  num_stripe,
short  range 
)

This function sets the parameters for profile generation.

These values define a specific pattern of lines depending on CVC_BC_DIRECTION (see Readout modes), which are virtually put on top of the acquired image. The actual processing routine uses any single line of the pattern to determine if it runs over a barcode. If so, the detected barcode will be read within the next step.

The readout configuration is an implicit part of the CVC_BC_CONFIG, since it provides a possibility to further adjust CVC_BC_DIRECTION. When not specifically configured, the following default parameter values are going to be used:

num_angle = 10
num_stripe = 10
range = 20

The chosen CVC_BC_DIRECTION determines which one(s) of the parameters are actually used. Please read Readout Modes for a more precise description.

Parameters
[in]configHandle to the configuration or NULL to use the default configuration.
[in]num_angleAbsolute number of profile rotations.
[in]num_stripeAbsolute number of profile lines.
[in]rangeDistance between lines in pixel.
Returns
CVC_BC_NO_ERROR on success, otherwise CVC_BC_PARAMETER_WARNING.
Supported platforms:
Win32
Win64
Related Topics:
CVC_BC_DIRECTION
CvcBcGetReadout

◆ CvcBcTeachDottedDataMatrix()

short CvcBcTeachDottedDataMatrix ( IMG  image,
long  plane,
RECT *  prc,
CVC_BC_DIRECTION  direction,
CVC_BC_CONFIG  config,
char  code[],
short  max_num_codechar,
CVC_BC_INFO pinfo,
short  size_of_info 
)

This function teach the parameters for decoding a unknown two-dimensional dotted Data Matrix barcode. The invocation is the same as CvcBcDecodeBarcode.

Before you can teach a dotted Data Matrix there have to be done some settings with the CvcBcSetDataMatrixEx function. The user must set the parameters:
dm_types, dm_format, rectangular, mirror, invers, distorted, quietzone and the parameter dm_ex_types = CVC_BC_DM_EX_DOTTED_DATAMATRIX.

Set the parameter direction in the CvcBcTeachDottedDataMatrix to CVC_BC_FENCE, CVC_BC_LADDER, CVC_BC_BOTH or, CVC_BC_OMNI but not to CVC_BC_SMALL_CODES.

Remark: If the time limit is to short the CvcBcTeachDottedDataMatrix fails. The CvcBcTeachDottedDataMatrix function takes some seconds.

The function also changes the following parameters of the Data Matrix structure without asking the user:

min_size minimum number of lines and columns
max_size maximum number of lines and columns
contrast_min minimal contrast value of the code
modulwidth modulwidth of the code

For example:
You teach a quadratic dotted Data Matrix code with 18x18 modules. The CvcBcTeachDottedDataMatrix function read the code and set the parameters min_size = 18 and max_size = 18. Because you also want to read dotted Data Matrix codes with the size 16x16, 20x20 and 22x22 you get the full parameters with the function CvcBcGetDataMatrixEx, than you only change min_size to 16 and max_size to 22 and set the parameters again with the function CvcBcSetDataMatrixEx. The maximum size for dotted Data Matrix codes is: quadratic codes up to 32x32 and rectangular codes up to 8x32 resp. 12x26 modules.

Remark: If you set the dm_ex_types = CVC_BC_DM_EX_DATAMATRIX or dm_ex_types = CVC_BC_DM_EX_2D_PHARMACODE and not modify the parameters min_size and max_size again you have still the changed parameters.

Note
The function is new in CVB 8.0 with Barcode Version 2.2.
Parameters
[in]imageHandle of the image object in which the barcode is searched.
[in]planeThe plane (the colour separation) in which the barcode is searched, or null if only one plane is present.
[in]prcPointer to a RECT structure which specifies the area in the image in which the barcode is searched.
[in]directionOrientation of the barcode.
[in]configConfiguration handle created with CvcBcCreateConfiguration.
[in]codePointer to a memory area in which the decoded data is stored.
[in]max_num_codecharSize of the memory area.
[out]pinfoPointer to a CVC_BC_INFO structure in which
information about the decoded barcode is stored.
[in]size_of_infoSize of the CVC_BC_INFO structure.
Returns
CVC_BC_NO_ERROR on success. If CvcBcTeachDottedDataMatrix function is successful then the decoded data is stored in the memory area code and the information about the decoded barcode is stored in pinfo.
Supported platforms:
Win32
Win64
Related Topics:
Data Matrix specification
CvcBcSetDataMatrixEx