Barcode Xpress Mobile for Android

How To

How to use Barcode Xpress for Android

This SDK provides the Barcode Xpress native recognition library and Java source code examples that show how to access it. The source code is divided into two layers. The most basic layer provides an interface to the native recognition library and is named BXAPI. Two other examples are sample applications that show how to use BXAPI. BXCameraSample manages the user interface and camera hardware, sending images to BXAPI for recognition. It may be used as an example or serve as the basis of your own application by customizing the hooks it provides for key operations. BXFileSample is a simple example of how to decode an image using BXAPI and use the results.

Deployment of Barcode Xpress Mobile is licensed on a per situation basis, and requires a licensing agreement with Accusoft. The Barcode Xpress Mobile SDK requires a license key to operate, which can be obtained upon completion of a licensing agreement with an Accusoft Sales Representative. Please contact sales@accusoft.com for more information.

The Java sources are located in src/com/accusoft/BarcodeXpress. The native recognition library is delivered as a shared library, located at BXAPI/libs/armeabi/libAccusoft.BarcodeXpress.so.

BarcodeXpress Mobile supports recognition of the full set of the types supported by the full version of Barcode Xpress. These are listed in supported barcode types.

BXAPI - package com.accusoft.BarcodeXpress.BXAPI

SDK users with an existing application will be interested primarily with BXAPI. It provides methods that accept images in several formats and it makes calls into the native recognition library for barcode decoding. It also provides utility methods for obtaining the library version, specifying the required license key, and setting the types of barcodes that will be recognized. The native recognition library has the optional ability to detect and reject blurred images. Important methods are:

  • recognizeImage(Bitmap image, long barcodeTypes) - Recognize and decode barcode from a Bitmap image, which may be in RGB_565 (16 bits per pixel), ARGB_8888 (32 bits per pixel), or grayscale (8 bits per pixel) format.
  • recognizeImage(byte[] rawPixels, int width, int height, int stride, int bpp, long barcodeTypes) - Recognize and decode barcode from an array of uncompressed pixel data, which can be in RGB_565, ARGB_8888, or 8-bit gray format. Suitable for processing an image from the video camera.
  • recognizeImageFromJPEGPixels(byte[] jpegPixels, long barcodeTypes) - Recognize and decode barcode from a byte array of JPEG-compressed pixel data. Suitable for processing an image from the picture camera.
  • setBlurDetection(boolean) - Enable (default) or disable rejection of blurred images before recognition is attempted.
  • getWorkerLibraryVersion() - Get version information from the decoding library.
  • YUVtoRGB565(byte[] pixels, int width, int height) - Convert a YUV image (supplied from video camera) to RGB565 format suitable for creating an Android Bitmap.

The BXLicense class holds information from the Accusoft license, primarily the license key. Until a valid license key is provided, the license key contained in the sources of BXCameraSample or BXFileSample may be used and will result in the final character of every decoded value being replaced with an asterisk (*). The constructor for BXAPI requires a BXLicense, and image recognition by the native library will not be performed if the license is invalid. The BXLicense constructor looks like this:


BXLicense(String OEMKey, Application application, long solutionKey1, long solutionKey2, long solutionKey3, long solutionKey4)

Note that the OEMKey string is provided by Accusoft upon completion of a licensing agreement, and that the solutionKey1, solutionKey2, solutionKey3, and solutionKey4 parameters are currently un-used.

The BXTypeConstants class defines the constants from which you build the set of barcode types you want the library to decode. This value would then be used as a parameter to one of the recognition methods of BXAPI.

The BXResult class contains the result of recognition by the native library. It contains points that describe a rectangle locating the barcode inside the image. It also contains decoding status, confidence, decoded data, and the barcode type. The class has methods to return information about what was learned by decoding the image:

  • getBarcodeType() - Returns the barcode type. You may use BXTypeConstants.toString() to obtain a String representation of its name.
  • getConfidence() - Returns an integer in the range 0..100 which describes how certain the result is.
  • getDataString() - Returns the decoded string from the barcode.
  • getResultPoints() - Returns a 4-element array of BXResultIdentLocation[] that contains the location of the barcode in the bitmap.
  • getResultStatus() - Returns a status code that describes the overall decoding operation.
  • getDataBytes() - returns a byte array which contains the raw decoded data.
  • getDataLength() - returns the length in bytes of the decoded data.

