伪控件树

脚本侧请优先用 WinAuto 视觉方法（一行导入即可）。Studio「找图找色 / RapidOCR / 伪控件树」写入编辑框也生成同一套 API。

实现：chatautox.auto.vision（转发 control_browser_lite.vision_find / vision_pseudo_tree）。

概念速览

能力	做什么	典型场景
`findpic`	在屏幕区域里匹配模板图	找按钮图标、固定 UI 贴图
`findcolor`	在区域里找接近目标色的像素	红点未读、主题色色块
`sample`	区域内随机取若干点颜色	判断头像区是否有图、是否空白
`get_color`	取某一点颜色	调试取色、配合找色
`capture`	截屏为 BGR 数组	自行 OpenCV 处理
`ocr`	区域文字识别	读无 UIA 文本
`pseudo_tree`	截图 → 近似控件树	会话/消息列表视觉对照
`click_pic` / `click_color`	找到后物理点中心	快速点击图标/色块

坐标约定：region = (x, y, w, h)，屏幕像素；找图/找色省略 region 时表示虚拟全屏。

截屏后端 prefer：None/auto（默认）| dxcam | mss | pil。找色若装了 DXCam 却未装 numba，会自动降级 mss，避免卡顿。

from chatautox import WinAuto
print(WinAuto.vision_status())
# {'dxcam': True, 'numba': True, 'paired': True, 'warn': '', ...}

推荐：一行导入

from chatautox import WinAuto

hits = WinAuto.findpic('btn.png', (100, 200, 400, 300), sim=0.9)
pos  = WinAuto.findcolor('FF0000', (0, 0, 800, 600))
pts  = WinAuto.sample((40, 120, 48, 48), n=3)
dump = WinAuto.pseudo_tree((68, 81, 240, 800), mode='session')
texts = WinAuto.ocr((68, 81, 240, 200))
WinAuto.click_pic('btn.png', (100, 200, 400, 300))
WinAuto.click_color('E74C3C', (500, 300, 400, 200))

也可：from chatautox.auto import findpic, findcolor, sample, ocr, pseudo_tree。

Studio 面板对照

打开 操作 → 功能，相关页签：

页签	作用	写入编辑框生成
找图找色	模板/框选模板、找图、找色、区域采样	`WinAuto.findpic` / `findcolor` / `sample` / `click_*`
RapidOCR文字识别	锚点区域截图识别	`WinAuto.ocr`
截图→伪控件树	会话/消息视觉近似 UIA dump	`WinAuto.pseudo_tree`

搜索区域：与 OCR 共用锚点（控件树选中控件 → 基准角 + 横+/纵+/宽/高）。也可「框选」直接定 (x,y,w,h)。

找图建议

「框选模板」或「选择…」准备小图（尽量裁干净、少背景）。
把搜索区域缩到目标附近（全屏慢且易误匹配）。
sim 从 0.9 试起；找不到再降到 0.85～0.88；误匹配则升高。
勾选「找到后物理点击中心」可试跑点击；「写入编辑框」生成脚本。

找色建议

「取色(点选)」点屏幕取 RRGGBB。
多点时设「最多」与「间距」；可开「多点随机匹配」。
「预览标注」用红点标命中位置。

采样建议

框一块区域（如头像位），点数 3～8、间距 ≥8。
看返回的 (x,y,RRGGBB) 分布：是否接近皮肤色/主题色/纯白背景。

API 参考

✨findpic

在屏幕（或指定区域）做模板匹配，返回命中列表。

hits = WinAuto.findpic(
    r'D:\tpl\send.png',
    (800, 600, 400, 300),
    sim=0.9,
    n=3,
    prefer='auto',
)
if not hits:
    raise RuntimeError('未找到模板')
hit = hits[0]
print(hit.x, hit.y, hit.w, hit.h, hit.score, hit.center)
# center = (x + w//2, y + h//2)

参数：

参数	类型	默认	说明
pic	str \| ndarray	必填	模板路径（支持中文路径）或 BGR `ndarray`
region	tuple\|None	None	`(x,y,w,h)`；`None`=虚拟全屏
sim	float	`0.9`	相似度阈值 0～1（OpenCV `TM_CCOEFF_NORMED`）
n	int	`1`	最多返回几个命中（多结果时会抑制邻近重复）
prefer	str\|None	None	截屏后端：`dxcam` / `mss` / `pil` / `auto`

返回值：list[FindPicHit]，未找到为 []。

字段	说明
`x`, `y`	命中左上角屏幕坐标
`w`, `h`	模板宽高
`score`	匹配分
`center`	中心点 `(cx, cy)`

注意：

