or run

tessl search

Version

Workspace: tessl
Visibility: Public
Created: about 8 hours ago
Last updated: about 8 hours ago

docs

examples

guides

reference

c-api.md encodings.md errors.md formats.md geometry.md gtin.md images.md reader-options.md reading.md results.md structured-append.md utilities.md writing.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++

Reader Configuration

The ReaderOptions class provides extensive configuration for barcode detection and decoding. All options use a chainable builder pattern for convenient configuration.

ReaderOptions Class

class ReaderOptions {
public:
    ReaderOptions();  // Constructor with sensible defaults

    // Format Selection
    BarcodeFormats formats() const;
    ReaderOptions& setFormats(BarcodeFormats v) &;
    ReaderOptions&& setFormats(BarcodeFormats v) &&;

    // Scanning Strategies
    bool tryHarder() const;
    ReaderOptions& setTryHarder(bool v) &;
    ReaderOptions&& setTryHarder(bool v) &&;

    bool tryRotate() const;
    ReaderOptions& setTryRotate(bool v) &;
    ReaderOptions&& setTryRotate(bool v) &&;

    bool tryInvert() const;
    ReaderOptions& setTryInvert(bool v) &;
    ReaderOptions&& setTryInvert(bool v) &&;

    bool tryDownscale() const;
    ReaderOptions& setTryDownscale(bool v) &;
    ReaderOptions&& setTryDownscale(bool v) &&;

    #ifdef ZXING_EXPERIMENTAL_API
    bool tryDenoise() const;
    ReaderOptions& setTryDenoise(bool v) &;
    ReaderOptions&& setTryDenoise(bool v) &&;
    #endif

    // Binarization
    Binarizer binarizer() const;
    ReaderOptions& setBinarizer(Binarizer v) &;
    ReaderOptions&& setBinarizer(Binarizer v) &&;

    // Pure Mode
    bool isPure() const;
    ReaderOptions& setIsPure(bool v) &;
    ReaderOptions&& setIsPure(bool v) &&;

    // Downscaling Parameters
    uint16_t downscaleThreshold() const;
    ReaderOptions& setDownscaleThreshold(uint16_t v) &;
    ReaderOptions&& setDownscaleThreshold(uint16_t v) &&;

    uint8_t downscaleFactor() const;
    ReaderOptions& setDownscaleFactor(uint8_t v) &;
    ReaderOptions&& setDownscaleFactor(uint8_t v) &&;

    // Linear Barcode Options
    uint8_t minLineCount() const;
    ReaderOptions& setMinLineCount(uint8_t v) &;
    ReaderOptions&& setMinLineCount(uint8_t v) &&;

    bool tryCode39ExtendedMode() const;
    ReaderOptions& setTryCode39ExtendedMode(bool v) &;
    ReaderOptions&& setTryCode39ExtendedMode(bool v) &&;

    bool returnCodabarStartEnd() const;  // Deprecated
    ReaderOptions& setReturnCodabarStartEnd(bool v) &;
    ReaderOptions&& setReturnCodabarStartEnd(bool v) &&;

    bool validateCode39CheckSum() const;  // Deprecated
    ReaderOptions& setValidateCode39CheckSum(bool v) &;
    ReaderOptions&& setValidateCode39CheckSum(bool v) &&;

    bool validateITFCheckSum() const;  // Deprecated
    ReaderOptions& setValidateITFCheckSum(bool v) &;
    ReaderOptions&& setValidateITFCheckSum(bool v) &&;

    // Multi-Symbol Detection
    uint8_t maxNumberOfSymbols() const;
    ReaderOptions& setMaxNumberOfSymbols(uint8_t v) &;
    ReaderOptions&& setMaxNumberOfSymbols(uint8_t v) &&;

    // Error Reporting
    bool returnErrors() const;
    ReaderOptions& setReturnErrors(bool v) &;
    ReaderOptions&& setReturnErrors(bool v) &&;

    // EAN/UPC Options
    EanAddOnSymbol eanAddOnSymbol() const;
    ReaderOptions& setEanAddOnSymbol(EanAddOnSymbol v) &;
    ReaderOptions&& setEanAddOnSymbol(EanAddOnSymbol v) &&;

    // Text Rendering
    TextMode textMode() const;
    ReaderOptions& setTextMode(TextMode v) &;
    ReaderOptions&& setTextMode(TextMode v) &&;

