or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdexperimental-writing.mdimage-processing.mdindex.mdlegacy-writing.mdreading.mdresult-processing.md
tile.json

tessl/generic-zxing-cpp

ZXing-C++ is a comprehensive barcode processing library that provides both reading and writing capabilities for a wide variety of barcode formats implemented in modern C++.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes

pkg:generic/zxing-cpp@2.3.x

To install, run

npx @tessl/cli install tessl/generic-zxing-cpp@2.3.0

index.mddocs/

ZXing-C++

ZXing-C++ ("zebra crossing") is an open-source, multi-format linear/matrix barcode image processing library implemented in C++. Originally ported from the Java ZXing Library, it has evolved into a high-performance C++20 library with significant improvements in runtime and detection performance. It provides comprehensive barcode reading and writing capabilities for a wide variety of formats including QR codes, UPC/EAN codes, DataMatrix, Aztec, PDF417, and many linear barcode formats.

Package Information

  • Package Name: zxing-cpp
  • Package Type: C++ Library
  • Language: C++20 (C++17 compatible mode available)
  • License: Apache-2.0
  • Build System: CMake 3.16+
  • Installation: Via package managers (vcpkg, conan, system packages) or build from source

Core Imports

For C++ projects using CMake:

#include "ZXing/ReadBarcode.h"     // Core reading functionality
#include "ZXing/WriteBarcode.h"    // Experimental writing API
#include "ZXing/MultiFormatWriter.h" // Legacy writing API

Basic Usage

Reading Barcodes

#include "ZXing/ReadBarcode.h"
#include <iostream>

int main() {
    // Assume image data is loaded from somewhere
    int width, height;
    unsigned char* data;
    
    // Create image view - supports various pixel formats
    auto image = ZXing::ImageView(data, width, height, ZXing::ImageFormat::Lum);
    
    // Configure reader options
    auto options = ZXing::ReaderOptions()
        .setFormats(ZXing::BarcodeFormat::Any)
        .setTryHarder(true)
        .setTryRotate(true);
    
    // Read single barcode
    auto result = ZXing::ReadBarcode(image, options);
    if (result.isValid()) {
        std::cout << ZXing::ToString(result.format()) << ": " 
                  << result.text() << std::endl;
    }
    
    // Read multiple barcodes
    auto results = ZXing::ReadBarcodes(image, options);
    for (const auto& barcode : results) {
        std::cout << ZXing::ToString(barcode.format()) << ": " 
                  << barcode.text() << std::endl;
    }
    
    return 0;
}

Writing Barcodes (Legacy API)

#include "ZXing/MultiFormatWriter.h"
#include "ZXing/BitMatrix.h"

// Create writer for specific format
auto writer = ZXing::MultiFormatWriter(ZXing::BarcodeFormat::QRCode)
    .setEncoding(ZXing::CharacterSet::UTF8)
    .setEccLevel(4)
    .setMargin(10);

// Generate barcode as bit matrix
auto matrix = writer.encode("Hello, World!", 300, 300);

// Convert to your preferred image format
// (matrix provides boolean values for each pixel)

Architecture

ZXing-C++ is designed around several key components:

  • Image Processing: ImageView class for zero-copy image data handling with multiple pixel format support
  • Format Detection: Automatic format detection or explicit format specification via BarcodeFormat enumeration
  • Reader Pipeline: Configurable reading pipeline with ReaderOptions for performance vs accuracy trade-offs
  • Writer APIs: Both legacy (MultiFormatWriter) and experimental (WriteBarcode) APIs for barcode generation
  • Type System: Strong typing with comprehensive enum classes and structured result objects
  • Error Handling: Detailed error reporting through Error class with categorized error types
  • Thread Safety: Thread-safe reading operations with no shared state

Capabilities

Barcode Reading

Core barcode detection and decoding functionality supporting over 20 barcode formats. Provides configurable accuracy vs performance trade-offs and comprehensive result metadata.

ZXing::Barcode ReadBarcode(const ImageView& image, const ReaderOptions& options = {});
ZXing::Barcodes ReadBarcodes(const ImageView& image, const ReaderOptions& options = {});

Barcode Reading

Image Processing

Image data handling and format conversion utilities. Supports multiple pixel formats, image transformations, and memory-efficient processing.

class ImageView {
    ImageView() = default;
    ImageView(const uint8_t* data, int width, int height, ImageFormat format, 
              int rowStride = 0, int pixStride = 0);
    ImageView(const uint8_t* data, int size, int width, int height, ImageFormat format, 
              int rowStride = 0, int pixStride = 0);
    
    int width() const;
    int height() const;
    int pixStride() const;
    int rowStride() const;
    ImageFormat format() const;
    
    const uint8_t* data() const;
    const uint8_t* data(int x, int y) const;
    
    ImageView cropped(int left, int top, int width, int height) const;
    ImageView rotated(int degree) const;
    ImageView subsampled(int scale) const;
};

class Image : public ImageView {
    Image() = default;
    Image(int w, int h, ImageFormat f = ImageFormat::Lum);
};

Image Processing

Configuration and Options

