CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-google-zxing--core

Core barcode encoding/decoding library supporting 17 formats including QR Code, Data Matrix, Aztec, PDF 417, and various 1D barcodes

—

Pending
Overview
Eval results
Files

configuration-hints.mddocs/reference/

Configuration Hints

Extensive configuration options for customizing decode and encode operations. DecodeHintType controls detection behavior (accuracy vs. speed, format filtering, character encoding), while EncodeHintType controls encoding parameters (error correction, margins, format-specific options). Hints are passed as Map<HintType, Object> to Reader and Writer methods.

Capabilities

DecodeHintType

Configuration options for barcode decoding operations. Passed as hints map to Reader.decode() methods.

/**
 * Enumeration of decode hint types for configuring Reader behavior.
 * Hints customize detection algorithms, format filtering, and character handling.
 */
public enum DecodeHintType {
    /**
     * Unspecified hint type for custom or format-specific hints (Object).
     * Used for passing additional configuration to specific readers.
     * Default: null
     */
    OTHER,

    /**
     * Image is pure barcode with no border/quiet zone (Boolean).
     * Enables fast extraction for clean synthetic images.
     * Default: false
     */
    PURE_BARCODE,

    /**
     * Limit decoding to specific formats (Collection<BarcodeFormat>).
     * Improves speed by skipping unused format detectors.
     * Default: Try all formats
     */
    POSSIBLE_FORMATS,

    /**
     * Spend more time for better accuracy (Boolean).
     * Enables additional detection passes and heuristics.
     * Default: false
     */
    TRY_HARDER,

    /**
     * Character encoding for decoded text (String).
     * Examples: "UTF-8", "ISO-8859-1", "Shift_JIS"
     * Default: Platform default or detected from barcode
     */
    CHARACTER_SET,

    /**
     * Valid data lengths for Code 39/93/128 (int[]).
     * Filters false positives by length.
     * Default: Accept any length
     */
    ALLOWED_LENGTHS,

    /**
     * Assume Code 39 has check digit (Boolean).
     * Validates and strips check digit.
     * Default: false
     */
    ASSUME_CODE_39_CHECK_DIGIT,

    /**
     * Assume GS1 format encoding (Boolean).
     * Interprets FNC1 characters for GS1 Application Identifiers.
     * Default: false
     */
    ASSUME_GS1,

    /**
     * Return Codabar start/stop characters (Boolean).
     * Includes A/B/C/D characters in decoded text.
     * Default: false (strips start/stop)
     */
    RETURN_CODABAR_START_END,

    /**
     * Callback for result points during detection (ResultPointCallback).
     * Receive notifications of finder patterns, alignment patterns, etc.
     * Default: null (no callback)
     */
    NEED_RESULT_POINT_CALLBACK,

    /**
     * Allowed UPC/EAN extension lengths (int[]).
     * Typically {2, 5} for price and issue extensions.
     * Default: Accept 2 or 5 digit extensions
     */
    ALLOWED_EAN_EXTENSIONS,

    /**
     * Also try decoding inverted image (Boolean).
     * Attempts detection with colors reversed (white bars on black).
     * Default: false
     */
    ALSO_INVERTED
}

Usage Examples:

import com.google.zxing.*;
import java.util.*;

Map<DecodeHintType, Object> hints = new EnumMap<>(DecodeHintType.class);

// Example 1: Speed optimization - limit to QR codes only
hints.put(DecodeHintType.POSSIBLE_FORMATS,
    Collections.singletonList(BarcodeFormat.QR_CODE));

// Example 2: Maximum accuracy
hints.put(DecodeHintType.TRY_HARDER, Boolean.TRUE);
hints.put(DecodeHintType.ALSO_INVERTED, Boolean.TRUE);

// Example 3: Pure barcode (synthetic image with no border)
hints.put(DecodeHintType.PURE_BARCODE, Boolean.TRUE);

// Example 4: Character encoding
hints.put(DecodeHintType.CHARACTER_SET, "UTF-8");