    CharacterSet characterSet() const;
    ReaderOptions& setCharacterSet(CharacterSet v) &;
    ReaderOptions&& setCharacterSet(CharacterSet v) &&;
    ReaderOptions& setCharacterSet(std::string_view v) &;
    ReaderOptions&& setCharacterSet(std::string_view v) &&;

    // Utility
    bool hasFormat(BarcodeFormats f) const;
};

Default Values

ReaderOptions defaults:
  formats: None (will scan all formats)
  tryHarder: true
  tryRotate: true
  tryInvert: true
  tryDownscale: true
  tryDenoise: false
  binarizer: LocalAverage
  isPure: false
  downscaleThreshold: 500
  downscaleFactor: 3
  minLineCount: 2
  maxNumberOfSymbols: 255
  tryCode39ExtendedMode: true
  returnErrors: false
  eanAddOnSymbol: Ignore
  textMode: HRI
  characterSet: Unknown (auto-detect)

Format Selection

// Scan for all formats (default)
auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::Any);

// Scan for specific format
options.setFormats(ZXing::BarcodeFormat::QRCode);

// Scan for multiple formats (bitwise OR)
options.setFormats(
    ZXing::BarcodeFormat::QRCode |
    ZXing::BarcodeFormat::DataMatrix |
    ZXing::BarcodeFormat::PDF417
);

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

// All 2D codes
options.setFormats(ZXing::BarcodeFormat::MatrixCodes);

Scanning Strategies

Try Harder

Spend more time analyzing the image:

options.setTryHarder(true);  // Default

Benefits: Higher detection rate, especially for damaged/poor quality barcodes Drawback: Slower processing

Try Rotate

Attempt to detect barcodes at 90°, 180°, and 270° orientations:

options.setTryRotate(true);  // Default

Benefits: Finds barcodes regardless of orientation Drawback: ~4x slower (tries 4 orientations)

Try Invert

Look for inverted barcodes (light bars on dark background):

options.setTryInvert(true);  // Default

Benefits: Finds inverted codes Drawback: ~2x slower

Try Downscale

For large images, try downscaled versions:

options.setTryDownscale(true);  // Default

Benefits: Faster on large images, can improve detection Parameters: downscaleThreshold, downscaleFactor

Try Denoise (Experimental)

Apply morphological closing filter before detection:

#ifdef ZXING_EXPERIMENTAL_API
options.setTryDenoise(true);  // Default: false
#endif

Benefits: Better detection on noisy images Drawback: Slower, experimental feature

Binarization

enum class Binarizer {
    LocalAverage,    // Adaptive local threshold
    GlobalHistogram, // Global histogram-based threshold
    FixedThreshold,  // Fixed at 127
    BoolCast         // Threshold at 0
};

// Default: LocalAverage for matrix codes, GlobalHistogram for linear
options.setBinarizer(ZXing::Binarizer::LocalAverage);

// For pre-binarized images
options.setBinarizer(ZXing::Binarizer::BoolCast);

// For uniform lighting
options.setBinarizer(ZXing::Binarizer::GlobalHistogram);

Pure Mode

For synthetic/generated barcodes with perfect alignment:

options.setIsPure(true);  // Default: false

Enables fast-path processing. Only use when:

Image contains single barcode
Barcode is perfectly aligned (no rotation)
No perspective distortion
No noise or damage

Downscaling Parameters

Control when and how downscaling occurs:

// Downscale if min(width, height) > 500
options.setDownscaleThreshold(500);  // Default

// Scale factor (2, 3, or 4)
options.setDownscaleFactor(3);  // Default

// Example: 3000x2000 image → 1000x666 (factor 3)

Linear Barcode Options

Minimum Line Count

Number of scan lines that must match:

options.setMinLineCount(2);  // Default

// More conservative (fewer false positives)
options.setMinLineCount(3);

// More aggressive (more detections, more false positives)
options.setMinLineCount(1);

Code 39 Extended Mode

Enable full ASCII support for Code 39:

options.setTryCode39ExtendedMode(true);  // Default

Multi-Symbol Detection

Maximum number of barcodes to find:

// Find up to 10 barcodes
options.setMaxNumberOfSymbols(10);

// Find all barcodes (up to 255)
options.setMaxNumberOfSymbols(255);  // Default

// Stop after first barcode
options.setMaxNumberOfSymbols(1);

Error Reporting

Return barcodes even if they have errors:

options.setReturnErrors(true);  // Default: false

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

