Skip to content

Commit 1459cdc

Browse files
yushulxyushulx
committed
Added SKILL and prompt for tuning parameters
1 parent c93de82 commit 1459cdc

10 files changed

Lines changed: 3080 additions & 0 deletions

File tree

‎examples/official/annotation_tool/.github/prompts/tune-dbr-template.prompt.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
name: "Tune DBR Template"
3+
description: "Tune Dynamsoft Barcode Reader template parameters when the default DBR preset cannot decode a hard barcode image. Use for difficult QR, DataMatrix, PDF417, 1D, blurry, low-contrast, skewed, cropped, mirrored, or repeated NO_RESULT cases."
4+
argument-hint: "image path, current template path, expected format, constraints"
5+
agent: "agent"
6+
model: "GPT-5 (copilot)"
7+
---
8+
9+
Tune a Dynamsoft Barcode Reader template for the user's image and template inputs.
10+
Do not assume the image is a QR code and do not assume any existing example template is the correct first move.
11+
12+
Workflow:
13+
14+
1. Inspect the image itself first using the image tool.
15+
2. Describe the visible symptoms before proposing any parameter changes.
16+
3. Read the current template file if the user provided one.
17+
4. Decide whether any existing example template in the workspace is actually relevant to this image's format and failure mode. If not, say so explicitly and ignore it.
18+
5. Run `python validate_dbr_template.py <image> --template-file <template>` first when a template file is available.
19+
Make sure the script initializes the DBR license before it creates `CaptureVisionRouter`; otherwise ignore `NO_RESULT` from that run.
20+
6. If the user also provided a known-good template, run `python compare_dbr_template_profiles.py <current-template> <known-good-template>` and use that diff to choose the next parameter family.
21+
7. Run `python probe_dbr_templates.py <image>`.
22+
8. If the image still fails, run `python probe_dbr_templates.py <image> --variant-set basic --report-json tuning-report.json`.
23+
9. Classify the failure as one of:
24+
- scope problem
25+
- localization problem
26+
- decode problem
27+
- acceptance problem
28+
- pixels likely unrecoverable by template-only tuning
29+
10. Propose the smallest template change that tests the classification.
30+
11. If a known-good template differs mainly in `DeformationResistingModes`, decode `ImageParameterOptions`, or text-zone removal, prioritize migrating those before adding more `DeblurModes`.
31+
12. If a change is needed, create or update a focused template file instead of editing a large exported template unless the user explicitly asked otherwise.
32+
13. Re-run `python validate_dbr_template.py <image> --template-file <candidate-template>` after the edit.
33+
34+
Output format:
35+
36+
- Visual diagnosis
37+
- Diagnosis
38+
- Example-template relevance
39+
- Exact JSON change
40+
- Validation command
41+
- Next fallback step if it still fails
42+
43+
Constraints:
44+
45+
- Do not skip image inspection when the image is available.
46+
- Do not assume the included incomplete-QR template applies unless the image really matches that failure pattern.
47+
- Change one parameter family at a time.
48+
- Do not skip a known-good template diff when one is available.
49+
- Do not keep randomizing parameters after raw plus basic variants all fail.
50+
- Say explicitly when preprocessing or recapturing the image is more justified than more template edits.
51+
- Treat standalone helper output as valid only after DBR license initialization is confirmed.