分辨率 / DPI / 主题色变化会导致分数下降，应重新截模板。
模板不要大于搜索区域。
多命中时在结果图上挖掉邻域再找下一个，避免同一图标重复。

✨findcolor

在区域中查找接近目标色的像素。

# 单点：返回 (x, y) 或 None
pos = WinAuto.findcolor('FF0000', (0, 0, 800, 600), sim=0.95)
pos = WinAuto.findcolor('#E74C3C', region, sim=0.9)
pos = WinAuto.findcolor((231, 76, 60), region)          # RGB 元组
pos = WinAuto.findcolor(0xE74C3C, region)

# 多点：返回 [(x,y), ...]
pts = WinAuto.findcolor(
    '00AAFF', region,
    sim=0.92, n=5, dist=12, random=True,
)

颜色格式：'RRGGBB' / '#RRGGBB' / '0xRRGGBB' / 0xRRGGBB / (r,g,b) / 'R,G,B'。
若写成 RRGGBB-偏移 形式，取主色部分。

参数：

参数	类型	默认	说明
color	见上	必填	目标色
region	tuple\|None	None	搜索区域；`None`=全屏
sim	float	`1.0`	1.0=精确；越小容差越大（内部转成 RGB 容差）
n	int	`1`	`1`→单点 `(x,y)\|None`；`>1`→点列表
dist	int	`8`	多点最小间距（像素）
random	bool	False	True=在匹配像素中随机抽点（适合分散色块）
prefer	str\|None	None	截屏后端（无 numba 时 DX 会降级 mss）

返回值：

n=1：(x, y) 或 None
n>1：list[tuple[int,int]]（可能为空列表）

性能：高频多点找色请 pip install numba，并与 DXCam 配对；否则会降级 mss。用 WinAuto.vision_status() 查看 paired / warn。

✨sample

在区域内随机取若干点颜色（不指定目标色），用于判断区域内容分布。

pts = WinAuto.sample((120, 80, 64, 64), n=4, dist=12, seed=1)
# [(x, y, 'RRGGBB'), ...]
for x, y, hex_color in pts:
    print(x, y, hex_color)

参数：

参数	类型	默认	说明
region	tuple	必填	`(x,y,w,h)`，不可省略
n	int	`3`	采样点数
dist	int	`8`	点之间最小间距
prefer	str\|None	None	截屏后端
seed	int\|None	None	随机种子；固定则结果可复现

返回值：list[tuple[int, int, str]]，每项 (屏幕x, 屏幕y, 'RRGGBB')。

✨get_color

取屏幕一点颜色。

hex_color = WinAuto.get_color(960, 540)   # 'A1B2C3'

参数：x, y 屏幕坐标；prefer 可选。

返回值：'RRGGBB' 字符串（无 # 前缀）。

✨capture

截取屏幕区域，返回 BGR numpy 数组（OpenCV 习惯）。

import cv2
bgr = WinAuto.capture((100, 100, 400, 300))
cv2.imwrite('out.png', bgr)

# 全屏（虚拟屏）
full = WinAuto.capture()

参数：region=None 为全屏；prefer 可选。

✨click_pic

找图并物理鼠标点击第一个命中的中心。成功 True，未找到 False。

# 左键（默认）
ok = WinAuto.click_pic(r'D:\tpl\ok.png', (700, 400, 500, 400), sim=0.88)

# 右键（弹出菜单等）
ok = WinAuto.click_pic(r'D:\tpl\avatar.png', region, sim=0.9, right=True)

if not ok:
    raise RuntimeError('找图未命中')

# 等价手写：先找再右键坐标
hits = WinAuto.findpic(r'D:\tpl\avatar.png', region, sim=0.9)
if hits:
    cx, cy = hits[0].center
    auto = WinAuto(0, mode='mouse')
    auto.right_click_xy(cx, cy, mode='mouse')

不经过 UIA。right=False 左键，right=True 右键。

参数：同 findpic 的 pic / region / sim / prefer，另加：

参数	类型	默认	说明
right	bool	False	True=物理右键，False=左键

✨click_color

找色并物理点击该点。

ok = WinAuto.click_color('E74C3C', (500, 300, 400, 200), sim=0.9)
ok = WinAuto.click_color('E74C3C', region, sim=0.9, right=True)  # 右键

参数：同 findcolor 单点用法（n 固定为 1），另加 right: bool = False。

✨ocr

对区域截图做 RapidOCR，返回文字、置信度与屏幕坐标矩形。

for text, score, rect in WinAuto.ocr((68, 81, 240, 200)):
    # rect = (left, top, right, bottom) 屏幕坐标
    print(text, score, rect)

# 可传入已创建的引擎，避免重复加载
from rapidocr_onnxruntime import RapidOCR
engine = RapidOCR()
rows = WinAuto.ocr(region, engine=engine)

