图像识别模块总览 - Overview

本分类做什么

在 大图、内存图或已绑定窗口画面 中，按 模板相似度 或 色差+方向 查找目标位置；部分接口支持 多模板（路径用 | 拼接）、旋转扫描、二值/阈值匹配 与 动画/GIF 时段匹配。返回一般为 JSON 字符串指针（需 GetStringFromPtr + FreeStringPtr），坐标含义因系列而异（屏幕/文件图 vs 相对绑定窗口）。

使用前通常配合 图像处理：GetScreenDataPtr、LoadImage 等得到 OLAImage；绑定窗口场景需先 BindWindow。

一、先分清两条产品线：Match* 与 Find*

二者 不是 简单改名，参数与语义不同。

对比项Match*（匹配）Find*（查找）
核心参数matchVal（0～1 相似度）、type（匹配模式 1～5）、angle（旋转步进）、scale（缩放）deltaColor（色差串，如 "101010"）、matchVal，无 type/angle 这一套
典型用途与模板做 结构相似度 匹配，可调 灰度/彩色/透明 等类型（见各页 type 说明）在色差容忍下 按扫描方向 找 第一个 或 全部 位置
结果Match*：默认最优一条；带 All 的返回 全部 达标位置Find*：无 All → 第一个；带 All → 全部
方向由算法在区域内搜索最优/全部Find* 有 dir（多种扫描顺序，如左上到右下、从中心等）

选型：需要 type/透明/旋转 时用 Match*；更贴近 颜色偏差 + 扫描顺序、接口更轻时用 Find*。

二、第二维：MatchImage* vs MatchWindows*

系列图源与区域坐标系
MatchImage*源图为 文件路径 或 OLAImage 句柄（整图或已裁好的图）相对 该源图 的像素坐标（具体见各接口返回值说明）
MatchWindows*在 已绑定窗口 上取 矩形区域 (x1,y1,x2,y2)，仅需模板返回 相对绑定窗口 的坐标

选型：已 BindWindow 且只关心窗内区域 → MatchWindows*；源图来自文件或内存大图、与绑定无关 → MatchImage*。

三、第三维：Path / Ptr / 混合（仅 MatchImage）

模板与源图的数据来源组合（命名即含义）：

接口形态源图模板说明
MatchImageFromPath文件路径文件路径最省事，适合磁盘上的源图与模板
MatchImageFromPtrOLAImageOLAImage双内存，重复匹配时避免反复读盘
MatchImageFromPathAll路径路径与上相同，但返回 所有 匹配位
MatchImageFromPtrAll指针指针内存版 全部 结果
MatchImagePtrFromPathOLAImage路径源已在内存（如截图句柄），模板仍用文件
MatchImagePtrFromPathAllOLAImage路径上者的 全部 结果版

差异要点：

  • 无后缀 / 非 All：通常返回 最优一条（文档称默认最优结果）。
  • 带 All：同一套参数下仅返回 识别率大于等于阈值 的位置；低于阈值的结果不输出，适合一屏多图标。
  • PtrFromPath：减少 模板路径 反复加载时的使用方式，源必须是 LoadImage/GetScreenDataPtr 等得到的句柄。

MatchImageFromPathAll 等页中 scale 在 All 系列里常标注为 源图缩放；与 MatchImageFromPath 中配合窗口的缩放含义请以 对应详情页 为准，避免混用。

四、MatchWindows*：绑定窗口上的「普通匹配」与「全部」

在 已绑定窗口 的 (x1,y1,x2,y2) 内匹配，模板可为路径或内存。

接口模板结果数量
MatchWindowsFromPath路径最优
MatchWindowsFromPathAll路径全部
MatchWindowsFromPtrOLAImage最优
MatchWindowsFromPtrAllOLAImage全部

差异：仅 模板 来自路径还是句柄，以及 最优 vs 全部；其余 matchVal、type、angle、scale 与 MatchImage 系一致。

五、MatchWindowsThreshold*：二值化后再匹配（线稿/UI 轮廓）

在普通 MatchWindows* 基础上，增加 colorJson（颜色模型，见 ColorModel），对区域做 二值/分色 后再与模板比对，适合 边缘清晰、颜色单一 的界面元素。