‎examples/official/annotation_tool/.github/skills/dbr-template-tuner/SKILL.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
name: dbr-template-tuner
3+
description: 'Tune Dynamsoft Barcode Reader template JSON when the default DBR preset returns NO_RESULT on a hard barcode image. Use for difficult QR, DataMatrix, PDF417, 1D, blurry, low-contrast, mirrored, skewed, cropped, warped, or cluttered images when you need evidence-driven parameter tuning instead of random template edits.'
4+
argument-hint: 'image path, current template path, expected barcode type if known'
5+
user-invocable: true
6+
---
7+
8+
# DBR Template Tuning
9+
10+
## When to Use
11+
12+
- The default DBR preset fails with `NO_RESULT` on a barcode image.
13+
- You need to tune `dbr_template.json` or create a focused template for one failure case.
14+
- You want evidence before changing `LocalizationModes`, `DeblurModes`, `MinQuietZoneWidth`, or related parameters.
15+
- You want AI to stop random parameter churn and use a repeatable workflow.
16+
17+
## Inputs
18+
19+
- Image path
20+
- The image itself attached to chat when available, so AI can inspect visual symptoms before changing parameters
21+
- Current template path if one already exists
22+
- Expected format if known, such as `QR`, `DataMatrix`, or `Code128`
23+
- Whether preprocessing is allowed or the ask is strictly template-only
24+
- Whether any included example template is actually relevant to this image
25+
26+
## Procedure
27+
28+
1. Observe the image before touching the template.
29+
Use the image tool on the provided barcode image and describe visible symptoms in concrete terms: quiet-zone loss, border clipping, blur, low contrast, warping, wrinkles, inversion, reflection, background texture, finder-pattern damage, or perspective skew.
30+
31+
2. Validate the current template directly through the simplest DBR path.
32+
The validator must initialize the DBR license before creating `CaptureVisionRouter`; otherwise treat `NO_RESULT` as invalid evidence.
33+
Run `python validate_dbr_template.py <image> --template-file <template>`.
34+
35+
3. Establish a broader baseline only after the direct validation result is known.
36+
Run `python probe_dbr_templates.py <image>`.
37+
38+
Do not assume an existing example template is the right first answer. Only reuse one when the symbol type and failure pattern are close enough to justify it.
39+
40+
4. If the user already has a proven template from Dynamsoft or another teammate, compare it before theorizing.
41+
Run `python compare_dbr_template_profiles.py <current-template> <proven-template>`.
42+
43+
5. If everything still returns `NO_RESULT`, test whether simple preprocessing changes the outcome.
44+
Run `python probe_dbr_templates.py <image> --variant-set basic --report-json tuning-report.json`.
45+
46+
6. Use image observation, the direct validation result, the result matrix, and the template diff to classify the failure.
47+
- Raw image succeeds with a candidate template: keep tuning in the template only.
48+
- Only a preprocessed variant succeeds: the image needs preprocessing plus template tuning.
49+
- No raw or basic variant succeeds: treat this as a stop signal for template-only tuning and say so explicitly.
50+
- A proven template differs mainly in `DeformationResistingModes` or separate decode `ImageParameterOptions`: prioritize those before adding more `DeblurModes`.
51+
52+
7. Change one parameter family at a time.
53+
- Scope first: `ExpectedBarcodesCount`, `BarcodeFormatIds`
54+
- Localization second: `LocalizationModes`, `ConfidenceThreshold`
55+
- Decode third: `DeformationResistingModes`, decode `ImageParameterOptions`, `DeblurModes`, `BarcodeScaleModes`, grayscale and binarization choices
56+
- Acceptance last: `MinQuietZoneWidth`, `MirrorMode`, `ReturnPartialBarcodeValue`
57+
58+
8. Keep the edit minimal.
59+
Prefer a new focused template file with one `CaptureVisionTemplate` over editing a large exported default file.
60+
61+
9. Re-run the direct validator after each edit.
62+
Run `python validate_dbr_template.py <image> --template-file <candidate-template>`.
63+
64+
10. Re-run the broader probe only when needed.
65+
Do not make another parameter change before the previous change is tested.
66+
67+
## Lessons From The Official Template Example
68+
69+
- More `DeblurModes` is not automatically better; a proven template may win through `DRM_BROAD_WARP` and `DRM_DEWRINKLE` with `DeblurModes = null`.
70+
- Separate image parameters for localization and decoding can matter.
71+
- Do not assume custom `BarcodeFormatSpecificationOptions` are needed; leaving default format behavior intact may be better.
72+
- `IfEraseTextZone = 0` can preserve damaged structure that an aggressive text-zone removal step might destroy.
73+
- Standalone DBR helper scripts need license initialization too, not just the GUI app.
74+
- Treat any example template in this folder as a reference point, not a default first move.
75+
76+
## Output Requirements
77+
78+
When using this skill, return:
79+
80+
- a short visual diagnosis based on the image itself
81+
- a short diagnosis of the likely failure mode
82+
- the smallest candidate template change that tests the diagnosis
83+
- the exact direct-validation command to run next
84+
- whether any existing example template is relevant or should be ignored
85+
- a stop condition when evidence suggests the pixels are not recoverable by template tuning alone
86+
87+
## References
88+
89+
- Read the image symptom guide in [image-symptoms.md](./references/image-symptoms.md)
90+
- Read the tuning matrix in [parameter-playbook.md](./references/parameter-playbook.md)

