BarcodeReader Class

Summary

The main class for LEADTOOLS toolkit support for reading barcodes.

Syntax

Objective-C

C++/CLI

Java

Python

public sealed class BarcodeReader

@interface LTBarcodeReader : NSObject

public class BarcodeReader

public ref class BarcodeReader sealed

class BarcodeReader:

Remarks

The BarcodeReader class is used to read one or more barcodes from an image. An instance of BarcodeReader cannot be created directly. Instead, use the instance created inside BarcodeEngine, and access it through the BarcodeEngine.Reader property.

BarcodeEngine engine = new BarcodeEngine(); 
BarcodeReader reader = engine.Reader; 
// The reader can be used now, for example, to read a single UPCA barcode from an image: 
BarcodeData data = reader.ReadBarcode(myImage, LeadRect.Empty, BarcodeSymbology.UPCA);

It is also possible to use the BarcodeReader directly through the BarcodeEngine.Reader property.

BarcodeEngine engine = new BarcodeEngine(); 
// Use the instance in BarcodeEngine directly, for example, to read a single UPCA barcode from an image: 
BarcodeData data = engine.Reader.ReadBarcode(myImage, LeadRect.Empty, BarcodeSymbology.UPCA);

Reading Barcodes

The BarcodeReader class contains the following overloaded methods for reading barcodes:

Method	Description
ReadBarcode	Searches and reads a single barcode from an image. This method returns a BarcodeData object containing the data for the first barcode found in the image; or null (Nothing in Visual Basic) if no barcodes are found. "Found" means it satisfies the other parameters of the method such as symbology types, search area, and read options.
ReadBarcodes	Searches and reads multiple barcodes from an image. This method returns an array of BarcodeData objects containing the data for each barcode found in the image. If no barcodes are found, an empty array (of length equal to 0) is returned. Again, "Found" means it satisfies the other parameters of the method such as symbology types, search area, and read options.

All methods accept a valid image that contains the image data, an optional search rectangle, the symbologies of interest, and any extra read options.

The returned BarcodeData object(s) contain the data for the barcode or barcodes found. Some of the data include:

Member	Description
BarcodeData.Symbology	A member of the BarcodeData.Symbology enumeration that specifies the symbology (or type) of the barcode found
BarcodeData.Bounds	The barcode's location and size in the image
The data (accessed through BarcodeData.GetData)	The raw data found inside the barcode, as a byte array
BarcodeData.Value	A string representation (in ASCII) of the data. The value returned is simply the ASCII text of the byte array returned from BarcodeData.GetData

For other data, refer to BarcodeData for more information.

Note that depending on the symbology type, a derived class can be returned (casted back to BarcodeData), from the read methods. Refer to BarcodeData for more information.

When reading barcodes, use the ReadSymbology method to get real-time information about the barcodes being searched for, as well as the read status.

Input Image

The ReadBarcode and ReadBarcodes methods accept as a parameter a RasterImage object containing the image data. This must be a valid object (it cannot be null or Nothing). Typically, a RasterImage object is obtained by loading it from a disk file or stream using the Leadtools.Codecs.RasterCodecs class, acquiring it from a scanning device using the Leadtools.Twain.TwainSession class, or any of the many other means supported by LEADTOOLS.

To achieve the best results when searching, the barcode must be large and clear enough for the BarcodeReader object to detect and read it. A barcode of one or more inches in width and height is almost always enough to be read successfully. Hence, an input image with a resolution of 200 DPI and larger, is recommended. If the source of the image is a smart phone camera, then these images will have a large pixel density (For instance, 5M pixels) and the barcode image is of enough dimension to be read successfully even if resolution is small (typically 72 or 96 DPI with most phone cameras). LEADTOOLS can read these images without any problems.

Bitonal (Black/White) images are the preferred format of input images. If the image has colors, then LEADTOOLS internally performs intensity detection to convert it to B/W before detecting the barcodes. This is done automatically by the engine; typically all that is needed is to pass the image as is. However, if the image is unclear, broken, or has noise, external image processing may be required.