参数：

参数	类型	默认	说明
region	tuple	必填	`(x,y,w,h)`
engine	RapidOCR\|None	None	复用引擎；默认内部懒加载

返回值：list[tuple[str, float, tuple[int,int,int,int]]]，每项为 (text, score, (left, top, right, bottom))。坐标已换算为屏幕坐标。

依赖：pip install rapidocr_onnxruntime pillow numpy。

✨pseudo_tree

截屏区域 → OCR → 近似 UIA 控件树文本。

dump = WinAuto.pseudo_tree((68, 81, 240, 800), mode='session')
print(dump)

dump, meta = WinAuto.pseudo_tree(
    region, mode='message', return_meta=True,
)
print(meta['mode'], meta['item_count'], meta.get('bubble_detector'))

参数：

参数	类型	默认	说明
region	tuple	必填	`(x,y,w,h)`
mode	str	`auto`	`auto` / `session`（会话列表）/ `message`（消息列表）
return_meta	bool	False	True → `(dump, meta)`
engine	RapidOCR\|None	None	OCR 引擎

说明：伪树 Class/Aid 不是真实 UIA，便于对照与物理坐标点击；正式自动化优先真实控件树 / Message API。

✨vision_status

st = WinAuto.vision_status()
print(st['dxcam'], st['numba'], st['paired'], st.get('warn'))

字段	说明
`dxcam`	是否可用 DXCam
`numba`	是否可用 numba
`paired`	找色高速配对是否合格
`warn`	非空则有降级提示
`color_backend_policy`	当前找色截屏策略说明

完整示例

找图点击按钮

from chatautox import WinAuto
import time

region = (700, 500, 600, 400)  # 先缩小搜索区
if WinAuto.click_pic(r'D:\tpl\send.png', region, sim=0.88):
    print('已点击发送图标')
else:
    hits = WinAuto.findpic(r'D:\tpl\send.png', region, sim=0.8, n=1)
    print('未点到，命中=', hits)

找未读红点再点

from chatautox import WinAuto

region = (40, 80, 320, 700)  # 会话列表大致区域
pos = WinAuto.findcolor('FA5151', region, sim=0.85)
if pos:
    # 也可用 click_color；这里演示拿到坐标后自行处理
    print('红点', pos)
    WinAuto.click_color('FA5151', region, sim=0.85)

采样判断区域是否有内容

from chatautox import WinAuto

pts = WinAuto.sample((60, 120, 48, 48), n=6, dist=10)
# 接近背景灰/白 → 可能空；色彩丰富 → 可能有头像
print(pts)

OCR + 伪树调试

from chatautox import WinAuto

region = (400, 100, 520, 700)
print(WinAuto.ocr(region)[:5])
dump, meta = WinAuto.pseudo_tree(region, mode='auto', return_meta=True)
print(meta['mode'], meta['item_count'])
print(dump[:500])

常见问题

现象	处理
`视觉能力依赖未安装`	`pip install -r control_browser_lite/requirements_vision.txt`
找图总是空	缩小 `region`；重截模板；降低 `sim`；确认缩放/DPI 一致
找图误匹配	提高 `sim`；模板裁更紧；限制搜索区
找色很卡	安装 `numba`；或显式 `prefer='mss'`；缩小区域
`paired=False`	装了 DXCam 无 numba，找色已降级 mss
OCR 报错	`pip install rapidocr_onnxruntime pillow numpy`
伪树气泡粘连	缩小 `region`；确认消息区截图清晰
`click_pic` 点偏	模板中心应对准可点区域；或 `findpic` 后用 `hit.center` 自行偏移再 `click_xy`

进阶（一般不必用）

底层模块 control_browser_lite.vision_find：

WinAuto	底层
`findpic`	`findpic` / `find_pic_on_screen`
`findcolor`	`findcolor` / `find_color_on_screen` / `find_color_points_on_screen`
`sample`	`sample` / `sample_region_colors`
`capture`	`capture_bgr` / `capture_region`
`get_color`	`get_color`
`pseudo_tree`	`vision_pseudo_tree.build_pseudo_tree`

其它：parse_color、resolve_prefer_for_color、FindPicHit 等。

#找图 / 找色 / 采样 / OCR / 伪控件树

#概念速览

#推荐：一行导入

#Studio 面板对照

#API 参考

#✨findpic

#✨findcolor

#✨sample

#✨get_color

#✨capture

#✨click_pic

#✨click_color

#✨ocr

#✨pseudo_tree

#✨vision_status

#完整示例

#找图点击按钮

#找未读红点再点

#采样判断区域是否有内容

#OCR + 伪树调试

#常见问题

#进阶（一般不必用）