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]	image	Handle 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]	plane	The 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]	prc	Pointer 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]	direction	Orientation 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]	config	Configuration 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]	code	Pointer 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_codechar	Size 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]	pinfo	Pointer 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_info	Size 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]	config	Handle to the configuration or NULL to use the default configuration.
[in]	num_angle	Pointer to the number of profile rotations.
[in]	num_stripe	Pointer to the number of profile lines.
[in]	range	Pointer 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]	config	Handle to the configuration or NULL to use the default configuration.
[in]	num_angle	Absolute number of profile rotations.
[in]	num_stripe	Absolute number of profile lines.
[in]	range	Distance 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]	image	Handle of the image object in which the barcode is searched.
[in]	plane	The plane (the colour separation) in which the barcode is searched, or null if only one plane is present.
[in]	prc	Pointer to a RECT structure which specifies the area in the image in which the barcode is searched.
[in]	direction	Orientation of the barcode.
[in]	config	Configuration handle created with CvcBcCreateConfiguration.
[in]	code	Pointer to a memory area in which the decoded data is stored.
[in]	max_num_codechar	Size of the memory area.
[out]	pinfo	Pointer to a CVC_BC_INFO structure in which information about the decoded barcode is stored.
[in]	size_of_info	Size 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