VisionLocator 视觉金字塔定位器

能做什么

VisionLocator 模拟人类视觉的「先全局扫视 → 再细节聚焦」方式，在屏幕上精准定位任何 UI 元素。

核心特性

• 多层级递归放大 — 从全屏到像素级，精度达 0.125px
• 候选区域智能筛选 — 支持精确/模糊/语义/位置加权 4 种匹配模式
• LLaVA 语义验证 — 用视觉语言模型二次确认找到的元素
• 坐标变换器 — 自动补偿放大比例，确保返回真实屏幕坐标

工作原理

全屏截图 (1920x1080)
    ↓ OCR + 快速扫描
候选区域列表 [区域A, 区域B, 区域C]
    ↓ 按匹配分数排序
放大最佳候选区 (2x)
    ↓ 精细 OCR
更精准候选列表
    ↓ 递归 (最多 9 层)
找到目标元素 → 返回真实坐标

快速使用

from vision_locator import VisionLocator

locator = VisionLocator()

# 在屏幕上查找"确认"按钮
result = locator.find("确认")
if result:
    x, y = result.x, result.y
    print(f"找到！坐标: ({x}, {y})")
    # 配合 pyautogui 点击
    import pyautogui
    pyautogui.click(x, y)

# 模糊匹配
result = locator.find("确认", match_mode="fuzzy")

# 带截图路径
result = locator.find_in_image("确认", image_path="screenshot.png")

# 查找所有匹配
results = locator.find_all("按钮")

精度层级

| 层级 | 精度 | 适用场景 |

|------|------|---------|

| L0 全屏 | 1px | 快速扫描，确定大致区域 |

| L1 区域 | 0.5px | 缩小范围 |

| L2 精细 | 0.25px | 精准识别 |

| L3 微观 | 0.125px | 极小元素、密集界面 |

匹配模式

| 模式 | 说明 |

|------|------|

| exact | 精确匹配，区分大小写 |

| fuzzy | 模糊匹配，允许部分字符偏差 |

| semantic | 语义匹配，"提交" ≈ "确认" ≈ "OK" |

| position | 位置加权，优先屏幕特定区域 |

依赖

• Python 3.8+
• Pillow — 截图处理
• rapidocr-onnxruntime 或 easyocr — OCR 识别
• pyautogui — 屏幕截图（可替换）
• Ollama + LLaVA（可选，用于语义验证）