李伟
1874c4a5bb
统一补齐对齐核心工具类、RoiAlignment 算子、模板匹配对齐扩展和多语言资源，便于在检测前稳定完成示教 ROI 到运行图的变换。 Co-authored-by: Cursor <cursoragent@cursor.com>
82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
# ROI 对齐接入说明（给流水线）
|
||
|
||
本文用于把 `RotatedTemplateMatching` 的结果接到 ROI 对齐，再把对齐后的 `Poly*` 注入到下游检测算子（如 `VoidMeasurement`、`QfnLeadPadVoid`）。
|
||
|
||
## 1. 最小流程
|
||
|
||
1. 先执行模板匹配（`RotatedTemplateMatching`）。
|
||
2. 读取匹配位姿（`CenterX/CenterY/Angle`）。
|
||
3. 用 `AlignmentRecipe` 做 ROI 变换。
|
||
4. 把变换后的 `PolyCount/PolyX*/PolyY*` 写入下游检测参数。
|
||
5. 再执行下游检测算子。
|
||
|
||
## 2. 推荐调用方式（最少代码）
|
||
|
||
```csharp
|
||
using XP.ImageProcessing.Core.Alignment;
|
||
|
||
// 1) recipe 来自示教（ReferencePose + RoiPoints）
|
||
AlignmentRecipe recipe = LoadRecipe();
|
||
|
||
// 2) templateOutput 为 RotatedTemplateMatching 的 OutputData
|
||
if (!RoiAlignmentPipelineBridge.TryAlignFromTemplateMatch(
|
||
recipe,
|
||
templateOutput,
|
||
out var alignResult))
|
||
{
|
||
// 匹配失败或对齐失败：按业务判定 NG/中断
|
||
throw new InvalidOperationException(alignResult.ErrorMessage ?? "ROI alignment failed.");
|
||
}
|
||
|
||
// 3) detectionParams 为下一步检测算子的参数字典（VoidMeasurement / QfnLeadPadVoid 等）
|
||
RoiAlignmentApplier.WriteToParameters(detectionParams, alignResult, setRoiModePolygon: true);
|
||
|
||
// 4) 执行下游检测算子
|
||
// ProcessImageWithOutputAsync(..., detectionParams, ...)
|
||
```
|
||
|
||
## 3. 若你走 `RoiAlignment` 算子节点
|
||
|
||
如果流程里显式放了 `RoiAlignment` 节点：
|
||
|
||
- 输入参数：`RefCenterX/RefCenterY/RefAngle`、`MeasuredCenterX/MeasuredCenterY/MeasuredAngle`、示教 `Poly*`。
|
||
- 输出参数：`PolyCount/PolyX*/PolyY*`、`RoiAlignmentSuccess`、`RoiAlignmentMessage`。
|
||
|
||
将 `RoiAlignment` 的输出字典拷贝到下游检测参数，可用：
|
||
|
||
```csharp
|
||
if (!RoiAlignmentPipelineBridge.TryCopyAlignedRoiToDetectionParameters(
|
||
roiAlignmentOutput,
|
||
detectionParams,
|
||
out var error))
|
||
{
|
||
throw new InvalidOperationException(error ?? "Copy aligned ROI failed.");
|
||
}
|
||
```
|
||
|
||
## 4. 关键键名（常量）
|
||
|
||
- ROI 对齐输出键：`RoiAlignmentOutputKeys`
|
||
- `Success` = `RoiAlignmentSuccess`
|
||
- `Message` = `RoiAlignmentMessage`
|
||
- `ResultText` = `ResultText`
|
||
- `ReferenceCenterX/ReferenceCenterY/ReferenceAngle`
|
||
- `MeasuredCenterX/MeasuredCenterY/MeasuredAngle`
|
||
- `TransformedPointCount`
|
||
- 多边形键：`RoiPolygonParameterNames`
|
||
- `PolyCount`
|
||
- `PolyX(i)` / `PolyY(i)`
|
||
- `RoiMode`（值建议写 `Polygon`）
|
||
|
||
## 5. 失败处理建议
|
||
|
||
- `TryAlignFromTemplateMatch == false`：模板匹配失败或无效。
|
||
- `alignResult.Success == false`：示教点不足（<3）或配方异常。
|
||
- `PolyCount < 3`：不要继续下游检测，直接标记本次检测失败。
|
||
|
||
## 6. 示教数据要求
|
||
|
||
- `ReferencePose` 必须与示教 ROI 的坐标系一致（同一张示教图）。
|
||
- `RoiPoints` 至少 3 点，建议按轮廓顺序保存。
|
||
- 建议示教图先自匹配一次后再落 `ReferencePose`，减少中心约定偏差。
|