图像匹配检测节点

图像 · 使用文档

图像匹配检测节点

功能说明

增强版图像匹配检测 - 在检测图片中查找模板图片的位置，支持多种特征提取和智能过滤

核心功能

多源图片输入：支持Bitmap、URI、文件路径、文件夹多种图片输入方式
增强特征匹配：支持多种特征提取器融合，提高匹配准确度
智能坐标命名：基于图像特征自动生成有意义的坐标名称
高级过滤功能：支持JSON文件过滤、坐标数据过滤、特征相似度过滤
批量处理：支持多模板图片和多检测图片批量匹配

输入说明

模板图片输入（要查找的图片）

支持以下多种输入方式（按优先级处理）：

文件路径列表：逗号分隔的文件路径，如：/sdcard/template1.png,/sdcard/template2.png
文件夹路径：包含模板图片的文件夹路径
Bitmap对象：直接从其他节点获取的Bitmap
URI列表：内容URI列表

检测图片输入（要在其中查找的图片）

支持以下多种输入方式（按优先级处理）：

文件路径列表：逗号分隔的文件路径，如：/sdcard/test1.png,/sdcard/test2.png
文件夹路径：包含检测图片的文件夹路径
Bitmap对象：直接从其他节点获取的Bitmap
URI列表：内容URI列表

检测参数配置

基本检测参数

相似度阈值：0.0-1.0，值越高匹配越严格（默认：0.9）
最大匹配数：单张检测图片中最多返回的匹配数量（默认：10）
匹配方法：
- TM_CCOEFF_NORMED：相关系数归一化（推荐）
- TM_CCORR_NORMED：互相关归一化
- TM_SQDIFF_NORMED：平方差归一化

坐标名称相关配置

坐标名称查找方向：
- right：在匹配位置右侧查找特征
- left：在匹配位置左侧查找特征
- up：在匹配位置上方查找特征
- down：在匹配位置下方查找特征
- all：在所有方向查找特征（默认）

特征提取配置

使用图像特征：是否启用图像特征提取（默认：true）
增强特征匹配：是否启用多种特征融合模式（默认：true）
- 启用时：使用颜色直方图、颜色矩、LBP、梯度直方图、感知哈希等多种特征融合
- 禁用时：使用单一特征提取器
特征区域大小：
- 特征区域宽度：提取特征的区域宽度（像素，默认：100）
- 特征区域高度：提取特征的区域高度（像素，默认：100）
- 特征区域距离：特征区域与匹配点的距离（像素，默认：50）

单一特征提取器（当增强特征匹配禁用时）

特征提取器：
- COLOR_HISTOGRAM：颜色直方图
- COLOR_MOMENTS：颜色矩
- LBP：局部二值模式
- GRADIENT_HISTOGRAM：梯度直方图
- PHASH：感知哈希
特征编码：
- HEX：十六进制编码（默认）
- BASE64：Base64编码
- BINARY：二进制编码
- COMPACT：紧凑格式
特征精度：
- LOW：低精度（处理速度快）
- MEDIUM：中精度（推荐，默认）
- HIGH：高精度（最准确）
哈希算法：
- MD5：标准MD5哈希（默认）
- SHA256：SHA-256哈希
- PERCEPTUAL_HASH：感知哈希
- DCT_HASH：DCT哈希

过滤功能

过滤数据来源

坐标列表输入：JSON数组或坐标对象列表
JSON文件：包含坐标数据的JSON文件路径
JSON文件夹：包含多个JSON坐标文件的文件夹路径

过滤模式

排除模式：从匹配结果中移除与过滤数据相似的匹配（默认）
包含模式：只保留与过滤数据相似的匹配

过滤参数

图像特征相似度阈值：0.0-1.0，用于比较图像特征的相似度（默认：0.5）
- 当相似度高于此阈值时，视为相似坐标

输出接口

执行状态输出

执行输出 → 连接到下一个节点的执行输入
检测成功 → 布尔值，检测成功时为true
检测失败 → 布尔值，检测失败时为true

匹配结果输出

匹配坐标列表 → 所有匹配的坐标数据列表
- 每个匹配包含：中心坐标、相似度、坐标名称、边界框等
匹配数量 → 匹配到的坐标总数
原始数量 → 过滤前的匹配数量
过滤数量 → 过滤后的匹配数量
过滤后位置列表 → 经过过滤后的坐标列表

最佳匹配输出

最佳匹配中心坐标 → 相似度最高的匹配位置
- 包含：x坐标、y坐标、坐标名称、特征区域框、相似度、边界框
最佳匹配相似度 → 最佳匹配的相似度分数

状态判断输出

有输出坐标 → 布尔值，当有匹配坐标时为true
无输出坐标 → 布尔值，当没有匹配坐标时为true

