OCR 後端

AutoControl 提供三個可插拔的 OCR 引擎，共用同一組公開 API。依照安裝環境與腳本要辨識的語言挑一個用就好：

後端	適用情境	安裝方式
`tesseract`	ASCII / 西方語言、最輕量	`pip install pytesseract` + 把 `tesseract.exe` 放進 PATH
`easyocr`	CJK 但不想裝外部執行檔	`pip install easyocr`（首次呼叫會下載約 64 MB 模型）
`paddleocr`	中文／日文／韓文最高品質	`pip install paddlepaddle paddleocr`

選擇後端的順序

啟用的後端依照以下順序決定：

OCR 函式呼叫時傳入的 backend= 參數。
AUTOCONTROL_OCR_BACKEND 環境變數。
自動偵測 — 依序嘗試 tesseract → easyocr → paddleocr，挑出第一個 import 成功的。

實務上你只要 pip install 你要的那個後端，剩下的交給自動偵測即可:

from je_auto_control import find_text_matches

# 沒有 backend 參數、沒有環境變數 → 自動偵測
matches = find_text_matches("登入")

要強制指定某個後端時:

matches = find_text_matches("登入", backend="easyocr")

或在整個行程指定:

$ AUTOCONTROL_OCR_BACKEND=paddleocr python my_script.py

語言代碼

每個後端原生使用的語言代碼不同，但公開 API 都接受同一組標準寫法（Tesseract 風格），呼叫時會在邊界做翻譯：

AutoControl 標準代碼	Tesseract	EasyOCR	PaddleOCR
`eng`	`eng`	`en`	`en`
`chi_tra` / `zh-TW`	`chi_tra`	`ch_tra`	`chinese_cht`
`chi_sim` / `zh-CN`	`chi_sim`	`ch_sim`	`ch`
`jpn`	`jpn`	`ja`	`japan`
`kor`	`kor`	`ko`	`korean`

其他語言（法／德／阿拉伯文……）直接傳該後端的原生代碼即可，會原樣傳入。

Tesseract 安裝注意

Windows 必須另外安裝 Tesseract 執行檔（UB-Mannheim build 最常見）。若 tesseract.exe 不在 PATH 上:

from je_auto_control import set_tesseract_cmd
set_tesseract_cmd(r"C:\Program Files\Tesseract-OCR\tesseract.exe")

語言檔（*.traineddata）放在 Tesseract-OCR\\tessdata\\ 底下，要哪個語言就從 tessdata GitHub repo 抓對應檔案複製進去。

EasyOCR / PaddleOCR 安裝注意

兩者都會在第一次呼叫某個語言時懶下載神經模型，存放路徑：

EasyOCR：~/.EasyOCR/model/（每個語言約 64 MB）。
PaddleOCR：~/.paddleocr/（偵測 + 辨識模型合計約 50 MB）。

因此第一次呼叫會明顯比之後慢，建議在開機或測試 setup 預熱一次。

無 GUI 使用

三個後端都符合 AutoControl「功能必須能脫離 GUI 使用」的規範。公開 API 如下:

from je_auto_control import (
    find_text_matches, locate_text_center, wait_for_text,
    click_text, read_text_in_region, find_text_regex,
)

每個函式都吃同一組參數（lang、region、min_confidence、 backend、case_sensitive），回傳的 TextMatch 已自動換算為絕對螢幕座標。

JSON 動作介面

OCR 也透過 executor 對 JSON 動作檔開放:

{"command": "AC_locate_text", "text": "登入", "lang": "chi_tra"}
{"command": "AC_click_text",  "text": "確定", "backend": "easyocr"}

兩個指令的參數與 Python 端完全一致。

診斷

要確認當前環境有哪些後端可用:

from je_auto_control.utils.ocr.backends import get_backend

for name in ("tesseract", "easyocr", "paddleocr"):
    try:
        backend = get_backend(name)
        print(name, "可用" if backend.available else "不可用")
    except Exception as exc:  # noqa: BLE001
        print(name, "錯誤：", exc)