Skip to content
qiannian edited this page Jun 13, 2026 · 1 revision

OpenCV

OpenCV 图像处理和模板匹配

接口目录

公共说明

以下 Cv* 接口为导出的 COM 方法,模板匹配接口使用当前图色输入源;文件预处理接口直接读取 src_file 并输出到 dst_file

输入源

OpenCV 模板匹配类接口内部会通过 CaptureRegion 获取搜索区域,实际输入源由当前显示输入方式决定:

输入方式 是否需要绑定窗口 说明
默认 screen 不强制 已绑定窗口时从绑定窗口取图;未绑定时会使用桌面窗口作为屏幕输入
SetDisplayInput("pic:图片路径") 不需要 从指定图片取图,坐标以图片左上角为原点
SetDisplayInput("mem:内存参数") 不需要 从内存图片取图,坐标以内存图片左上角为原点
SetDisplayInput("screen") 取决于当前绑定状态 切回屏幕或窗口截图输入

因此,如果不绑定窗口但需要使用 OpenCV 匹配,先调用 SetDisplayInput("pic:...")SetDisplayInput("mem:...") 指定图片输入源,再调用 CvMatchTemplateCvMatchAnyTemplateCvMatchAllTemplatesCvFeatureMatchTemplateCvEdgeMatchTemplateCvShapeMatchTemplate 等匹配接口。匹配参数里的 x,y,width,height 会按当前输入源的宽高进行区域转换和限制,区域无效时接口返回失败。

OpenCV dir

描述
0 从左到右
1 从右到左
2 从上到下
3 从下到上

strip_mode

描述
0 不拆分条带,按 dir 在完整区域内搜索
1 横向条带并行搜索,只支持 dir=0 从左到右、dir=1 从右到左
2 纵向条带并行搜索,只支持 dir=2 从上到下、dir=3 从下到上

strip_mode 用于把搜索区域沿指定轴拆成多个互相有重叠的条带并行匹配,命中即停时可以降低大区域搜索延迟。条带方向必须和 dir 的主搜索方向一致:横向条带按 X 轴拆分,只能配合左右搜索;纵向条带按 Y 轴拆分,只能配合上下搜索。不兼容的组合会直接匹配失败。

method

描述
0 TM_SQDIFF,平方差匹配,比较像素差异,原始分数越小越像,适合背景稳定、亮度差异不大的模板
1 TM_SQDIFF_NORMED,归一化平方差匹配,和 0 类似但分数归一化,更适合不同尺寸或不同对比度图片,推荐作为稳妥默认值
2 TM_CCORR,相关匹配,比较模板和图像的直接相关性,原始分数越大越像,对亮度变化较敏感
3 TM_CCORR_NORMED,归一化相关匹配,和 2 类似但分数归一化,比 2 更适合亮度轻微变化的场景
4 TM_CCOEFF,相关系数匹配,会去除均值影响,适合整体亮度变化但结构仍一致的图片
5 TM_CCOEFF_NORMED,归一化相关系数匹配,抗整体亮度变化能力较好,分数直观,常用于普通模板匹配

接口返回的 score 已统一为相似度语义:无论使用哪种 method,都是越大越像。内部会把 TM_SQDIFF 和 TM_SQDIFF_NORMED 的原始低分优先结果转换为 1 - 原始分数,所以 threshold 仍按 0.0-1.0 的相似度阈值理解即可。

color_mode

描述
0 彩色匹配
1 灰度匹配

单模板匹配接口的 retjson 成功时常见格式如下,失败时返回 {"ok":0}

{"ok":1,"x":10,"y":20,"width":30,"height":40,"score":0.987000}

CvMatchAnyTemplate 命中时会额外返回模板名称:

{"ok":1,"name":"btn_ok","x":10,"y":20,"width":30,"height":40,"score":0.987000}

CvMatchAllTemplates 返回结果数组,无命中时返回 {"ok":0,"results":[]}

{"ok":1,"results":[{"name":"btn_ok","x":10,"y":20,"width":30,"height":40,"score":0.987000}]}

预处理使用建议

预处理接口主要用于把原始截图或图片整理成更适合识别、匹配、分割、轮廓分析的输入。预处理不会直接替代找图或 OCR,而是用来降低背景、噪声、光照、尺寸差异对后续算法的影响。