BXCameraSample - package com.accusoft.BarcodeXpress.BXCameraSample

Users looking for a simple Android application to scan barcodes with the camera, and display decoded results, will be interested in BXCameraSample. Android applications interact with the hardware using an event-driven interface called an Activity. The Activity model means that certain actions are done in callbacks. BXCameraSample provides callbacks that happen at key points in the application, such as when an image frame has been obtained from the camera or when decoding results are available. These callbacks allow for insertion of customized code to be run at key points during application execution.

Specifically, the following callbacks are provided by BXCameraSampleActivity.java:

  • onStartBarcodeXpress() - Called upon initialization of the activity, when application is being started.
  • onResumeRecognition(SurfaceHolder holder) - Called when the activity gains focus, both at application startup and after having previously lost focus (user switched to another application).
  • onPictureImage(byte[]) - Called after capturing a JPEG-encoded picture image from the camera, but before passing it to the recognition library.
  • onPreviewImage(byte[] yuvData, int width, int height) - Called after capturing a preview image from the camera, but before passing it to the recognition library.
  • onBarcodeRecognition(Bundle msgBundle) - Called when a barcode is recognized by Barcode Xpress.

When onBarcodeRecognition(Bundle msgBundle) is called, the msgBundle parameter may be used as follows:

  • msgBundle.getParcelable("Bitmap") - Returns the Bitmap that was decoded.
  • msgBundle.getParcelable("Result") - Returns a BXResult which contains the results of decoding the image.

In addition, the method setBarcodeTypes(long barcodeTypes) is provided to allow you to enable or disable the recognition of any of the supported barcode types.

The BXAPI.BXLicense class holds information from the Accusoft license. The constructor for BXAPI requires a BXLicense; image recognition by the native library will not be performed if the license key is invalid It would be appropriate to set the license in BXCameraSample.onStartBarcodeXpress(). The BXCameraSample class will then handle setting the license in a manner that will allow the recognition library to proceed successfully.

BXFileSample - package com.accusoft.BarcodeXpress.BXFileSample

Users who want to see the mechanism for integrating Barcode Xpress, without all the complexity of camera management, will be interested in BXFileSample. It shows the basic operations necessary to decode an image and use the results. The image file that it decodes is located in res/drawable-hdpi/barcode.bmp.

Customizing

Things you will want to customize for your own build of either demo application are as follows:

  • Application Icon: the SDK ships with high, medium and low resolution demo icons. If you rename these icons, you will want to change the android:icon element in AndroidManifest.xml. The icons are located at:
                        res/drawable-hdpi/icon_demo.png
                        res/drawable-mdpi/icon_demo.png
                        res/drawable-ldpi/icon_demo.png
                        
  • Keystore: for your convenience, a .keystore file is provided; you will want to replace this with a .keystore file you have built for your application.
  • Properties files: Three properties files are provided in each of the Sample directories: build.properties (which contains your build password that goes into the .keystore file), local.properties (which defines where the Android SDK is installed) and default.properties (which defines the Android target and the path to the BXAPI library).
  • AndroidManifest.xml: A number of things are specified in the manifest that are particular to your organization; the included manifest is an example only.

If you already have your own application and are integrating Barcode Xpress, you will want to merge the supplied properties files and AndroidManifest.xml, and then simply copy src/com/accusoft and libs/armeabi/libAccusoft.BarcodeXpress.so into your build directory.

Permissions

This SDK requires the following permission setting, found in AndroidManifest.xml:

          android.permission.CAMERA
          

If you wish to write data to the SD card, you may also wish to add the following below the existing uses-permission elements:

          <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
          

If you wish to read data from the SD card, you may also wish to add the following below the existing uses-permission elements:

          <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
          

Build and Deploy Barcode Mobile Sample Application

Use the following instructions as a guideline to load, run and deploy the sample application.

NOTE: These instructions may be used with IntelliJ IDE and Android Studios.

  1. Open the IDE.
  2. Click File > Import Project.
  3. Navigate to the BXCameraSample directory and select the folder. Click OK.
  4. Select Create project from existing sources.
  5. Enter the project name and location.
  6. No libraries are found. Click Next.
  7. Select the default module. Click Next.
  8. Select the JDK 1.7 files.
  9. Select the Android SDK files. Click Next.
  10. Click Finish
  11. Make the project.
  12. Set up the Android deployment settings.
  13. Run the project.