Comprehensive configuration system for optimizing barcode detection for specific use cases and image characteristics.

class ReaderOptions {
    ReaderOptions();
    
    // Format selection
    ReaderOptions& setFormats(BarcodeFormats formats);
    BarcodeFormats formats() const noexcept;
    
    // Performance vs accuracy trade-offs
    ReaderOptions& setTryHarder(bool tryHarder);
    ReaderOptions& setTryRotate(bool tryRotate);
    ReaderOptions& setTryInvert(bool tryInvert);
    ReaderOptions& setTryDownscale(bool tryDownscale);
    
    // Binarization
    ReaderOptions& setBinarizer(Binarizer binarizer);
    Binarizer binarizer() const noexcept;
    
    // Image characteristics
    ReaderOptions& setIsPure(bool isPure);
    ReaderOptions& setDownscaleThreshold(uint16_t threshold);
    ReaderOptions& setDownscaleFactor(uint8_t factor);
    
    // Result filtering
    ReaderOptions& setMinLineCount(uint8_t count);
    ReaderOptions& setMaxNumberOfSymbols(uint8_t max);
    ReaderOptions& setReturnErrors(bool returnErrors);
    
    // Text processing
    ReaderOptions& setTextMode(TextMode mode);
    ReaderOptions& setCharacterSet(CharacterSet charset);
    ReaderOptions& setCharacterSet(std::string_view charset);
    
    // Format-specific options
    ReaderOptions& setTryCode39ExtendedMode(bool tryExtended);
    ReaderOptions& setEanAddOnSymbol(EanAddOnSymbol mode);
    
    bool hasFormat(BarcodeFormats f) const noexcept;
};

Configuration

Legacy Barcode Writing

Established barcode generation API supporting the most common barcode formats with basic customization options.

class MultiFormatWriter {
    explicit MultiFormatWriter(BarcodeFormat format);
    
    MultiFormatWriter& setEncoding(CharacterSet encoding);
    MultiFormatWriter& setEccLevel(int level);
    MultiFormatWriter& setMargin(int margin);
    
    BitMatrix encode(const std::string& contents, int width, int height) const;
    BitMatrix encode(const std::wstring& contents, int width, int height) const;
};

Legacy Writing

Experimental Barcode Writing

Advanced barcode generation API with extended format support and multiple output formats including SVG, UTF-8 text, and bitmap images.

class CreatorOptions {
    CreatorOptions(BarcodeFormat format);
    ~CreatorOptions();
    CreatorOptions(CreatorOptions&&);
    CreatorOptions& operator=(CreatorOptions&&);
    
    CreatorOptions& format(BarcodeFormat f);
    CreatorOptions& readerInit(bool v);
    CreatorOptions& forceSquareDataMatrix(bool v);
    CreatorOptions& ecLevel(std::string level);
};

class WriterOptions {
    WriterOptions();
    ~WriterOptions();
    WriterOptions(WriterOptions&&);
    WriterOptions& operator=(WriterOptions&&);
    
    WriterOptions& scale(int scale);
    WriterOptions& sizeHint(int hint);
    WriterOptions& rotate(int degrees);
    WriterOptions& withHRT(bool hrt);
    WriterOptions& withQuietZones(bool quiet);
};

Barcode CreateBarcodeFromText(std::string_view contents, const CreatorOptions& options);
Barcode CreateBarcodeFromBytes(const void* data, int size, const CreatorOptions& options);

std::string WriteBarcodeToSVG(const Barcode& barcode, const WriterOptions& options = {});
std::string WriteBarcodeToUtf8(const Barcode& barcode, const WriterOptions& options = {});
Image WriteBarcodeToImage(const Barcode& barcode, const WriterOptions& options = {});

Experimental Writing

Result Processing

Comprehensive result analysis and metadata extraction from decoded barcodes, including structured append sequence handling and error analysis.

class Result {
    Result() = default;
    Result(const std::string& text, int y, int xStart, int xStop, 
           BarcodeFormat format, SymbologyIdentifier si, Error error = {},
           bool readerInit = false);
    
    bool isValid() const;
    BarcodeFormat format() const;
    
    const ByteArray& bytes() const;
    ByteArray bytesECI() const;
    std::string text(TextMode mode) const;
    std::string text() const;
    
    std::string ecLevel() const;
    ContentType contentType() const;
    bool hasECI() const;
    
    const Position& position() const;
    void setPosition(Position pos);
    int orientation() const;
    
    bool isMirrored() const;
    bool isInverted() const;
    
    std::string symbologyIdentifier() const;
    
    int sequenceSize() const;
    int sequenceIndex() const;
    std::string sequenceId() const;
    bool isLastInSequence() const;
    bool isPartOfSequence() const;
    
    bool readerInit() const;
    int lineCount() const;
    std::string version() const;
    
    const Error& error() const;
    
    bool operator==(const Result& other) const;
};

Barcode MergeStructuredAppendSequence(const Barcodes& results);
Barcodes MergeStructuredAppendSequences(const Barcodes& barcodes);

Result Processing

Supported Formats

ZXing-C++ supports the following barcode formats:

Linear/1D Formats:

  • UPC-A, UPC-E
  • EAN-8, EAN-13
  • Code 39, Code 93, Code 128
  • Codabar
  • ITF (Interleaved Two of Five)
  • DataBar (RSS), DataBar Expanded, DataBar Limited
  • DX Film Edge

Matrix/2D Formats:

  • QR Code, Micro QR Code, rMQR Code
  • DataMatrix
  • Aztec
  • PDF417
  • MaxiCode (partial support)

Types

enum class BarcodeFormat {
    None, Aztec, Codabar, Code39, Code93, Code128, DataBar, DataBarExpanded,
    DataMatrix, EAN8, EAN13, ITF, MaxiCode, PDF417, QRCode, UPCA, UPCE,
    MicroQRCode, RMQRCode, DXFilmEdge, DataBarLimited,
    
    LinearCodes = Codabar | Code39 | Code93 | Code128 | EAN8 | EAN13 | ITF | 
                  DataBar | DataBarExpanded | DataBarLimited | DXFilmEdge | UPCA | UPCE,
    MatrixCodes = Aztec | DataMatrix | MaxiCode | PDF417 | QRCode | MicroQRCode | RMQRCode,
    Any = LinearCodes | MatrixCodes
};

enum class ImageFormat : uint32_t {
    None, Lum, LumA, RGB, BGR, RGBA, ARGB, BGRA, ABGR
};

enum class TextMode : unsigned char {
    Plain, ECI, HRI, Hex, Escaped
};

enum class Binarizer : unsigned char {
    LocalAverage, GlobalHistogram, FixedThreshold, BoolCast
};

enum class EanAddOnSymbol : unsigned char {
    Ignore, Read, Require
};

enum class ContentType { 
    Text, Binary, Mixed, GS1, ISO15434, UnknownECI 
};

enum class CharacterSet : unsigned char {
    Unknown, ASCII, ISO8859_1, ISO8859_2, ISO8859_3, ISO8859_4, ISO8859_5,
    ISO8859_6, ISO8859_7, ISO8859_8, ISO8859_9, ISO8859_10, ISO8859_11,
    ISO8859_13, ISO8859_14, ISO8859_15, ISO8859_16, Cp437, Cp1250, Cp1251,
    Cp1252, Cp1256, Shift_JIS, Big5, GB2312, GB18030, EUC_JP, EUC_KR,
    UTF16BE, UTF8, UTF16LE, UTF32BE, UTF32LE
};

class Error {
    enum class Type : uint8_t { None, Format, Checksum, Unsupported };
    
    Error() = default;
    Error(Type type, std::string msg = {});
    
    Type type() const noexcept;
    const std::string& msg() const noexcept;
    std::string location() const;
    explicit operator bool() const noexcept;
    
    bool operator==(const Error& other) const noexcept;
    bool operator!=(const Error& other) const noexcept;
    
    static constexpr auto Format = Type::Format;
    static constexpr auto Checksum = Type::Checksum;
    static constexpr auto Unsupported = Type::Unsupported;
};

class ByteArray : public std::vector<uint8_t> {
    ByteArray() = default;
    ByteArray(std::initializer_list<uint8_t> list);
    explicit ByteArray(int len);
    explicit ByteArray(const std::string& str);
    
    void append(const ByteArray& other);
    std::string_view asString(size_t pos = 0, size_t len = std::string_view::npos) const;
};

class BitMatrix {
    BitMatrix() = default;
    BitMatrix(int width, int height);
    explicit BitMatrix(int dimension);
    
    int width() const;
    int height() const;
    bool get(int x, int y) const;
    void set(int x, int y, bool val = true);
    void flip(int x, int y);
    void flipAll();
    
    BitMatrix copy() const;
};

template <typename T>
class Quadrilateral : public std::array<T, 4> {
    using Point = T;
    
    Quadrilateral() = default;
    Quadrilateral(T tl, T tr, T br, T bl);
    
    constexpr Point topLeft() const noexcept;
    constexpr Point topRight() const noexcept;
    constexpr Point bottomRight() const noexcept;
    constexpr Point bottomLeft() const noexcept;
    
    double orientation() const;
};

struct SymbologyIdentifier {
    char code = 0;
    char modifier = 0;
    char eciModifierOffset = 0;
    
    std::string toString(bool hasECI = false) const;
};

// Utility Functions
std::string ToString(BarcodeFormat format);
std::string ToString(BarcodeFormats formats);
std::string ToString(ContentType type);
std::string ToString(const Error& e);

BarcodeFormat BarcodeFormatFromString(std::string_view str);
BarcodeFormats BarcodeFormatsFromString(std::string_view str);
CharacterSet CharacterSetFromString(std::string_view str);

std::string ToHex(const ByteArray& bytes);

// Type Aliases
using Position = QuadrilateralI;
using QuadrilateralF = Quadrilateral<PointF>;
using QuadrilateralI = Quadrilateral<PointI>;
using Barcode = Result;
using Barcodes = std::vector<Barcode>;
using BarcodeFormats = Flags<BarcodeFormat>;