常见使用场景:

  • 模板匹配前:先使用 CvCrop 缩小关注区域,或用 CvToGrayCvDenoiseCvSharpen 减少颜色和噪点干扰。
  • 颜色目标定位:使用 CvInRange 提取指定颜色范围,再用 CvMorphology 清理小噪点,最后用 CvConnectedComponentsCvFindContours 获取区域。
  • 文字或图标提取:使用 CvToBinaryCvThreshold 得到黑白图,再用 CvCropValid 去掉空白边缘,便于保存字库、做轮廓或统一尺寸。
  • 低对比度图片:使用 CvEqualizeCvCLAHE 提升对比度,再进行二值化、边缘提取或模板匹配。
  • 形状分析:使用 CvToEdgeCvToOutlineCvMorphology 生成更清晰的边界,再调用 CvFindContoursCvShapeMatchTemplate

建议先把每一步的输出保存成图片检查效果,再组合成 CvPreprocessPipeline。如果二值图结果有很多散点,优先尝试 morph:open;如果目标断裂或内部有小孔,优先尝试 morph:close;如果目标颜色稳定,优先使用 CvInRange,如果颜色不稳定但前景背景反差明显,优先使用 CvThresholdCvToBinary

接口方法

CvLoadTemplate

加载 OpenCV 模板

long CvLoadTemplate(name,file_path)
参数 类型 描述
name string 模板名称
file_path string 模板图片路径

如果模板图片包含透明通道,CvLoadTemplate 会自动把 alpha 通道转换为匹配掩码。透明区域不会参与模板匹配,因此透明 PNG 可以直接作为带掩码模板使用;需要使用独立掩码文件时再调用 CvLoadMaskedTemplate

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvLoadTemplate("btn_ok","btn_ok.png")

CvLoadMaskedTemplate

加载带掩码的 OpenCV 模板

long CvLoadMaskedTemplate(name,template_path,mask_path)
参数 类型 描述
name string 模板名称
template_path string 模板图片路径
mask_path string 掩码图片路径

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvLoadMaskedTemplate("btn_ok","btn_ok.png","btn_ok_mask.png")

CvRemoveTemplate

移除指定 OpenCV 模板

long CvRemoveTemplate(name)
参数 类型 描述
name string 模板名称

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvRemoveTemplate("btn_ok")

CvRemoveAllTemplates

移除全部 OpenCV 模板

long CvRemoveAllTemplates()

返回值

类型:int

  • 1:成功

示例

op.CvRemoveAllTemplates()

CvHasTemplate

判断 OpenCV 模板是否存在

long CvHasTemplate(name)
参数 类型 描述
name string 模板名称

返回值

类型:int

  • 0:不存在
  • 1:存在

示例

ret = op.CvHasTemplate("btn_ok")

CvGetTemplateCount

获取已加载的 OpenCV 模板数量

long CvGetTemplateCount()

返回值

类型:int

返回模板数量

示例

count = op.CvGetTemplateCount()

CvGetAllTemplateNames

获取全部 OpenCV 模板名称

string CvGetAllTemplateNames()

返回值

类型:string

返回以 | 分割的模板名称列表

示例

names = op.CvGetAllTemplateNames()

CvGetOpenCvVersion

获取当前 OpenCV 版本

string CvGetOpenCvVersion()

返回值

类型:string

返回 OpenCV 版本号

示例

version = op.CvGetOpenCvVersion()

CvLoadTemplateList

批量加载 OpenCV 模板

long CvLoadTemplateList(template_list)
参数 类型 描述
template_list string 模板列表,格式为"name,path|name2,path2"

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvLoadTemplateList("btn_ok,btn_ok.png|btn_cancel,btn_cancel.png")

CvMatchTemplate

在指定区域内进行 OpenCV 单模板匹配

long CvMatchTemplate(x,y,width,height,template_name,threshold,dir,strip_mode,method,color_mode,retjson)
参数 类型 描述
x int 区域左上 X 坐标
y int 区域左上 Y 坐标
width int 区域宽度
height int 区域高度
template_name string 已加载的模板名称
threshold double 匹配阈值,通常取值 0.0-1.0
dir int OpenCV 查找方向,见上方 dir
strip_mode int 条带搜索模式,见上方 strip_mode
method int OpenCV 模板匹配方法,见上方 method
color_mode int 颜色模式,见上方 color_mode
retjson string* 变参指针: 返回匹配结果 JSON

返回值

类型:int

  • 0:失败或未命中
  • 1:成功命中

示例

var retjson string
ret = op.CvMatchTemplate(0,0,800,600,"btn_ok",0.9,0,0,5,0,&retjson)

CvMatchTemplateScale

在指定区域内按多个缩放比例进行 OpenCV 模板匹配

