Lkinfer文档

Appearance

模板匹配找图接口 ​

版本：1.26.0613

包含两类找图功能：

  • 模板匹配找图（findPic 系列）：多目标匹配，同时返回所有匹配位置
  • 纯模板匹配（templateMatch 系列）：单目标最佳匹配，支持色彩模式选择

一、模板匹配找图（findPic 系列） ​

findPic ​

cpp
EXPORT_DLL_API const char* findPic(const char* img_path, const char* target_path, int model, int number, float sim);

功能：在图片中查找目标图片（多目标模板匹配）。

参数类型说明
img_path输入原图路径
target_path输入目标模板图片路径
model输入匹配算法模式，见下方对照表
number输入要找多少个。找 1 个填 1，找全部填 999
sim输入相似度阈值（0~1），越高越严格

算法模式对照表：

mode算法光照鲁棒性速度适用场景
1CCOEFF_NORMED★★★★★较慢推荐通用，复杂条件下可靠
2SQDIFF★☆☆☆☆最快完全相同精确匹配
3CCORR_NORMED★★★☆☆中等抗乘性光照变化
4CCOEFF★★★★☆较慢线性关系匹配（不同对比度）
5SQDIFF_NORMED★★★☆☆快抗线性光照变化
6CCORR★★☆☆☆快成比例相似的快速粗匹配

返回值：JSON 数组，每项包含匹配位置：

json
[
  {"x": 100, "y": 200, "w": 50, "h": 60},
  {"x": 300, "y": 400, "w": 50, "h": 60}
]

特殊返回值：

值说明
"-1"原图不存在
"-2"目标图片不存在
"[]"无匹配结果

调用示例：

cpp
const char* result = findPic("screen.png", "icon.png", 1, 1, 0.8f);
printf("查找结果: %s\n", result);

findPicDraw ​

cpp
EXPORT_DLL_API const char* findPicDraw(const char* img_path, const char* target_path, int model, int number, float sim);

功能：找图并绘制结果框（显示窗口）。参数同 findPic。

调用示例：

cpp
const char* result = findPicDraw("screen.png", "icon.png", 1, 5, 0.8f);
printf("查找结果: %s\n", result);

findPicOut ​

cpp
EXPORT_DLL_API const char* findPicOut(const char* img_path, const char* target_path, int model, int number, float sim, const char* out_path);

功能：找图并绘制结果框（输出到文件）。

参数类型说明
out_path输入结果图片保存路径

返回值同 findPic。

调用示例：

cpp
const char* result = findPicOut("screen.png", "icon.png", 1, 1, 0.8f, "result.png");
printf("查找结果: %s\n", result);

二、纯模板匹配（templateMatch 系列） ​

templateMatch ​

cpp
EXPORT_DLL_API const char* templateMatch(const char* imgPath, const char* templPath, float threshold, int mode, int method);

功能：纯模板匹配找图（单目标最佳匹配，无旋转缩放）。与 findPic 系列的区别是：

  • 仅返回最佳匹配（而非所有匹配）
  • 支持色彩模式选择（彩色/灰度）
  • 返回值包含主图尺寸字段
  • score 统一归一化到 0~1 越大越好
参数类型说明
imgPath输入主图路径
templPath输入模板图片路径
threshold输入匹配阈值（0.0 ~ 1.0），推荐 0.8
mode输入色彩模式：0 = 彩色（BGR 三通道），1 = 灰度（单通道，速度更快）
method输入算法模式：1=CCOEFF_NORMED（推荐）, 2=SQDIFF, 3=CCORR_NORMED, 4=CCOEFF, 5=SQDIFF_NORMED, 6=CCORR

返回值：JSON 字符串，格式如下：

json
{
  "matched": true,
  "x": 100,
  "y": 200,
  "w": 50,
  "h": 60,
  "img_width": 1920,
  "img_height": 1080,
  "score": 0.95
}

字段说明：

字段类型说明
matchedbool是否匹配成功
xint匹配位置左上角 x 坐标
yint匹配位置左上角 y 坐标
wint模板图宽度
hint模板图高度
img_widthint主图宽度
img_heightint主图高度
scorefloat最佳匹配分值（归一化到 0~1，越大越好）
errorstring仅失败时存在，描述原因

