capture_template

Overview ¶

cmd/capture_template is a manual template-recapture tool. It pulls a single screenshot from the live BlueStacks instance over adb, asks the user (on the terminal) for a rect of pixel coordinates describing the target template region, crops, writes it to assets/templates/<name>.png, backs up the previous version to <name>.png.bak, then runs MatchMultiScaleROI against the source frame so the user gets immediate feedback ("✓ conf=0.91 at (442,285)" or "✗ no match — try again").

Typical workflow to recapture text_wall.png from a clean session:

1. In BlueStacks, navigate to MainVillage → tap builder head → scroll the upgrades menu to bring the "Wall" row to a stable position on screen. (This tool does NOT drive the menu — see run_test_wall_upgrade.sh for that.)
2. Run `run_capture_template.sh text_wall`. The tool snaps a preview to output/template_captures/<ts>/captured_screen.png — open that PNG in Preview / your image viewer.
3. Inspect the PNG and enter the bounding rect of the "Wall" label in physical (screen) coords when prompted (e.g. "350 270 450 300"). Coords can be either corner-format (4 numbers) or center-format (prefix the line with `c`, e.g. `c 400 285 100 30`).
4. The tool writes assets/templates/text_wall.png, archives the previous one to .bak, prints the verification confidence.

Coordinate space: always the PHYSICAL pixel size of the captured frame (e.g. 860x732 for 860x732 devices). The tool warns otherwise and never rescales — keeping the trace from capture to crop single-step avoids off-by-one errors at non-ref resolutions.

SAFETY: the template is written to `<name>.png.tmp` first, then a verify pass runs, and only on success does the tmp file rename over the live file. This means if conf is below `--min-conf` or no matches are found, the previous live template is preserved (unchanged on disk) and the broken capture lands in `<name>.png.failed-<ts>` for inspection. The .bak backup is still written so the user has belt-and-braces recovery options.