long CvMatchTemplateScale(x,y,width,height,template_name,scales,threshold,method,color_mode,retjson)
参数 类型 描述
x int 区域左上 X 坐标
y int 区域左上 Y 坐标
width int 区域宽度
height int 区域高度
template_name string 已加载的模板名称
scales string 缩放比例列表,格式如"0.8|1|1.2";传空字符串时使用自动缩放候选
threshold double 匹配阈值,通常取值 0.0-1.0
method int OpenCV 模板匹配方法
color_mode int 颜色模式
retjson string* 变参指针: 返回匹配结果 JSON

返回值

类型:int

  • 0:失败或未命中
  • 1:成功命中

示例

ret = op.CvMatchTemplateScale(0,0,800,600,"btn_ok","0.8|1|1.2",0.9,5,0,&retjson)

如果不确定目标缩放比例,可以把 scales 传为空字符串,让内部自动尝试一组缩放候选:

ret = op.CvMatchTemplateScale(0,0,800,600,"btn_ok","",0.9,5,0,&retjson)

CvMatchAnyTemplate

在指定区域内匹配多个 OpenCV 模板,命中任意一个即返回

long CvMatchAnyTemplate(x,y,width,height,template_names,threshold,dir,strip_mode,method,color_mode,retjson)
参数 类型 描述
x int 区域左上 X 坐标
y int 区域左上 Y 坐标
width int 区域宽度
height int 区域高度
template_names string 模板名称列表,使用竖线分割
threshold double 匹配阈值,通常取值 0.0-1.0
dir int OpenCV 查找方向
strip_mode int 条带搜索模式
method int OpenCV 模板匹配方法
color_mode int 颜色模式
retjson string* 变参指针: 返回匹配结果 JSON

返回值

类型:int

  • 0:失败或未命中
  • 1:成功命中

示例

ret = op.CvMatchAnyTemplate(0,0,800,600,"btn_ok|btn_cancel",0.9,0,0,5,0,&retjson)

CvMatchAllTemplates

在指定区域内匹配多个 OpenCV 模板,并返回全部命中结果

long CvMatchAllTemplates(x,y,width,height,template_names,threshold,dir,strip_mode,method,color_mode,retjson)
参数 类型 描述
x int 区域左上 X 坐标
y int 区域左上 Y 坐标
width int 区域宽度
height int 区域高度
template_names string 模板名称列表,使用竖线分割
threshold double 匹配阈值,通常取值 0.0-1.0
dir int OpenCV 查找方向
strip_mode int 条带搜索模式
method int OpenCV 模板匹配方法
color_mode int 颜色模式
retjson string* 变参指针: 返回匹配结果 JSON

返回值

类型:int

  • 0:失败或无命中
  • 1:有命中结果

示例

ret = op.CvMatchAllTemplates(0,0,800,600,"btn_ok|btn_cancel",0.9,0,0,5,0,&retjson)

CvFeatureMatchTemplate

使用特征点在指定区域内匹配模板

long CvFeatureMatchTemplate(x,y,width,height,template_name,threshold,retjson)
参数 类型 描述
x int 区域左上 X 坐标
y int 区域左上 Y 坐标
width int 区域宽度
height int 区域高度
template_name string 已加载的模板名称
threshold double 匹配阈值,通常取值 0.0-1.0
retjson string* 变参指针: 返回匹配结果 JSON

返回值

类型:int

  • 0:失败或未命中
  • 1:成功命中

示例

ret = op.CvFeatureMatchTemplate(0,0,800,600,"btn_ok",0.8,&retjson)

CvEdgeMatchTemplate

使用边缘图在指定区域内匹配模板

long CvEdgeMatchTemplate(x,y,width,height,template_name,threshold,retjson)
参数 类型 描述
x int 区域左上 X 坐标
y int 区域左上 Y 坐标
width int 区域宽度
height int 区域高度
template_name string 已加载的模板名称
threshold double 匹配阈值,通常取值 0.0-1.0
retjson string* 变参指针: 返回匹配结果 JSON

返回值

类型:int

  • 0:失败或未命中
  • 1:成功命中

示例

ret = op.CvEdgeMatchTemplate(0,0,800,600,"btn_ok",0.8,&retjson)

CvShapeMatchTemplate

使用轮廓形状在指定区域内匹配模板

long CvShapeMatchTemplate(x,y,width,height,template_name,threshold,retjson)
参数 类型 描述
x int 区域左上 X 坐标
y int 区域左上 Y 坐标
width int 区域宽度
height int 区域高度
template_name string 已加载的模板名称
threshold double 匹配阈值,通常取值 0.0-1.0
retjson string* 变参指针: 返回匹配结果 JSON

返回值

类型:int

  • 0:失败或未命中
  • 1:成功命中

示例

