Barcode actions

The Barcode action library performs recognition of barcodes on pages or in a field. The page can contain a single barcode or multiple barcodes. The value of a barcode is stored and can be used by subsequent actions. The value of a barcode can be stored with a page as part of it's data. Barcodes can also be used for controlling the logical flow of Datacap rules, as a separator page indicator or a mechanism to assign a page type.

The page must be a single page TIF, PNG, BMP or JPEG image. Other types of images or documents are not supported. Document types such as PDF, DOC, multi-page TIF, etc., can be converted to a TIF image using the Convert action library. It is recommended that the best practices guide is reviewed to understand what kind of images work well for recognition.

Action Summary

GetAllBarcodes : Reads all barcodes on the page and returns them in a delimited string.

GetBarcode : Reads the first barcode on a page.

GetDataMatrixBarcode : Reads the first Data Matrix barcode on a page.

GetPDF2DBarcode : Reads the first PDF-417 barcode on a page.

IdentifyPageByBarcode : Sets the page type based on a barcode value.

MatchAnyBarcode : Compares an expected value with all the barcodes on the page.

MatchBarcodePrefix : Compares an expected prefix value with all the barcodes on the page.

MatchFirstBarcode : Compares the first barcode read on the page with a value.

SetBarcodeMinimumConfidence : Sets the minimum tolerance required to except a barcode read as accurate.

Setting The Expected Barcode Type

It may still be necessary to set the expected barcode type for the engine to find and recognize the barcode. If a barcode is not being detected, set the proper barcode type to aid the barcode detection. Multiple barcode types can be set. It is recommended that the expected barcode types are specifically configured.

The expected barcode types can be easily set using the "BAR/P" tab property within the "Zones" tab of Datacap Studio. This property can be set by selecting the target DCO node page or field that has an associated rule that calls barcode recognition, locking the DCO, and selecting the expected barcode types. This automatically calculates the correct value based on all the selected types and sets the bp_tp variable for your application in the Setup DCO. For best results, keep the expected types to a minimum. When you use this property to set the expected barcode type, it is not necessary to separately set the bp_tp variable manually within the setup DCO or at runtime using actions.

Alternatively, the expected barcode type can be set at runtime on the target field/page being recognized by setting the variable bp_tp. If the bp_tp variable is empty or does not exist, the engine defaults to "Unknown".

rrSet("256","@X.bp_tp") for reading a Code 39 barcode.

Variable Length Royal Mail Barcodes

The Royal Mail barcode is a fixed length barcode. Some countries use a variable length variation of the Royal Mail barcode, such as the Postal Services of Portugal. To allow reading of a variable length Royal Mail barcode for Portuguese CTT, in addition to selecting the Royal Mail barcode type, the variable length setting must be enabled. Setting the DCO variable "RoyalMailVariableLength" to "1" will allow detection of variable length Royal Mail barcodes. It is allowed to enable variable length for fixed length Royal Mail barcodes, if the length restriction does not need to be enforced.

 rrSet("1", "@P.RoyalMailVariableLength")
rrSet("134217728", "@P.bp_tp")
GetBarcode()

Minimum and Maximum Expected Barcodes Settings

Multiple barcodes can exist and be recognized on a single page. The DCO variable bp_su controls the maximum number of barcodes that will attempt to be read on a single page. If not specified, the default maximum is 10.

The minimum number of expected barcodes can be specified using the DCO variable bp_minExpected. This setting will control when image enhancement takes place. Unless specified, the minimum expected barcodes will default to the same value as the maximum number of barcodes setting.

The engine uses these variables to determine how many barcodes are expected on the page and will cause the engine to stop looking once the threshold has been met. If the expected number of barcodes is not met, the engine can perform internal image adjustments to the image and read it again looking for the expected number of barcodes. If your pages will only have one expected barcode, then set the minimum and maximum expected barcode variables to 1 for best results.

Barcode Detection Steps

If the number of recognized barcodes is equal to or more than the specified minimum, then image enhancement is skipped. If the minimum number of barcodes has not been reached, and if image enhancement is enabled, then barcode recognition is performed a second time using the configured type of image enhancement in an attempt to read the barcode.

