Custom Options of the native decoder library

The setCustomOption(string option, int value) method adjusts optional scanning and output settings.

Before setting an option #

• Names are case-sensitive. Use the exact spelling shown below, including the capitals in the SADL_ options.
• Check the return value: 0 means the option name was recognized; -1 means it was not recognized. Success does not guarantee that the value is sensible or that the required feature is available.
• These settings are shared. Every option in this user reference affects all Config instances in the process, not just the instance used to set it. Configure them before scanning starts; do not change them while scans are running.
• Defaults below are startup defaults. Creating or cloning a Config does not reset shared settings.
• Use 0 and 1 for on/off options unless other values are explicitly listed. The setter generally does not reject out-of-range inputs.

Output formatting #

upce_leading_zero #

Keep or remove the first zero in UPC-E results.

• Default: 1.
• Values: 1 keeps the leading zero; 0 removes it when present.
• Use when: your application expects UPC-E data without the initial zero.
• Note: affects both returned text and bytes. It does not remove other zeros, does not apply to UPC-E1, and has no effect when upcE.expandToUPCA is enabled.

strict_gs1_rules #

Choose whether GS1 formatting may return partially valid data.

• Default: 0.
• Values: 0 allows recognized fields to be formatted even if the input has unrecognized data or invalid field lengths; 1 requires the parser's checks to pass.
• Requires: formatting set to Formatting::GS1 or Formatting::Automatic, and GS1-marked barcode data.
• Note: in permissive mode, formatted JSON reports Validation and, when applicable, ValidationErrors. Strict mode can prevent GS1 formatted output; it does not by itself reject the underlying decoded barcode or guarantee full GS1 compliance.

gs1_format_decimal_places #

Make supported GS1 measurements and amounts easier to read in formatted JSON by adding a decimal separator.

• Default: 0.
• Values: 0 leaves the values unchanged; 1 uses a period; 2 uses a comma. C++ character values '.' and ',' are also accepted.
• Example: AI 3102 with value 001234 is displayed as 12.34 with 1, or 12,34 with 2.
• Requires: successful GS1 formatting through Formatting::GS1 or Formatting::Automatic.
• Note: this selects the separator, not the number of decimal places; the GS1 field specifies the precision. It affects supported fields in formatted JSON only, not formattedText or the original decoded data.

Scanning features #

decoding_timeout_ms #

Limit how long the barcode scanner continues trying to decode an image.

• Default: 0 (no custom time limit).
• Values: 0 disables the limit; a positive integer specifies milliseconds.
• Use when: predictable responsiveness is more important than trying every decoding attempt.
• Note: this is a best-effort time budget, not a guaranteed deadline for the complete API call. Processing already in progress may continue past the limit. Some barcodes may be missed; results already found may still be returned. Do not rely on this to time-limit OCR or document recognition.
• Input safety: use at most 2147483 milliseconds on the SDK's usual 32-bit int targets. Larger inputs can overflow the current conversion; negative values are not supported.

allow_qr_nesting #

Allow a smaller QR code inside a larger QR code to be returned as a separate result.

• Default: 0.
• Values: 0 uses normal QR handling; 1 enables nested-QR handling.
• Requires: the QR decoder enabled. Set maximumResultsCount to at least 2 to receive both codes.
• Note: intended for clearly different-sized QR codes. It does not guarantee that every overlapping or nested layout can be read, and does not enable the same behavior for Micro QR.

enable_ocr_functionality #

Allow the OCR text-recognition feature to run.

• Default: 0.
• Values: 0 disables access to OCR text recognition; 1 enables access.
• Requires: an OCR-capable SDK build, its required runtime resources, and the OCRText decoder enabled separately.
• Note: this switch does not enable OCRText on its own and is not the switch for ID-document recognition. Attempting to scan with OCRText enabled while this option is 0 raises an error.

Image padding #

These two options apply to the synchronous Barkoder::DecodeImageMemory() path in the supplied implementation. Do not assume the same preprocessing is applied by asynchronous or GPU image APIs.

add_image_margins #

Add a border around an input image before scanning it.

• Default: 0.
• Values: 0 adds no border; a positive integer adds that many pixels on each side.
• Example: 20 adds 20 pixels on the left, right, top, and bottom.
• Use when: a tightly cropped barcode has too little surrounding space. Padding cannot restore barcode content that was cut off.
• Note: choose the border appearance with add_image_margins_color. Returned barcode corner and polygon coordinates are shifted back to the original image coordinates. Padding uses extra memory; avoid unnecessarily large values. If using a restricted region of interest, verify it with padding enabled.

add_image_margins_color #

Choose how an added border is filled.