for (const auto& bc : barcodes) {
    if (!bc.isValid()) {
        // Check error
        auto err = bc.error();
        if (err.type() == ZXing::Error::Checksum) {
            std::cerr << "Checksum error: " << err.msg() << "\n";
        }
    }
}

EAN/UPC Add-On Handling

enum class EanAddOnSymbol {
    Ignore,  // Don't look for add-on
    Read,    // Read if present
    Require  // Require add-on
};

// Read EAN-2/5 add-on if present
options.setEanAddOnSymbol(ZXing::EanAddOnSymbol::Read);

// Require add-on (reject without it)
options.setEanAddOnSymbol(ZXing::EanAddOnSymbol::Require);

// Ignore add-on (default)
options.setEanAddOnSymbol(ZXing::EanAddOnSymbol::Ignore);

Text Rendering

enum class TextMode {
    Plain,   // Decoded text (default before v2.0)
    ECI,     // ECI protocol preserved
    HRI,     // Human Readable Interpretation (default)
    Hex,     // Hex dump of bytes
    Escaped  // Non-printable chars escaped
};

// Human-readable (default)
options.setTextMode(ZXing::TextMode::HRI);

auto barcode = ZXing::ReadBarcode(image, options);
std::string text = barcode.text();  // Uses HRI mode

// Or override per barcode
std::string plain = barcode.text(ZXing::TextMode::Plain);
std::string hex = barcode.text(ZXing::TextMode::Hex);

Character Set

Fallback character set when auto-detection fails:

// Auto-detect (default)
options.setCharacterSet(ZXing::CharacterSet::Unknown);

// Force specific charset
options.setCharacterSet(ZXing::CharacterSet::UTF8);
options.setCharacterSet(ZXing::CharacterSet::Shift_JIS);

// From string
options.setCharacterSet("ISO-8859-1");

Method Chaining

All setters support chaining:

auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::QRCode)
    .setTryHarder(true)
    .setTryRotate(false)
    .setMaxNumberOfSymbols(5)
    .setTextMode(ZXing::TextMode::Plain);

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

Preset Configurations

Fast Scan (Known Barcode Type)

auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::QRCode)
    .setTryHarder(false)
    .setTryRotate(false)
    .setTryInvert(false)
    .setTryDownscale(false);

Accurate Scan (Any Barcode)

auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::Any)
    .setTryHarder(true)
    .setTryRotate(true)
    .setTryInvert(true)
    .setTryDownscale(true)
    .setMaxNumberOfSymbols(20);

Pure Barcode (Generated Image)

auto options = ZXing::ReaderOptions()
    .setFormats(ZXing::BarcodeFormat::QRCode)
    .setIsPure(true)
    .setTryRotate(false)
    .setBinarizer(ZXing::Binarizer::BoolCast);

Large Image Optimization

auto options = ZXing::ReaderOptions()
    .setTryDownscale(true)
    .setDownscaleThreshold(1000)
    .setDownscaleFactor(4);

Barcode Reading - Using ReaderOptions with reading functions
Barcode Formats - Available format constants
Character Encodings - Character set details

Version

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

reader-options.mddocs/reference/

Reader Configuration

ReaderOptions Class

Default Values

Format Selection

Scanning Strategies

Try Harder

Try Rotate

Try Invert

Try Downscale

Try Denoise (Experimental)

Binarization

Pure Mode

Downscaling Parameters

Linear Barcode Options

Minimum Line Count

Code 39 Extended Mode

Multi-Symbol Detection

Error Reporting

EAN/UPC Add-On Handling

Text Rendering

Character Set

Method Chaining

Preset Configurations

Fast Scan (Known Barcode Type)

Accurate Scan (Any Barcode)

Pure Barcode (Generated Image)

Large Image Optimization

Related

Version

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

reader-options.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/reference/

Reader Configuration

ReaderOptions Class

Default Values

Format Selection

Scanning Strategies

Try Harder

Try Rotate

Try Invert

Try Downscale

Try Denoise (Experimental)

Binarization

Pure Mode

Downscaling Parameters

Linear Barcode Options

Minimum Line Count

Code 39 Extended Mode

Multi-Symbol Detection

Error Reporting

EAN/UPC Add-On Handling

Text Rendering

Character Set

Method Chaining

Preset Configurations

Fast Scan (Known Barcode Type)

Accurate Scan (Any Barcode)

Pure Barcode (Generated Image)

Large Image Optimization

Related

reader-options.mddocs/reference/