BarcodeReader Class

Summary

Main class for the LEADTOOLS support for reading barcodes.

Syntax

Objective-C

C++

Java

public sealed class BarcodeReader

Public NotInheritable Class BarcodeReader

@interface LTBarcodeReader : NSObject

public class BarcodeReader

public ref class BarcodeReader sealed

Remarks

The BarcodeReader class is used to read one or more barcodes from an image. You cannot create an instance of BarcodeReader directly, instead, use the instance created for you inside BarcodeEngine and access through the BarcodeEngine.Reader property:

Dim engine As New BarcodeEngine() 
Dim reader As BarcodeReader = engine.Reader 
' Use can use the reader now, for example, read a single UPCA barcode from an image: 
Dim data As BarcodeData = reader.ReadBarcode(myImage, LeadRect.Empty, BarcodeSymbology.UPCA)

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

Or you can use the BarcodeReader directly through the BarcodeEngine.Reader property:

Dim engine As New BarcodeEngine() 
' Use the instance in BarcodeEngine directly, for example, read a single UPCA barcode from an image: 
Dim data As BarcodeData = engine.Reader.ReadBarcode(myImage, LeadRect.Empty, BarcodeSymbology.UPCA)

BarcodeEngine engine = new BarcodeEngine(); 
// Use the instance in BarcodeEngine directly, for example, 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 methods used to read barcodes:

Method	Description
ReadBarcode	Search and read a single barcode from an image. This method will return a BarcodeData object containing the data for the first barcode found in the images. Or null (Nothing in Visual Basic) if no barcodes are found. "Found" means it satisfies the other parameters to the method such as symbology types, search area and read options.
ReadBarcodes	Search and read multiple barcode from an image. This method will return an array of BarcodeData objects containing the data for the all barcodes found in the image. Or an empty array (of length equals to 0) if no barcodes are found. Again, "Found" means it satisfies the other parameters to the method such as symbology types, search area and read options.

All these overloaded methods accept a valid image that contains the image data, and 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. These include:

Member	Description
BarcodeData.Symbology	A member of the BarcodeSymbology enumeration that specifies the symbology (or type) of the barcode found
BarcodeData.Bounds	The barcode 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 an ASCII text of the byte array returned from BarcodeData.GetData

And many more, refer to BarcodeData for more information.

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

When reading barcodes, the ReadSymbology can be used to get real time information on the barcodes being searched for and the read status.

Input Image

The ReadBarcode and ReadBarcodes methods accept as a parameter a RasterImage object that contains the image data. This must be a valid object (cannot be null or Nothing). You typically obtain a RasterImage object by loading it from a disk file or stream using the Leadtools.Codecs.RasterCodecs class, acquiring 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. 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 will internally perform intensity detection to convert it to B/W before detecting the barcodes. This is done automatically by the engine; you typically pass the image as is. However, if the image is unclear, broken or has noise, then external image processing might be required.

LEADTOOLS can automatically read barcodes skewed at any angle. However, if you have vertical barcodes, then you must change the barcode search direction to something other than the defaulted BarcodeSearchDirection.Horizontal. Setting this to BarcodeSearchDirection.HorizontalAndVertical will read any barcode at any orientation and skew at the expense of more processing and less detection speed.

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

Search Bounds

The read methods accept a parameter of type LeadRect that specifies the area of interest in the image where the barcode search and detection is to be performed. You can pass LeadRect.Empty to search the whole 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 the symbologies (barcode types) to search for. You can also pass the special BarcodeSymbology.Unknown to instruct the engine to search for all available symbologies.

If you know the barcode type beforehand then it is highly recommended you pass only the equivalent symbology (or symbologies). The less the number of symbologies to look for the faster, the detection speed and vice versa.

The BarcodeEngine.GetSupportedSymbologies method will return an array containing all the symbologies (BarcodeSymbology) supported by LEADTOOLS. Not all of these symbologies might be available (usable) by the current BarcodeReader object depending on level of LEADTOOLS support unlocked and presence of back end support assemblies. The GetAvailableSymbologies can be used 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. These options are used to fine tune the search parameters or provide extra pre-known information that might enhance the recognition speed and accuracy. The base abstract class for the options is BarcodeReadOptions. LEADTOOLS 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). These options can be retrieved using the GetDefaultOptions method passing the symbology of interest. You can then change the members of the returned BarcodeReadOptions (or after casting it to the appropriate derived class).

