431 lines
16 KiB
Markdown
431 lines
16 KiB
Markdown
# Vision 模块使用文档
|
||
|
||
## 1. 文档范围
|
||
|
||
本文档说明当前 [`MainShell/Vision`](MainShell/Vision) 模块在“一个算法一个文件夹”的结构下的职责划分和推荐使用方式，重点覆盖：
|
||
|
||
- [`IImageCaptureService`](MainShell/Vision/ImageCapture/IImageCaptureService.cs) / [`ImageCaptureService`](MainShell/Vision/ImageCapture/ImageCaptureService.cs)：负责按当前已准备好的相机模式执行采图
|
||
- [`IFindTemplateService`](MainShell/Vision/FindTemplate/IFindTemplateService.cs:10) / [`FindTemplateService`](MainShell/Vision/FindTemplate/FindTemplateService.cs:14)：负责模板匹配算法的采图与处理
|
||
- [`VisionParController`](MainShell/Models/VisionParController.cs)：负责视觉前置硬件参数准备，包括相机参数、触发模式和抓流状态
|
||
- [`FindTemplateRequest`](MainShell/Vision/FindTemplate/FindTemplateRequest.cs:8) / [`FindTemplateImageRequest`](MainShell/Vision/FindTemplate/FindTemplateImageRequest.cs:6)：负责模板匹配请求建模
|
||
- [`VisionProcessResult`](MainShell/Vision/Common/VisionProcessResult.cs:8) / [`VisionProcessResult<TData>`](MainShell/Vision/Common/VisionProcessResultOfT.cs:9)：负责承载通用处理状态与强类型算法结果
|
||
- [`ImageCaptureResult`](MainShell/Vision/ImageCapture/ImageCaptureResult.cs:25) / [`ImageCaptureStatus`](MainShell/Vision/ImageCapture/ImageCaptureResult.cs:11)：负责承载采图状态、消息与图像对象
|
||
|
||
当前目录划分如下：
|
||
|
||
- `Common/`：共享结果模型与算法参数基类
|
||
- `ImageCapture/`：采图接口、实现与采图相关模型
|
||
- `FindTemplate/`：模板匹配算法接口、实现、请求、参数、结果
|
||
- `FindMark/`：Mark 识别参数与后续算法扩展入口
|
||
- `FindDie/`：Die 定位参数与后续算法扩展入口
|
||
- `FindCenter/`：中心识别草稿算法骨架
|
||
|
||
## 2. 当前模块职责边界
|
||
|
||
### 2.1 [`VisionParController`](MainShell/Models/VisionParController.cs)
|
||
|
||
负责视觉前置硬件准备：
|
||
|
||
- 设置曝光和增益
|
||
- 设置触发模式
|
||
- 设置触发源
|
||
- 设置触发延时
|
||
- 启动或停止抓流
|
||
- 设置光源参数
|
||
|
||
### 2.2 [`ImageCaptureService`](MainShell/Vision/ImageCapture/ImageCaptureService.cs)
|
||
|
||
只负责执行采图动作：
|
||
|
||
- 不再自动切换触发模式
|
||
- 不再自动切换触发源
|
||
- 不再自动设置触发延时
|
||
- 不再自动启停抓流
|
||
- 同一相机的采图请求在服务内部按相机粒度串行执行
|
||
- 通过 [`ImageCaptureResult`](MainShell/Vision/ImageCapture/ImageCaptureResult.cs:25) 返回成功、取消、无帧或设备状态异常等结果
|
||
|
||
调用方必须在采图前通过 [`VisionParController`](MainShell/Models/VisionParController.cs) 或其他上层硬件控制流程准备好相机状态。
|
||
|
||
### 2.3 [`FindTemplateService`](MainShell/Vision/FindTemplate/FindTemplateService.cs:14)
|
||
|
||
负责：
|
||
|
||
- 模板匹配参数校验
|
||
- 模板匹配采图流程组织
|
||
- 单个模板匹配结果构建
|
||
- 多个模板匹配结果集合构建
|
||
- 返回 [`VisionProcessResult<FindTemplateResult>`](MainShell/Vision/Common/VisionProcessResultOfT.cs:9) 或 [`VisionProcessResult<FindTemplatesResult>`](MainShell/Vision/Common/VisionProcessResultOfT.cs:9)
|
||
|
||
当前模板匹配算法本体仍为占位实现，尚未接入真实视觉算法库。当前占位实现会明确返回失败，避免上层流程误判为识别成功。
|
||
|
||
## 3. 当前推荐结构
|
||
|
||
当前推荐使用“一个算法一个实现”的结构，即：
|
||
|
||
- 每个算法拥有独立接口，例如 [`IFindTemplateService`](MainShell/Vision/FindTemplate/IFindTemplateService.cs:10)
|
||
- 每个算法拥有独立实现，例如 [`FindTemplateService`](MainShell/Vision/FindTemplate/FindTemplateService.cs:14)
|
||
- 每个算法拥有独立请求、参数、结果模型
|
||
- 不再使用统一算法总入口服务
|
||
|
||
推荐未来新增算法继续按相同方式组织，例如：
|
||
|
||
- `FindMark/IFindMarkService.cs`
|
||
- `FindMark/FindMarkService.cs`
|
||
- `FindMark/FindMarkRequest.cs`
|
||
- `FindMark/FindMarkResult.cs`
|
||
|
||
如果算法需要“已有图像直接处理”的场景，可按需再增加 `XXXImageRequest.cs`。
|
||
|
||
## 4. 推荐调用顺序
|
||
|
||
推荐顺序如下：
|
||
|
||
1. 先通过 [`VisionParController`](MainShell/Models/VisionParController.cs) 准备相机与光源参数
|
||
2. 再通过 [`IImageCaptureService`](MainShell/Vision/ImageCapture/IImageCaptureService.cs) 执行采图，或由具体算法服务内部采图
|
||
3. 最后通过具体算法服务，例如 [`IFindTemplateService`](MainShell/Vision/FindTemplate/IFindTemplateService.cs:10)，执行算法
|
||
|
||
## 5. 采图前提说明
|
||
|
||
### 5.1 连续流采图
|
||
|
||
当 [`CameraCaptureMode.Stream`](MainShell/Vision/ImageCapture/CameraCaptureMode.cs) 用于采图时，调用前应确保：
|
||
|
||
- 相机已打开
|
||
- 相机已处于 grabbing 状态
|
||
- 相机已被配置为适合连续流取图的工作模式
|
||
|
||
### 5.2 软触发采图
|
||
|
||
当 [`CameraCaptureMode.SoftTrigger`](MainShell/Vision/ImageCapture/CameraCaptureMode.cs) 用于采图时，调用前应确保：
|
||
|
||
- 相机已打开
|
||
- 相机已处于 grabbing 状态
|
||
- 相机已被配置为软触发模式
|
||
- 触发源已设置为软件触发
|
||
|
||
如果上述前提不满足，[`ImageCaptureService`](MainShell/Vision/ImageCapture/ImageCaptureService.cs) 不会代替调用方修改硬件状态，而是直接失败并记录日志。
|
||
|
||
## 6. 请求模型
|
||
|
||
模板匹配当前使用独立请求模型：
|
||
|
||
- [`FindTemplateRequest`](MainShell/Vision/FindTemplate/FindTemplateRequest.cs:8)：用于“采图 + 算法”流程
|
||
- [`FindTemplateImageRequest`](MainShell/Vision/FindTemplate/FindTemplateImageRequest.cs:6)：用于“已有图像 + 算法”流程
|
||
|
||
推荐新算法默认最小模型集为：
|
||
|
||
- `XXXRequest`
|
||
- `XXXResult`
|
||
|
||
只有在算法确实需要时，再增加：
|
||
|
||
- `XXXParameters`
|
||
- `XXXImageRequest`
|
||
|
||
## 7. 结果模型
|
||
|
||
当前结果模型已调整为四层：
|
||
|
||
- [`VisionProcessResult`](MainShell/Vision/Common/VisionProcessResult.cs:8)：仅承载成功/失败/异常/消息
|
||
- [`VisionProcessResult<TData>`](MainShell/Vision/Common/VisionProcessResultOfT.cs:9)：承载强类型算法结果数据
|
||
- [`ImageCaptureResult`](MainShell/Vision/ImageCapture/ImageCaptureResult.cs:25)：承载采图动作结果、状态、消息和图像对象
|
||
- [`VisionMatchResult`](MainShell/Vision/Common/VisionMatchResult.cs:6)：承载扩展匹配信息
|
||
|
||
模板匹配当前返回：
|
||
|
||
- [`VisionProcessResult<FindTemplateResult>`](MainShell/Vision/Common/VisionProcessResultOfT.cs:9)
|
||
- [`VisionProcessResult<FindTemplatesResult>`](MainShell/Vision/Common/VisionProcessResultOfT.cs:9)
|
||
|
||
[`FindTemplateResult`](MainShell/Vision/FindTemplate/FindTemplateResult.cs:6) 当前包含：
|
||
|
||
- `CenterX`
|
||
- `CenterY`
|
||
- `Score`
|
||
- `Match`
|
||
|
||
[`FindTemplatesResult`](MainShell/Vision/FindTemplate/FindTemplatesResult.cs:6) 当前包含：
|
||
|
||
- `Items`
|
||
|
||
## 8. 当前算法实现状态
|
||
|
||
当前状态如下：
|
||
|
||
- 采图服务已按新职责边界实现
|
||
- 模板匹配保持独立接口与独立服务实现
|
||
- 采图结果已区分成功、取消、设备状态错误、无帧和驱动异常
|
||
- 已不再使用统一视觉算法入口服务
|
||
- [`FindTemplateService`](MainShell/Vision/FindTemplate/FindTemplateService.cs:14) 当前仍为占位实现，尚未接入真实算法
|
||
- 已预留单个模板匹配与多个模板匹配两套接口
|
||
- 多个模板匹配当前已明确约定输出规则：保留底层原始顺序，不做得分筛选、不做去重、不做聚类合并
|
||
|
||
因此本模块当前适合作为：
|
||
|
||
- 视觉接入骨架
|
||
- 采图与参数联调骨架
|
||
- 按算法拆服务的长期结构基础
|
||
|
||
## 9. 取消与超时说明
|
||
|
||
[`ImageCaptureService`](MainShell/Vision/ImageCapture/ImageCaptureService.cs) 当前采图仍基于底层同步驱动接口。
|
||
|
||
这意味着：
|
||
|
||
- `CancellationToken` 主要控制外层任务流程
|
||
- 取消仅能在进入驱动前或驱动返回后生效
|
||
- 不一定能真正中断驱动内部阻塞调用
|
||
- 软触发底层超时仍受驱动实现限制
|
||
|
||
[`FindTemplateService`](MainShell/Vision/FindTemplate/FindTemplateService.cs:14) 当前会区分：
|
||
|
||
- 调用方主动取消
|
||
- 参数校验失败
|
||
- 算法未实现
|
||
- 采图阶段失败
|
||
|
||
## 10. 图像对象生命周期说明
|
||
|
||
- 通过 [`FindTemplateService.ProcessAsync()`](MainShell/Vision/FindTemplate/FindTemplateService.cs:22) 内部采集到的图像，由服务内部释放
|
||
- 通过 [`IFindTemplateService.ProcessImageAsync()`](MainShell/Vision/FindTemplate/IFindTemplateService.cs:22) 或 [`IFindTemplateService.ProcessMultipleImageAsync()`](MainShell/Vision/FindTemplate/IFindTemplateService.cs:36) 传入的已有图像，由调用方负责释放
|
||
- 调用方不应在算法执行期间提前释放正在使用的图像对象
|
||
|
||
## 11. 多模板匹配规则
|
||
|
||
当前多个模板匹配算法接口约定如下：
|
||
|
||
1. 输入一张图像和一组模板匹配参数
|
||
2. 调用底层模板匹配能力，获取原始匹配结果集合
|
||
3. 不按 `MinScore` 做二次筛选
|
||
4. 不做最佳值选优
|
||
5. 不做结果去重
|
||
6. 不做聚类合并
|
||
7. 保持底层算法返回顺序
|
||
8. 将原始匹配结果逐个映射为 [`FindTemplateResult`](MainShell/Vision/FindTemplate/FindTemplateResult.cs:6) 并输出到 [`FindTemplatesResult`](MainShell/Vision/FindTemplate/FindTemplatesResult.cs:6)
|
||
|
||
## 12. 新增算法模板建议
|
||
|
||
推荐新增一个普通算法时，默认最小文件集合为：
|
||
|
||
- `IXXXService.cs`
|
||
- `XXXService.cs`
|
||
- `XXXRequest.cs`
|
||
- `XXXResult.cs`
|
||
|
||
复杂算法再按需增加：
|
||
|
||
- `XXXParameters.cs`
|
||
- `XXXImageRequest.cs`
|
||
|
||
这样可以兼顾：
|
||
|
||
- 一算法一实现的清晰边界
|
||
- 文件数量不过度膨胀
|
||
- 后续维护和问题定位的可读性
|
||
|
||
## 13. 代码使用示例
|
||
|
||
### 13.1 示例一：由算法服务内部采图后执行单个模板匹配
|
||
|
||
这是推荐的业务调用方式。先通过 [`VisionParController`](MainShell/Models/VisionParController.cs) 准备相机状态，再调用 [`IFindTemplateService.ProcessAsync()`](MainShell/Vision/FindTemplate/IFindTemplateService.cs:14)。
|
||
|
||
```csharp
|
||
using MainShell.Common;
|
||
using MainShell.Vision;
|
||
using System.Threading;
|
||
using System.Threading.Tasks;
|
||
|
||
public class VisionUsageExample
|
||
{
|
||
private readonly IFindTemplateService _findTemplateService;
|
||
|
||
public VisionUsageExample(IFindTemplateService findTemplateService)
|
||
{
|
||
_findTemplateService = findTemplateService;
|
||
}
|
||
|
||
public async Task ExecuteAsync(CancellationToken cancellationToken)
|
||
{
|
||
FindTemplateRequest request = new FindTemplateRequest();
|
||
request.CameraSource = CameraType.UpCamera;
|
||
request.TimeoutMilliseconds = 3000;
|
||
request.CaptureOptions.TimeoutMilliseconds = 2000;
|
||
request.CaptureOptions.CaptureMode = CameraCaptureMode.Stream;
|
||
request.Parameters.UseRoi = true;
|
||
request.Parameters.RoiName = "DieCenterRoi";
|
||
request.Parameters.TemplatePath = "Template/DieCenter";
|
||
request.Parameters.MinScore = 0.8d;
|
||
|
||
VisionProcessResult<FindTemplateResult> result = await _findTemplateService.ProcessAsync(
|
||
request,
|
||
cancellationToken).ConfigureAwait(false);
|
||
|
||
if (!result.Succeeded)
|
||
{
|
||
string failureMessage = result.Message;
|
||
return;
|
||
}
|
||
|
||
FindTemplateResult data = result.Data;
|
||
double centerX = data.CenterX;
|
||
double centerY = data.CenterY;
|
||
double score = data.Score;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 13.2 示例二：对已有图像执行多个模板匹配
|
||
|
||
这个方式适合调试、联调或者需要复用同一帧图像的场景。
|
||
|
||
```csharp
|
||
using MainShell.Common;
|
||
using MainShell.Models;
|
||
using MainShell.Vision;
|
||
using System.Threading;
|
||
using System.Threading.Tasks;
|
||
|
||
public class VisionImageUsageExample
|
||
{
|
||
private readonly IImageCaptureService _imageCaptureService;
|
||
private readonly IFindTemplateService _findTemplateService;
|
||
|
||
public VisionImageUsageExample(
|
||
IImageCaptureService imageCaptureService,
|
||
IFindTemplateService findTemplateService)
|
||
{
|
||
_imageCaptureService = imageCaptureService;
|
||
_findTemplateService = findTemplateService;
|
||
}
|
||
|
||
public async Task ExecuteAsync(CancellationToken cancellationToken)
|
||
{
|
||
CameraCaptureOptions captureOptions = new CameraCaptureOptions();
|
||
captureOptions.TimeoutMilliseconds = 2000;
|
||
captureOptions.CaptureMode = CameraCaptureMode.Stream;
|
||
|
||
ImageCaptureResult captureResult = await _imageCaptureService.CaptureAsync(
|
||
CameraType.UpCamera,
|
||
captureOptions,
|
||
cancellationToken).ConfigureAwait(false);
|
||
|
||
if (!captureResult.Succeeded)
|
||
{
|
||
string captureFailureMessage = captureResult.Message;
|
||
return;
|
||
}
|
||
|
||
MxImage image = captureResult.Image;
|
||
try
|
||
{
|
||
FindTemplateImageRequest request = new FindTemplateImageRequest();
|
||
request.TimeoutMilliseconds = 3000;
|
||
request.Parameters.UseRoi = false;
|
||
request.Parameters.TemplatePath = "Template/DieCenter";
|
||
request.Parameters.MinScore = 0.8d;
|
||
|
||
VisionProcessResult<FindTemplatesResult> result = await _findTemplateService.ProcessMultipleImageAsync(
|
||
image,
|
||
request,
|
||
cancellationToken).ConfigureAwait(false);
|
||
|
||
if (!result.Succeeded)
|
||
{
|
||
string failureMessage = result.Message;
|
||
return;
|
||
}
|
||
|
||
FindTemplatesResult data = result.Data;
|
||
int count = data.Items.Count;
|
||
}
|
||
finally
|
||
{
|
||
if (image != null)
|
||
{
|
||
image.Dispose();
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 13.3 示例三：如何判断采图失败原因
|
||
|
||
[`ImageCaptureResult`](MainShell/Vision/ImageCapture/ImageCaptureResult.cs:25) 适合在上层做更细的失败分流。
|
||
|
||
```csharp
|
||
using MainShell.Common;
|
||
using MainShell.Vision;
|
||
using System.Threading;
|
||
using System.Threading.Tasks;
|
||
|
||
public class CaptureResultExample
|
||
{
|
||
private readonly IImageCaptureService _imageCaptureService;
|
||
|
||
public CaptureResultExample(IImageCaptureService imageCaptureService)
|
||
{
|
||
_imageCaptureService = imageCaptureService;
|
||
}
|
||
|
||
public async Task ExecuteAsync(CancellationToken cancellationToken)
|
||
{
|
||
ImageCaptureResult captureResult = await _imageCaptureService.CaptureAsync(
|
||
CameraType.UpCamera,
|
||
2000,
|
||
CameraCaptureMode.Stream,
|
||
cancellationToken).ConfigureAwait(false);
|
||
|
||
if (captureResult.Succeeded)
|
||
{
|
||
return;
|
||
}
|
||
|
||
switch (captureResult.Status)
|
||
{
|
||
case ImageCaptureStatus.Cancelled:
|
||
break;
|
||
|
||
case ImageCaptureStatus.CameraNotFound:
|
||
case ImageCaptureStatus.CameraNotOpen:
|
||
case ImageCaptureStatus.CameraNotGrabbing:
|
||
case ImageCaptureStatus.NoFrame:
|
||
case ImageCaptureStatus.DriverError:
|
||
string message = captureResult.Message;
|
||
break;
|
||
|
||
default:
|
||
break;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 13.4 示例四：新增一个新算法时的推荐骨架
|
||
|
||
以 `FindMark` 为例，推荐至少准备：
|
||
|
||
- `FindMark/IFindMarkService.cs`
|
||
- `FindMark/FindMarkService.cs`
|
||
- `FindMark/FindMarkRequest.cs`
|
||
- `FindMark/FindMarkResult.cs`
|
||
|
||
如果需要已有图像处理，再增加：
|
||
|
||
- `FindMark/FindMarkImageRequest.cs`
|
||
|
||
如果参数较复杂，再增加：
|
||
|
||
- `FindMark/FindMarkParameters.cs`
|
||
|
||
服务实现建议沿用 [`FindTemplateService`](MainShell/Vision/FindTemplate/FindTemplateService.cs:14) 的结构：
|
||
|
||
- `ProcessAsync()` 负责“采图 + 单个模板匹配”
|
||
- `ProcessImageAsync()` 负责“已有图像 + 单个模板匹配”
|
||
- `ProcessMultipleAsync()` 负责“采图 + 多个模板匹配”
|
||
- `ProcessMultipleImageAsync()` 负责“已有图像 + 多个模板匹配”
|
||
- `NormalizeRequest()` 负责标准化
|
||
- `ValidateRequest()` 负责参数校验
|
||
- `CloneParameters()` 负责避免共享可变输入对象
|
||
|
||
这样可以保证不同算法之间结构一致，便于维护和扩展。
|