net.rim.device.api.barcodelib
Class BarcodeDecoder

java.lang.Object
  net.rim.device.api.barcodelib.BarcodeDecoder

All Implemented Interfaces:

ImageDecoder

public class BarcodeDecoder
extends Object
implements ImageDecoder

A barcode decoder class that recognizes 1D and 2D barcodes. Supports formats that are supported by the included com.google.zxing library.

To ensure faster processing, you should always attempt to configure this decoder to only decode barcode types that you wish to process. The following code sample shows how to configure a BarcodeDecoder to scan for QR codes only.

 
 Hashtable hints = new Hashtable()
 Vector formats = new Vector();
 formats.addElement(BarcodeFormat.QR_CODE);
 hints.put(DecodeHintType.POSSIBLE_FORMATS, formats);
 BarcodeDecoder decoder = new BarcodeDecoder(hints); 
 

Since:

BlackBerry API 6.0.0

Constructor Summary

BarcodeDecoder()
Creates an instance of a BarcodeDecoder with no hints specified for how to interpret the camera data.

BarcodeDecoder(Hashtable hints)
Creates an instance of a BarcodeDecoder class which tries to decode barcodes given a Hashtable of hints on how to interpret the camera data.

Method Summary
void	crop(XYRect frame, int width, int height) Used to crop the image for decoding.
Object	decode(byte[] yuv, int width, int height) Attempts to decode the provided image given the configuration of this ImageDecoder.
Object	decode(Bitmap bitmap) Attempts to decode the provided bitmap given the configuration of this ImageDecoder.
void	enableCrop(boolean crop) Enable cropping, which is accessed via the crop method.
static void	getFramingRect(XYRect frame, int width, int height) Calculates a rect which is a subset of the rect defined by width * height.
Hashtable	getHints() Retrieve the decoder hints.
MultiFormatReader	getReader() Retrieve the reader that's used for decoding.
boolean	isCrop() Crop status of this BarcodeDecoder.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BarcodeDecoder

public BarcodeDecoder()

Creates an instance of a BarcodeDecoder with no hints specified for how to interpret the camera data. It is strongly suggested that you configure your BarcodeDecoder to only decode barcode types you are expecting to process.

See Also:

MultiFormatReader

Since:

BlackBerry API 6.0.0

BarcodeDecoder

public BarcodeDecoder(Hashtable hints)

Creates an instance of a BarcodeDecoder class which tries to decode barcodes given a Hashtable of hints on how to interpret the camera data. This is equivalent to:

 MultiFormatReader reader = new MultiFormatReader();
 reader.setHints(hints);
 

Parameters:

hints - see class documentation for an example of how to use the hints

See Also:

MultiFormatReader, DecodeHintType

Since:

BlackBerry API 6.0.0

Method Detail

decode

public Object decode(byte[] yuv,
                     int width,
                     int height)

Attempts to decode the provided image given the configuration of this ImageDecoder.

Specified by:

decode in interface ImageDecoder

Parameters:

yuv - The image data.

width - The width of the image.

height - The height of the image.

Returns:

An Object of type Result if the scan was successful (that contains the decoded text), null otherwise.

Throws:

IllegalStateException - if this BarcodeDecoder hasn't been configured with any DecodeHintType.POSSIBLE_FORMATS

IllegalArgumentException - if the rect returned from BarcodeDecoder.crop(net.rim.device.api.ui.XYRect, int, int) violates the conditions of PlanarYUVLuminanceSource.

NullPointerException - if yuv is null.

See Also:

ImageDecoder, PlanarYUVLuminanceSource

Since:

BlackBerry API 7.0.0

crop

public void crop(XYRect frame,
                 int width,
                 int height)

Used to crop the image for decoding. The BarcodeDecoder.decode(byte[] yuv, int width, int height) method executes this in order to determine which area of the image should be cropped (i.e. the cropped area passed into PlanarYUVLuminanceSource for decoding). This method first checks to see if cropping has been enabled (via isCrop), which can be set via enableCrop. If isCrop return true, this then calls BarcodeDecoder.getFramingRect(net.rim.device.api.ui.XYRect, int, int) to do the actual cropping. This method is also called by BarcodeScannerOverlayField so that the cropped region can be augmented over the viewfinder. BarcodeDecoder.getFramingRect(net.rim.device.api.ui.XYRect, int, int) is intented to be a conservative, default cropping estimate. Smaller camera frames will be processed faster, and overriding this method with more aggressive cropping will improve performance if your application will allow for it.

Parameters:

frame - Cropped frame, which should be strictly smaller than width * height. The XYRect.set(int, int, int, int) is used to set the cropped frame. This method does nothing if frame is null.

width - Original frame width.

height - Original frame height.

See Also:

PlanarYUVLuminanceSource

Since:

BlackBerry API 7.0.0

enableCrop

public final void enableCrop(boolean crop)

Enable cropping, which is accessed via the crop method.

Parameters:

crop - true to enable crop, false otherwise.

Since:

BlackBerry API 7.0.0

isCrop

public final boolean isCrop()

Crop status of this BarcodeDecoder. Crop is enabled by default.

Returns:

true if cropping is enabled, false otherwise.

Since:

BlackBerry API 7.0.0

getFramingRect

public static void getFramingRect(XYRect frame,
                                  int width,
                                  int height)

Calculates a rect which is a subset of the rect defined by width * height. When the width is greater than the height, we assume the frame is in landscape, so we crop 10% of the frame top and bottom. When the width is less than the height, we assume the frame is in portrait mode, so we crop 15% of the frame top and bottom. In both portrait and landscape, the 10 most left and right pixels are also cropped.

Parameters:

frame - Cropped frame, which should be strictly smaller than width * height. The XYRect.set(int, int, int, int) is used to set the cropped frame. This method does nothing if frame is null.

width - Original frame width.

height - Original frame height.

Since:

BlackBerry API 7.0.0

getHints

public Hashtable getHints()

Retrieve the decoder hints.

Returns:

decoder hints, never null.

Since:

BlackBerry API 7.0.0

getReader

public MultiFormatReader getReader()

Retrieve the reader that's used for decoding.

Returns:

reader, never null.

Since:

BlackBerry API 7.0.0

decode

public Object decode(Bitmap bitmap)

Attempts to decode the provided bitmap given the configuration of this ImageDecoder.

Parameters:

bitmap - The Bitmap containing a barcode.

Returns:

An Object of type Result if the scan was successful, null otherwise.

Throws:

IllegalStateException - if this BarcodeDecoder hasn't been configured with any DecodeHintType.POSSIBLE_FORMATS.

NullPointerException - if bitmap is null.

See Also:

ImageDecoder, BitmapLuminanceSource

Since:

BlackBerry API 7.0.0