ret = op.CvShapeMatchTemplate(0,0,800,600,"btn_ok",0.8,&retjson)

CvToGray

将图片转换为灰度图

适用于不关心颜色、只关心明暗结构的场景,比如按钮、文字、图标的模板匹配前处理。灰度图可以减少颜色变化带来的影响,也能降低后续二值化、边缘提取的复杂度。

long CvToGray(src_file,dst_file)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvToGray("src.png","gray.png")

CvCrop

裁剪图片

适用于只处理图片中的固定区域,例如界面中的小地图、血条、按钮区。先裁剪再做匹配或分析,可以减少误匹配范围,并提升后续处理速度。

long CvCrop(src_file,x,y,width,height,dst_file)
参数 类型 描述
src_file string 源图片路径
x int 裁剪区域 X
y int 裁剪区域 Y
width int 裁剪宽度
height int 裁剪高度
dst_file string 输出图片路径

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvCrop("src.png",10,10,100,80,"crop.png")

CvResize

调整图片尺寸

适用于统一输入图片尺寸,例如把不同分辨率下截取的图标缩放到固定大小后再保存、分析或训练字库。模板匹配前如果目标比例固定,也可以先缩放到统一尺寸再处理。

long CvResize(src_file,width,height,dst_file)
参数 类型 描述
src_file string 源图片路径
width int 输出宽度
height int 输出高度
dst_file string 输出图片路径

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvResize("src.png",200,120,"resize.png")

CvThreshold

对图片进行阈值化处理

适用于前景和背景有明显明暗差异的场景,例如黑白文字、浅色按钮文字、图标轮廓。otsu 适合自动选择阈值,adaptive 适合光照不均的图片,binary_invotsu_inv 适合前景比背景更暗的图片。

long CvThreshold(src_file,dst_file,threshold,max_value,mode)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径
threshold double 阈值
max_value double 最大值
mode string 模式:binarybinary_invotsuotsu_invadaptiveadaptive_inv

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvThreshold("src.png","binary.png",128,255,"binary")

CvInRange

按颜色范围过滤图片

适用于目标颜色稳定的场景,例如血条颜色、固定 UI 高亮色、地图标记、技能冷却遮罩。输出通常是二值掩码,后续常配合 CvMorphology 去噪,再用 CvConnectedComponents 找目标区域。

long CvInRange(src_file,dst_file,color_space,lower,upper)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径
color_space string 颜色空间:bgrhsvgray
lower string 下限,格式如"0,0,250",也支持竖线分隔
upper string 上限,格式如"5,5,255",也支持竖线分隔

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvInRange("src.png","range.png","bgr","0,0,250","5,5,255")

CvMorphology

对图片进行形态学处理

适用于二值图清理和形状修复。erode 可收缩白色区域、去掉细小噪点;dilate 可扩张白色区域、连接断裂目标;open 先腐蚀后膨胀,常用于去除小白点;close 先膨胀后腐蚀,常用于填补小孔或连接细缝。

long CvMorphology(src_file,dst_file,mode,kernel_size,iterations)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径
mode string 模式:erodedilateopenclose
kernel_size int 核大小
iterations int 迭代次数

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvMorphology("range.png","morph.png","open",3,1)

CvThin

对图片进行细化/骨架化处理

适用于把较粗的二值线条压缩成单像素骨架,例如线条地图、路径、笔画结构分析。它通常在二值化和形态学清理之后使用,不适合直接处理复杂彩色原图。

long CvThin(src_file,dst_file,mode)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径
mode string 模式:zhang_suenguo_hallmorph

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvThin("morph.png","thin.png","zhang_suen")

CvToBinary

自动二值化图片

适用于快速把图片转换成黑白图,常用于文字、图标、简单 UI 元素的前景提取。它内部会自动处理阈值,适合先快速看效果;如果需要精确控制阈值或反色,请使用 CvThreshold

long CvToBinary(src_file,dst_file)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvToBinary("src.png","binary.png")

CvToEdge

提取图片边缘

适用于关注物体边界而不是颜色填充的场景,例如边框按钮、图标轮廓、形状匹配前处理。边缘结果通常会比原图更少受颜色变化影响,但对噪点也更敏感,必要时先用 CvDenoiseCvBlur

long CvToEdge(src_file,dst_file)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvToEdge("src.png","edge.png")

CvToOutline

提取图片轮廓线

适用于从二值或高对比图中抽取外轮廓,例如检测目标外框、道具形状、连通区域边界。它更偏向轮廓表达,常用于后续 CvFindContours 或人工检查预处理效果。

long CvToOutline(src_file,dst_file)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvToOutline("src.png","outline.png")