// Example 5: GS1-128 barcode with Application Identifiers
hints.put(DecodeHintType.ASSUME_GS1, Boolean.TRUE);
hints.put(DecodeHintType.POSSIBLE_FORMATS,
    Collections.singletonList(BarcodeFormat.CODE_128));

// Example 6: Result point callback for visual feedback
hints.put(DecodeHintType.NEED_RESULT_POINT_CALLBACK, new ResultPointCallback() {
    @Override
    public void foundPossibleResultPoint(ResultPoint point) {
        System.out.println("Found: " + point.getX() + ", " + point.getY());
    }
});

// Example 7: Code 39 with check digit validation
hints.put(DecodeHintType.ASSUME_CODE_39_CHECK_DIGIT, Boolean.TRUE);

// Use hints with reader
Reader reader = new MultiFormatReader();
Result result = reader.decode(bitmap, hints);

EncodeHintType

Configuration options for barcode encoding operations. Passed as hints map to Writer.encode() methods.

/**
 * Enumeration of encode hint types for configuring Writer behavior.
 * Hints customize error correction, margins, and format-specific parameters.
 */
public enum EncodeHintType {
    /**
     * Error correction level (Object, format-specific type).
     * - QR Code: ErrorCorrectionLevel (L, M, Q, H)
     * - Aztec: Integer percentage (23, 33, 50, etc.)
     * - PDF417: Integer level (0-8)
     * Default: Format-specific default (usually medium)
     */
    ERROR_CORRECTION,

    /**
     * Character encoding for input text (String).
     * Examples: "UTF-8", "ISO-8859-1", "Shift_JIS"
     * Default: "ISO-8859-1"
     */
    CHARACTER_SET,

    /**
     * Data Matrix symbol shape preference (SymbolShapeHint).
     * Values: FORCE_NONE, FORCE_SQUARE, FORCE_RECTANGLE
     * Default: FORCE_NONE (automatic)
     */
    DATA_MATRIX_SHAPE,

    /**
     * Use compact Data Matrix encoding (Boolean).
     * Enables minimal encoder for optimal size.
     * Default: false
     */
    DATA_MATRIX_COMPACT,

    /**
     * Minimum symbol size (Dimension).
     * Deprecated - used by Data Matrix for size constraints.
     */
    MIN_SIZE,

    /**
     * Maximum symbol size (Dimension).
     * Deprecated - used by Data Matrix for size constraints.
     */
    MAX_SIZE,

    /**
     * Quiet zone margin in pixels (Integer).
     * Border around barcode for scanner reading.
     * Default: Format-specific (typically 4 modules)
     */
    MARGIN,

    /**
     * Use compact PDF417 format (Boolean).
     * Omits right row indicator columns for smaller size.
     * Default: false
     */
    PDF417_COMPACT,

    /**
     * PDF417 compaction mode (Compaction enum).
     * Values: AUTO, TEXT, BYTE, NUMERIC
     * Default: AUTO
     */
    PDF417_COMPACTION,

    /**
     * PDF417 dimension constraints (Dimensions object).
     * Specifies min/max rows and columns.
     * Default: Automatic selection
     */
    PDF417_DIMENSIONS,

    /**
     * PDF417 auto ECI insertion (Boolean).
     * Automatically insert Extended Channel Interpretation.
     * Default: false
     */
    PDF417_AUTO_ECI,

    /**
     * Aztec layer specification (Integer).
     * Negative: Compact (-1 to -4)
     * Positive: Full-range (1 to 32)
     * Zero or omitted: Automatic
     * Default: 0 (automatic)
     */
    AZTEC_LAYERS,

    /**
     * Exact QR Code version (Integer, 1-40).
     * Forces specific version instead of automatic selection.
     * Default: Automatic (smallest that fits)
     */
    QR_VERSION,

    /**
     * QR Code mask pattern (Integer, 0-7).
     * Forces specific mask pattern.
     * Default: Automatic (best pattern)
     */
    QR_MASK_PATTERN,