错误场景：

场景返回
参数为空指针{"matched":false,"error":"参数为空"}
阈值不在 0~1{"matched":false,"error":"阈值范围错误"}
色彩模式不是 0/1{"matched":false,"error":"色彩模式参数错误"}
算法模式不是 1~6{"matched":false,"error":"算法模式参数错误"}
主图不存在{"matched":false,"error":"主图不存在"}
模板图不存在{"matched":false,"error":"模板图不存在"}
模板图大于主图{"matched":false,"error":"模板图大于主图"}
匹配分值低于阈值{"matched":false,"error":"未找到匹配"}

调用示例：

cpp
const char* result = templateMatch("screen.png", "icon.png", 0.8f, 0, 1);
printf("匹配结果: %s\n", result);

templateMatchAll ​

cpp
EXPORT_DLL_API const char* templateMatchAll(const char* imgPath, const char* templPath, float threshold, int mode, int method, int minDist);

功能：纯模板匹配，返回所有超过阈值的匹配位置（而非仅最佳匹配），支持去重。

参数类型说明
imgPath输入主图路径
templPath输入模板图片路径
threshold输入匹配阈值（0.0 ~ 1.0），推荐 0.8
mode输入色彩模式，同 templateMatch
method输入算法模式，同 templateMatch
minDist输入最小去重距离（像素）。相邻匹配点距离小于此值的将被合并（只保留分数最高的）。推荐设为模板宽高的较小值（如模板 32x32 则传 16），传 0 表示不去重

返回值：JSON 字符串，与 templateMatch 的区别是包含 list 数组（存放所有匹配位置）：

json
{
  "matched": true,
  "count": 2,
  "img_width": 1920,
  "img_height": 1080,
  "list": [
    {"x": 100, "y": 200, "w": 50, "h": 60, "score": 0.95},
    {"x": 300, "y": 400, "w": 50, "h": 60, "score": 0.82}
  ]
}

失败时返回：

json
{"matched":false,"count":0,"img_width":0,"img_height":0,"list":[]}

调用示例：

cpp
// 不去重，保留所有超阈值匹配
const char* result = templateMatchAll("screen.png", "icon.png", 0.8f, 0, 1, 0);
printf("全部匹配结果: %s\n", result);

// 去重，距离小于 16px 的相近匹配只保留分数最高的一个
result = templateMatchAll("screen.png", "icon.png", 0.8f, 0, 1, 16);
printf("去重后匹配: %s\n", result);

templateMatchMulti ​

cpp
EXPORT_DLL_API const char* templateMatchMulti(const char* imgPath, const char* templPaths, float threshold, int mode, int method);

功能：多模板匹配。用英文逗号分隔多个模板图片路径，对每个模板依次执行匹配，返回 key-value 格式的 JSON 对象。

参数类型说明
imgPath输入主图路径
templPaths输入多个模板图片路径，用英文逗号分隔，如 "icon1.png,icon2.png,icon3.png"
threshold输入匹配阈值（0.0 ~ 1.0），推荐 0.8
mode输入色彩模式，同 templateMatch
method输入算法模式，同 templateMatch

返回值：JSON 字符串对象。整体校验失败时返回 "{}"。key 命名规则："in_" + n（n 从 0 索引）。

json
{
  "in_0": {
    "matched": true,
    "x": 100, "y": 200,
    "w": 50, "h": 60,
    "img_width": 1920, "img_height": 1080,
    "score": 0.95
  },
  "in_1": {
    "matched": false,
    "x": 0, "y": 0,
    "w": 32, "h": 32,
    "img_width": 1920, "img_height": 1080,
    "score": 0.12,
    "error": "未找到匹配"
  }
}

注意：某个模板读取失败不影响其他模板继续匹配，该条返回 matched: false + error: "模板图无效"。

调用示例：

cpp
const char* result = templateMatchMulti("screen.png", "btn1.png,btn2.png,btn3.png", 0.8f, 0, 1);
printf("多模板匹配: %s\n", result);

templateMatchMultiAll ​

cpp
EXPORT_DLL_API const char* templateMatchMultiAll(const char* imgPath, const char* templPaths, float threshold, int mode, int method, int minDist);