接口模板
MatchWindowsThresholdFromPath路径
MatchWindowsThresholdFromPathAll路径，全部结果
MatchWindowsThresholdFromPtrOLAImage
MatchWindowsThresholdFromPtrAllOLAImage，全部结果

与普通 MatchWindows 的差异：多 colorJson，走 阈值/二值 管线；无 与 MatchImage* 直接一一对应的 Threshold 版本时，以侧栏为准。

六、FindImage* vs FindWindows*（查找线）

与 Match 对照：色差 deltaColor + 相似度 matchVal，无 type/angle。

6.1 全图/文件图：FindImage*

接口源与模板结果
FindImageFromPath均为路径第一个，带 dir
FindImageFromPathAll均为路径全部（无 dir）
FindImageFromPtr均为 OLAImage第一个，带 dir
FindImageFromPtrAll均为 OLAImage全部

6.2 绑定窗口：FindWindows*

接口模板结果
FindWindowsFromPath路径第一个，区域 (x1,y1,x2,y2) + dir
FindWindowsFromPathAll路径全部
FindWindowsFromPtrOLAImage第一个
FindWindowsFromPtrAllOLAImage全部

差异小结：FindImage vs FindWindows = 图源与坐标系（整图 vs 绑定窗区域）；FromPath vs FromPtr = 路径 vs 句柄；无 All = 第一个 + 方向 dir，有 All = 枚举全部。

七、MatchAnimation*：动画 / GIF 场景

在 时间窗 内持续匹配 动态区域（如 GIF），命中即返回，参数含 帧间隔 delay、总时长 time、线程数 threadCount。

接口模板来源
MatchAnimationFromPath路径
MatchAnimationFromPtrOLAImage

与静态 MatchWindows* 的差异：多时间/线程相关参数，用于 动效 而非单帧截图。

八、整图度量（不做滑窗模板搜索）

两张 已对齐的 OLAImage 直接比整体相似度或误差，不是「在大图里找小图」。

接口作用
CalculateSSIM结构相似性指数（SSIM）
IsSameImage是否相同（整体判定）
CalculateHistograms直方图比较
CalculateMSE均方误差（MSE）

与 Match/Find 的区别：无模板在源图上滑动；适用于 两帧对比、整屏是否变化 等。

九、调试与其它

接口作用
ShowMatchWindow全局开关：找图、找字、识字 等是否 弹窗预览（调试用，正式环境建议关闭）

十、返回值与后续处理

  • 字符串指针：多数返回 long 指针，需 GetStringFromPtr 取 JSON 文本，再 FreeStringPtr。
  • JSON 解析：可使用 JSON 分类中的 ParseMatchImageJson、GetMatchImageAllCount、ParseMatchImageAllJson 等，与多结果、多矩形字段解析配合。
  • 最优解与命中判定：
    • 非 All 系列通常返回一条“最优解”（当前搜索区域中分数最高的候选）。
    • 实际是否命中请以返回 JSON 的 matchstate（部分页面可能写作 matchState）为准，而不是仅看是否返回了坐标。
    • 当候选识别率（相似度）大于等于你传入的阈值（如 matchVal）时，matchstate=true；低于阈值则为 false。
    • All 系列只会输出识别率 >= 阈值 的条目，低于阈值的候选会被过滤；业务代码仍建议先判断 matchstate 再使用坐标。

十一、快速选型表

你的需求优先考虑的接口
已绑定窗口，只要最佳匹配MatchWindowsFromPath / MatchWindowsFromPtr
已绑定窗口，要所有出现位置MatchWindowsFromPathAll / MatchWindowsFromPtrAll
线稿/强对比 UI，需颜色模型二值化MatchWindowsThreshold* 对应 Path/Ptr/All
源图在内存、模板在文件MatchImagePtrFromPath（及 All）
源与模板都在内存、高性能重复跑MatchImageFromPtr / FromPtrAll
用色差 + 扫描方向找 第一个FindImageFromPath / FindWindowsFromPath（注意 dir）
用色差找 全部FindImageFromPathAll / FindWindowsFromPathAll
GIF/动画直到出现MatchAnimationFromPath / MatchAnimationFromPtr
两整张图是否像、SSIM/MSECalculateSSIM、CalculateMSE 等

更细的参数默认值、JSON 字段与边界条件 以各接口详情页为准；本页用于 名称与系列差异 对照。

Last Updated: