or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated

docs

reference

c-api.mdencodings.mderrors.mdformats.mdgeometry.mdgtin.mdimages.mdreader-options.mdreading.mdresults.mdstructured-append.mdutilities.mdwriting.md
index.md
tile.json

tessl/github-zxing-cpp--zxing-cpp

tessl install tessl/github-zxing-cpp--zxing-cpp@2.3.0

Open-source, multi-format linear/matrix barcode image processing library implemented in C++

formats.mddocs/reference/

Barcode Formats

ZXing-C++ supports a wide variety of barcode formats, including both linear (1D) and 2D/matrix codes. The BarcodeFormat enum and related types provide format identification and filtering.

BarcodeFormat Enum

enum class BarcodeFormat : uint32_t {
    None            = 0,       // No barcode detected

    // Linear (1D) Codes
    Aztec           = (1 << 0),
    Codabar         = (1 << 1),
    Code39          = (1 << 2),
    Code93          = (1 << 3),
    Code128         = (1 << 4),
    DataBar         = (1 << 5),   // GS1 DataBar (RSS-14)
    DataBarExpanded = (1 << 6),   // GS1 DataBar Expanded
    DataBarLimited  = (1 << 7),   // GS1 DataBar Limited
    DataMatrix      = (1 << 8),
    EAN8            = (1 << 9),
    EAN13           = (1 << 10),
    ITF             = (1 << 11),  // Interleaved Two of Five
    MaxiCode        = (1 << 12),
    PDF417          = (1 << 13),
    QRCode          = (1 << 14),
    UPCA            = (1 << 15),
    UPCE            = (1 << 16),
    MicroQRCode     = (1 << 17),
    RMQRCode        = (1 << 18),  // Rectangular Micro QR Code
    DXFilmEdge      = (1 << 19),  // DX Film Edge Barcode

    // Format Groups
    LinearCodes     = 0x000FFF,   // All linear barcode formats
    MatrixCodes     = 0x3FF000,   // All 2D/matrix barcode formats
    Any             = 0x3FFFFF    // All supported formats
};

// Type-safe set of formats (bitfield wrapper)
class BarcodeFormats {
    // Bitfield operations, implicitly convertible to/from BarcodeFormat
};

Format Categories

Linear (1D) Codes

Linear barcodes are one-dimensional and typically encode numeric or alphanumeric data:

// All linear formats
auto linearFormats = ZXing::BarcodeFormat::LinearCodes;

// Individual linear formats
ZXing::BarcodeFormat::Codabar         // Legacy format for libraries, blood banks
ZXing::BarcodeFormat::Code39          // Alphanumeric, used in automotive, defense
ZXing::BarcodeFormat::Code93          // Compact version of Code 39
ZXing::BarcodeFormat::Code128         // High-density, full ASCII
ZXing::BarcodeFormat::DataBar         // GS1 DataBar (RSS-14)
ZXing::BarcodeFormat::DataBarExpanded // GS1 DataBar with more data
ZXing::BarcodeFormat::DataBarLimited  // GS1 DataBar for small items
ZXing::BarcodeFormat::DXFilmEdge      // Film cartridge encoding
ZXing::BarcodeFormat::EAN8            // Short EAN for small products
ZXing::BarcodeFormat::EAN13           // European Article Number (retail)
ZXing::BarcodeFormat::ITF             // Interleaved 2 of 5 (shipping)
ZXing::BarcodeFormat::UPCA            // Universal Product Code (retail)
ZXing::BarcodeFormat::UPCE            // Compact UPC

2D/Matrix Codes

Matrix barcodes are two-dimensional and can store much more data:

// All matrix formats
auto matrixFormats = ZXing::BarcodeFormat::MatrixCodes;

// Individual matrix formats
ZXing::BarcodeFormat::Aztec           // Compact 2D, used in transport
ZXing::BarcodeFormat::DataMatrix      // Common in manufacturing, electronics
ZXing::BarcodeFormat::MaxiCode        // Fixed-size, used by UPS
ZXing::BarcodeFormat::MicroQRCode     // Smaller version of QR Code
ZXing::BarcodeFormat::PDF417          // Stacked linear, used on IDs
ZXing::BarcodeFormat::QRCode          // Most popular 2D code
ZXing::BarcodeFormat::RMQRCode        // Rectangular Micro QR Code