‎examples/official/annotation_tool/.github/skills/dbr-template-tuner/references/image-symptoms.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Image Symptom Guide
2+
3+
## Goal
4+
5+
Force AI to look at the barcode image first and translate visible symptoms into the next DBR parameter family to test.
6+
7+
## Observation Checklist
8+
9+
Describe only what is visible in the image before touching the template:
10+
11+
- Is the quiet zone missing or very thin?
12+
- Is any edge of the symbol clipped by the image boundary?
13+
- Is the symbol warped, stretched, or wrinkled?
14+
- Is the image blurry or just low contrast?
15+
- Are the finder patterns intact or partially damaged?
16+
- Is the code dark-on-light, light-on-dark, or ambiguous?
17+
- Is there heavy background texture or nearby text?
18+
- Is the symbol front-facing or perspective-skewed?
19+
20+
## Symptom To Parameter Family
21+
22+
### Missing quiet zone or edge clipping
23+
24+
- Check `MinQuietZoneWidth`
25+
- Test padded image variants
26+
- Avoid changing many decode modes first
27+
28+
### Warped, folded, or wrinkled symbol
29+
30+
- Prioritize `DeformationResistingModes`
31+
- Compare against any proven template using `DRM_BROAD_WARP` or `DRM_DEWRINKLE`
32+
- Do not assume extra `DeblurModes` is the answer
33+
34+
### Low contrast but still sharp
35+
36+
- Focus on grayscale enhancement and binarization behavior
37+
- Check separate decode `ImageParameterOptions`
38+
39+
### Blur without obvious geometric damage
40+
41+
- Focus on `DeblurModes` and decode image scaling
42+
- Keep localization stable if the symbol is already likely found
43+
44+
### Background texture or nearby text
45+
46+
- Check texture removal and `IfEraseTextZone`
47+
- Verify that text-zone removal is not erasing damaged QR structure
48+
49+
### Inverted or ambiguous foreground/background
50+
51+
- Check grayscale transforms and inverted variants
52+
53+
## Required AI Behavior
54+
55+
Before proposing template edits, AI should explicitly state:
56+
57+
1. What it sees in the image
58+
2. Which parameter family those symptoms point to
59+
3. Why it is not changing unrelated parameter families first

