测试质量保障计算机视觉【免费下载链接】AirtestUI Automation Framework for Games and Apps项目地址https://gitcode.com/gh_mirrors/ai/Airtest点击查看免费下载本文以 airtest.aircv.keypoint_matching_contrib 模块为骨架深入讲解 Airtest 中依赖 opencv-contrib 扩展模块实现的三种特征点匹配算法BRIEF、SIFT、SURF的设计思路、类结构、核心参数与调用方式并结合 源码、基类实现 与 测试用例 给出可在实际 UI 自动化脚本中直接落地的配置与调优方案。读完本文你将理解 SIFT/SURF/BRIEF 各自适用场景掌握如何通过CVSTRATEGY让 Airtest 在截图匹配时优先使用 contrib 特征点匹配以及如何在缺少 contrib 模块时优雅降级。一、模块定位Airtest 特征点匹配的“扩展引擎”Airtest 的图像识别airtest.core.cv中的Template匹配流程支持多种匹配策略模板匹配tpl、mstpl、gmstpl与特征点匹配。特征点匹配按是否依赖 opencv-contrib 分为两组分组模块匹配类依赖主仓库内置keypoint_matching.pyKAZEMatching、BRISKMatching、AKAZEMatching、ORBMatching仅需标准 opencvcontrib 扩展keypoint_matching_contrib.pyBRIEFMatching、SIFTMatching、SURFMatching需要 opencv-contribkeypoint_matching_contrib.py的模块 docstring 明确指出Detect keypoints with BRIEF/SIFT/SURF. Need opencv-contrib module.也就是说该模块是 Airtest 特征点匹配家族中能力更强、但对运行环境要求更高的部分三种算法中只有 SIFT 在较新的 OpenCV 主仓库中可以直接使用BRIEF 与 SURF 始终需要编译/安装 contrib 扩展。从 airtest/core/cv.py 的 MATCHING_METHODS 注册表 可以看到这三个类与内置特征点方法一同注册进了 Airtest 的统一匹配策略MATCHING_METHODS { tpl: TemplateMatching, mstpl: MultiScaleTemplateMatchingPre, gmstpl: MultiScaleTemplateMatching, kaze: KAZEMatching, brisk: BRISKMatching, akaze: AKAZEMatching, orb: ORBMatching, sift: SIFTMatching, surf: SURFMatching, brief: BRIEFMatching, }因此在ST.CVSTRATEGY中填入sift、surf、brief即可让 Airtest 在实际截图查找时调用本模块的匹配类。需要特别注意的是如果运行环境的 OpenCV 没有 contrib 模块Template._try_match会捕获 aircv.NoModuleError 并打印警告后返回None随后 Airtest 会继续尝试策略列表中的下一个方法而不会中断脚本# airtest/core/cv.py 中 _try_match 的关键逻辑 except aircv.NoModuleError as err: G.LOGGING.warning(surf/sift/brief is in opencv-contrib module. You can use tpl/kaze/brisk/akaze/orb in CVSTRATEGY, or reinstall opencv with the contrib module.) return None二、版本兼容设计check_cv_version_is_new与检测器初始化策略模块顶部定义了一个关键函数用于区分 OpenCV 2.x 与 OpenCV 3/4.x 时代完全不同的 API 接口def check_cv_version_is_new(): opencv版本是3.0或4.0以上, API接口与2.0的不同. if cv2.__version__.startswith(3.) or cv2.__version__.startswith(4.): return True else: return False该函数是模块内所有类初始化检测器时的“分叉点”OpenCV 2.x采用cv2.FeatureDetector_create/cv2.DescriptorExtractor_create这类遗留工厂函数OpenCV 3/4.x改用cv2.xfeatures2d.*_create这一新的工厂 APISIFT 在特定版本后进入主仓库见下文。这一设计保证了 Airtest 在不同 OpenCV 大版本下都能尝试构建匹配器同时用异常兜底的方式向用户报告“缺少 contrib 模块”这一明确诊断信息。从 docs/locale 的中文翻译对照 也可以看到官方文档对基类相关方法init_detector、show_match_image等均有完整的 i18n 覆盖说明这套特征点匹配 API 是 Airtest 对外稳定文档化的一部分。三、类结构三个匹配类如何继承统一的基类流水线BRIEFMatching、SIFTMatching、SURFMatching均继承自 airtest/aircv/keypoint_base.py 中的KeypointMatching基类并只重写三个钩子方法钩子方法职责contrib 各子类实现METHOD_NAME日志中显示的方法名BRIEF/SIFT/SURFinit_detector()创建检测器与匹配器各自创建 STARBRIEF、SIFT、SURF 检测器get_keypoints_and_descriptors(image)提取关键点与描述子分别调用detectcompute或detectAndComputematch_keypoints(des_sch, des_src)对描述子做匹配统一使用knnMatch(..., k2)而完整的“识别 → 结果计算”流水线全部沉淀在基类find_best_result()中keypoint_base.py图像合法性校验调用check_image_valid图像无效直接返回None特征点提取与初筛_get_key_points()调用上述钩子方法得到匹配对再用FILTER_RATIO默认0.59建议 0.4–0.6过滤掉“最近邻与次近邻距离过近”的非独特点并去重保证“源图像一点不能映射搜索图像多点”按匹配对数分支计算目标区域0/1对 → 无法定位返回None2对 →_handle_two_good_points用两对点推算中心点与缩放比例3对 →_handle_three_good_points取两点中点合并为两对点处理4对 →_many_good_pts使用cv2.findHomographyRANSAC距离阈值 5.0计算单应矩阵再将搜索图四角映射到大图中得到目标区域合理性校验_target_error_check要求识别区域宽高不小于 5 像素、且与搜索图尺寸的缩放倍率在 0.2–5 倍之间否则视为识别失败置信度计算截取目标区域缩放至与搜索图同尺寸调用_cal_confidence计算相似度confidence threshold才返回结果。最终返回的结果由 utils.generate_result 封装为字典包含result中心点坐标、rectangle四角点与confidence三个字段。基类还提供show_match_image()keypoint_base.py用于把搜索图与源图拼接并用随机颜色线条可视化特征点匹配关系方便调试。四、BRIEFMatchingSTAR 检测器 BRIEF 描述子BRIEFMatching是三个类中唯一使用“检测器 描述子”分离流程的类其METHOD_NAME BRIEFkeypoint_matching_contrib.py。检测器初始化init_detectorif check_cv_version_is_new(): # OpenCV3/4, star/brief is in contrib module, you need to compile it seperately. try: self.star_detector cv2.xfeatures2d.StarDetector_create() self.brief_extractor cv2.xfeatures2d.BriefDescriptorExtractor_create() except: import traceback traceback.print_exc() print(to use %s, you should build contrib with opencv3.0 % self.METHOD_NAME) raise NoModuleError(There is no %s module in your OpenCV environment ! % self.METHOD_NAME) else: # OpenCV2.x self.star_detector cv2.FeatureDetector_create(STAR) self.brief_extractor cv2.DescriptorExtractor_create(BRIEF) # create BFMatcher object: self.matcher cv2.BFMatcher(cv2.NORM_L1) # cv2.NORM_L1 cv2.NORM_L2 cv2.NORM_HAMMING(not useable)关键点解读为什么是 STAR 而不是 ORB/FASTBRIEF 本身只是描述子需要搭配一个快速检测器。模块注释明确建议 “recommand CenSurE as a fast detector”即 CenSurESTAR检测器——它在保持速度的同时对尺度变化有一定鲁棒性适合游戏/应用截图中常见的缩放场景匹配距离度量BRIEF 描述子本质是二进制串按理应使用汉明距离NORM_HAMMING但源码注释标注NORM_HAMMING(not useable)实际使用BFMatcher(cv2.NORM_L1)。这与基类 KAZE 的默认配置一致属于 Airtest 在工程实践中的经验选择读者在二次开发时不宜直接照搬教科书配置而应以实测为准失败模式在 OpenCV 3/4 下若未安装 contribxfeatures2d不存在会抛出NoModuleError并打印提示“你应该使用 opencv3.0 构建 contrib”。特征点提取get_keypoints_and_descriptors将两个步骤分开执行# find the keypoints with STAR kp self.star_detector.detect(image, None) # compute the descriptors with BRIEF keypoints, descriptors self.brief_extractor.compute(image, kp) return keypoints, descriptors匹配match_keypoints调用self.matcher.knnMatch(des_sch, des_src, k2)k2 表示每个特征点取最匹配的两个候选供基类用FILTER_RATIO做比值筛选。适用性判断测试用例中对该方法的评价是“识别特征点少只适合强特征图像的匹配”tests/test_aircv.py即 BRIEF 适合纹理清晰、特征显著的截图如图标、按钮上的高对比图形而对弱纹理界面效果有限。五、SIFTMatching最稳定但最慢的选择SIFTMatching的METHOD_NAME SIFT并声明了 FLANN 匹配所需的索引参数keypoint_matching_contrib.py# SIFT识别特征点匹配参数设置: FLANN_INDEX_KDTREE 0 def init_detector(self): if check_cv_version_is_new(): try: # opencv3 3.4.12 or opencv4 4.5.0, sift is in main repository self.detector cv2.SIFT_create(edgeThreshold10) except AttributeError: try: self.detector cv2.xfeatures2d.SIFT_create(edgeThreshold10) except: raise NoModuleError( There is no %s module in your OpenCV environment, need contrib module! % self.METHOD_NAME) else: # OpenCV2.x self.detector cv2.SIFT(edgeThreshold10) # create FlnnMatcher object: self.matcher cv2.FlannBasedMatcher({algorithm: self.FLANN_INDEX_KDTREE, trees: 5}, dict(checks50))值得注意的工程细节版本分叉最精细的一个类源码注释明确写明了 SIFT 的“转正”时间线——OpenCV 主仓库从3.4.12与4.5.0起内置 SIFT此前的版本需要从cv2.xfeatures2d获取而 OpenCV 2.x 时代则直接使用cv2.SIFTedgeThreshold10降低边缘响应阈值减少在图像边缘产生的伪关键点这是针对 UI 截图中大量直线/边框元素的经验调参FLANN 快速近似匹配SIFT 描述子是 128 维浮点向量点集规模大时暴力匹配BFMatcher开销高因此这里使用FlannBasedMatcher索引为KDTreealgorithm0trees5搜索时执行checks50次校验在速度与召回之间取得平衡特征提取与匹配一体化get_keypoints_and_descriptors直接调用detector.detectAndCompute(image, None)一步得到关键点与描述子。测试用例对 SIFT 的评价是“慢最稳定”tests/test_aircv.py。在 test_aircv.py 的类注释 中还有一组来自开发者的经验排序可作为算法选型的参考注意这是仓库注释中的工程经验非官方性能承诺内存消耗kaze (2GB) sift akaze surf brisk brief orb tpl单纯效果推荐tpl surf ≈ sift kaze brisk akaze brief orb有限内存下的推荐tpl surf sift brisk akaze brief orb kaze六、SURFMatching速度快、效果不错的 contrib 方案SURFMatching的METHOD_NAME SURF并提供了两个可调类属性keypoint_matching_contrib.py# 是否检测方向不变性:0检测/1不检测 UPRIGHT 0 # SURF算子的Hessian Threshold HESSIAN_THRESHOLD 400 # SURF识别特征点匹配方法设置: FLANN_INDEX_KDTREE 0 def init_detector(self): if check_cv_version_is_new(): # OpenCV3/4, surf is in contrib module, you need to compile it seperately. try: self.detector cv2.xfeatures2d.SURF_create(self.HESSIAN_THRESHOLD, uprightself.UPRIGHT) except: raise NoModuleError(There is no %s module in your OpenCV environment, need contribmodule! % self.METHOD_NAME) else: # OpenCV2.x self.detector cv2.SURF(self.HESSIAN_THRESHOLD, uprightself.UPRIGHT) # create FlnnMatcher object: self.matcher cv2.FlannBasedMatcher({algorithm: self.FLANN_INDEX_KDTREE, trees: 5}, dict(checks50))参数含义HESSIAN_THRESHOLD 400Hessian 响应阈值只有大于该阈值的斑点blob才会被保留为关键点。阈值越大关键点越少、越快但可能漏检在纹理丰富的游戏截图中可适当调低如 300换取更多特征点在弱纹理界面可调高以过滤噪声点UPRIGHT 0upright0表示检测方向不变性SURF 会为每个关键点计算主方向从而对旋转鲁棒若 UI 元素从不旋转可改为1显著提速匹配器与 SIFT 完全一致FlannBasedMatcher(KDTree, trees5, checks50)因为 SURF 与 SIFT 一样产生浮点描述子依赖限制SURF 在 OpenCV 3/4 下始终位于 contrib 的xfeatures2d中且目前没有进入主仓库的计划因此只要使用新版 OpenCVSURF 就必然需要安装 opencv-contrib。测试用例的评价是“快效果不错”tests/test_aircv.py。七、调用方式直接实例化与通过 CVSTRATEGY 集成方式一脚本内直接调用匹配类在 Airtest 脚本中可以直接用与测试用例相同的方式实例化匹配类并获取结果from airtest.aircv import imread from airtest.aircv.keypoint_matching_contrib import SIFTMatching, SURFMatching, BRIEFMatching # 读取搜索图小图/模板与源图大图/截图 search imread(template.png) screen imread(screen.png) # 返回 dict: {result: (x, y), rectangle: [...], confidence: 0.xxx} result SIFTMatching(search, screen, threshold0.7, rgbTrue).find_best_result() if result: print(result[result], result[confidence])构造参数与基类一致keypoint_base.py参数类型含义默认/建议im_searchnumpy 数组待查找的小图特征点源必填im_sourcenumpy 数组被查找的大图/截图必填thresholdfloat置信度阈值匹配成功需confidence threshold0.7全局默认见 settings.pyrgbboolTrue用 RGB/HSV 三通道加权置信度False用灰度 CCOEFF按场景选择置信度计算逻辑在基类_cal_confidencekeypoint_base.pyrgbTrue时走 cal_rgb_confidence三通道分别做TM_CCOEFF_NORMED后取最小值并转 HSV 强化颜色差异rgbFalse时走 cal_ccoeff_confidence灰度相关系数最终置信度经(1 confidence) / 2归一到[0, 1]区间。方式二通过ST.CVSTRATEGY接入 Airtest 统一查找流程在日常 UI 自动化中更常见的用法是把sift/surf/brief加入 airtest/core/settings.py 的 CVSTRATEGYfrom airtest.core.api import * from airtest.core.settings import Settings as ST ST.CVSTRATEGY [sift, tpl, brisk] # 优先 SIFT 特征点匹配 ST.THRESHOLD 0.7 # 全局置信度阈值 [0, 1] # 之后 touch/wait/exists 等 API 的截图匹配会自动按策略顺序尝试 touch(Template(some_icon.png))Airtest 默认策略是[mstpl, tpl, sift, brisk]但 settings.py 有一段版本自适应逻辑当 OpenCV 版本处于(3.4.2, 4.4.0)区间时自动降级为[mstpl, tpl, brisk]此区间 SIFT 仍滞留 contrib避免每次匹配都抛出NoModuleError。这也从侧面说明想让 SIFT 直接可用建议使用 OpenCV 3.4.12 或 4.5.0并确保环境中确实装有 contrib 模块SURF/BRIEF 则任何新版本都依赖 contrib。Template._cv_matchairtest/core/cv.py会按CVSTRATEGY顺序逐个调用注册表里的匹配类命中即返回若某个 contrib 方法抛出NoModuleError会打印警告并继续尝试下一个方法不会导致脚本崩溃。此外如果录制时记录了record_pos与resolutioncv.py 中的_find_keypoint_result_in_predict_area还支持先在预测区域内做特征点匹配对应设置项KEYPOINT_MATCHING_PREDICTION True以缩小搜索范围、提升匹配速度与准确率。八、环境准备与故障排查安装 opencv-contribSURF 与 BRIEF以及旧版本的 SIFT都位于 contrib 模块需要单独安装。以 pip 为例pip install opencv-contrib-python注意opencv-contrib-python与opencv-python不能共存于同一环境安装 contrib 版本前应先卸载标准版本否则会因同名.so文件冲突导致导入失败。这是 OpenCV 官方分发包的已知约束。常见异常对照现象原因处理NoModuleError: There is no SIFT module in your OpenCV environment, need contrib module!使用的 OpenCV 版本 3.4.12 / 4.5.0 且未装 contrib升级 OpenCV 或安装 contribNoModuleError: There is no SURF module in your OpenCV environment, need contribmodule!任何新版 OpenCV 下未装 contribSURF 始终在 contrib安装opencv-contrib-python匹配结果始终为None特征点不足 / 置信度低于 threshold调低阈值、检查图片是否过于模糊或弱纹理、换用 SIFTNoMatchPointError: Not enough feature points in input images !小图或大图中检测到的关键点 2换用特征更丰富的图片或换算法error.pyMatchResultCheckError识别区域小于 5 像素或缩放超出 0.2–5 倍该区域视为无效匹配可换用tpl等策略keypoint_base.py结合测试用例验证仓库的 tests/test_aircv.py 提供了三个 contrib 匹配类的直接回归用例测试素材位于 tests/matching_images/keypoint_search.png为小图、keypoint_screen.png为 1080x1920 大图。可以直接运行python -m pytest tests/test_aircv.py -k contrib -v来验证当前环境是否具备运行 contrib 特征点匹配的条件。测试断言匹配结果均为dict即成功定位到了目标区域是排查环境与参数问题的第一手参照。九、选型建议小结方法速度稳定性环境要求推荐场景SIFT慢最稳定OpenCV 3.4.12 / 4.5.0 内置更早版本需 contrib复杂界面、旋转/缩放变化大的元素追求高准确率SURF快效果不错始终需要 contrib特征丰富的游戏界面兼顾速度与效果可调HESSIAN_THRESHOLDBRIEF快特征点少始终需要 contrib强特征、高对比度图形图标、按钮弱纹理界面慎用综合仓库注释与测试用例的经验效果与稳定性上SIFT/SURF优于BRIEF内存敏感环境下优先SURF而非KAZE若环境无法安装 contrib则应回退到 keypoint_matching.py 中的内置 KAZE/BRISK/AKAZE/ORB或直接使用模板匹配tpl。这些经验数据均来自 tests/test_aircv.py 的注释在实际项目中请以自身设备与素材的实测结果为准。赞分享测试质量保障计算机视觉【免费下载链接】AirtestUI Automation Framework for Games and Apps项目地址https://gitcode.com/gh_mirrors/ai/Airtest点击查看免费下载相关推荐Airtest aircv SIFT 图像识别模块解析特征点匹配、置信度计算与实战使用指南Airtest aircv SIFT 图像识别模块解析特征点匹配、置信度计算与实战使用指南 导读 airtest.aircv.sift 是 Airtest 开测试质量保障计算机视觉Airtest 特征点匹配基类 KeypointMatching 深度解析KAZE 识别框架与源码级原理Airtest 特征点匹配基类 KeypointMatching 深度解析KAZE 识别框架与源码级原理 导读 本文围绕 Airtest 图像识别体系中的特征测试质量保障计算机视觉Airtest 图像识别算法性能基准测试指南特征点匹配方法对比与 benchmark 工具实战Airtest 图像识别算法性能基准测试指南特征点匹配方法对比与 benchmark 工具实战 本文以 benchmark/README.md https:/测试质量保障计算机视觉创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考