For example, if the configured minimum barcodes is 1 and the maximum is 10, first barcode recognition is performed without any image enhancement and attempt is made to read up to 10 barcodes. If at least 1 barcode is read, then the action is complete. If 0 barcodes are read, then the action performs the specified image enhancement and attempts once more to recognize the barcodes on the page. If 0 barcodes are read and no image enhancement is configured, the action completes without a second attempt at recognition.

Another example is if two barcodes are expected with the minimum set to 2. If 2 or more barcodes are read, then recognition stops. If less than two are read and if image enhancement is enabled, the barcode action performs the configured image enhancement type and attempts to read the barcode again. It will do this for each type of enabled image enhancement.

Image Enhancements

Barcodes are more tolerant to image deterioration than traditional recognition. Damaged barcodes can often still be recognized. The fault tolerance can vary based on the specific barcode type, as a whole, they are more resilient than traditional character recognition. Barcodes are also generally more tolerant to skew and rotation problems.

It is still possible that barcodes can have problems being read if the image is of poor quality. For example, if it has been poorly scanned, copied several times, or has other visible issues, a barcode may still not be read correctly. The barcode action library has built in image enhancement mechanisms to internally adjust the image when the barcode cannot be read.

Image enhancement may be necessary in order to help read damaged or poorly scanned barcodes. Depending on the problem with the barcode, different types of enhancements may make the barcode readable. The barcode actions offer a way to enhance the image while reading the barcode. To enable this feature, set the variable bp_enhance to "1". When set to "1", the engine tries to recognize the barcode without image enhancement.

If the minimum number of barcodes has not been read, then the action will try again using the specified image enhancement. If the minimum number of barcodes has been read, then the image enhancement will be skipped. If your barcode images are such that they will always require image enhancement, set bp_enhance to "2", which will skip the first recognition step that attempts to recognize without image enhancement.

Enabling image enhancement for barcodes will only alter the image during barcode recognition, the original image in the batch will be left unchanged.

The image enhancements are not cumulative, enable only one type of image enhancement that is needed. If sometimes one image enhancement helps, for example binarize, and other times a different image enhancement helps, such as smooth zoom, then both can be enabled, however, the minimum and maximum also need to be set. The engine will try each image enhancement that is enabled until the minimum number of expected barcodes is read. It is not possible to control the order in which the engine tries multiple enhancements. For best performance, enable the minimum number of enhancements that help your images.

Image Enhancement Types

Smooth Zoom: bp_zoom - Scales the image larger to help improve recognition for small barcodes.

Blur: bp_blur - Blurs the image which can help jagged lines.

Dilate: bp_dilate - Expands pixels making lines thicker

Erode: bp_erode - Removes pixels along line edges.

Flip: bp_flip - It is usually not necessary to flip the image for an upside-down barcode to recognize.

Resize: bp_resize - Enlarges the image which could help small barcodes, similar to zoom.

Binarize: bp_binarize - Converts 24 and 8 bit images to 1 bit. A 1 bit image can improve recognition for barcodes where the contrast between the barcode lines and the background is low or when there is light shading preventing recognition.

These enhancements are temporary and will not change the image within the batch.

Enabling Image Enhancement

rrSet("1","@X.bp_enhance")

Each specific image enhancement can be enabled by setting the associated DCO variable to "1" or disabled by setting it to "0". By default, "Smooth Zoom" is always enabled and all other image enhancements are disabled.

For example, if "Smooth Zoom" is the desired enhancement, simply enabling image enhancement by setting bp_enhance to "1" will enable image enhancement for Smooth Zoom.

rrSet("1","@X.bp_enhance")
rrSet("0","@X.bp_zoom")
rrSet("1","@X.bp_binarize")

The above example, and other examples in this library, show how to set DCO variables using rrSet. This action will set variables at runtime. Alternatively these variables can be set in the Setup DCO from within Datacap Studio. Setting the variables within the Setup DCO can be more efficient. For example, assume that the above three rrSet actions are called on page type "Other". Assuming the batch ingests 100 pages, then these three actions will be called on every page, resulting in 300 calls to the rrSet action. Alternatively, these three variables can be created and set in the DCO from within Datacap Studio on the "Other" DCO object. When set in the Setup DCO, the variables will automatically exist on every "Other" object and rrSet will not need to be called within the rules to create these variables on every object within the batch.

Enabling Multiple Enhancements