CvDenoise

对图片进行去噪处理

适用于截图中有压缩噪声、模拟器渲染毛边、背景纹理干扰的场景。去噪可以提高二值化和模板匹配稳定性,但过强的去噪可能抹掉细小文字或细线,建议先保存输出图检查。

long CvDenoise(src_file,dst_file)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvDenoise("src.png","denoise.png")

CvCropValid

裁剪图片中的有效内容区域

适用于去掉二值图或透明边界中的空白区域,例如从大图中提取实际图标、文字笔画、轮廓主体。常用于保存模板、生成字库条目或统一后续分析区域。

long CvCropValid(src_file,dst_file)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvCropValid("src.png","valid.png")

CvEqualize

对图片进行直方图均衡

适用于整体偏暗、偏亮或对比度不足的灰度图片。它会增强全局对比度,让暗处细节更明显,适合光照整体变化的截图;如果局部区域明暗差异很大,优先考虑 CvCLAHE

long CvEqualize(src_file,dst_file)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvEqualize("src.png","equalize.png")

CvCLAHE

使用 CLAHE 对图片进行局部对比度增强

适用于局部光照不均、某些区域过暗或过亮的图片。相比 CvEqualize,CLAHE 更强调局部对比度,并通过 clip_limit 限制过度增强,适合 OCR 前处理、低对比图标和复杂背景中的边缘增强。

long CvCLAHE(src_file,dst_file,clip_limit,tile_grid_size)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径
clip_limit double 对比度限制
tile_grid_size int 网格大小

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvCLAHE("src.png","clahe.png",2.0,8)

CvBlur

对图片进行模糊处理

适用于平滑噪声、弱化纹理背景,常作为阈值化或边缘检测前的准备步骤。gaussian 通用性较好,median 更适合椒盐噪声,bilateral 能尽量保留边缘但速度较慢,box 简单快速。

long CvBlur(src_file,dst_file,mode,kernel_size)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径
mode string 模式:gaussianmedianbilateralbox
kernel_size int 核大小

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvBlur("src.png","blur.png","gaussian",3)

CvSharpen

对图片进行锐化处理

适用于图标边缘发糊、缩放后细节不清、文字边缘不明显的场景。锐化能增强边缘和局部对比,但也可能放大噪声,通常建议在轻微去噪后使用,并控制 strength 不要过大。

long CvSharpen(src_file,dst_file,strength)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径
strength double 锐化强度

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvSharpen("src.png","sharpen.png",1.0)

CvConnectedComponents

分析图片中的连通区域

适用于从二值图中获取一个个独立目标区域,例如色块、文字块、图标亮点、地图标记。返回的矩形和面积可以用于筛选候选目标,也可以作为下一步截图、OCR、模板匹配的 ROI。

long CvConnectedComponents(src_file,min_area,retjson)
参数 类型 描述
src_file string 源图片路径
min_area double 最小面积,小于该面积的区域会被忽略
retjson string* 变参指针: 返回连通区域结果 JSON

返回值

类型:int

  • 0:失败
  • 1:成功

示例

ret = op.CvConnectedComponents("binary.png",10,&retjson)

CvFindContours

分析图片中的轮廓

适用于需要边界形状信息的场景,例如判断矩形框、圆形按钮、物体外形,或把二值图中的目标边界取出来做形状筛选。相比连通域,它会返回轮廓周长和点数量,更适合形状相关判断。

long CvFindContours(src_file,min_area,retjson)
参数 类型 描述
src_file string 源图片路径
min_area double 最小面积,小于该面积的轮廓会被忽略
retjson string* 变参指针: 返回轮廓结果 JSON

返回值

类型:int

  • 0:失败
  • 1:成功

示例

ret = op.CvFindContours("binary.png",10,&retjson)

CvPreprocessPipeline

按顺序执行 OpenCV 预处理流水线

适用于把多个预处理步骤合成一次调用,减少中间文件和脚本逻辑。建议先逐个接口调试并保存中间图片,确认每一步效果后,再把步骤串成 pipeline。

long CvPreprocessPipeline(src_file,dst_file,pipeline)
参数 类型 描述
src_file string 源图片路径
dst_file string 输出图片路径
pipeline string 流水线,步骤用竖线分隔,参数用 :,

支持的步骤包括:graybinaryedgeoutlinedenoiseequalizecropvalidclaheblursharpenthresholdinrangemorphthinresize

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.CvPreprocessPipeline("src.png","out.png","inrange:bgr,0,0,250,5,5,255|morph:open,3,1|thin:zhang_suen")

Clone this wiki locally