# VisionMaster 工具使用讲解

## 结论先行

**VisionMaster 的核心使用方式是通过拖拽工具模块搭建视觉检测流程。** 每个工具都有明确的“输入依赖”和“输出结果”，理解这一点是掌握 VM 的关键。以下按工具类别逐一讲解核心工具的使用方法。

## 一、定位工具：方案的“地基”

定位工具是整个视觉流程的起点，作用是在图像中找到目标工件的位姿（X、Y、角度）。**没有定位，后续测量和检测的 ROI 无法自动跟随工件变化。**

### 1. 高精度匹配

**功能**：基于轮廓几何特征的亚像素级模板匹配，先学习模板的边缘轮廓，再在搜索图中寻找最相似实例。

**核心特性**：抗光照变化、抗遮挡、抗部分缺失，支持平移+旋转+缩放。

**关键参数**：
- **最小匹配分数**：相似度阈值，达到该值才认为匹配成功。工业场景通常要求 0.8 以上
- **角度范围**：设置目标可能旋转的角度区间
- **尺度范围**：设置目标可能缩放的倍数区间
- **最大匹配个数**：允许查找的最大目标数量

**典型应用**：精密贴装对位、机器人抓取引导、晶圆/芯片定位。

### 2. 快速匹配

**功能**：面向高节拍产线优化的模板匹配，速度优先，在保证基础精度的前提下大幅缩短单帧耗时。

**核心特性**：可一次返回多个目标，适合在线高速检测。

**典型应用**：高速分拣、流水线快速定位、读码前预定位。

### 3. 直线查找

**功能**：在 ROI 内检测边缘点，拟合成直线。

**关键参数**：
- **边缘极性**：“黑到白”指按箭头方向由黑色变为白色的分界线；“白到黑”相反；“任意极性”不限制方向
- **边缘类型**：**最强**（梯度最大的边缘，默认选项）、**第一条**（最先检测到的边缘）、**最后一条**
- **边缘阈值**（0~255）：梯度阈值，只有超过该值的边缘点才被检测。**数值越大抗噪越强，但可能丢失弱边缘**
- **滤波尺寸**：对噪点起滤波作用，数值越大抗噪越强，但边缘点数量减少
- **卡尺数量**：边缘点由多个卡尺卡出，数量越多越精细但速度越慢

**典型应用**：测量直线度、找边缘位置、作为测量工具的上游输入。

### 4. 圆查找

**功能**：在 ROI 内自动拟合圆形轮廓，输出圆心与半径。

**关键参数**：
- **边缘类型**：**最强边缘**适合边缘清晰场景；**第一条边缘**适合检测内圆；**最后一条边缘**适合检测外圆轮廓
- **边缘阈值与滤波尺寸的联动调节**：先设较小滤波尺寸（1-2），逐步提高边缘阈值至噪声被抑制；若边缘仍不清晰，再适当增大滤波尺寸
- **剔除点数**：误差过大被排除、不参与拟合的点数，离群点越多该值应越大

**典型应用**：PCB板定位孔检测、轴承尺寸测量、精密零件圆度检测。

## 二、测量工具：接收几何对象，输出数值

测量工具**不直接处理图像**，而是接收上游定位模块输出的点、线、圆对象，计算它们之间的几何关系。

### 1. 线线测量

**功能**：测量两条直线之间的距离和夹角。

**输出参数**：
- **距离**：两条直线段共四个端点，每个端点到另一条直线的距离，取**均值**
- **绝对距离**：距离的绝对值
- **夹角**：两条直线的角度差值
- **交点X/Y**：两条直线延长线的交点坐标

**配置方式**：可选择“按线”（输入直线查找的结果）、“按点”（自定义起点终点）或“按坐标”。

**典型应用**：测量方形边框上下边距离、手机盖板白色区域宽度。

### 2. 线圆测量

**功能**：测量圆心到直线的距离。

**核心输出**：圆心到直线的垂直距离、直线到圆轮廓的最短距离、是否相交。

**典型应用**：测量零件上孔位到边缘的距离、引脚到基准线的间距。

## 三、卡尺工具：批量边缘测量

**功能**：用于测量物体的宽度、边缘特征的位置以及图像中边缘对的位置和间距。

**为什么用它**：如果需要检测芯片的每一个 PIN 的宽度和坐标，用单个边缘点工具需要一个一个画，用卡尺工具可以**一次性测量出来**。

**使用流程**：
1. 先做好定位和位置修正（确保卡尺 ROI 能跟随工件移动）
2. 拖入卡尺工具，在边缘附近画一条带方向的 ROI
3. 设置边缘类型、极性、边缘阈值
4. 运行，读取边缘距离、宽度等输出

**关键参数**：
| 参数 | 含义 | 说明 |
|---|---|---|
| 边缘类型 | 最强/第一条/最后一条 | “最强”找梯度最大的边缘 |
| 边缘极性 | 黑到白/白到黑/任意 | 抓错极性会找不到边 |
| 边缘阈值 | 梯度阈值（0~255） | 越大抗噪越强、边缘越少 |
| 滤波尺寸 | 平滑窗口大小 | 越大越抗噪，但边缘精度下降 |

**调参经验**：边缘阈值从小往大调，调到既能稳定抓住边缘又不抓噪点为止。

## 四、标定转换：像素坐标转物理坐标

**功能**：在完成标定后，将相机坐标系下的像素坐标转换为机械臂世界坐标系下的物理坐标。

**为什么需要**：模板匹配输出的是**像素坐标**，机器人需要的是**物理坐标（毫米）**。标定转换就是建立两者之间的映射关系。

**使用步骤**：
1. 加载已生成的标定文件（标定时保存的路径）
2. 将上游定位模块的输出作为“图像坐标点输入”
3. 执行，输出物理坐标系下的位置

**典型应用**：机器人抓取引导、精密对位。

## 五、格式化：通信前的必要步骤

**功能**：把多个模块的输出数值整合成一条可发送的字符串。

**为什么需要**：定位和测量模块的输出是分散的数值，通信发送需要一条完整的数据包。格式化工具就是“打包”环节。

**配置方式**：
1. 点击右侧链接图标，选择需要格式化的数据（如“标定转换—输出点—物理坐标系X”）
2. 在数据之间设置分隔符（如逗号）
3. 可设置结束符：`\r`（回车）、`\n`（换行）、`\r\n`（回车换行）

**格式说明**：
- `%s`：不做格式化处理，直接输出为字符串
- `%0d`：按整数输出，数字 0 可替换为其他正整数（输出长度，不足补 0）
- `%0.0f`：按浮点格式输出

## 六、通信工具：连接外部设备

### 接收数据

**功能**：从外部设备读入数据，可触发相机拍照或软件运行。

**解析方式**：
- **文本-协议解析**：对 ASCII 字符数据按分隔符解析（如“1；2”解析成 int 的 1 和 2）
- **文本-协议组装**：解析后按规则校验，校验成功后组装传到模块参数中使用
- **字节匹配-协议组装**：按字节顺序解析，支持比较、上升沿、下降沿等校验

### 发送数据

**功能**：将格式化结果通过 TCP、UDP、串口、Modbus 等协议发送给 PLC 或机器人。

**使用步骤**：在通信管理中创建通信设备（如 TCP 客户端），拖入“发送数据”，选择“输出至通信设备”，发送数据选“格式化结果”。

## 七、总结

VM 工具使用的核心逻辑可以概括为一句话：**定位 → 测量/卡尺 → 标定转换 → 格式化 → 通信发送**。