This implementation can detect barcodes in one of several formats within - * an image, and then decode what it finds. This implementation supports all - * barcode formats that this library supports.
+ * MultiFormatReader is a convenience class and the main entry point into the library for most uses. + * By default it attempts to decode all barcode formats that the library supports. Optionally, you + * can provide a hints object to request different behavior, for example only decoding QR codes. * - * @author srowen@google.com (Sean Owen), dswitkin@google.com (Daniel Switkin) + * @author Sean Owen + * @author dswitkin@google.com (Daniel Switkin) */ public final class MultiFormatReader implements Reader { - public Result decode(MonochromeBitmapSource image) throws ReaderException { - return decode(image, null); + private Hashtable hints; + private Vector readers; + + /** + * This version of decode honors the intent of Reader.decode(BinaryBitmap) in that it + * passes null as a hint to the decoders. However, that makes it inefficient to call repeatedly. + * Use setHints() followed by decodeWithState() for continuous scan applications. + * + * @param image The pixel data to decode + * @return The contents of the image + * @throws NotFoundException Any errors which occurred + */ + public Result decode(BinaryBitmap image) throws NotFoundException { + setHints(null); + return decodeInternal(image); + } + + /** + * Decode an image using the hints provided. Does not honor existing state. + * + * @param image The pixel data to decode + * @param hints The hints to use, clearing the previous state. + * @return The contents of the image + * @throws NotFoundException Any errors which occurred + */ + public Result decode(BinaryBitmap image, Hashtable hints) throws NotFoundException { + setHints(hints); + return decodeInternal(image); + } + + /** + * Decode an image using the state set up by calling setHints() previously. Continuous scan + * clients will get a large speed increase by using this instead of decode(). + * + * @param image The pixel data to decode + * @return The contents of the image + * @throws NotFoundException Any errors which occurred + */ + public Result decodeWithState(BinaryBitmap image) throws NotFoundException { + // Make sure to set up the default state so we don't crash + if (readers == null) { + setHints(null); + } + return decodeInternal(image); } - public Result decode(MonochromeBitmapSource image, Hashtable hints) throws ReaderException { + /** + * This method adds state to the MultiFormatReader. By setting the hints once, subsequent calls + * to decodeWithState(image) can reuse the same set of readers without reallocating memory. This + * is important for performance in continuous scan clients. + * + * @param hints The set of hints to use for subsequent calls to decode(image) + */ + public void setHints(Hashtable hints) { + this.hints = hints; boolean tryHarder = hints != null && hints.containsKey(DecodeHintType.TRY_HARDER); - Vector possibleFormats = hints == null ? null : (Vector) hints.get(DecodeHintType.POSSIBLE_FORMATS); - Vector readers = new Vector(); - if (possibleFormats != null) { + Vector formats = hints == null ? null : (Vector) hints.get(DecodeHintType.POSSIBLE_FORMATS); + readers = new Vector(); + if (formats != null) { boolean addOneDReader = - possibleFormats.contains(BarcodeFormat.UPC_A) || - possibleFormats.contains(BarcodeFormat.UPC_E) || - possibleFormats.contains(BarcodeFormat.EAN_13) || - possibleFormats.contains(BarcodeFormat.EAN_8) || - possibleFormats.contains(BarcodeFormat.CODE_39) || - possibleFormats.contains(BarcodeFormat.CODE_128); + formats.contains(BarcodeFormat.UPC_A) || + formats.contains(BarcodeFormat.UPC_E) || + formats.contains(BarcodeFormat.EAN_13) || + formats.contains(BarcodeFormat.EAN_8) || + //formats.contains(BarcodeFormat.CODABAR) || + formats.contains(BarcodeFormat.CODE_39) || + formats.contains(BarcodeFormat.CODE_93) || + formats.contains(BarcodeFormat.CODE_128) || + formats.contains(BarcodeFormat.ITF) || + formats.contains(BarcodeFormat.RSS14) || + formats.contains(BarcodeFormat.RSS_EXPANDED); // Put 1D readers upfront in "normal" mode if (addOneDReader && !tryHarder) { - readers.addElement(new MultiFormatOneDReader()); + readers.addElement(new MultiFormatOneDReader(hints)); } - if (possibleFormats.contains(BarcodeFormat.QR_CODE)) { + if (formats.contains(BarcodeFormat.QR_CODE)) { readers.addElement(new QRCodeReader()); } - if (possibleFormats.contains(BarcodeFormat.DATAMATRIX)) { + if (formats.contains(BarcodeFormat.DATA_MATRIX)) { readers.addElement(new DataMatrixReader()); } + if (formats.contains(BarcodeFormat.PDF417)) { + readers.addElement(new PDF417Reader()); + } // At end in "try harder" mode if (addOneDReader && tryHarder) { - readers.addElement(new MultiFormatOneDReader()); + readers.addElement(new MultiFormatOneDReader(hints)); } } if (readers.isEmpty()) { if (!tryHarder) { - readers.addElement(new MultiFormatOneDReader()); + readers.addElement(new MultiFormatOneDReader(hints)); } readers.addElement(new QRCodeReader()); - // TODO re-enable once Data Matrix is ready - // readers.addElement(new DataMatrixReader()); + + readers.addElement(new DataMatrixReader()); + + // TODO: Enable once PDF417 has passed QA + //readers.addElement(new PDF417Reader()); + if (tryHarder) { - readers.addElement(new MultiFormatOneDReader()); + readers.addElement(new MultiFormatOneDReader(hints)); } } + } + + public void reset() { + int size = readers.size(); + for (int i = 0; i < size; i++) { + Reader reader = (Reader) readers.elementAt(i); + reader.reset(); + } + } - for (int i = 0; i < readers.size(); i++) { + private Result decodeInternal(BinaryBitmap image) throws NotFoundException { + int size = readers.size(); + for (int i = 0; i < size; i++) { Reader reader = (Reader) readers.elementAt(i); try { return reader.decode(image, hints); @@ -85,7 +160,7 @@ public final class MultiFormatReader implements Reader { } } - throw new ReaderException("No barcode was detected in this image."); + throw NotFoundException.getNotFoundInstance(); } }