测试质量保障计算机视觉【免费下载链接】AirtestUI Automation Framework for Games and Apps项目地址https://gitcode.com/gh_mirrors/ai/Airtest点击查看免费下载本文导读Airtest 是面向游戏与应用的 UI 自动化测试框架图像识别是其核心能力之一而airtest/aircv/template.py正是整套图像识别链路的入口模块。本文将围绕该模块的两个公开函数find_template/find_all_template结合aircv包内的工具函数、置信度算法、上层Template类与测试用例完整讲解模板匹配的参数语义、执行流程、返回结果格式与调参实践。读完本文你将掌握如何在 Airtest 中直接调用底层模板匹配 API理解threshold与rgb两个参数的真实作用并能根据源码判断不同场景下的参数选择。模块定位aircv.template 在 Airtest 中的作用docs/all_module/airtest.aircv.template.rst是 Airtest 文档体系中针对airtest/aircv/template.py模块的 API 说明页Sphinxautomodule自动生成其内容主体即该模块的完整源码。模块位于 airtest/aircv/template.py并在 airtest/aircv/init.py 中被显式导出from .template import find_template, find_all_template # noqa因此aircv.template是 Airtest 图像识别体系中模板匹配Template Matching这一基础算法的公开入口。模块 docstring 直接定义了用户可调节的两个核心参数对用户提供的调节参数threshold: 筛选阈值默认为 0.8rgb: 彩色三通道进行彩色权识别模板匹配的原理是在屏幕截图im_source中滑动搜索预先准备好的小图im_search找出相似度最高或所有超过阈值的区域。它是 Airtest 中touch、swipe、wait、exists等 API 的识别底座——上层 airtest/core/cv.py 中MATCHING_METHODS字典的tpl项即指向模板匹配实现类且ST.CVSTRATEGY默认策略一般将tpl放在首位。核心 API 一find_template —— 找到最优匹配区域函数签名与文档一致airtest/aircv/template.pydef find_template(im_source, im_search, threshold0.8, rgbFalse):参数说明参数类型默认值含义im_sourcenumpy 数组cv2 图像无屏幕截图即大图作为搜索空间im_searchnumpy 数组cv2 图像无待查找的目标小图即模板thresholdfloat0.8筛选阈值识别结果的置信度confidence低于该值则判定为未找到返回NonergbboolFalse是否启用彩色三通道校验为True时对候选区域做 BGR 三通道加权识别为False时直接采用灰度匹配的相关系数需要注意im_source/im_search必须是 numpy 矩阵格式的图像通常通过airtest.aircv.imread(filename)读取airtest/aircv/aircv.py。该函数支持中文路径因为 Python 3 下使用cv2.imdecode(np.fromfile(...))而非直接cv2.imread。内部执行流程四步find_template的源码把整个匹配过程拆成了清晰的四步每步都有独立私有函数支撑校验图像输入调用check_source_larger_than_search(im_source, im_search)airtest/aircv/utils.py检查模板图是否比截图更大若im_search的高或宽超过im_source会抛出TemplateInputError(error: in template match, found im_search bigger than im_source.)异常类定义见 airtest/aircv/error.py。这保证了匹配的物理可行性。计算匹配结果矩阵调用_get_template_result_matrix()airtest/aircv/template.py。由于cv2.matchTemplate只能处理灰度图这里先把两张图通过img_mat_rgb_2_grayairtest/aircv/utils.py内部即cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)转为灰度然后执行res cv2.matchTemplate(i_gray, s_gray, cv2.TM_CCOEFF_NORMED)即使用归一化相关系数法TM_CCOEFF_NORMED在截图矩阵上滑动模板生成一张相似度热度图res其取值范围理论上落在 [-1, 1] 之间。取出最优位置并计算置信度通过cv2.minMaxLoc(res)拿到结果矩阵中的最大值max_val及其位置max_loc即模板左上角在截图中的坐标。随后由_get_confidence_from_matrixairtest/aircv/template.py计算最终置信度rgbFalse时confidence max_val直接使用灰度匹配的相关系数rgbTrue时从截图中裁出候选区域img_crop im_source[max_loc[1]:max_loc[1]h, max_loc[0]:max_loc[0]w]调用cal_rgb_confidence(img_crop, im_search)做三通道彩色校验详见下文。计算目标矩形与中心点生成标准结果_get_target_rectangle(max_loc, w, h)airtest/aircv/template.py以匹配到的左上角为基准加上模板宽高w, h得到中心点middle_point与四角点序列rectangle顺序为左上→左下→右下→右上再交给generate_result封装。最后执行return best_match if confidence threshold else None即低于阈值一律视为未找到。返回结果格式generate_resultairtest/aircv/utils.py统一了所有 aircv 识别结果的字典格式ret dict(resultmiddle_point, # 中心点坐标 (x, y)供点击使用 rectanglepypts, # 四个角点顺序为 左上-左下-右下-右上 confidenceconfi) # 置信度 float上层 airtest/core/cv.py 的match_in正是利用result字段通过TargetPos换算实际点击焦点而rectangle可用于画框、断言或日志展示。核心 API 二find_all_template —— 找出所有匹配区域当同一张截图里出现多个相同目标例如一屏多个领取按钮时使用find_all_templateairtest/aircv/template.pydef find_all_template(im_source, im_search, threshold0.8, rgbFalse, max_count10):相比find_template多了max_count参数默认10用于限制最多返回的匹配数量。其流程如下同样先做输入校验与结果矩阵计算进入while True循环每轮用cv2.minMaxLoc(res)取出当前矩阵中的最优值计算置信度若confidence threshold或len(result) max_count则终止循环记录本轮结果后用cv2.rectangle(res, ..., (0,0,0), -1)把已匹配区域在结果矩阵中涂黑屏蔽进入下一轮继续寻找次优匹配源码中注释掉的cv2.floodFill是另一种候选屏蔽方案最终选用矩形屏蔽矩形范围即模板在截图中的覆盖区域返回结果列表若没有任何匹配结果列表为空则返回None。result [] # 每个元素都是 {result: 中心点, rectangle: 四角点, confidence: 置信度}注意循环中有一个细节len(result) max_count是在confidence threshold之后才判断实际最多可能返回max_count 1个结果编写上层逻辑时如对数量有严格要求应自行裁剪。置信度计算的两个分支灰度相关系数与 RGB 三通道校验_get_confidence_from_matrix揭示了rgb参数的本质——它决定置信度的计算口径灰度模式rgbFalse直接信任cv2.matchTemplate的TM_CCOEFF_NORMED结果。速度快但只比较亮度结构颜色相同的不同物体可能互相误判。彩色模式rgbTrue对候选区域逐通道校验。其实现位于 airtest/aircv/cal_confidence.py 的cal_rgb_confidencenp.clip(img, 10, 245)将像素值裁剪到 [10, 245]减少极限值纯黑/纯白对后续角度计算的影响cv2.cvtColor(..., COLOR_BGR2HSV)将两图转到 HSV 色彩空间强化颜色的区分度cv2.copyMakeBorder(..., 10, 10, 10, 10, BORDER_REPLICATE)扩展置信度计算区域并故意把边界两像素置为 0 和 255加入取值范围干扰防止算法过于放大微小差异cv2.split拆分三个通道对每个通道单独跑cv2.matchTemplate(..., TM_CCOEFF_NORMED)得到三个相关系数最终return min(bgr_confidence)—— 取三通道中最小的那个作为整体置信度。取三通道最小值意味着只要任何一个颜色通道匹配度不达标整体置信度就会被拉低因此rgbTrue时对颜色变化的敏感度显著更高适合背景复杂、同类形状不同颜色的场景例如区分红色和绿色的相同按钮。代价是额外的裁图、HSV 转换和三轮匹配计算。工程封装对照函数式 API 与 TemplateMatching 类airtest/aircv/template.py提供的是函数式 API而框架内部实际运行的是 airtest/aircv/template_matching.py 中的TemplateMatching类两者算法流程完全同构函数式template.py类封装template_matching.pyfind_template(im_source, im_search, threshold, rgb)TemplateMatching(im_search, im_source, threshold, rgb).find_best_result()find_all_template(im_source, im_search, threshold, rgb, max_count)TemplateMatching(...).find_all_results()_get_template_result_matrix同名方法_get_template_result_matrix_get_confidence_from_matrix同名方法_get_confidence_from_matrix两类实现共享同样的工具函数generate_result、check_source_larger_than_search、img_mat_rgb_2_gray与置信度算法cal_rgb_confidence。类版本额外增加了print_run_time装饰器airtest/aircv/utils.py记录耗时并把最大结果数固化在类常量MAX_RESULT_COUNT 10。值得注意的一点差异函数式版本rgb默认False而类版本默认rgbTrue直接使用时应留意这个默认值区别。在上层 API 中的完整调用链Template 类与 CVSTRATEGYaircv.template的匹配函数并非孤立存在它们通过 airtest/core/cv.py 接入 Airtest 的touch/wait/exists等脚本 API用户在脚本中写touch(Template(tpl.png))即创建Template对象airtest/core/cv.py。其构造函数暴露了threshold、rgb、scale_max、scale_step、target_pos、record_pos、resolution等参数其中threshold缺省时取全局ST.THRESHOLD见 airtest/core/settings.py。匹配时Template._cv_match按ST.CVSTRATEGY配置的方法顺序逐个尝试tpl映射到TemplateMatching调用其find_best_result()airtest/core/cv.py。sift/surf/brief等方法若因缺少 opencv-contrib 模块而失败会被_try_match捕获并降级不影响后续方法。loop_findairtest/core/cv.py则驱动截图→匹配→超时重试的循环每次循环调用G.DEVICE.snapshot()获取im_source调用query.match_in(screen)timeout内找不到就抛出TargetNotFoundError。注意loop_find中threshold的传递方式只有传入非空threshold时才会覆盖query.threshold否则沿用 Template 对象自身配置。另外Template对象在record_pos/resolution存在时可借助Predictorairtest/core/cv.py预测目标在屏幕上的大致区域用于关键点类匹配的剪裁加速。对于普通脚本用户而言这意味着aircv.template的两个threshold、rgb参数与Template/ST.CVSTRATEGY完全贯通Template(x.png, threshold0.9, rgbTrue)最终就会以rgbTrue走cal_rgb_confidence彩色校验路径。测试验证模板匹配的正确性由单测保障aircv.template的匹配行为有对应单元测试覆盖见 tests/test_aircv.pydef test_func_find_template(self): Test find_template function in template.py. result find_template(self.template_src, self.template_sch, thresholdself.THRESHOLD, rgbself.RGB) self.assertIsInstance(result, dict) def test_func_find_all_template(self): Test find_all_template function in template.py. result find_all_template(self.template_src, self.template_sch, thresholdself.THRESHOLD, rgbself.RGB) self.assertIsInstance(result, list)测试类TestAircvtests/test_aircv.py设置的THRESHOLD 0.7、RGB True并加载 tests/matching_images/template_search.png模板与 tests/matching_images/template_screen.png整屏截图作为输入。同文件中test_find_template类封装版本tests/test_aircv.py还验证了TemplateMatching类路径。此外测试文件头部注释给出了各匹配算法的工程经验排序单纯效果推荐程度tpl surf ≈ sift ...从侧面印证模板匹配是 Airtest 中效果与资源占用最均衡的默认首选方案。如需复现可在仓库根目录执行python -m pytest tests/test_aircv.py或参考 runtest.sh前提是安装requirements.txt中的 opencv 依赖。调参实践threshold 与 rgb 的选取建议结合源码行为可以给出如下可验证的调参结论threshold默认 0.8confidence 低于此值即返回None/ 停止查找。由于TM_CCOEFF_NORMED是归一化相关系数0.8 是一个工程上较稳健的起点目标被遮挡、光照变化或缩放时相关系数会明显下降此时可适当下调如 0.6~0.7。测试中使用的0.7即为低阈值示例。rgb默认 False截图是彩色图时推荐开启rgbTrue它能借助三通道最小值校验显著降低形状相同、颜色不同的误报代价是每次匹配多出 HSV 转换与三通道匹配的开销。若目标区域颜色单一、背景干净或对性能敏感如高频循环查找保持rgbFalse即可。模板大小im_search尺寸必须小于im_source否则直接抛TemplateInputError且模板越小灰度相关性对噪声越敏感threshold可能需要相应放宽。多目标场景使用find_all_template时可通过max_count限制返回数量并结合rectangle四点坐标做后续去重与排序。小结airtest.aircv.template是 Airtest 图像识别体系中最基础、最常用的匹配算法模块find_template与find_all_template两个函数以threshold默认 0.8与rgb默认 False两个参数完整覆盖了单目标最优匹配与多目标遍历匹配两类需求。其灰度TM_CCOEFF_NORMED匹配 可选 RGB/HSV 三通道校验 标准result/rectangle/confidence返回格式的设计也被上层TemplateMatching类、Template对象与CVSTRATEGY策略链完整复用。理解本模块就相当于掌握了 Airtest 中所有基于图片定位 API 的底层运作机制。赞分享测试质量保障计算机视觉【免费下载链接】AirtestUI Automation Framework for Games and Apps项目地址https://gitcode.com/gh_mirrors/ai/Airtest点击查看免费下载创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
企业数字化 ERP 产品动态
相关推荐
GEF name-break 命令详解：为 GDB 断点命名，让 stripped 二进制调试不再“靠猜“ 网络安全开发工具 【免费下载链接】gef GEF (GDB Enhanced Features) - a modern experience for GDB with advanced debugging capabilities for exploit devs & reverse engineers on Linux 项目地址： https://gitcode.com/gh_mirrors/gef/gef 点击查看 免费下… · 2026/9/25 3:19:59
IronOS 开源焊台固件全解：设备支持矩阵、刷写流程与在机菜单系统的源码级剖析 嵌入式固件硬件开发智能硬件 【免费下载链接】IronOS Open Source Soldering Iron firmware 项目地址： https://gitcode.com/gh_mirrors/ir/IronOS 点击查看 免费下载 本文以 IronOS 项目的文档索引 Documentation/index.md 为主体，系统梳理这款"智… · 2026/9/25 3:19:59
我用 Codex 从零做出一个“子弹撞木块”动力学仿真项目：VS Code、客户端与完整工作流实录 /* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/9/25 3:19:59
MikroORM 在 Babel 与 SWC 转译环境下的装饰器元数据配置完整指南 后端 【免费下载链接】mikro-orm TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases. 项目地址： https://gitcode.com/gh_mir… · 2026/9/25 5:33:47
华为CE8800密码过期警告处理：机制、操作与排查实战 上周远程登一台 CE8850 做季度巡检，SSH 连上去之后，屏幕上除了正常的版本信息，还多了一行格外扎眼的提醒：Warning: The password will expire in 21 days. The password needs to be changed, Continue? [Y/N]:干网络这一行&… · 2026/9/25 5:33:41
Atlas 300V部署YOLO全记录：从ONNX到OM的推理迁移实战 前阵子在客户现场折腾了一周，核心任务就一句话：把一张Atlas 300V 24G运算加速卡塞进服务器，把原本跑在GPU上的YOLO检测服务迁过去，还要保证1080P视频能实时出结果。这卡名字看着像显卡，但实际是专为AI推理设计的加速卡… · 2026/9/25 5:33:41
xberg C FFI 实战：用 force_ocr 强制对每一页 PDF 执行 OCR 后端AI 应用NLP 【免费下载链接】xberg Polyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with … · 2026/9/25 5:33:41
创维E900V22D刷机全攻略：S905L3SB芯片兼容性解析与救砖实战 /* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/9/25 1:00:31
MQTT协议原理与Broker服务器搭建实战：从Mosquitto到EMQX /* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/9/25 1:00:37