You can also create an instance of one of the derived BarcodeReadOptions classes and use it directly in the ReadBarcode and ReadBarcodes methods that accepts a single or array of options as a parameter.

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

In certain situations however, using explicit options may be required, for example, to fine tune reading a certain image or to read barcodes using independent options in multiple threads and a single BarcodeReader. In these cases, you can 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 XML file or stream using the LoadOptions and SaveOptions methods.

Example

This example reads all the barcodes in an image

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:\Users\Public\Documents\LEADTOOLS Images"; 
}

Imports Leadtools 
Imports Leadtools.Codecs 
Imports Leadtools.Barcode 
Imports Leadtools.ImageProcessing 
 
Public Sub BarcodeReader_Example() 
   Dim imageFileNames() As String = 
   { 
      Path.Combine(LEAD_VARS.ImagesDir, "Barcode1.tif"), 
      Path.Combine(LEAD_VARS.ImagesDir, "Barcode2.tif") 
   } 
 
   ' Create a Barcode engine 
   Dim engine As New BarcodeEngine() 
 
   ' Get the Barcode reader instance 
   Dim reader As BarcodeReader = engine.Reader 
 
   ' Load the image 
   Using codecs As New RasterCodecs() 
      For Each imageFileName As String In imageFileNames 
         Using image As RasterImage = codecs.Load(imageFileName, 0, CodecsLoadByteOrder.BgrOrGray, 1, 1) 
            ' Read all the barcodes in this image 
            Dim barcodes() As BarcodeData = reader.ReadBarcodes(image, LeadRect.Empty, 0, Nothing) 
 
            ' Print out the barcodes we found 
            Console.WriteLine("{0} contains {1} barcodes", imageFileName, barcodes.Length) 
            For i As Integer = 0 To barcodes.Length - 1 
               Dim barcode As BarcodeData = barcodes(i) 
               Console.WriteLine("  {0} - {1} - {2}", i + 1, barcode.Symbology, barcode.Value) 
            Next 
            Console.WriteLine("-----------------") 
         End Using 
      Next 
   End Using 
End Sub 
 
Public NotInheritable Class LEAD_VARS 
   Public Const ImagesDir As String = "C:\Users\Public\Documents\LEADTOOLS Images" 
End Class

c#[Silverlight C# Example] 
using Leadtools; 
using Leadtools.Codecs; 
using Leadtools.Forms; 
using Leadtools.Barcode; 
using Leadtools.ImageProcessing; 
using Leadtools.Examples; 
 
public void BarcodeReader_Example(RasterImage image, string imageFileName) 
{ 
   // Create a Barcode engine 
   BarcodeEngine engine = new BarcodeEngine(); 
 
   // Get the Barcode reader instance 
   BarcodeReader reader = engine.Reader; 
 
   // Load the image 
   RasterCodecs codecs = new RasterCodecs(); 
 
   // Read all the barcodes in this image 
   BarcodeData[] barcodes = reader.ReadBarcodes(image, LogicalRectangle.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("-----------------"); 
} 
vb[Silverlight VB Example] 
Imports Leadtools 
Imports Leadtools.Codecs 
Imports Leadtools.Forms 
Imports Leadtools.Barcode 
Imports Leadtools.ImageProcessing 
Imports Leadtools.ImageProcessing.Color 
 
Public Sub BarcodeReader_Example(ByVal image As RasterImage, ByVal imageFileName As String) 
   ' Create a Barcode engine 
   Dim engine As BarcodeEngine = New BarcodeEngine() 
 
   ' Get the Barcode reader instance 
   Dim reader As BarcodeReader = engine.Reader 
 
   ' Load the image 
   Dim codecs As RasterCodecs = New RasterCodecs() 
 
   ' Read all the barcodes in this image 
   Dim barcodes As BarcodeData() = reader.ReadBarcodes(image, LogicalRectangle.Empty, 0, Nothing) 
 
   ' Print out the barcodes we found 
   Console.WriteLine("{0} contains {1} barcodes", imageFileName, barcodes.Length) 
   Dim i As Integer = 0 
   Do While i < barcodes.Length 
      Dim barcode As BarcodeData = barcodes(i) 
      Console.WriteLine("  {0} - {1} - {2}", i + 1, barcode.Symbology, barcode.Value) 
      i += 1 
   Loop 
   Console.WriteLine("-----------------") 
End Sub