or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated

docs

guides

integration.mdquick-start.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++

quick-start.mddocs/guides/

Quick Start Guide

This guide will help you get started with ZXing-C++ for reading and writing barcodes.

Installation

Via Package Managers

# vcpkg
vcpkg install zxing-cpp

# conan
conan install zxing-cpp

# pip (Python bindings)
pip install zxing-cpp

# Linux distributions
apt install libzxing-dev  # Debian/Ubuntu
dnf install zxing-cpp-devel  # Fedora

CMake Integration

find_package(ZXing REQUIRED)
target_link_libraries(your_app ZXing::ZXing)

Reading Your First Barcode

Step 1: Include Headers

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

Step 2: Prepare Image Data

// Example: grayscale image data
uint8_t* imageData = /* your image data */;
int width = 640;
int height = 480;

// Create ImageView
auto image = ZXing::ImageView(imageData, width, height, ZXing::ImageFormat::Lum);

Step 3: Read Barcode

// Read single barcode
auto barcode = ZXing::ReadBarcode(image);

if (barcode.isValid()) {
    std::cout << "Found: " << barcode.text() << "\n";
    std::cout << "Format: " << ZXing::ToString(barcode.format()) << "\n";
} else {
    std::cerr << "No barcode found\n";
}

Complete Example

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

int main() {
    // Your image data (example: grayscale)
    uint8_t* data = loadImage("barcode.png");
    int width = 640, height = 480;
    
    // Create image view
    auto image = ZXing::ImageView(data, width, height, ZXing::ImageFormat::Lum);
    
    // Read barcode
    auto barcode = ZXing::ReadBarcode(image);
    
    if (barcode.isValid()) {
        std::cout << "Text: " << barcode.text() << "\n";
        std::cout << "Format: " << ZXing::ToString(barcode.format()) << "\n";
    } else {
        std::cerr << "Error: " << barcode.error().msg() << "\n";
    }
    
    return 0;
}

Reading Multiple Barcodes

#include "ZXing/ReadBarcode.h"

// Configure to find multiple barcodes
auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::Any)
    .setMaxNumberOfSymbols(10);

auto barcodes = ZXing::ReadBarcodes(image, options);

std::cout << "Found " << barcodes.size() << " barcodes:\n";
for (const auto& bc : barcodes) {
    if (bc.isValid()) {
        std::cout << "  " << ZXing::ToString(bc.format()) 
                  << ": " << bc.text() << "\n";
    }
}

Configuring Reader Options

Specify Barcode Formats

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

// Multiple formats
auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::QRCode | 
                ZXing::BarcodeFormat::DataMatrix);

// All linear codes
auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::LinearCodes);

Adjust Detection Strategies

auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::Any)
    .setTryHarder(true)       // More thorough scanning
    .setTryRotate(true)       // Try rotated images
    .setTryInvert(true)       // Try inverted colors
    .setTryDownscale(true);   // Downscale large images

Writing Your First Barcode (Experimental)

Note: Requires ZXING_EXPERIMENTAL_API=ON when building.

Step 1: Include Headers

#include "ZXing/WriteBarcode.h"

Step 2: Create Barcode

// Create QR code
ZXing::CreatorOptions options(ZXing::BarcodeFormat::QRCode);
options.ecLevel("H");  // High error correction

auto barcode = ZXing::CreateBarcodeFromText("Hello World", options);

Step 3: Render Barcode

// Render to SVG
auto svg = ZXing::WriteBarcodeToSVG(barcode);
std::cout << svg << "\n";

// Or render to image
ZXing::WriterOptions writerOpts;
writerOpts.scale(4).withQuietZones(true);
auto image = ZXing::WriteBarcodeToImage(barcode, writerOpts);

Complete Example

#include "ZXing/WriteBarcode.h"
#include <fstream>

int main() {
    // Create QR code
    ZXing::CreatorOptions options(ZXing::BarcodeFormat::QRCode);
    options.ecLevel("H");
    
    auto barcode = ZXing::CreateBarcodeFromText("https://example.com", options);
    
    if (!barcode.isValid()) {
        std::cerr << "Failed to create barcode\n";
        return 1;
    }
    
    // Render to SVG
    ZXing::WriterOptions writerOpts;
    writerOpts.scale(4).withQuietZones(true);
    auto svg = ZXing::WriteBarcodeToSVG(barcode, writerOpts);
    
    // Save to file
    std::ofstream file("qrcode.svg");
    file << svg;
    
    return 0;
}

