Manatee Works Barcode Scanner SDK...Java interface – defined in the BarcodeScaner.java class file....

Cognex Corporation One Vision Drive Natick, MA 01760-2059 (508) 650-3000 fax (508) 650-3333 www.manateeworks.com ManateeWorks Inc @manateeworks

Manatee Works

Barcode Scanner SDK v3.1

Quick Start Guide

https://manateeworks.com/

https://www.facebook.com/manateeworksinc

https://twitter.com/manateeworks


Overview The Manatee Works Barcode Scanner SDK is implemented as a software library that provides a light-weight, yet powerful barcode detection and decoding API optimized for mobile platforms. The core routines are implemented in a static C library for high performance and portability, and where necessary, native wrappers are provided for the various platforms (e.g., a Java implementation class for Android).

A set of plugins provide enhanced functionality and are included with the Barcode Scanner SDK at no additional cost:

Barcode Scanner Parser Plugin – a set of industry standard data parsers, greatly simplifying the job of extracting data from various standard barcodes like driver’s licenses and GS1 shipping labels;

Barcode Scanner Aimer Plugin - greater scanner engine efficiency and performance with features like Heads-Up Barcode Scanning™, triggering, delayed scanning, and more. The Aimer Plugin works in conjunction with a StingRay module. Visit www.stingrayhub.com for more information on the StingRay line of products;

Barcode Scanner Analytics Plugin – an API for securely logging and analyzing application scanning data. Through the Manatee Developer Network, your analytics dashboard can then be used to learn more about your barcode scanning use. Analytics are available for location data, mobile phone metrics, barcode symbology, and even custom data points.

The Barcode Scanner library supports the following barcode symbologies and sub-types:

Aztec Code

Codabar/Ames Code

Code 11/USD-8

Code 25 o Standard o Interleaved o ITF-14 o IATA o Matrix o COOP o Inverted

Code 39/USD-3/Alpha 39 o Code 32 o PZN o Extended

Code 93 o Standard o Extended

Code 128/EAN-14/GS1-128 o Code 128 A, B, and C




https://manateeworks.com/plugins

https://manateeworks.com/parsers

http://stingrayhub.com/

https://manateeworks.com/analytics

https://manateeworks.com/aztec-code

https://manateeworks.com/codabar

https://manateeworks.com/code-11






o SSCC-18 o UCC/EAN-128

Data Matrix o Square o Rectangular o GS1

DotCode

EAN o EAN-8 o EAN-13 o ISBN o ISMN o ISSN o JAN o EAN Add-on

GS1 Databar (Reduced Space Symbology) family of linear symbologies: o RSS-14 o RSS-14 Stacked o RSS Limited o RSS Expanded

MaxiCode

MSI Plessey

PDF417 o Standard o Compact/Truncated

Postal Codes o POSTNET o PLANET o Intelligent Mail Barcode o Royal Mail

QR Code o Standard o Micro

UPC o UPC-A o UPC-E o UPC-E0 o UPC-E1 o UPC Add-on

The Parser Plugin implements data parsing for the following industry standard formats:

AAMVA CDS (Driver’s License/ID Card)

GS1/GTIN




https://manateeworks.com/data-matrix

http://manateeworks.com/dotcode

https://manateeworks.com/ean

https://manateeworks.com/gs1-databar

https://manateeworks.com/msi-plessey

https://manateeworks.com/pdf417

https://manateeworks.com/qr-code

https://manateeworks.com/upc

https://manateeworks.com/parsers/aamva

https://manateeworks.com/parsers/gs1


HIBC

ISBT 128

IUID

MaxiCode

The list of symbologies and parsers available for use is based on the license purchased and is controlled by the license key provided at the time of purchase. A trial license includes the use of all supported symbologies and parsers for the evaluation period. Note that additional symbologies and parsers can be added to an existing license; contact [email protected] for assistance.

