yushulx/python-barcode-qrcode-sdk/template-optimizer

DBR Template Optimizer

Iteratively optimize a Dynamsoft Barcode Reader (DBR) template JSON to achieve the best possible barcode decode rate on a set of difficult images. Can also educate users about DBR template structure and parameters, or generate visual decode reports.

Capabilities

1. Optimize — Iteratively tune a template against a test image set
2. Educate — Explain DBR template structure, parameters, and best practices
3. Report — Generate visual HTML reports showing per-image decode results

Operating Rules

These rules apply in every mode, especially during optimization:

1. Observe before editing. Inspect the barcode image first and describe visible symptoms: quiet-zone loss, border clipping, blur, low contrast, inversion, warping, wrinkles, nearby text, or texture.
2. Prefer the cheapest trustworthy evidence first. For a single-image failure, use the repository's direct validator before running a large harness sweep.
3. Change one parameter family at a time. Do not modify localization, decode, and acceptance rules together unless there is strong evidence they are coupled.
4. Use a stop condition. If the raw image and the basic variant sweep both fail, say explicitly that template-only tuning is likely exhausted for the current pixels.
5. Prefer focused templates for focused problems. When the task is about one known symbol or one recurring failure case, favor a minimal single-template JSON over editing a large exported default file.
6. Do not assume example templates are relevant. Reuse an existing template only when the barcode type and failure pattern are close enough to justify it.
7. If no template is supplied, generate a focused template first. Use the barcode format, expected count, ROI, and symptom pattern to synthesize the smallest defensible starting template; treat any reference template as comparison evidence, not as a requirement.

Mode Selection

Choose the mode based on what the user asks:

If ambiguous, ask the user which mode they want.

Inside Optimize, choose the execution track that matches the request:

• Single-image triage — use when the user is trying to rescue one hard image or one failure case.
• Dataset optimization — use when the user wants the best template across many images and needs score-based iteration.

Skill Resources

This skill is self-contained. Set SKILL_DIR to the directory containing this SKILL.md file.

All required resources are inside SKILL_DIR:

SKILL_DIR/
   PROMPT.md
   SKILL.md
   KNOWLEDGE.md
   requirements.txt
   tools/validate_dbr_template.py
   tools/probe_dbr_templates.py
   tools/compare_dbr_template_profiles.py
   tools/dbr_license.py
   resources/harness_py/main.py
   resources/harness_py/requirements.txt
   resources/report/report_template.html
   templates/examples/dbr_template.json
   templates/v3.4.1000/parameters.md

The bundled single-image evidence tools live under tools/, the batch harness lives under resources/harness_py/, and the supporting reference lives in KNOWLEDGE.md plus templates/v3.4.1000/parameters.md.

Use the bundled tools under SKILL_DIR/tools/ as the first-line evidence path for single-image triage.

The Python harness runs directly from SKILL_DIR/resources/harness_py/main.py.

Dependencies

Portable Use

For Copilot, Claude, or another coding agent:

1. Keep PROMPT.md, SKILL.md, and KNOWLEDGE.md together in SKILL_DIR.
2. Ask the agent to read SKILL_DIR/PROMPT.md and follow this workflow.
3. Use bundled tools under SKILL_DIR/tools/ for single-image triage.
4. Use SKILL_DIR/resources/harness_py/ for dataset benchmarking and reporting.

Copilot Invocation Tips

Use clear prompts so Copilot enters the correct mode:

• Use the template-optimizer skill to tune this barcode image
• Use the template-optimizer skill to optimize these images
• Use the template-optimizer skill to explain DeblurModes
• Use the template-optimizer skill to generate a decode report

If discovery does not trigger automatically, ask Copilot to read SKILL_DIR/PROMPT.md first, then execute the requested mode.

Mode: Optimize

Optimization has two tracks:

• Track A: Single-image triage — diagnose one failure case quickly and make the smallest defensible template change.
• Track B: Dataset optimization — iterate against a directory of images and maximize decode success with metrics.

Step 0 — Gather Information

Ask the user for the following. Use the AskUserQuestion tool for structured choices where applicable.

Choose the track immediately after Step 0:

• If the user supplied one hard image or explicitly wants help with one failure case, start with Track A.
• If the user supplied a directory and wants rate maximization, benchmark gains, or an HTML report, use Track B.
• If Track A finds a working candidate and the user later wants broader validation, promote that candidate into Track B.

Ground truth file format (optional JSON):

{
  "image1.png": ["expected_barcode_text_1"],
  "image2.jpg": ["expected_text_A", "expected_text_B"]
}

Step 1 — Single-Image Triage (Track A)

Use this track before broad harness work when the problem is a single barcode image.

1a. Observe the image first

Inspect the image directly and record only what is visible:

• Is the quiet zone missing or very thin?
• Is any edge clipped by the image boundary?
• Is the symbol warped, folded, stretched, or wrinkled?
• Is it blurry, or mainly low contrast?
• Is it dark-on-light, light-on-dark, or ambiguous?
• Is there heavy background texture or nearby text?

State which single parameter family those symptoms point to before changing anything.

1b. Validate the current template through the simplest path

Use the bundled helper tools here.

1. Run the direct validator first:

``bash python SKILL_DIR/tools/validate_dbr_template.py <image> --template-file <template> ``

The validator must initialize the DBR license before creating CaptureVisionRouter; otherwise NO_RESULT is not trustworthy evidence.

1. Establish the broader baseline only after the direct result is known:

``bash python SKILL_DIR/tools/probe_dbr_templates.py <image> ``

1. If the user already has a reference template, compare it before theorizing:

``bash python SKILL_DIR/tools/compare_dbr_template_profiles.py <current-template> <reference-template> ``

1. For mixed barcode+OCR templates (barcode decode plus text recognition with barcode-referenced ROI), verify wiring before parameter sweeps:

• Capture with the exact template name present under CaptureVisionTemplates[].Name.
• Confirm TargetROIDefOptions for OCR uses ReferenceObjectFilter with ART_BARCODE and a valid ReferenceObjectOriginIndex.
• If no template exists yet, generate a combined candidate with one barcode task and one OCR task whose ROI is derived from the barcode result.
• Match the intended capture path first (for example file-based capture_multi_pages(...) versus ndarray capture(...)) and validate raw input before trying upscale variants.
• If that raw path still fails but deterministic nearest_2x succeeds with the same template, treat it as runtime alignment to template assumptions, not as a custom OCR heuristic win.

1. If everything still returns NO_RESULT, test whether simple preprocessing changes the outcome:

``bash python SKILL_DIR/tools/probe_dbr_templates.py <image> --variant-set basic --report-json tuning-report.json ``

1c. Classify the failure before editing

Use the image observation, direct validation result, probe matrix, and optional template diff together:

• Raw image succeeds with a candidate template → keep tuning in the template only.
• Only a preprocessed variant succeeds → recommend preprocessing plus template tuning; do not pretend template-only tuning solved the problem.
• No raw or basic variant succeeds → stop and say template-only tuning is likely exhausted for the current pixels.
• A reference template mainly differs in deformation handling or separate decode image parameters → prioritize those before adding more DeblurModes.
• Tiny single-code DataMatrix crops stall under the standard path → compare DPMCRM_SKIP versus DPMCRM_GENERAL before adding rescue ROIs or center-only crops. Validate that candidate on a neighboring slice too, because inverted-only DPM ports can overfit badly.

1d. Make one minimal edit

Apply exactly one parameter family per edit, in this order:

1. Scope first: ExpectedBarcodesCount, BarcodeFormatIds, DPMCodeReadingModes
2. Localization second: LocalizationModes, ConfidenceThreshold
3. Decode third: DeformationResistingModes, decode ImageParameterOptions, DeblurModes, BarcodeScaleModes, grayscale and binarization choices
4. Acceptance last: MinQuietZoneWidth, MirrorMode, ReturnPartialBarcodeValue

Prefer a new focused template file with one CaptureVisionTemplate over editing a large exported default file.

1e. Re-validate immediately

After each edit, re-run the direct validator before making another change:

python SKILL_DIR/tools/validate_dbr_template.py <image> --template-file <candidate-template>

Re-run the broader probe only when the direct result changes or remains ambiguous.

Step 2 — Setup Verification (Track B)