Auto-Thresholded Template Matching (Otsu on the Score Map)

Every call to match_template_all forces the caller to guess min_score: too low floods NMS with background noise, too high drops scaled / re-themed targets, and the right value differs per asset and per screen. match_autothresh removes the magic number — it runs Otsu’s method on the correlation score histogram (not pixel intensities, the way preprocess.binarize does) to find the valley between the “background correlation” mass and the “real match” mass, and returns that cut-off plus a separability number so the caller knows when the histogram is unimodal (no clear match → don’t trust the threshold).

It reuses visual_match._score_map (the full matchTemplate surface the public matchers discard) and cv2_utils.blobs.connected_boxes — each above-threshold region yields a single peak, avoiding the duplicate hits a raw pixel scan + NMS leaves on a wide correlation peak. The haystack is injectable; the analysis is unit-testable on synthetic arrays. Imports no PySide6.

Headless API

from je_auto_control import match_auto, auto_threshold

# no min_score to tune — the threshold is derived from the score map
for hit in match_auto("save_button.png", floor=0.5):
    print(hit.center, hit.score)

info = auto_threshold("save_button.png")
# {"threshold": 0.83, "separability": 0.61, "n_above": 2}
if info["separability"] < 0.3:
    print("no clear match — threshold not trustworthy")

match_auto returns one Match per above-threshold region, ordered by score and capped at max_results; the cut-off is max(floor, otsu_threshold) so a unimodal / noisy surface cannot drag it below a sane floor. auto_threshold returns {threshold, separability, n_above} — separability near 0 means the score histogram is unimodal and the threshold should be treated as unreliable.

Executor commands

AC_match_auto (template / floor / max_results / region / method → {count, matches}) and AC_auto_threshold (template / region / method → {found, info}). They are exposed as the MCP tools ac_match_auto / ac_auto_threshold (read-only) and as the Script Builder commands Match Template (auto-threshold) / Auto Threshold (Otsu on scores) under Image.