In general, the SDK’s API follows several paradigms: a C language interface (for iOS, Windows, Linux, etc.); a C# language interface (also for Windows, Windows Phone); and a Java language interface (for Android and Java):

C interface – defined in the include file BarcodeScanner.h;

C# helper class – defined in BarcodeHelper.cs;

Java interface – defined in the BarcodeScaner.java class file.

Introduction The Manatee Works Barcode Scanner SDK (referred to as the “SDK”) provides a simple, but powerful API for detecting and decoding barcodes in a grayscale image. The general steps to using the SDK are as follows:

1. Initialize the SDK with a license key. This only needs to be done once in the application, typically at start-up, but always prior to scanning;

2. Specify which symbologies to decode. The SDK can detect and decode almost 40 different barcode types and subtypes, but most applications only need to decode one or a handful;

3. Set optional features like: a. Decoding effort level; b. Scan direction; c. Scanning rectangle;

4. Capture an image; 5. Scan image for a barcode.

Each of these steps is described in more detail in the sections that follow. Code snippets are provided as examples, but not all supported platforms and frameworks are covered in this Quick Start Guide. Refer to the documentation and sample programs that come with each SDK distribution for fully functional, platform specific implementations.

1. Initialize the SDK with a license key. After purchasing the SDK license (or requesting a trial license), the Manatee Works Developer Network generates an alphanumeric license key string. In order to unlock the licensed features of the SDK, the




https://manateeworks.com/parsers/hibc

https://manateeworks.com/parsers/isbt-128

https://manateeworks.com/parsers/iuid

mailto:[email protected]

https://manateeworks.com/developers


application program must pass this key to the SDK, using the register method. Thus, in Java, the call looks something like this:

result = BarcodeScanner.MWBregisterSDK("Vgryrw9NXctE81Kef8eBcTcU8vKcaNTYpBvurcOBmMY=",this);

While in C:

result = MWB_registerSDK("Vgryrw9NXctE81Kef8eBcTcU8vKcaNTYpBvurcOBmMY=");

And in C# (in BarcodeHelper.cs):

int registerResult = Scanner.MWBregisterSDK("Vgryrw9NXctE81Kef8eBcTcU8vKcaNTYpBvurcOBmMY=");

The license key only needs to be passed to the SDK once when the application is executed, prior to other SDK calls being made. Thus, this call is typically made during application startup or prior to entering the barcode scanning program flow.

Note that if a valid key is NOT provided to the SDK, the SDK will appear to continue to function normally; however, decoded barcode results will be randomly masked with asterisk characters.

2. Specify which symbologies to decode By default, after the application and library startup, all barcode symbologies are inactive. Before first use, the developer must specify which symbology(s) the SDK should recognize and decode. This is performed using the MWB_setActiveCodes(int mask) function; multiple symbologies are selected by ORing values together. For example, to enable Data Matrix, PDF417, and QR Code, the following syntax would be used:

int status = MWB_setActiveCodes(MWB_CODE_MASK_DM |

MWB_CODE_MASK_PDF |

MWB_CODE_MASK_QR);

These options will remain in effect while the application is running or until another call to MWB_setActiveCodes() occurs.

Some of the symbologies have multiple sub-types that will all be enabled when MWB_setActiveCodes() is used. For example, enabling EAN/UPC (MWB_CODE_MASK_EANUPC) actually enables 4 symbologies: EAN-8, EAN-13, UPC-A, and UPC-E. Individual sub-types can be selected using MWB_setActiveSubcodes(int symbology, int mask) after enabling the symbology group. To just enable UPC-A and UPC-E, use the following:

status = MWB_setActiveCodes(MWB_CODE_MASK_EANUPC);

if ( status == MWB_RT_OK }

{

Status = MWB_setActiveSubcodes(MWB_CODE_MASK_EANUPC,

MWB_SUBC_MASK_EANUPC_UPC_A | MWB_SUBC_MASK_EANUPC_UPC_E);

}

