ZXBarcode Functions

Functions
cvbres_t	ZXBinarize (IMG imageIn, cvbdim_t plane, cvbdim_t left, cvbdim_t top, cvbdim_t right, cvbdim_t bottom, TZXBinarizerMode binarizerMode, IMG &imgOut)
	Binarize the input image. More...
cvbres_t	ZXReadCode (IMG imageIn, cvbdim_t plane, cvbdim_t left, cvbdim_t top, cvbdim_t right, cvbdim_t bottom, TZXBinarizerMode binarizerMode, TZXReaderMode readerMode, TZXBarcodeFormats barcodeFormats, TZXResult &result)
	Read one barcode in an image. More...
cvbres_t	ZXReadMultipleCodes (IMG imageIn, cvbdim_t plane, cvbdim_t left, cvbdim_t top, cvbdim_t right, cvbdim_t bottom, TZXBinarizerMode binarizerMode, TZXReaderMode readerMode, TZXBarcodeFormats barcodeFormats, size_t &maxResults, TZXResult *results)
	Read multiple barcodes in an image. More...

Detailed Description

Function Documentation

ZXBinarize()

cvbres_t ZXBinarize	(	IMG	imageIn,
		cvbdim_t	plane,
		cvbdim_t	left,
		cvbdim_t	top,
		cvbdim_t	right,
		cvbdim_t	bottom,
		TZXBinarizerMode	binarizerMode,
		IMG &	imgOut
	)

Binarize the input image.

This function applies the binarizer that the function ZXReadCode is going use internally.

Attention

It is not necessary to apply binarization to an image prior to calling ZXReadCode. ZXReadCode will always automatically binarize the image passed to it. The purpose of the ZXBinarize function is to visualize the effect of binarization when setting up the tool parameters.

Please note that this function is not guaranteed to be thread-safe and we strongly advise against calling it simultaneously from different threads.