rrSet("1","@X.bp_enhance")
rrSet("0","@X.bp_zoom")
rrSet("1","@X.bp_binarize")
rrSet("1","@X.bp_blur")

The action will then use the blur and binarize enhancements until the minimum number is read. If bp_enhance is set to "1" the action will always first try to recognize without any enhancements and only if the minimum is not reached, will it continue. Each additional enhancement type enabled will be attempted until the minimum are read or all enabled enhancements have been attempted.

For best performance, always set the minimum number of barcodes expected or the action may perform unnecessary enhancements. The order in which the enhancements are attempted by the barcode action cannot be controlled.

Barcode Orientation

Barcode orientation defaults to both horizontal and vertical. Specifying the orientation may help in detection of barcodes. For example, if the barcodes are to be always horizontal, then detection and recognition can be improved by setting the orientation to Horizontal only. If necessary, the orientation can be configured by setting the DCO variable bp_or.

0 = Horizontal and Vertical.

1 = Horizontal.

2 = Vertical.

3 = Horizontal, Vertical and Diagonal.

Barcode Byte Mode

Some specific barcode types, such as PDF-417, allow null characters within the data stream. If this occurs, the full length of the barcode can be truncated returning only the characters up to the first null character. This is typically observable by noting that the read barcode data is shorter than expected. For example, if the barcode should be a 40 character ID but it returns truncated text.

To treat a barcode as byte data, set the DCO variable BarcodeUseByte to "1". This setting will treat the stream as bytes and also convert any null characters to spaces so the entire string can then be utilized in other parts of the application. By default, this parameter is off.

When in byte mode, the default replacement character of a space can be set to a different replacement character by setting the DCO variable BarcodeReplacementChar to the desired replacement character. For example, rrSet("-","@X.BarcodeReplacementChar") sets the variable "BarcodeReplacementChar" on the current DCO object to "-" which will change the replacement character from a space to a dash when byte mode is enabled.

Patch Codes

Patch codes can be recognized in addition to barcodes. Patch codes are very similar to barcodes but can be less reliable. If all pages are checked for patch codes it is possible for lines on a page that resemble patch codes can be mistaken for patch codes. While this is somewhat rare, but can happen. If you have a choice between creating separator sheets that use patch codes or barcodes, a barcode is the reliable option.

When the barcode type is set to Patch Code, the following string values may be returned by the engine (the string value depends on the type of Patch Code that is found):

Patch 1: 1100

Patch 2: 1001

Patch 3: 1010

Patch 4 / Toggle Patch: 0110

Patch 6: 0011

Patch T / Transfer patch: 0101

When recognizing PatchCodes, the barcode type must be set explicitly to PatchCode. The default barcode type setting of "Unknown" will not detect PatchCodes.

Barcode Results Stored In DCO Variables

The results of barcode recognition will be stored in field data, in DCO variables or both. When barcode recognition is performed on a field, the results of the barcode read are stored in the field's text value. When recognized on a page, results can be stored in variables such as GetBarCodeList and GetBarCode. Storing and retrieving data from DCO variables is a common task for actions and Datacap applications. Refer to the action help for names of variables that are created from barcode recognition.

The top-level help topic of the ApplicationObjects action library discusses the Datacap Object Hierarchy (DCO) including the different object levels and object variables. It is recommended that the DCO is well understood when writing a Datacap application.

Smart Parameters

Parameters that use an "@" notation, such as "@X.xxxx", "@P.xxxx", "@STRING()", "@PILOT()", etc., are known as "smart parameters". The data passed as a parameter to an action will be evaluated at runtime. For example, "@X" is notation for accessing the current object. "@P" accesses the page object, which could be the current object, or a parent object. Being evaluated at runtime, allows recognized data or other batch specific data to be passed to actions or stored as metadata. A smart parameter such as @DATE could be used to name export files based on the current date. Similar smart parameters will retrieve the current batch ID, current batch directory, current operator ID, and more. Smart parameters are a very powerful mechanism of getting data from other areas of the application and copying it into a new location or passing it as a parameter to an action. It is recommended that the smart parameter documentation is reviewed to understand the full capabilities available. The top-level help of the ValidationAndTextAdjustments action library also has information about smart parameters. Some characters such as +, \ and . also have special smart parameter meaning and may be interpreted as a smart parameter. This can be controlled using smart parameter syntax.