    /**
     * Use compact QR Code (Boolean).
     * Experimental compact encoding.
     * Default: false
     */
    QR_COMPACT,

    /**
     * Use GS1 format (Boolean).
     * Encodes with FNC1 for GS1 Application Identifiers.
     * Default: false
     */
    GS1_FORMAT,

    /**
     * Force specific Code 128 code set (Integer).
     * 0 = Code Set A
     * 1 = Code Set B
     * 2 = Code Set C
     * Default: Automatic selection
     */
    FORCE_CODE_SET,

    /**
     * Force C40 encoding for Data Matrix (Boolean).
     * Uses C40 mode instead of automatic selection.
     * Default: false
     */
    FORCE_C40,

    /**
     * Use compact Code 128 (Boolean).
     * Enables compact encoding optimizations.
     * Default: false
     */
    CODE128_COMPACT
}

Usage Examples:

import com.google.zxing.*;
import com.google.zxing.qrcode.decoder.ErrorCorrectionLevel;
import com.google.zxing.datamatrix.encoder.SymbolShapeHint;
import com.google.zxing.pdf417.encoder.*;
import java.util.*;

Map<EncodeHintType, Object> hints = new EnumMap<>(EncodeHintType.class);

// Example 1: QR Code with high error correction
hints.put(EncodeHintType.ERROR_CORRECTION, ErrorCorrectionLevel.H);
hints.put(EncodeHintType.CHARACTER_SET, "UTF-8");
hints.put(EncodeHintType.MARGIN, 1);  // Minimal margin

Writer writer = new QRCodeWriter();
BitMatrix qr = writer.encode("Data", BarcodeFormat.QR_CODE, 300, 300, hints);

// Example 2: Data Matrix with forced square shape
hints.clear();
hints.put(EncodeHintType.DATA_MATRIX_SHAPE, SymbolShapeHint.FORCE_SQUARE);
hints.put(EncodeHintType.DATA_MATRIX_COMPACT, Boolean.TRUE);

Writer dmWriter = new DataMatrixWriter();
BitMatrix dm = dmWriter.encode("Data", BarcodeFormat.DATA_MATRIX, 200, 200, hints);

// Example 3: PDF417 with dimension constraints
hints.clear();
hints.put(EncodeHintType.PDF417_DIMENSIONS, new Dimensions(6, 10, 10, 30));
hints.put(EncodeHintType.PDF417_COMPACTION, Compaction.TEXT);
hints.put(EncodeHintType.ERROR_CORRECTION, 4);

Writer pdfWriter = new PDF417Writer();
BitMatrix pdf = pdfWriter.encode("Text data", BarcodeFormat.PDF_417, 400, 200, hints);

// Example 4: Aztec with specific layers
hints.clear();
hints.put(EncodeHintType.AZTEC_LAYERS, -2);  // Compact, 2 layers
hints.put(EncodeHintType.ERROR_CORRECTION, 50);  // 50% EC

Writer aztecWriter = new AztecWriter();
BitMatrix aztec = aztecWriter.encode("Data", BarcodeFormat.AZTEC, 150, 150, hints);

// Example 5: GS1-128 barcode
hints.clear();
hints.put(EncodeHintType.GS1_FORMAT, Boolean.TRUE);

Writer gs1Writer = new Code128Writer();
BitMatrix gs1 = gs1Writer.encode("01095011010209171719050810ABCD",
    BarcodeFormat.CODE_128, 400, 100, hints);

// Example 6: QR Code with forced version
hints.clear();
hints.put(EncodeHintType.QR_VERSION, 10);  // Force version 10

BitMatrix qrV10 = writer.encode("Data", BarcodeFormat.QR_CODE, 400, 400, hints);

Hint Combinations by Use Case

Mobile App Scanning (Decode)