LEADTOOLS can automatically read barcodes skewed at any angle. However, to read vertical barcodes, it is necessary to change the barcode search direction to something other than the default BarcodeSearchDirection.Horizontal. To read any barcode at any orientation and any skew (at the expense of more processing time and lower detection speed), set the barcode search direction to BarcodeSearchDirection.HorizontalAndVertical.

Because linear barcodes (1D) do not have many details, LEADTOOLS will generally read the barcode without any external processing. The 2D barcodes such as QR, PDF417, MicroPDF417, and Datamatrix however, contain a lot of details and so a clean image is necessary. When reading 2D barcodes, enable "double-passing" to automatically perform auto-clean up on these images. If detection fails, refer to QRBarcodeReadOptions.EnableDoublePass, PDF417BarcodeReadOptions.EnableDoublePass, MicroPDF417BarcodeReadOptions.EnableDoublePass, or DatamatrixBarcodeReadOptions.EnableDoublePass for more information. These options require extra processing time. All are disabled by default in order to achieve maximum detection speed.

Search Bounds

The read methods accept a LeadRect parameter that specifies the area of interest in the image where barcode search and detection is to be performed. Pass LeadRect.Empty to search the entire image. Naturally, restricting the search bounds to a small area increases the detection speed and vice versa.

Symbologies

The read methods accept one or more BarcodeSymbology enumeration members that specify which symbologies (barcode types) to search for. Pass the special BarcodeSymbology.Unknown value to search for all available symbologies.

If the specific barcode type is known beforehand, it is best to pass only that specific symbology (or symbologies). The fewer the number of symbologies to look for, the faster the detection speed, and vice versa.

The BarcodeEngine.GetSupportedSymbologies method returns an array containing all symbologies (BarcodeSymbology) supported by LEADTOOLS. Not all of these symbologies may be available (usable) by the current BarcodeReader object, depending on the level of LEADTOOLS support unlocked, and the presence of back-end support assemblies. Call GetAvailableSymbologies at any time to return the subset of the symbologies that are currently usable by this BarcodeReader object.

Read Options

LEADTOOLS provides extra options to use when reading barcodes. Use these options to fine-tune the search parameters, or provide additional pre-known information that can possibly enhance recognition speed and accuracy. The base abstract class for options is BarcodeReadOptions. LEADTOOLS also provides derived classes for each symbology (or group of symbologies). Refer to BarcodeReadOptions for more information.

The BarcodeReader class contains default options for each barcode symbology (or group of common symbologies). Retrieve the options by calling the GetDefaultOptions method, then passing the symbology of interest. The members of the returned BarcodeReadOptions can then be changed (casting it to the appropriate derived class beforehand, if necessary).

It is also possible to create an instance of one of the derived BarcodeReadOptions classes and use it directly in any of the ReadBarcode and ReadBarcodes methods that accept a single or array of options as a parameter.

The default options are an easy way to easily change the options used by the BarcodeReader object in one place so that it is not necessary to keep the option objects in the application. All the read methods have versions that do not require explicit options (or use null for the ones that require options).

In certain situations, however, explicit options are required. One example would be to fine-tune reading a certain image or to use a single BarcodeReader to read many barcodes using independent options in multiple threads. In such cases, use the read methods that accept specific options to override all or some of these options. If the reader cannot find the required options for a symbology in the specific options passed to the method, it will use the default version stored in the class.

The BarcodeReader.ReadBarcodes(RasterImage image, LeadRect searchBounds, int maximumBarcodes, BarcodeSymbology[] symbologies, BarcodeReadOptions[] options) example shows how to create two threads: One for reading horizontal barcodes and one for reading vertical barcodes. It will then use the same BarcodeReader to try and read all the barcodes from an image using both threads.