Keep in mind that while your license may include many symbologies, for best performance you should consider only enabling the ones your application will ever need; the more symbologies enabled, the harder the SDK has to work to recognize and decode them.





3. Set optional features The Manatee Works Barcode Scanner SDK has a number of tunable parameters. Some of these impact the overall performance and behavior of the decoder while others are specific to a given symbology. Below are just a few of the common settings application developers may change.

Effort level The basic process of locating and decoding a barcode from an image involves looking at “slices” of the image for barcode patterns. The relative number of slices the decoder looks at can be controlled with the MWB_setLevel(uint level) function. In most cases, the default effort level (2) is sufficient to detect the barcode. However, under certain conditions, the application program may need the SDK to “try harder” (effort level 3) by looking at more slices or conversely, to “not try as hard” (effort level 1) by looking at fewer slices—the trade-off being performance.

In cases where the application may encounter damaged barcodes or poor lighting conditions, adjusting the effort level may help:

MWB_setLevel(3);

Like other settings, the effort level set will stay in effect until the MWB_setLevel() function is called with a different value.

Note that MWB_setLevel() supports levels 1-5; however, 4 and 5 are not intended for online or mobile applications as these will consume an inordinate amount of CPU (in some cases, taking more than 30 seconds to process an image).

Scan direction By default, when the SDK is attempting to locate a barcode in an image, it looks both vertically and horizontally. This means the orientation of the image is relatively unimportant, but this can slow detection. If the application programmer has specific knowledge of how the barcode will be oriented in the image (for example, because the design of the application itself dictates a specific orientation), then the SDK can be set to only look for barcodes in that direction.

To change the default scan direction, use the MWB_setDirection(uint direction) function. For example, to set only horizontal scanning use the following:

MWB_setDirection(MWB_SCANDIRECTION_HORIZONTAL);

The SDK also supports omnidirectional scanning, permitting most barcodes to be scanned from almost any angle (as the decoder will scan images diagonally as well as vertically and horizontally); again, just be aware that enabling omnidirectional scanning may degrade performance. The following shows enabling omnidirectional scanning in C#:

Scanner.MWBsetDirection((uint)Scanner.MWB_SCANDIRECTION_OMNI);

Scanning Rectangle By default, the SDK attempts to locate barcodes within the entirety of an image it is provided. This can lead to poor performance especially when dealing with high-resolution images or slow devices. In





many cases though, the application programmer may have knowledge of where the barcode is located within the image and just how much of the image it is likely to occupy. Consider the following example image:

If we knew that our application would always be used to scan Code 128 barcodes that were always more or less the same size as above, we can plainly see that the code actually only occupies a small fraction of the image. Further, we can assume that our user is likely going to center the barcode within the viewer. Thus, we can define a rectangle, in percentages, that represents the area of the image we want the SDK to scan for barcodes. Here is our example again with a theoretical “scanning rectangle” drawn in green around our barcode:

The blue lines and percentages represent the offset within the image and size of the barcode area. We can then provide the SDK with our scanning rectangle for Code 128 barcodes:

MWB_setScanningRect(MWB_CODE_MASK_128, 10, 33, 80, 33);





Defining the scanning rectangle for Android is a little different as it uses a Rect object (with the same parameters as the API call: left, top, width, and height):

Rect scanArea = new Rect(10, 33, 80, 33);

BarcodeScanner.MWBsetScanningRect(BarcodeScanner.MWB_CODE_MASK_128, scanArea);

Refer to the Manatee Works SDK Reference Manual for additional details.

4. Capture an image Once the SDK has been provided a license key and the decoding options set, the next step is to capture an image. The exact details of camera initialization and image capture are different for each supported platform and are beyond the scope of this Quick Start Guide. However, each distribution includes a fully functional sample program demonstrating these concepts where applicable. Refer to the sample programs for more details.