‎examples/official/annotation_tool/.github/skills/dbr-template-tuner/references/parameter-playbook.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# DBR Parameter Playbook
2+
3+
## Goal
4+
5+
Use image symptoms to narrow the next DBR parameter change instead of changing unrelated sections.
6+
7+
When a proven template exists, diff the template structure before editing anything:
8+
9+
```bash
10+
python compare_dbr_template_profiles.py current-template.json proven-template.json
11+
```
12+
13+
## Decision Table
14+
15+
### Few symbols, known format
16+
17+
- Set `ExpectedBarcodesCount` to `1`
18+
- Restrict `BarcodeFormatIds` to the expected format family
19+
- Prefer a focused template file over editing a multi-template export
20+
21+
### Barcode likely exists but is not found
22+
23+
- Change `LocalizationModes` before decode modes
24+
- Add or prioritize `LM_SCAN_DIRECTLY`, `LM_CONNECTED_BLOCKS`, `LM_NEURAL_NETWORK`
25+
- Lower `ConfidenceThreshold` only after narrowing the format and count
26+
27+
### Barcode is found on some variants but decode is unstable
28+
29+
- Leave localization unchanged
30+
- Check whether a proven template is solving this with `DeformationResistingModes` instead of `DeblurModes`
31+
- Prefer migrating `DRM_BROAD_WARP`, `DRM_DEWRINKLE`, or a separate decode image parameter block before adding more deblur modes
32+
- Then try stronger grayscale or binarization variants
33+
- Touch acceptance parameters only after decode-oriented changes are exhausted
34+
35+
### Suspected quiet-zone or crop issue
36+
37+
- Lower `MinQuietZoneWidth`
38+
- Try `MirrorMode = MM_BOTH` when orientation is uncertain
39+
- Test padded variants before making more template edits
40+
41+
### Light-on-dark or unusual foreground/background
42+
43+
- Include both `GTM_ORIGINAL` and `GTM_INVERTED`
44+
- Test normal and inverted binarized variants
45+
46+
### No raw image or basic variant decodes in any engine
47+
48+
- Stop calling it a template problem without qualification
49+
- Report that template-only tuning is likely exhausted for the current pixels
50+
- Recommend preprocessing, re-capture, crop refinement, or a human-verified ground truth path
51+
52+
## Official Template Lessons
53+
54+
- Proven templates may keep `BarcodeFormatSpecificationNameArray` as `null`; do not invent format specs without evidence.
55+
- Proven templates may separate localization and decode image parameters. That split is a real parameter family, not just formatting.
56+
- `IfEraseTextZone` is worth checking when the symbol is damaged or small.
57+
- If a proven template differs from yours mainly in deformation handling, do not keep iterating on localization or quiet-zone settings first.
58+
59+
## AI Guidance
60+
61+
When AI proposes a new template, require it to provide these four items together:
62+
63+
1. The observed symptom from the image or probe report
64+
2. The single parameter family being changed
65+
3. The exact JSON snippet to change
66+
4. The next validation command
67+
68+
Reject proposals that change localization, decoding, and acceptance rules all at once unless there is a strong reason.
69+
70+
## Minimal Template Strategy
71+
72+
- Keep one `CaptureVisionTemplate`
73+
- Keep one `TargetROIDefOptions` entry
74+
- Keep one focused `BarcodeReaderTaskSettingOptions` entry
75+
- Add `ImageParameterOptions` only when preprocessing behavior is part of the hypothesis
76+
- Copy only proven sections from exported templates

