or run

tessl search

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++

ZXing-C++

ZXing-C++ ("zebra crossing") is an open-source, multi-format barcode image processing library for C++. It reads and writes barcodes in 20+ formats including QR codes, Data Matrix, Aztec, PDF417, and all common linear barcodes (UPC, EAN, Code 128, etc.).

Package Information

Package: zxing-cpp (PyPI), GitHub: zxing-cpp/zxing-cpp
Language: C++20 (C++17 compatible with limitations)
License: Apache-2.0
Version: 2.3.0
Namespace: ZXing
Dependencies: None (pure C++)
Thread Safety: Fully thread-safe

Quick Start

Reading Barcodes

#include "ZXing/ReadBarcode.h"

auto image = ZXing::ImageView(data, width, height, ZXing::ImageFormat::Lum);
auto options = ZXing::ReaderOptions().setFormats(ZXing::BarcodeFormat::Any);
auto barcodes = ZXing::ReadBarcodes(image, options);

for (const auto& barcode : barcodes) {
    if (barcode.isValid()) {
        std::cout << barcode.text() << "\n";
    }
}

Writing Barcodes (Experimental)

#include "ZXing/WriteBarcode.h"

ZXing::CreatorOptions options(ZXing::BarcodeFormat::QRCode);
auto barcode = ZXing::CreateBarcodeFromText("Hello World", options);
auto svg = ZXing::WriteBarcodeToSVG(barcode);

Core API

Main Functions

namespace ZXing {
    // Reading
    Barcode ReadBarcode(const ImageView& image, const ReaderOptions& options = {});
    Barcodes ReadBarcodes(const ImageView& image, const ReaderOptions& options = {});
    
    // Writing (experimental)
    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 = {});
    Image WriteBarcodeToImage(const Barcode& barcode, const WriterOptions& options = {});
}

Key Types

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

class Barcode {
    bool isValid() const;
    const Error& error() const;
    BarcodeFormat format() const;
    std::string text() const;
    const ByteArray& bytes() const;
    const Position& position() const;
    int orientation() const;
};

class ReaderOptions {
    ReaderOptions& setFormats(BarcodeFormats v);
    ReaderOptions& setTryHarder(bool v);
    ReaderOptions& setTryRotate(bool v);
    ReaderOptions& setTryInvert(bool v);
    ReaderOptions& setMaxNumberOfSymbols(uint8_t v);
};

Supported Formats

Linear (1D) Codes

UPC-A, UPC-E, EAN-8, EAN-13, Code 39, Code 93, Code 128, Codabar, ITF, GS1 DataBar (all variants), DX Film Edge

2D/Matrix Codes

QR Code, Micro QR Code, rMQR Code, Aztec, Data Matrix, PDF417, MaxiCode

Quick Reference

Image Formats

Format	Description	Bytes/Pixel
`Lum`	Grayscale	1
`RGB`	Red-Green-Blue	3
`BGR`	Blue-Green-Red (OpenCV)	3
`RGBA`	RGB + Alpha	4
`BGRA`	BGR + Alpha	4

Reader Options

Option	Default	Description
`formats`	None	Barcode formats to detect
`tryHarder`	true	Spend more time for accuracy
`tryRotate`	true	Try 90/180/270° rotations
`tryInvert`	true	Try inverted colors
`tryDownscale`	true	Downscale large images
`maxNumberOfSymbols`	255	Max barcodes to find

Error Types

Type	Description
`None`	No error
`Format`	Decoding/format error
`Checksum`	Checksum validation failed
`Unsupported`	Unsupported feature

Barcode Format Groups

BarcodeFormat::LinearCodes  // All 1D formats
BarcodeFormat::MatrixCodes  // All 2D formats
BarcodeFormat::Any          // All formats

Build Configuration

CMake Flags

ZXING_EXPERIMENTAL_API=ON - Enable writing API
ZXING_WRITERS=ON - Enable barcode writing
ZXING_READERS=ON - Enable barcode reading (default)
ZXING_C_API=ON - Build C API wrapper

Requirements

C++20 recommended (C++17 with limitations)
CMake 3.16+
No external dependencies

Language Wrappers

Official wrappers available for: C, Python, Rust, Android (Java/Kotlin), iOS (Objective-C/Swift), .NET (C#/F#), WebAssembly, WinRT, Kotlin/Native

Documentation

Guides

Quick Start Guide - Getting started with ZXing-C++
Integration Guide - Integrating with OpenCV, Qt, and other frameworks

Examples

Real-World Scenarios - Common use cases and patterns
Edge Cases - Advanced scenarios and troubleshooting

API Reference

Reading API - Barcode detection and decoding
Writing API - Barcode generation (experimental)
Barcode Results - Result objects and metadata
Image Handling - ImageView and image formats
Reader Options - Configuration options
Barcode Formats - Supported formats details
Error Handling - Error types and handling
Geometry - Position and geometric types
Character Encodings - Text encoding support
GTIN Utilities - UPC/EAN utilities
Structured Append - Multi-symbol barcodes
C API - C wrapper API
Utilities - Version and utility functions

Common Patterns

Read QR Code from OpenCV Mat

cv::Mat mat = cv::imread("image.jpg");
auto image = ZXing::ImageView(mat.data, mat.cols, mat.rows, 
                               ZXing::ImageFormat::BGR, mat.step);
auto barcode = ZXing::ReadBarcode(image);

Generate QR Code to SVG

ZXing::CreatorOptions opts(ZXing::BarcodeFormat::QRCode);
opts.ecLevel("H");
auto barcode = ZXing::CreateBarcodeFromText("https://example.com", opts);
auto svg = ZXing::WriteBarcodeToSVG(barcode);

Read Multiple Barcodes

auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::Any)
    .setMaxNumberOfSymbols(10);
auto barcodes = ZXing::ReadBarcodes(image, options);

Handle Errors

auto barcode = ZXing::ReadBarcode(image);
if (!barcode.isValid()) {
    std::cerr << "Error: " << barcode.error().msg() << "\n";
}

Performance Tips

Use Grayscale: Convert images to grayscale before processing
Specify Formats: Limit to expected formats for faster detection
Crop ROI: Process only the region containing the barcode
Disable Strategies: Turn off tryRotate, tryInvert if not needed
Downscale Large Images: Enable tryDownscale for high-resolution images

Design Philosophy

Value Types: No hidden heap allocations in hot paths
Thread-Safe: All operations are thread-safe
No Exceptions: Errors returned via Error type, not exceptions
Zero Dependencies: Pure C++ with no external libraries
Chainable API: Builder pattern for options classes

Version Information

const std::string& ZXing::Version();  // Get library version

Current version: 2.3.0

Version