图片信息输出

模板图片尺寸 → 第一张模板图片的尺寸（宽度、高度）
检测图片尺寸 → 第一张检测图片的尺寸（宽度、高度）
处理的文件列表 → 实际处理的图片文件列表
总文件数 → 处理的文件总数

特征信息输出

特征图片列表 → 提取的特征图片列表
特征数量 → 提取的特征总数
特征模式 → 当前使用的特征模式
特征权重 → 各特征提取器的权重分布
使用的提取器 → 实际使用的特征提取器列表

使用流程示例

基本使用流程

准备模板图片：截取要查找的按钮或图标作为模板
配置检测参数：设置相似度阈值、最大匹配数等
连接图片源：将检测图片连接到节点输入
执行匹配检测：运行节点进行图像匹配
处理匹配结果：根据匹配结果执行后续操作

连接建议

模板图片输入：
- 截图节点 → 模板图片(Bitmap)
- 图片源节点 → 模板图片(文件路径列表)
检测图片输入：
- 截图节点 → 检测图片(Bitmap)
- 图片源节点 → 检测图片(文件夹)
过滤坐标输入：
- 坐标存储节点 → 过滤坐标
- 整理坐标节点 → 过滤坐标
匹配结果输出：
- 匹配坐标列表 → 点击列表节点
- 最佳匹配中心坐标 → 点击节点
- 有输出坐标 → 条件判断节点

高级特性

增强特征匹配模式

当启用"增强特征匹配"时，系统会自动使用以下特征提取器组合：

颜色直方图：30%权重，提取颜色分布特征
颜色矩：20%权重，提取颜色统计特征
LBP：20%权重，提取纹理特征
梯度直方图：15%权重，提取边缘特征
感知哈希：15%权重，提取结构特征

这种多特征融合方式能显著提高在不同光照、角度变化下的匹配准确性。

智能坐标命名

基于图像特征自动生成有意义的坐标名称：

在匹配位置周围提取图像特征
将特征编码为紧凑字符串
生成类似"feature_abc123"的坐标名称
便于后续的坐标过滤和重用

批量处理能力

支持以下批量处理场景：

单模板多检测：用一个模板图片在多个检测图片中查找
多模板单检测：用多个模板图片在一个检测图片中查找
多模板多检测：用多个模板图片在多个检测图片中查找

应用场景

UI测试

验证界面元素是否正常显示
检测按钮状态变化
确认对话框出现

文档处理

查找文档中的特定图标
识别表格位置
定位签名区域

图像分析

在多张图片中查找相同物体
检测图片重复内容
识别图像中的特定模式

参数调优建议

相似度阈值：
- 简单场景：0.8-0.9
- 复杂场景：0.7-0.8
- 模糊匹配：0.6-0.7
特征区域大小：
- 小图标：50×50像素
- 中等元素：100×100像素
- 大区域：200×200像素

内存管理

批量处理限制：单次处理图片不宜过多，建议不超过50张
使用文件路径：大图片建议使用文件路径而不是Bitmap输入

错误处理

常见错误及解决方案

未找到匹配：
- 降低相似度阈值
- 检查模板图片是否正确
- 检查模板内容是否包含检测图片
- 调整特征提取参数
匹配过多：
- 提高相似度阈值
- 启用过滤功能
- 调整特征相似度阈值
性能问题：
- 减少同时处理的图片数量
- 使用较小的图片尺寸

调试建议

使用"特征图片列表"输出检查特征提取效果
通过"匹配数量"和"原始数量"对比过滤效果

示例配置

批量UI元素检测

模板图片文件夹：/sdcard/screenshots/
检测图片文件夹：/sdcard/ui_templates/
相似度阈值：0.9
过滤模式：排除模式
过滤JSON文件：/sdcard/filter_coordinates.json

技术实现说明

匹配算法原理

模板匹配：使用OpenCV的模板匹配算法进行初步定位
特征提取：在匹配位置周围提取多种图像特征
特征融合：加权融合多种特征计算综合相似度
结果过滤：根据阈值和过滤规则筛选最终结果

坐标数据结构

每个匹配坐标包含以下信息：

{
  "center": {
    "x": 150,
    "y": 200
  },
  "similarity": 0.95,
  "searchImageIndex": 0,
  "templateImageIndex": 0,
  "coordinateName": "feature_a1b2c3",
  "searchImageName": "button_template",
  "templateImageName": "screen_shot",
  "boundingBox": {
    "left": 120,
    "top": 180,
    "right": 180,
    "bottom": 220
  },
  "featureRegionBox": {
    "left": 100,
    "top": 160,
    "right": 200,
    "bottom": 240
  }
}