‎examples/official/annotation_tool/README.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,78 @@ pip install -r requirements.txt
3535
python main.py
3636
```
3737

38+
### DBR Template Tuning Workflow
39+
40+
If the default DBR preset returns `NO_RESULT` on a hard image, start with an evidence-gathering pass instead of guessing parameters or jumping straight to one special-case template:
41+
42+
```bash
43+
python probe_dbr_templates.py path/to/image.png
44+
```
45+
46+
The probe script tries:
47+
48+
- the built-in `PT_READ_BARCODES` preset
49+
- every template inside `dbr_template.json`
50+
- the included `dbr_incomplete_qr_template.json` example template
51+
52+
The `dbr_incomplete_qr_template.json` file is only an example for one hard incomplete-QR case. It is not the default answer for every difficult image. For other failures, use the same workflow to create a new focused template that matches the actual barcode type and failure mode.
53+
54+
If you want to test only that example template:
55+
56+
```bash
57+
python probe_dbr_templates.py path/to/image.png --template-file dbr_incomplete_qr_template.json
58+
```
59+
60+
If you want a broader evidence pass before changing template parameters, include common preprocessing variants and save a machine-readable report:
61+
62+
```bash
63+
python probe_dbr_templates.py path/to/image.png --variant-set basic --report-json tuning-report.json
64+
```
65+
66+
If you already have a known-good template from Dynamsoft, compare it with your current template before guessing:
67+
68+
```bash
69+
python compare_dbr_template_profiles.py current-template.json known-good-template.json
70+
```
71+
72+
If you want the smallest possible validator, run the template directly through `CaptureVisionRouter.capture()`:
73+
74+
```bash
75+
python validate_dbr_template.py path/to/image.png --template-file candidate-template.json
76+
```
77+
78+
Both standalone helpers, `validate_dbr_template.py` and `probe_dbr_templates.py`, initialize the DBR license before they create `CaptureVisionRouter`. If you add another DBR-only helper script, call `ensure_dbr_license()` first or treat any `NO_RESULT` as untrusted.
79+
80+
To use any custom template inside the GUI, click `Import DBR Template` and select the JSON file you want to test.
81+
82+
The included `dbr_incomplete_qr_template.json` shows what a focused template looks like for one hard single-QR image:
83+
84+
- narrow the task to one symbol type with `BarcodeFormatIds = ["BF_QR_CODE", "BF_MICRO_QR"]`
85+
- narrow the scene to one barcode with `ExpectedBarcodesCount = 1`
86+
- make localization more aggressive by combining `LM_SCAN_DIRECTLY`, `LM_CONNECTED_BLOCKS`, `LM_NEURAL_NETWORK`, `LM_STATISTICS`, and `LM_LINES`
87+
- keep both `GTM_ORIGINAL` and `GTM_INVERTED` grayscale transforms so dark-on-light and light-on-dark candidates are both tested
88+
- strengthen decode with multiple `DeblurModes`, including `DM_NEURAL_NETWORK` and `DM_DEEP_ANALYSIS`
89+
- relax QR acceptance a bit with `MinQuietZoneWidth = 0` and a lower `MinResultConfidence`
90+
91+
After comparing against the official template, there is one important correction to that example strategy: do not assume more `DeblurModes` is the next best move. The official template leans much more on `DeformationResistingModes` such as `DRM_BROAD_WARP` and `DRM_DEWRINKLE`, uses a separate decode image-parameter block, keeps `BarcodeFormatSpecificationNameArray` unset, and sets `IfEraseTextZone` to `0`.
92+
93+
Another important correction is workflow-related: image observation should come first. Before AI edits a template, it should inspect the image and explicitly describe visible symptoms such as quiet-zone loss, clipping, warp, blur, low contrast, inversion, or background texture. Those observations should decide which parameter family gets changed first.
94+
95+
When a new image still fails, tune in this order instead of editing many sections at once:
96+
97+
1. Observe the image first and write down the visible symptoms.
98+
2. Validate the current template with `python validate_dbr_template.py ...`.
99+
Make sure the script initializes the DBR license before creating `CaptureVisionRouter`; otherwise the result is not trustworthy.
100+
3. Restrict the scope when appropriate: one barcode, one format, long timeout.
101+
4. Compare against any known-good template before theorizing.
102+
5. Adjust localization next: add modes or lower `ConfidenceThreshold`.
103+
6. Adjust decode after that: check `DeformationResistingModes`, decode-specific image parameters, grayscale/binarization, and only then add or remove `DeblurModes`.
104+
7. Relax format rules last: quiet zone, mirror mode, partial value.
105+
106+
This keeps each change falsifiable, so you can tell which parameter family actually helped.
107+
108+
If both the raw image and the `basic` variant sweep still return `NO_RESULT`, treat that as evidence that template-only tuning is likely exhausted for the current pixels. At that point, further random parameter changes are usually lower value than preprocessing, better cropping, or a cleaner source image.
109+
38110
### Keyboard Shortcuts
39111

40112
| Key | Action |

0 commit comments

Comments
 (0)