• Default: -1.
• Values: -1 extends the image's edge pixels; 0 through 255 use a solid shade (0 = black, 255 = white).
• Requires: add_image_margins greater than 0.
• Note: the solid fill is grayscale, including on color images; this is not an RGB color value. Edge extension repeats the nearest border pixels; it does not mirror the image. Use only the documented values.

Advanced scanning settings #

Keep the defaults unless testing shows a benefit on your own images and devices.

center_only_scan #

Keep barcodes that cover or lie close to the center of the configured region of interest.

• Default: 0 (no center filter).
• Values: 0 disables filtering; a positive integer sets the allowed distance as a percentage of the image's shorter side.
• Example: 10 allows a gap of up to 10% of the shorter image side between the ROI center and the nearest barcode edge.
• Note: a barcode covering the ROI center is kept. Smaller positive values are stricter; larger values allow barcodes farther away. 1 is a narrow tolerance, not a generic on/off value. This is not a centered crop or a limit on how many results are returned. Barcodes outside the tolerance can be omitted even when readable.

single_line_scan #

Read 1D barcodes crossing a fixed line through the center of the region of interest.

• Default: 0.
• Values: 0 uses normal scanning; 1 uses a horizontal scan line; 2 uses a vertical scan line.
• Use when: barcode position and orientation are controlled, such as a fixed scanning station.
• Note: the line must cross the bars, not run along them. Off-center or rotated barcodes may be missed. This mode replaces normal barcode-region selection with a fixed 1D region, so it is not suitable for general mixed 1D/2D scanning.

location_expanding_1d #

Refine the reported outline of a decoded 1D barcode so it can cover more of the barcode's visible height.

• Default: 1.
• Values: 1 enables this extra outline refinement; 0 skips it.
• Use when: tuning the appearance or cost of barcode-location reporting.
• Note: this controls an extra location-refinement step after decoding; it does not expand the input image or change the decoded text. Disabling it can leave a smaller outline. It is not a guarantee of an exact barcode boundary.

disable_full_resolution_decode #

Skip the full-resolution barcode-region search to reduce scanning work.

• Default: 0.
• Values: 0 allows the normal search; 1 skips the full-resolution region-search pass.
• Use when: large images scan too slowly and small barcodes are not important.
• Note: small or finely detailed barcodes may be missed. Despite its name, this is not a guarantee that all decoding uses reduced-resolution images; some paths can still use original-resolution pixels.

Feature-specific parsing #

These options belong in the relevant workflow guides, rather than in a general scanner quick-start. Parsing options do not enable a decoder or choose a formatting mode automatically. Formatted output is stored in result.extra["formattedJSON"] and result.extra["formattedText"]; available data depends on the build and licensing.

parser_show_warnings #

Include available boarding-pass parsing warnings in formatted JSON.

• Default: 0.
• Values: 0 omits the warnings array; 1 includes it when warnings exist.
• Requires: boarding-pass parsing through Formatting::BCBP or Formatting::Automatic.
• Note: currently applies to the BCBP boarding-pass parser only. Warnings appear in the JSON Issues array; this is not a general decoder logging or validation switch.

SADL_decode_image #

Extract the portrait image embedded in a South African driving-licence barcode.

• Default: 1.
• Values: 1 enables portrait image extraction and its output field; 0 skips the portrait image while allowing the licence's other fields to be parsed.
• Requires: PDF417 decoding, SADL parsing through Formatting::SADL or Formatting::Automatic, and a build with SADL image support for portrait extraction.
• Output: the ImageRawBase64 field contains Base64-encoded raw grayscale pixels, not a JPEG or PNG. Use the returned Image Width and Image Height fields to interpret it.
• Note: this is not OCR or an option for scanning a photograph of the licence. The portrait image can be empty when image support or licensing is unavailable.

SADL_decode_ID #

Allow South African ID-card barcode data to be recognized by the SADL parser.

• Default: 0.
• Values: 0 disables this additional format; 1 enables it.
• Requires: PDF417 decoding and SADL parsing through Formatting::SADL or Formatting::Automatic.
• Note: recognizes supported barcode payloads only; it does not read printed ID-card text or enable general document recognition. It is independent of portrait image extraction.

SADL_decode_vehicle_disk #

Allow South African vehicle-licence-disc barcode data to be recognized by the SADL parser.

• Default: 0.
• Values: 0 disables this additional format; 1 enables it.
• Requires: PDF417 decoding and SADL parsing through Formatting::SADL or Formatting::Automatic.
• Note: recognizes supported barcode payloads only, not printed vehicle details. It is independent of portrait image extraction. The key uses the spelling disk even though the document is commonly called a licence disc.