Working with Formats

Checking Format

auto barcode = ZXing::ReadBarcode(image);

if (barcode.isValid()) {
    ZXing::BarcodeFormat format = barcode.format();

    // Check specific format
    if (format == ZXing::BarcodeFormat::QRCode) {
        std::cout << "This is a QR Code\n";
    }
}

Converting Format to String

// Single format
ZXing::BarcodeFormat format = ZXing::BarcodeFormat::QRCode;
std::string name = ZXing::ToString(format);
std::cout << name << "\n";  // Output: "QRCode"

// Multiple formats
ZXing::BarcodeFormats formats = ZXing::BarcodeFormat::QRCode |
                                 ZXing::BarcodeFormat::DataMatrix;
std::string names = ZXing::ToString(formats);
std::cout << names << "\n";  // Output: "QRCode | DataMatrix"

Parsing Format from String

// Parse single format
ZXing::BarcodeFormat format = ZXing::BarcodeFormatFromString("QRCode");

if (format == ZXing::BarcodeFormat::None) {
    std::cout << "Invalid format string\n";
}

// Parse multiple formats (throws on invalid string)
try {
    ZXing::BarcodeFormats formats =
        ZXing::BarcodeFormatsFromString("QRCode | DataMatrix | EAN13");

    std::cout << "Parsed formats successfully\n";
} catch (const std::exception& e) {
    std::cerr << "Invalid format string: " << e.what() << "\n";
}

BarcodeFormats Type

The BarcodeFormats type is a type-safe wrapper for combining multiple formats:

// Create from single format
ZXing::BarcodeFormats formats1 = ZXing::BarcodeFormat::QRCode;

// Combine multiple formats with OR operator
ZXing::BarcodeFormats formats2 = ZXing::BarcodeFormat::QRCode |
                                  ZXing::BarcodeFormat::DataMatrix;

// Use predefined groups
ZXing::BarcodeFormats allLinear = ZXing::BarcodeFormat::LinearCodes;
ZXing::BarcodeFormats allMatrix = ZXing::BarcodeFormat::MatrixCodes;
ZXing::BarcodeFormats everything = ZXing::BarcodeFormat::Any;

// Check if format is included
if (formats2 & ZXing::BarcodeFormat::QRCode) {
    std::cout << "QR Code is enabled\n";
}

Setting Formats in ReaderOptions

// Read only QR codes
auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::QRCode);

// Read QR codes and Data Matrix codes
options.setFormats(ZXing::BarcodeFormat::QRCode |
                   ZXing::BarcodeFormat::DataMatrix);

// Read all linear codes
options.setFormats(ZXing::BarcodeFormat::LinearCodes);

// Read all formats (default)
options.setFormats(ZXing::BarcodeFormat::Any);

// Check if specific format is enabled
if (options.hasFormat(ZXing::BarcodeFormat::QRCode)) {
    std::cout << "QR Code detection is enabled\n";
}

auto barcode = ZXing::ReadBarcode(image, options);

Format Capabilities

Error Correction Support

Formats with built-in error correction:

// QR Code: L (7%), M (15%), Q (25%), H (30%)
// Aztec: 5% to 95%
// PDF417: Level 0-8 (auto-selected based on data)
// Data Matrix: Various schemes

if (barcode.format() == ZXing::BarcodeFormat::QRCode ||
    barcode.format() == ZXing::BarcodeFormat::DataMatrix ||
    barcode.format() == ZXing::BarcodeFormat::Aztec ||
    barcode.format() == ZXing::BarcodeFormat::PDF417) {

    std::string ecLevel = barcode.ecLevel();
    std::cout << "Error correction: " << ecLevel << "\n";
}

Structured Append Support

Formats supporting multi-symbol sequences:

// Formats with structured append support
ZXing::BarcodeFormats structuredFormats =
    ZXing::BarcodeFormat::QRCode |
    ZXing::BarcodeFormat::PDF417 |
    ZXing::BarcodeFormat::DataMatrix |
    ZXing::BarcodeFormat::Aztec;

if (structuredFormats & barcode.format()) {
    if (barcode.isPartOfSequence()) {
        std::cout << "Part of multi-symbol sequence\n";
    }
}

ECI Support