This function uses the zxing-cpp library (see https://github.com/glassechidna/zxing-cpp). zxing-cpp is a fork of the zxing project and is published under the Apache v2.0 license which requires applications and libraries that make use of this function to declare in their license information that they are using the zxing-cpp library. This may be done e.g. by adding a link to the zxing-cpp project page and the Apache v2.0 license terms (https://github.com/glassechidna/zxing-cpp/blob/master/COPYING) e.g. to a "Help" or "About" screen. In Common Vision Blox the respective links have been added to the document OpenSourceLicenses.chm.

Parameters

[in]	imageIn	Input image. The plane of the input image to be processed needs to have 8 bits per pixel, otherwise an error will be returned.
[in]	plane	Plane of the input image to be processed. Must be in the range [0...ImageDimension(imageIn)-1]. Note that ZXing Barcode can only process luminance information. If the input image uses a color format, either select a suitable plane or convert it to luminance information before processing it in ZXBarcode.
[in]	left	Left edge of the area of interest.
[in]	top	Top edge of the area of interest.
[in]	right	Right edge of the area of interest.
[in]	bottom	Bottom edge of the area of interest.
[in]	binarizerMode	Selects the binarization algorithm to use. Valid values are taken from the TZXBinarizerMode enumeration.
[out]	imgOut	If the input image was binarized successfully, then imgOut will receive the binarized image.

Returns

This function may return the following error codes (taken from CVCError.h; apply CVC_ERROR_FROM_HRES before comparing!):

Value	Meaning
CVC_E_OK	The input was successfully processed.
CVC_E_NOIMAGE	imageIn does not refer to a valid CVB image.
CVC_E_INVALIDPLANE	plane is outside the range [0...ImageDimension(imageIn)-1]
CVC_E_INVALIDDATATYPE	the selected image plane does not have 8 bits per pixels
CVC_E_PARAMETER	The parameters left, top, right and bottom do not define a valid area of interest or an invalid binarizer mode was specified.
CVC_E_ERROR	an unspecified error occurred

ZXReadCode()

cvbres_t ZXReadCode	(	IMG	imageIn,
		cvbdim_t	plane,
		cvbdim_t	left,
		cvbdim_t	top,
		cvbdim_t	right,
		cvbdim_t	bottom,
		TZXBinarizerMode	binarizerMode,
		TZXReaderMode	readerMode,
		TZXBarcodeFormats	barcodeFormats,
		TZXResult &	result
	)

Read one barcode in an image.

Unlike its counterpart, ZXReadMultipleCodes, this function only reads one code. For an image with more than one code of the selected symbology it is undefined which code will be returned.

Attention

Please note that this function is not guaranteed to be thread-safe and we strongly advise against calling it simultaneously from different threads.

When calling this function without a valid Common Vision Blox Foundation Package license, the results returned by the function call will be partly garbled: Any '0' in the result will be replaced by a '5' and any 'e' or 'E' will be replaced by an 'x' or 'X' respectively.

This function uses the zxing-cpp library (see https://github.com/glassechidna/zxing-cpp). zxing-cpp is a fork of the zxing project and is published under the Apache v2.0 license which requires applications and libraries that make use of this function to declare in their license information that they are using the zxing-cpp library. This may be done e.g. by adding a link to the zxing-cpp project page and the Apache v2.0 license terms (https://github.com/glassechidna/zxing-cpp/blob/master/COPYING) e.g. to a "Help" or "About" screen. In Common Vision Blox the respective links have been added to the document OpenSourceLicenses.chm.

Parameters

[in]	imageIn	Input image. The plane of the input image to be processed needs to have 8 bits per pixel, otherwise an error will be returned.
[in]	plane	Plane of the input image to be processed. Must be in the range [0...ImageDimension(imageIn)-1]. Note that ZXing Barcode can only process luminance information. If the input image uses a color format, either select a suitable plane or convert it to luminance information before processing it in ZXBarcode.
[in]	left	Left edge of the area of interest.
[in]	top	Top edge of the area of interest.
[in]	right	Right edge of the area of interest.
[in]	bottom	Bottom edge of the area of interest.
[in]	binarizerMode	Selects the binarization algorithm to use. Valid values are taken from the TZXBinarizerMode enumeration.
[in]	readerMode	Specifies a reader mode as defined in the TZXReaderMode enumeration.
[in]	barcodeFormats	Provides a hint at what barcode formats are to be expected in the image. This hint does not limit the reading of codes if the hint points toward e.g. Code 128 and/or QR codes and the image contains a DataMatrix code, the code will be read nevertheless. However, providing the reader with the information what code(s) might be visible in the image may speed up reading slightly. This value can be a bit-wise combination of the flags in the TZXBarcodeFormats enum if more than one symbology is to be expected (remember, however, that even if multiple symbologies were specified, this function will read one code; for reading multiple codes please use ZXReadMultipleCodes instead).
[out]	result	Properties of the barcode that has been read.

Returns

This function may return the following error codes (taken from CVCError.h; apply CVC_ERROR_FROM_HRES before comparing!):

Value	Meaning
CVC_E_OK	The input was successfully processed.
CVC_E_NOIMAGE	imageIn does not refer to a valid CVB image.
CVC_E_INVALIDPLANE	plane is outside the range [0...ImageDimension(imageIn)-1]
CVC_E_INVALIDDATATYPE	the selected image plane does not have 8 bits per pixels
CVC_E_PARAMETER	The parameters left, top, right and bottom do not define a valid area of interest or an invalid binarizer mode was specified or an invalid format was specified.
CVC_E_NOTENOUGHDATA	The function was unable to find and/or read a bar or matrix code
CVC_E_ERROR	an unspecified error occurred

ZXReadMultipleCodes()

cvbres_t ZXReadMultipleCodes	(	IMG	imageIn,
		cvbdim_t	plane,
		cvbdim_t	left,
		cvbdim_t	top,
		cvbdim_t	right,
		cvbdim_t	bottom,
		TZXBinarizerMode	binarizerMode,
		TZXReaderMode	readerMode,
		TZXBarcodeFormats	barcodeFormats,
		size_t &	maxResults,
		TZXResult *	results
	)

Read multiple barcodes in an image.

Unlike its counterpart, ZXReadCode, this function reads all recognizable codes of the selected symbologies in an image.

Attention

Please note that reading multiple codes with one call will take considerably longer than reading a single code only! This is caused by the function call trying to find multiple codes in multiple locations and at multiple sizes in the image and has to be considered normal behavior.

Please also note that this function is not guaranteed to be thread-safe and we strongly advise against calling it simultaneously from different threads.

When calling this function without a valid Common Vision Blox Foundation Package license, the results returned by the function call will be partly garbled: Any '0' in the result will be replaced by a '5' and any 'e' or 'E' will be replaced by an 'x' or 'X' respectively.

This function uses the zxing-cpp library (see https://github.com/glassechidna/zxing-cpp). zxing-cpp is a fork of the zxing project and is published under the Apache v2.0 license which requires applications and libraries that make use of this function to declare in their license information that they are using the zxing-cpp library. This may be done e.g. by adding a link to the zxing-cpp project page and the Apache v2.0 license terms (https://github.com/glassechidna/zxing-cpp/blob/master/COPYING) e.g. to a "Help" or "About" screen. In Common Vision Blox the respective links have been added to the document OpenSourceLicenses.chm.

Parameters

[in]	imageIn	Input image. The plane of the input image to be processed needs to have 8 bits per pixel, otherwise an error will be returned.
[in]	plane	Plane of the input image to be processed. Must be in the range [0...ImageDimension(imageIn)-1]. Note that ZXing Barcode can only process luminance information. If the input image uses a color format, either select a suitable plane or convert it to luminance information before processing it in ZXBarcode.
[in]	left	Left edge of the area of interest.
[in]	top	Top edge of the area of interest.
[in]	right	Right edge of the area of interest.
[in]	bottom	Bottom edge of the area of interest.
[in]	binarizerMode	Selects the binarization algorithm to use. Valid values are taken from the TZXBinarizerMode enumeration.
[in]	readerMode	Specifies a reader mode as defined in the TZXReaderMode enumeration.
[in]	barcodeFormats	Provides a hint at what barcode formats are to be expected in the image. This hint does not limit the reading of codes if the hint points toward e.g. Code 128 and/or QR codes and the image contains a DataMatrix code, the code will be read nevertheless. However, providing the reader with the information what code(s) might be visible in the image may speed up reading slightly. This value can be a bit-wise combination of the flags in the TZXBarcodeFormats enum if more than one symbology is to be expected.
[in,out]	maxResults	Maximum number of results the memory block pointed to by maxResults can hold. If the call returns successfully (as indicated by the return value CVC_E_ERROR) then maxResults will hold the number of codes that was read successfully. If reading failed the parameter will be set to zero.
[in]	results	Pointer to a block of memory that receives the barcode read results. Must be allocated by the caller and needs to be big enough to hold at least maxResults results.

Returns

This function may return the following error codes (taken from CVCError.h; apply CVC_ERROR_FROM_HRES before comparing!):

Value	Meaning
CVC_E_OK	The input was successfully processed.
CVC_E_NOIMAGE	imageIn does not refer to a valid CVB image.
CVC_E_INVALIDPLANE	plane is outside the range [0...ImageDimension(imageIn)-1]
CVC_E_INVALIDDATATYPE	the selected image plane does not have 8 bits per pixels
CVC_E_PARAMETER	The parameters left, top, right and bottom do not define a valid area of interest or an invalid binarizer mode was specified or an invalid format was specified.
CVC_E_NOTENOUGHDATA	The function was unable to find and/or read a bar or matrix code
CVC_E_ERROR	an unspecified error occurred

Example

Read multiple QR codes with one function call

// assumptions:
// - img points to a valid image
size_t maxResults = 100;
std::vector<TZXResult> results(maxResults);
ZXReadMultipleCodes(img, 0, 0, 0, 0, ImageWidth(img) - 1, ImageHeight(img) - 1,
  ZXB_Hybrid, ZXRM_TryHarder, ZXBF_Qr, maxResults, results.data());
results.resize(maxResults);
std::for_each(results.begin(), results.end(), [](const TZXResult& res)
{
  std::cout << res.Text << std::endl;
});