Reading

edit

The packages read the codes back: Meziantou.Framework.Imaging.Barcodes finds the codes of an image, and Meziantou.Framework.Barcodes decodes every symbology from its modules, or the linear barcodes from the widths of their bars.

Reading images

Meziantou.Framework.Imaging.Barcodes reads the codes of the images of Meziantou.Framework.Imaging: any format it loads. Install it:

dotnet package add Meziantou.Framework.Imaging.Barcodes

ReadQRCodes finds the QR codes, Micro QR codes and rMQR codes of an image and decodes them. It gives each one once, with its Result and its Corners in the image.

using var image = QRCode.Create("https://www.meziantou.net").ToImage(); // or Image.Load("photo.png")

var results = image.ReadQRCodes();

var result = Assert.Single(results);
Assert.Equal("https://www.meziantou.net", result.Text);

// The corners of the symbol in the image: top-left, top-right, bottom-right, bottom-left
var topLeft = result.Corners[0];
Assert.True(topLeft.DistanceTo(new PointD(40, 40)) < 1); // after the quiet zone of 4 modules of 10 pixels

The readers read generated, printed and scanned images, and photographs taken with a phone: the symbols can be rotated, mirrored, scaled, blurred, compressed, unevenly lit (a shadow, a gradient) or photographed at an angle. A local threshold classifies the pixels as dark or light whatever the lighting, and the corners of the finder patterns of a QR code (and its alignment patterns), the edges of a Data Matrix symbol and the bullseye of an Aztec symbol give the perspective. A symbol needs its quiet zone and modules of at least 2 pixels. Symbols printed light on a dark background are read when the image has none printed dark on light. A transparent background reads as white.

The readers are checked against the sample images of zxing-cpp, including photographs and images without symbols. For the photographs they read and their limits, see Limitations.

QRCodeReadingOptions limits the Types to read and the MaximumResults.

ReadBarcodes2D reads the Data Matrix, PDF417 and Aztec symbols of an image the same way, with Barcode2DReadingOptions. Data Matrix and Aztec symbols can be in any orientation; the rows of a PDF417 symbol must be about horizontal or vertical.

using var image = Barcode2D.CreateDataMatrix("https://www.meziantou.net").ToImage(); // or Image.Load("label.png")

var results = image.ReadBarcodes2D();

var result = Assert.Single(results);
Assert.Equal((Barcode2DType.DataMatrix, "https://www.meziantou.net"), (result.Result.Type, result.Text));

ReadBarcodes reads the linear barcodes, with BarcodeReadingOptions. Parallel scan lines cross the image horizontally, vertically and at 30°, 60°, 120° and 150°: a barcode turned by another angle is read when a line crosses all its bars. The edges of the bars are found in the grayscale image, between the pixels, so that small and blurred barcodes keep the widths of their bars, and the outside of the image reads as white: a barcode cropped at its first and last bars is read. A barcode must be crossed by two lines that agree; Code 39, Codabar and ITF, whose check is weak or missing, by lines that cover at least 4% of their length, with 4 characters or more for Codabar and 6 digits or more for ITF, so that the patterns of other barcodes and of text are not read as them. The text printed under the bars is not read: it is not needed.

using var image = Barcode.CreateEan13("590123412345").ToImage(); // or Image.Load("product.jpg")

var results = image.ReadBarcodes();

var result = Assert.Single(results);
Assert.Equal((BarcodeType.Ean13, "5901234123457"), (result.Result.Type, result.Text));

Reading modules

QRCodeDecoder reads the data of a QR code from its modules: it reads the format information, fixes the errors that the error correction can fix, and decodes the segments. It reads the three kinds of QR codes: standard QR codes, Micro QR codes and rMQR codes.

var qrCode = QRCode.Create("https://www.meziantou.net", ErrorCorrectionLevel.M);

var result = QRCodeDecoder.Decode(qrCode);

Assert.Equal("https://www.meziantou.net", result.Text);
Assert.Equal((QRCodeType.Standard, 2, ErrorCorrectionLevel.M), (result.Type, result.Version, result.ErrorCorrectionLevel));

The decoder works on modules, not on pixels. Pass the modules as a matrix of bool, true for dark, indexed by row then column, without the quiet zone. The size of the matrix gives the kind of symbol: a square of 21 to 177 modules is a standard QR code, a square of 11 to 17 modules a Micro QR code, and a rectangle an rMQR code.

QRCodeDecoder.TryDecode returns false when the modules are not a QR code it can read; QRCodeDecoder.Decode throws a FormatException that tells why.

// The modules, true for dark, indexed by row then column, without quiet zone
var qrCode = QRCode.Create("HELLO WORLD", ErrorCorrectionLevel.Q);
var modules = new bool[qrCode.Height, qrCode.Width];
for (var row = 0; row < qrCode.Height; row++)
{
    for (var column = 0; column < qrCode.Width; column++)
    {
        modules[row, column] = qrCode[row, column];
    }
}

// Damage the symbol: the error correction restores the data
for (var column = 9; column < 14; column++)
{
    modules[12, column] = !modules[12, column];
}

Assert.True(QRCodeDecoder.TryDecode(modules, out var result));
Assert.Equal("HELLO WORLD", result.Text);
Assert.True(result.CorrectedErrorCount > 0);

A standard or Micro QR code read in a mirror has its rows and columns swapped: the decoder reads it too, and sets IsMirrored.

What the result holds