Formats supporting Extended Channel Interpretation:

// Most 2D formats support ECI for character encoding
if (barcode.hasECI()) {
    std::cout << "Barcode uses ECI encoding\n";
}

Format-Specific Features

UPC/EAN Add-On Symbols

// EAN/UPC formats can have 2-digit or 5-digit add-ons
auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::EAN13)
    .setEanAddOnSymbol(ZXing::EanAddOnSymbol::Read);

auto barcode = ZXing::ReadBarcode(image, options);

if (barcode.format() == ZXing::BarcodeFormat::EAN13) {
    std::string addOn = ZXing::GTIN::EanAddOn(barcode);
    if (!addOn.empty()) {
        std::cout << "Add-on: " << addOn << "\n";
    }
}

Code 39 Extended Mode

// Code 39 can encode full ASCII using extended mode
auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::Code39)
    .setTryCode39ExtendedMode(true);

auto barcode = ZXing::ReadBarcode(image, options);

Reader Initialization

// Some formats support reader initialization
if (barcode.readerInit()) {
    std::cout << "Reader Initialization/Programming symbol detected\n";
}

Format Detection Order

When using BarcodeFormat::Any, formats are searched in an optimized order:

  1. Matrix codes (usually faster to detect)
  2. Linear codes (scanned line-by-line)

To improve performance, specify only the formats you expect:

// Slow: searches all formats
auto options1 = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::Any);

// Fast: only searches for QR codes
auto options2 = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::QRCode);

// Medium: searches only retail formats
auto options3 = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::EAN13 |
                ZXing::BarcodeFormat::UPCA);

Format Selection Guidelines

By Use Case

// Retail/Product Scanning
ZXing::BarcodeFormats retail =
    ZXing::BarcodeFormat::EAN13 |
    ZXing::BarcodeFormat::EAN8 |
    ZXing::BarcodeFormat::UPCA |
    ZXing::BarcodeFormat::UPCE;

// Shipping/Logistics
ZXing::BarcodeFormats logistics =
    ZXing::BarcodeFormat::Code128 |
    ZXing::BarcodeFormat::DataMatrix |
    ZXing::BarcodeFormat::MaxiCode;

// General Purpose/Marketing
ZXing::BarcodeFormats marketing =
    ZXing::BarcodeFormat::QRCode |
    ZXing::BarcodeFormat::Aztec;

// Manufacturing/Electronics
ZXing::BarcodeFormats manufacturing =
    ZXing::BarcodeFormat::DataMatrix |
    ZXing::BarcodeFormat::Code128;

// Document/ID Cards
ZXing::BarcodeFormats documents =
    ZXing::BarcodeFormat::PDF417;

Creating Barcodes by Format

When using the experimental writing API:

#ifdef ZXING_EXPERIMENTAL_API
// Create options for specific format
ZXing::CreatorOptions qrOptions(ZXing::BarcodeFormat::QRCode);
qrOptions.ecLevel("H");  // High error correction

auto qrCode = ZXing::CreateBarcodeFromText("Hello World", qrOptions);

// Different format
ZXing::CreatorOptions dmOptions(ZXing::BarcodeFormat::DataMatrix);
dmOptions.forceSquareDataMatrix(true);

auto dataMatrix = ZXing::CreateBarcodeFromText("12345", dmOptions);
#endif

Format Support Status

Reading Support

All listed formats are supported for reading.

Writing Support (Experimental)

Most formats are supported for writing with ZXING_EXPERIMENTAL_API:

#ifdef ZXING_EXPERIMENTAL_API
// Check supported formats at runtime
ZXing::BarcodeFormats readFormats =
    ZXing::SupportedBarcodeFormats(ZXing::Operation::Read);

ZXing::BarcodeFormats writeFormats =
    ZXing::SupportedBarcodeFormats(ZXing::Operation::Create);

ZXing::BarcodeFormats bothFormats =
    ZXing::SupportedBarcodeFormats(ZXing::Operation::CreateAndRead);
#endif

MaxiCode Limitations

MaxiCode has partial read support only (structured messages not fully supported).

Related

  • Barcode Reading - Using formats in reading operations
  • Barcode Writing - Creating barcodes with specific formats
  • Reader Options - Configuring format detection
  • Utilities - Version and format support queries