The default options can also be loaded or saved as an XML file or stream using the LoadOptions and SaveOptions methods.

Example

This example reads all the barcodes in an image

Java

using Leadtools; 
using Leadtools.Codecs; 
using Leadtools.Barcode; 
using Leadtools.ImageProcessing; 
 
 
public void BarcodeReader_Example() 
{ 
   string[] imageFileNames = 
   { 
   Path.Combine(LEAD_VARS.ImagesDir, "Barcode1.tif"), 
   Path.Combine(LEAD_VARS.ImagesDir, "Barcode2.tif") 
 }; 
 
   // Create a Barcode engine 
   BarcodeEngine engine = new BarcodeEngine(); 
 
   // Get the Barcode reader instance 
   BarcodeReader reader = engine.Reader; 
 
   // Load the image 
   using (RasterCodecs codecs = new RasterCodecs()) 
   { 
      foreach (string imageFileName in imageFileNames) 
      { 
         using (RasterImage image = codecs.Load(imageFileName, 0, CodecsLoadByteOrder.BgrOrGray, 1, 1)) 
         { 
            // Read all the barcodes in this image 
            BarcodeData[] barcodes = reader.ReadBarcodes(image, LeadRect.Empty, 0, null); 
 
            // Print out the barcodes we found 
            Console.WriteLine("{0} contains {1} barcodes", imageFileName, barcodes.Length); 
            for (int i = 0; i < barcodes.Length; i++) 
            { 
               BarcodeData barcode = barcodes[i]; 
               Console.WriteLine("  {0} - {1} - {2}", i + 1, barcode.Symbology, barcode.Value); 
            } 
            Console.WriteLine("-----------------"); 
         } 
      } 
   } 
} 
 
static class LEAD_VARS 
{ 
   public const string ImagesDir = @"C:\LEADTOOLS23\Resources\Images"; 
}

 
import java.io.File; 
import java.io.IOException; 
import java.util.*; 
import java.util.concurrent.ExecutorService; 
import java.util.concurrent.Executors; 
 
import org.junit.*; 
import org.junit.Test; 
import org.junit.runner.JUnitCore; 
import org.junit.runner.Result; 
import org.junit.runner.notification.Failure; 
import static org.junit.Assert.*; 
 
import leadtools.*; 
import leadtools.barcode.*; 
import leadtools.codecs.*; 
import leadtools.imageprocessing.*; 
import leadtools.internal.ManualResetEvent; 
 
 
public void barcodeReaderExample() { 
   final String LEAD_VARS_IMAGES_DIR = "C:\\LEADTOOLS23\\Resources\\Images"; 
   String imageFileName = combine(LEAD_VARS_IMAGES_DIR, "barcode1.tif"); 
 
   // Create a Barcode engine 
   BarcodeEngine engine = new BarcodeEngine(); 
 
   // Get the Barcode reader instance 
   BarcodeReader reader = engine.getReader(); 
 
   // Load the image 
   RasterCodecs codecs = new RasterCodecs(); 
   RasterImage image = codecs.load(imageFileName, 0, CodecsLoadByteOrder.BGR_OR_GRAY, 1, 1); 
 
   // Read all the barcodes in this image 
   BarcodeData[] barcodes = reader.readBarcodes(image, LeadRect.getEmpty(), 0, null); 
 
   // Print out the barcodes we found 
   int index = 0; 
   System.out.printf("%1s contains %2s barcodes%n", imageFileName, barcodes.length); 
 
   for (int i = 0; i < barcodes.length; i++) { 
      BarcodeData barcode = barcodes[i]; 
      System.out.printf("  %1s - %2s - %3s%n", i + 1, barcode.getSymbology(), barcode.getValue()); 
      index = i; 
   } 
 
   assertTrue("Not all barcodes are present", index == barcodes.length - 1); 
   System.out.println("All barcodes have been accounted for"); 
   System.out.println("-----------------"); 
}