Working with Different Image Formats

Grayscale (Recommended)

auto image = ZXing::ImageView(data, width, height, ZXing::ImageFormat::Lum);

RGB

auto image = ZXing::ImageView(rgbData, width, height, ZXing::ImageFormat::RGB);

BGR (OpenCV default)

auto image = ZXing::ImageView(bgrData, width, height, ZXing::ImageFormat::BGR);

RGBA

auto image = ZXing::ImageView(rgbaData, width, height, ZXing::ImageFormat::RGBA);

Integration with OpenCV

#include <opencv2/opencv.hpp>
#include "ZXing/ReadBarcode.h"

cv::Mat mat = cv::imread("barcode.jpg");

// OpenCV uses BGR format
auto image = ZXing::ImageView(
    mat.data, 
    mat.cols, 
    mat.rows,
    ZXing::ImageFormat::BGR,
    mat.step  // row stride
);

auto barcode = ZXing::ReadBarcode(image);

Error Handling

Check Validity

auto barcode = ZXing::ReadBarcode(image);

if (!barcode.isValid()) {
    const auto& error = barcode.error();
    std::cerr << "Error type: " << static_cast<int>(error.type()) << "\n";
    std::cerr << "Message: " << error.msg() << "\n";
}

Error Types

switch (barcode.error().type()) {
    case ZXing::Error::Type::None:
        // Success
        break;
    case ZXing::Error::Type::Format:
        // Decoding error
        break;
    case ZXing::Error::Type::Checksum:
        // Checksum validation failed
        break;
    case ZXing::Error::Type::Unsupported:
        // Unsupported feature
        break;
}

Common Pitfalls

1. Wrong Image Format

// ❌ Wrong: OpenCV uses BGR, not RGB
auto image = ZXing::ImageView(mat.data, mat.cols, mat.rows, 
                               ZXing::ImageFormat::RGB);

// ✅ Correct: Specify BGR for OpenCV
auto image = ZXing::ImageView(mat.data, mat.cols, mat.rows, 
                               ZXing::ImageFormat::BGR, mat.step);

2. Not Checking Validity

// ❌ Wrong: Using result without checking
auto barcode = ZXing::ReadBarcode(image);
std::cout << barcode.text();  // May crash if invalid

// ✅ Correct: Always check validity first
if (barcode.isValid()) {
    std::cout << barcode.text();
}

3. Missing Row Stride

// ❌ Wrong: Ignoring row padding
auto image = ZXing::ImageView(data, width, height, format);

// ✅ Correct: Specify row stride if image has padding
auto image = ZXing::ImageView(data, width, height, format, rowStride);

Performance Tips

1. Use Grayscale

// Convert to grayscale before processing
cv::Mat gray;
cv::cvtColor(mat, gray, cv::COLOR_BGR2GRAY);
auto image = ZXing::ImageView(gray.data, gray.cols, gray.rows, 
                               ZXing::ImageFormat::Lum);

2. Limit Format Search

// Faster: only search for expected format
auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::QRCode);

3. Crop to Region of Interest

auto fullImage = ZXing::ImageView(data, width, height, format);
auto roi = fullImage.cropped(x, y, roiWidth, roiHeight);
auto barcode = ZXing::ReadBarcode(roi);

4. Disable Unnecessary Strategies

// If barcodes are always upright and not inverted
auto options = ZXing::ReaderOptions()
    .setTryRotate(false)
    .setTryInvert(false);

Next Steps

  • Real-World Scenarios - Common use cases
  • Integration Guide - Integrate with various frameworks
  • API Reference - Complete API documentation
  • Edge Cases - Advanced scenarios

Troubleshooting

Barcode Not Detected

  1. Check image quality (resolution, contrast)
  2. Try setTryHarder(true)
  3. Enable setTryRotate(true) and setTryInvert(true)
  4. Verify correct image format
  5. Check if barcode format is supported

Poor Performance

  1. Convert to grayscale
  2. Specify exact barcode format
  3. Crop to region of interest
  4. Disable unnecessary detection strategies
  5. Enable downscaling for large images

Compilation Errors

  1. Ensure C++20 support (or C++17 minimum)
  2. Link with ZXing library
  3. Check CMake configuration
  4. For writing API, enable ZXING_EXPERIMENTAL_API

Getting Help

  • Documentation: See API Reference for detailed information
  • Examples: Check Real-World Scenarios
  • GitHub: https://github.com/zxing-cpp/zxing-cpp
  • Issues: Report bugs on GitHub Issues