Map<DecodeHintType, Object> hints = new EnumMap<>(DecodeHintType.class);
hints.put(DecodeHintType.POSSIBLE_FORMATS,
    Arrays.asList(BarcodeFormat.QR_CODE, BarcodeFormat.EAN_13, BarcodeFormat.CODE_128));
hints.put(DecodeHintType.TRY_HARDER, Boolean.TRUE);
hints.put(DecodeHintType.CHARACTER_SET, "UTF-8");

High-Speed Document Scanning (Decode)

Map<DecodeHintType, Object> hints = new EnumMap<>(DecodeHintType.class);
hints.put(DecodeHintType.PURE_BARCODE, Boolean.TRUE);
hints.put(DecodeHintType.POSSIBLE_FORMATS,
    Collections.singletonList(BarcodeFormat.DATA_MATRIX));

Product Barcode Generation (Encode)

Map<EncodeHintType, Object> hints = new EnumMap<>(EncodeHintType.class);
// EAN-13 and UPC codes don't need hints typically
// Margin is automatic based on spec

QR Code for Maximum Reliability (Encode)

Map<EncodeHintType, Object> hints = new EnumMap<>(EncodeHintType.class);
hints.put(EncodeHintType.ERROR_CORRECTION, ErrorCorrectionLevel.H);
hints.put(EncodeHintType.CHARACTER_SET, "UTF-8");
hints.put(EncodeHintType.MARGIN, 4);  // Standard margin

Data Matrix for Manufacturing (Encode)

Map<EncodeHintType, Object> hints = new EnumMap<>(EncodeHintType.class);
hints.put(EncodeHintType.DATA_MATRIX_SHAPE, SymbolShapeHint.FORCE_SQUARE);
hints.put(EncodeHintType.DATA_MATRIX_COMPACT, Boolean.TRUE);
hints.put(EncodeHintType.CHARACTER_SET, "UTF-8");

Best Practices

Decode Hints:

  • Always set CHARACTER_SET to "UTF-8" for international text
  • Use POSSIBLE_FORMATS to improve speed when format is known
  • Use TRY_HARDER for difficult images (poor quality, small, damaged)
  • Use PURE_BARCODE only for clean synthetic images (significant speedup)
  • Use ALSO_INVERTED if barcodes may be inverted (white on black)

Encode Hints:

  • Set ERROR_CORRECTION based on use case (higher for durability, lower for capacity)
  • Always set CHARACTER_SET when encoding non-ASCII text
  • Set MARGIN to 0 or 1 only if space-constrained and print quality is excellent
  • Use format-specific hints (QR_VERSION, AZTEC_LAYERS) only when size is critical
  • Test with actual scanners after applying hints

Performance:

  • POSSIBLE_FORMATS reduces decoding time significantly
  • PURE_BARCODE provides major speedup for synthetic images
  • TRY_HARDER increases decoding time but improves success rate
  • Avoid TRY_HARDER for real-time video scanning unless necessary

Compatibility:

  • Not all hints apply to all formats (check format documentation)
  • Invalid hint values are typically ignored rather than throwing exceptions
  • Hints are optional - all readers/writers work with default settings
  • Test with multiple scanners when using non-default encoding settings

See Also

  • Core Reading and Writing - Using hints with Reader and Writer
  • QR Code Support - QR_VERSION, ERROR_CORRECTION hints
  • Data Matrix Support - DATA_MATRIX_SHAPE hint
  • PDF417 Support - PDF417_COMPACTION, PDF417_DIMENSIONS hints
  • Aztec Support - AZTEC_LAYERS hint
  • Exception Handling - Error handling with different hint configurations

Install with Tessl CLI

npx tessl i tessl/maven-com-google-zxing--core@3.5.1

docs

reference

aztec.md

barcode-formats.md

bit-structures.md

common-utilities.md

configuration-hints.md

core-reading-writing.md

datamatrix.md

exception-handling.md

image-processing.md

maxicode.md

multi-detection.md

oned.md

packages.md

pdf417.md

qrcode.md

result-handling.md

result-parsing.md

index.md

tile.json