5. Scan image for a barcode The final step is to pass the image buffer to the decoder to attempt to locate and decode a barcode. If a barcode is found, the SDK allocates memory for the result and returns this buffer and its length to the calling program. When called from C/C++, note that is it the responsibility of the calling program to free the buffer allocated by MWB_scanGrayscaleImage.





Calling the decoder from C:

unsigned char *pResult = NULL;

int length = MWB_scanGrayscaleImage(imgBuffer, imgWidth, imgHeight, &pResult);

if ( length > 0 ) {

// Process result

}

Calling the decoder from Java:

byte[] rawResult = null;

rawResult = BarcodeScanner.MWBscanGrayscaleImage(imgBuffer, imgWidth, imgHeight);

if ( rawResult.length > 0 ) {

// Process result

}

Working with MWResults By default, MWB_scanGrayscaleImage() returns a byte array of the “raw data” that was decoded from a barcode. In many instances, this may be all the information the application requires. However, a much richer set of data about the code scanned is available and can be accessed using the MWResults class (and it’s thread safe!).

MWResults not only provides the same raw data stream that MWB_scanGrayscaleImage() returns, but also offers additional data including:

Text Data – a normalized, text decoded version of the raw data in the barcode. For example, in Java, this is the .toString() version of the raw data from the barcode. Keep in mind that this value may be inaccurate if the raw data contains non-printable characters.

Plugin Data – the barcode data, formatted for use with SDK plugins like the Barcode Scanner Parser Plugin.

Type – the type of barcode decoded (see the list of bit mask identifies for the supported symbologies).

Sub-type – the sub-type of the barcode decoded, if applicable

GS1 – indicates if the barcode decoded is a GS1 compliant code

Barcode Location – the location of the barcode within the scanned image (the four corners of the barcode)

MWResults is implemented as an array of MWResult objects, with MWResults[0] being the first barcode decoded from an image. NOTE: Decoding of multiple barcodes from a single image is currently not implemented; however, the decoding results have been structured to allow this future enhancement.

To use MWResults, call the MWB_setResultType(int resultType) function before decoding an image. Again, like other SDK settings, this needs to only be done once:

int status = MWB_setResultType(MWB_RESULT_TYPE_MW);

When MWB_scanGrayscaleImage() is called, the array of bytes returned is now formatted as an MWResults object. Below is the Objective C example of how to properly decode it:





unsigned char *pResult = NULL;

MWResults *mwResults = nil;

MWResult *mwResult = nil;

int length = 0;

length = MWB_scanGrayscaleImage(imgBuffer, imgWidth, imgHeight, &pResult);

if ( length > 0 ){

if ( self.state == NORMAL ){

length = 0;

free(pResult);

} else {

mwResults = [[MWResults alloc] initWithBuffer:pResult];

if ( mwResults && mwResults.count > 0 ){

mwResult = [mwResults resultAtIntex:0];

}

free(pResult);

}

}

if ( mwResult != nil )

{

// Process results!

}

A similar syntax is used in both Java and C#, and example code can be found in the sample programs provided with those distributions.

Bit mask identifiers for supported symbologies The following lists the bitmask values for the symbologies supported by the SDK. This list can be found in the C header file BarcodeScanner.h, or in the Java class BarcodeScanner.java.

#define MWB_CODE_MASK_NONE 0x00000000u

#define MWB_CODE_MASK_QR 0x00000001u

#define MWB_CODE_MASK_DM 0x00000002u

#define MWB_CODE_MASK_RSS 0x00000004u

#define MWB_CODE_MASK_39 0x00000008u

#define MWB_CODE_MASK_EANUPC 0x00000010u


#define MWB_CODE_MASK_PDF 0x00000040u

#define MWB_CODE_MASK_AZTEC 0x00000080u



#define MWB_CODE_MASK_CODABAR 0x00000400u