QRCodeDecodeResult gives:

  • Text: the data as text. The byte segments are decoded with the character set of the ECI designator that precedes them. Without one, they are decoded as UTF-8 when they are valid UTF-8, which is what QRCode.Create writes, as Shift JIS when they look like Japanese text in Shift JIS (a word of 3 katakana or kanji, or bytes that are control characters in ISO/IEC 8859-1), which many Japanese generators write, and as ISO/IEC 8859-1 otherwise.
  • Segments: the segments of the data, with their Mode, their Text, the raw Bytes of a byte segment, and the EciAssignmentNumber of an ECI designator. Read the bytes when the QR code holds binary data. Pass the segments to QRCode.Create to encode the same data again.
  • The parameters of the symbol: Type, Version, ErrorCorrectionLevel and MaskPattern.
  • CorrectedErrorCount: the number of codewords the error correction fixed. A high count means a damaged symbol. Micro QR version M1 only detects errors: the decoder rejects an M1 symbol with an error.

Structured append

The symbols of a structured append sequence each hold a part of the data. StructuredAppend gives the place of a symbol in its sequence, and QRCodeDecoder.MergeStructuredAppend puts the data back together. It checks that every symbol of the sequence is there, once, and that the parity of the data matches.

var text = "Structured append splits this text across several QR codes, and the reader puts it back together.";
var symbols = QRCode.CreateStructuredAppend(text, ErrorCorrectionLevel.M, new QRCodeOptions { MaximumVersion = 2 });

// The symbols can be read in any order
var results = symbols.Reverse().Select(QRCodeDecoder.Decode).ToList();

Assert.Equal(text, QRCodeDecoder.MergeStructuredAppend(results));

Data Matrix, PDF417 and Aztec

Barcode2DDecoder reads Data Matrix (ECC 200), PDF417 and Aztec symbols. Pass the modules and the type of the symbol: the decoder finds the orientation of a Data Matrix or Aztec symbol from its finder pattern, mirrored included, and reads the rows of a PDF417 symbol from either side. A row of a PDF417 symbol can span several rows of the matrix.

var dataMatrix = Barcode2D.CreateDataMatrix("https://www.meziantou.net");

var result = Barcode2DDecoder.Decode(dataMatrix);

Assert.Equal("https://www.meziantou.net", result.Text);
Assert.Equal(Barcode2DType.DataMatrix, result.Type);

Barcode2DDecodeResult gives the Text, the raw Bytes, the EciAssignmentNumber of the first ECI designator, and the CorrectedErrorCount. The bytes are decoded as for QR codes: with the character set of their ECI designator, or as UTF-8 when they are valid UTF-8, as Shift JIS when they look like Japanese text in Shift JIS, and as ISO/IEC 8859-1 otherwise.

A Data Matrix symbol that starts with a FNC1 character holds GS1 element strings: IsGs1 is true, and the text is the human-readable interpretation, each application identifier in parentheses. The bytes keep the element strings, with a GS character for each FNC1 separator.

var gs1 = Barcode2D.CreateGs1DataMatrix(
    new Gs1Element("01", "09521234543213"),
    new Gs1Element("10", "ABC123"),
    new Gs1Element("21", "XYZ"));

var result = Barcode2DDecoder.Decode(gs1);

// The human-readable interpretation, and the bytes with a GS character for each FNC1 separator
Assert.True(result.IsGs1);
Assert.Equal("(01)09521234543213(10)ABC123(21)XYZ", result.Text);
Assert.Equal("010952123454321310ABC123\u001D21XYZ"u8.ToArray(), result.Bytes.ToArray());

Linear barcodes

BarcodeDecoder reads Code 39, Code 93, Code 128, GS1-128, EAN-8, EAN-13, UPC-A, UPC-E (with their 2- and 5-digit add-ons), Codabar, ITF and all the GS1 DataBar symbols. Pass a Barcode or its modules: the text is the one that Barcode.Text gives for a generated barcode. The check characters of Code 39 and the start and stop characters of Codabar are part of it, the add-on follows a space, and GS1 data is its human-readable interpretation.

var barcode = Barcode.CreateCode128("SKU-123456");

var result = BarcodeDecoder.Decode(barcode);

Assert.Equal((BarcodeType.Code128, "SKU-123456"), (result.Type, result.Text));

An EAN-13 symbol whose first digit is 0 has the same bars as a UPC-A symbol: the decoder reports it as BarcodeType.UpcA, with 12 digits.

Scan lines

BarcodeDecoder.DecodeScanLines reads the barcodes that scan lines cross. A scan line is the widths of its light and dark runs, starting with a light run, in any unit, such as the pixels of a row of an image. The decoder reads each line in both directions, measures the widths relative to each other, corrects bars that are uniformly too wide or too narrow, and requires the quiet zones around a symbol. The rows of a stacked GS1 DataBar symbol are put together from the lines that cross them.

// A scan line: the widths of its light and dark runs, starting with a light run, here 3 pixels per module
var barcode = Barcode.CreateEan13("590123412345");
var runs = new List<int> { 30 };
for (var column = 0; column < barcode.Width; column++)
{
    if (barcode[0, column] != (runs.Count % 2 == 0))
    {
        runs.Add(0);
    }

    runs[^1] += 3;
}

// The quiet zone after the last bar
runs.Add(30);

var results = BarcodeDecoder.DecodeScanLines([runs.ToArray()]);

var result = Assert.Single(results);
Assert.Equal((BarcodeType.Ean13, "5901234123457"), (result.Type, result.Text));
Assert.Equal((30, 30 + (95 * 3)), (result.Start, result.End));

A result gives the lines that cross the barcode (FirstScanLine and LastScanLine) and its position on them (Start and End). Code 39 without check character, Codabar and ITF have no check character: a damaged line can read as another text, so require several lines to agree.