Barcode Xpress Mobile for iOS
How To

How to use Barcode Xpress for iOS

The Barcode Xpress for iOS Software Development Kit provides an Objective-C interface to Accusoft's Barcode Xpress recognition library. Barcode Xpress is a thread-safe image processing library of code that will efficiently find and decode a large number of types of barcodes. The SDK provides BXInterface, a multi-threaded Objective-C interface to the native recognition library. BXInterface also interacts with the video camera hardware to handle the process of capturing and processing images. It provides a set of callbacks that allow an application to customize its behavior. A sample application named BXDemo is layered on top of BXInterface. BXDemo may serve as either an example or as the basis of your own application.

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 native recognition library is delivered in archive library format, and is named BarcodeXpress8.a. BXInterface and BXDemo are delivered as source code, accompanied by Xcode project files. You may use and modify these sources as you wish.

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.

Basic Concepts

The native recognition library is thread-safe and requires a valid license. Until a valid license key is provided, the license key contained in BXDemo's sources may be used and will result in the final character of every decoded value being replaced with an asterisk (*). Barcode Xpress provides methods to allow for license configuration and image recognition / manipulation. To use it in the very simplest configuration, you need only instantiate BXInterface with a license and then call its recognition method to decode barcodes contained in each image.

Most mobile applications have a user interface that will not tolerate synchronous image processing delays. To remedy that, we have provided source code for an Objective-C interface named BXInterface that wraps BarcodeXpress. BXInterface takes care of configuring the license information for BarcodeXpress. It provides threaded support for processing images asynchronously, and a series of callbacks that allow the main application to be written in an event-driven manner. BXInterface configures the camera hardware, and delegates itself to capture images from the video camera. It allows preview images to be written directly to a layer supplied by the application. Images are supplied to the user interface by callbacks at several points during the processing stage:

  • When images are captured from the video frame buffer.
  • When an image is about to be dispatched to an available processing thread.
  • When an image is successfully recognized and a decoded value is available. This callback also provides the decoded data.

BXInterface provides many properties and methods that allow it to be configured to act as the base for applications to build upon. The SDK provides source code for a sample application that provides a simple user interface and demonstrates how to use BXInterface. BXDemo displays all preview video imagery as though it is seen through a viewfinder. Behind the scenes, BXInterface is processing video frames. When a barcode is recognized, a callback is made to a BXDemo method that displays both the decoded value and the image that contained the barcode. Barcode Xpress provides information in its result, passed through BXInterface, that allows BXDemo to draw a rectangle around the location where the barcode was found.

Using BXInterface

BXInterface provides the core functionality for programs that want to perform barcode recognition on video images. The following snippet of code is taken from BXDemo. It shows how to configure BXInterface and have it begin gathering and processing video frames: 

    // Create and initialize a BXLicense.
    // Note that the newlines (\n) at the end of each line of the license key are required.
    // Note that the values for parameters key1, key2, key3 and key4 are currently unused.
       BXLicense* license = [[BXLicense alloc]
                          initWithData:@"A/2R0LQRQeRHHaen+bqwcggdbB7kDTDCCzU/P3GtiXQlnr0byBOCQW+5FPoBG/O4\n"
                          "2hVmCcxrZr4zBuUmFgsw64jJFhKsRtUqjdvWzqyJY2guYfZNhswtgziXZZm6n/rb\n"
                          "gv9pKn9pLFWmXk579SjZw7ZFDD3wWJM1XzyeW5VbAuw=\n"
                          mainBundle:[NSBundle mainBundle]
                          key1:1 key2:2 key3:3 key4:4 ];
    
    // Initialize the interface to the decoding library.
    barcodeXpress = [[BXInterface alloc] initWithLicense:license];
    [license release];
    
    // Define the callbacks that allow program control to be altered at key points.
    [barcodeXpress SetCameraCallback :self :@selector(onCameraUpdate:)];
    [barcodeXpress SetRecognitionCallback :self :@selector(onBarcodeRecognition:)];
    [barcodeXpress SetProcessingCallback :self :@selector(onProcessingBarcode:)];

    // Create a layer that will display preview imagery from the camera.
    AVCaptureVideoPreviewLayer *previewLayer = [[AVCaptureVideoPreviewLayer alloc] init];

    // Define the types of barcodes to decode.
    // See BarcodeXpressIOS.h for definitions of barcode types.
    [barcodeXpress SetBarcodeTypes : AllBarcodeTypes];
    
    // Configure the camera and start processing video frames.
    [barcodeXpress StartRecognition :previewLayer];

At this point, the program is up and running in an event-driven manner. BXInterface takes care of configuring the camera to use the optimum resolution it can provide. It uses the appropriate number of processing threads for the number of available CPU cores. It samples the video camera frame buffer and asynchronously sends those images to Barcode Xpress for recognition. When a barcode is recognized, BXInterface notifies the user interface through a callback.

BXDemo

BXDemo is a sample application built upon BXInterface, which in turn uses BarcodeXpress. It provides a simple user interface that shows a viewfinder with a laser line that encourages the user to center the barcode at a distance in which the camera can focus. The word "Processing.. ." is animated by the onProcessingBarcode() callback each time a decoding thread begins processing an image. The "accusoft.com" words are a button that invokes the web browser to view the Accusoft website. When the onBarcodeRecognition() callback is executed, several previously hidden views are made visible on top of the others. They display a thumbnail of the image that contains the barcode and the decoded data in a scrollable view. A Back button hides this results page and returns to the viewfinder, resuming image processing. The onCameraUpdate() callback has some commented-out code that shows an example of what can be done there. If the code is un-commented, it will threshold (binarize) and display each sampled image frame - showing a black & white version of it.

The callbacks provide a way for the user interface to control program execution. A callback can modify an image before it proceeds further in the processing pipeline. It can pause or stop the processing pipeline, etc. BXDemo uses the iPhone/iPad default Settings app to configure which types of barcodes to recognize. The source code is provided for BXDemo, allowing it to be used as the basis for your own application, and as an example of how to use BXInterface.