#define MWB_CODE_MASK_DOTCODE 0x00000800u


#define MWB_CODE_MASK_MSI 0x00002000u

#define MWB_CODE_MASK_MAXICODE 0x00004000u

#define MWB_CODE_MASK_POSTAL 0x00008000u

#define MWB_CODE_MASK_ALL 0x00ffffffu

Sub-types for GS1 Databar (RSS):

#define MWB_SUBC_MASK_RSS_14 0x00000001u

#define MWB_SUBC_MASK_RSS_14_STACK 0x00000002u

#define MWB_SUBC_MASK_RSS_LIM 0x00000004u

#define MWB_SUBC_MASK_RSS_EXP 0x00000008u

Sub-types for Code 25:

#define MWB_SUBC_MASK_C25_INTERLEAVED 0x00000001u

#define MWB_SUBC_MASK_C25_STANDARD 0x00000002u

#define MWB_SUBC_MASK_C25_ITF14 0x00000004u





#define MWB_SUBC_MASK_C25_IATA 0x00000008u

#define MWB_SUBC_MASK_C25_MATRIX 0x00000010u

#define MWB_SUBC_MASK_C25_COOP 0x00000020u

#define MWB_SUBC_MASK_C25_INVERTED 0x00000040u

Sub-types for EAN/UPC:

#define MWB_SUBC_MASK_EANUPC_EAN_13 0x00000001u

#define MWB_SUBC_MASK_EANUPC_EAN_8 0x00000002u

#define MWB_SUBC_MASK_EANUPC_UPC_A 0x00000004u

#define MWB_SUBC_MASK_EANUPC_UPC_E 0x00000008u

#define MWB_SUBC_MASK_EANUPC_UPC_E1 0x00000010u

Sub-types for Postal Code:

#define MWB_SUBC_MASK_POSTAL_POSTNET 0x00000001u

#define MWB_SUBC_MASK_POSTAL_PLANET 0x00000002u

#define MWB_SUBC_MASK_POSTAL_IM 0x00000004u

#define MWB_SUBC_MASK_POSTAL_ROYAL 0x00000008u

Sub-types for QR:

#define MWB_SUBC_MASK_QR_STANDARD 0x00000001u

#define MWB_SUBC_MASK_QR_MICRO 0x00000002u

Tips

Android Minimum OS The Manatee Works Barcode Scanner SDK has no minimum Android OS requirement, though the sample program provided requires a minimum of Android 2.3, as it supports live image scanning.

iOS Minimum OS The Manatee Works Barcode Scanner SDK for Apple requires a minimum iOS version of 7.0.

Scanning High Density Barcodes The prerequisites for scanning high-density barcodes, such as a US Driver’s License (PDF417), include a high resolution camera with autofocus. On iOS, that's available from the iPhone 4+, and the iPad 3+. For Android, most devices with an 8-megapixel camera will be successful. For lower density codes, the minimum requirements for mobile devices are a 5-megapixel autofocus camera. This covers the iPhone 3Gs or newer, iPod Touch 5 or newer, and the iPad 3 or newer, and most Android devices with OS 2.2 or higher. For both platforms, a mobile device with at least an 8-megapixel camera with autofocus is recommended.

Use sub-types As mentioned earlier, several of the symbologies have sub-types that can be individually enabled/disabled when decoding. By disabling unnecessary sub-types, decoding performance can be improved. Thus, if scanning, Code 25, GS1 Databar, Postal, QR, and/or EAN/UPC codes, consider using MWB_setActiveSubcodes() to limit the decoding algorithms to just the sub-types the application needs to scan.





We thank you for the opportunity to share our product with you.

Best wishes,

The Manatee Works Development Team!




Manatee Works Barcode Scanner SDK...Java interface – defined in the BarcodeScaner.java class file....

Documents

Transcript of Manatee Works Barcode Scanner SDK...Java interface – defined in the BarcodeScaner.java class file....