功能：多模板匹配（查找所有匹配位置），支持去重。入参与 templateMatchMulti 基本一致，多一个 minDist 参数，每个模板的返回值改为 list 数组格式（同 templateMatchAll）。

参数类型说明
imgPath输入主图路径
templPaths输入多个模板图片路径，用英文逗号分隔
threshold输入匹配阈值（0.0 ~ 1.0），推荐 0.8
mode输入色彩模式，同 templateMatch
method输入算法模式，同 templateMatch
minDist输入最小去重距离（像素），传 0 不去重

返回值：JSON 字符串对象，key 为 "in_0"、"in_1"...，value 包含 list 数组。

json
{
  "in_0": {
    "matched": true,
    "count": 2,
    "list": [
      {"x": 100, "y": 200, "w": 50, "h": 60, "score": 0.95},
      {"x": 300, "y": 400, "w": 50, "h": 60, "score": 0.82}
    ],
    "img_width": 1920,
    "img_height": 1080
  },
  "in_1": {
    "matched": false,
    "count": 0,
    "list": [],
    "img_width": 1920,
    "img_height": 1080
  }
}

整体校验失败时返回 "{}"。

调用示例：

cpp
const char* result = templateMatchMultiAll("screen.png", "btn1.png,btn2.png", 0.8f, 0, 1, 0);
printf("多模板全部匹配: %s\n", result);

// 带去重
result = templateMatchMultiAll("screen.png", "btn1.png,btn2.png", 0.8f, 0, 1, 16);
printf("多模板全部匹配(去重): %s\n", result);

templateMatchPointer ​

cpp
EXPORT_DLL_API const char* templateMatchPointer(const char* imgPath, const uint8_t* templData, int templLen, float threshold, int mode, int method);

功能：纯模板匹配，但模板图片从内存数据加载而非文件路径。适用于模板图片已读入内存的场景（如截图后直接在内存中做匹配，避免写临时文件）。

参数类型说明
imgPath输入主图路径
templData输入模板图片内存数据指针（const uint8_t* 指向图片文件原始二进制字节，如 PNG/JPG 编码数据）
templLen输入模板图片内存数据长度（字节数）
threshold输入匹配阈值（0.0 ~ 1.0），推荐 0.8
mode输入色彩模式，同 templateMatch
method输入算法模式，同 templateMatch

返回值：同 templateMatch。

调用示例：

cpp
// 从文件读取到内存后传入
FILE* f = fopen("icon.png", "rb");
fseek(f, 0, SEEK_END);
int len = ftell(f);
uint8_t* buf = (uint8_t*)malloc(len);
fseek(f, 0, SEEK_SET);
fread(buf, 1, len, f);
fclose(f);

const char* result = templateMatchPointer("screen.png", buf, len, 0.8f, 0, 1);
printf("匹配: %s\n", result);
free(buf);

templateMatchMultiPointer ​

cpp
EXPORT_DLL_API const char* templateMatchMultiPointer(const char* imgPath, const uint8_t* templData[], const int templLen[], int count, float threshold, int mode, int method);

功能：多模板匹配，模板图片从内存数据加载。采用方案一（指针数组 + 长度数组）传参，同时传入多张模板图片的内存数据。

参数类型说明
imgPath输入主图路径
templData输入指针数组，每个元素指向一张模板图片的原始字节数据（const uint8_t*）
templLen输入长度数组，每个元素对应一张模板图片的字节数
count输入模板图片数量
threshold输入匹配阈值（0.0 ~ 1.0），推荐 0.8
mode输入色彩模式，同 templateMatch
method输入算法模式，同 templateMatch

返回值：同 templateMatchMulti。

调用示例：

cpp
// 读取两张模板图片到内存
int len1, len2;
uint8_t* data1 = (uint8_t*)malloc(len1);
uint8_t* data2 = (uint8_t*)malloc(len2);
// ... fread 填充 data1、data2 ...

// 构建指针数组和长度数组
const uint8_t* ptrs[] = { data1, data2 };
int lens[] = { len1, len2 };

const char* result = templateMatchMultiPointer("screen.png", ptrs, lens, 2, 0.8f, 0, 1);
printf("多模板: %s\n", result);

free(data1);
free(data2);