新增 ROI 对齐基础能力并打通到算子与 UI。

统一补齐对齐核心工具类、RoiAlignment 算子、模板匹配对齐扩展和多语言资源，便于在检测前稳定完成示教 ROI 到运行图的变换。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-01 17:04:32 +08:00
parent b0397365b2
commit 1874c4a5bb
15 changed files with 790 additions and 1 deletions
@@ -0,0 +1,81 @@
+# 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`，减少中心约定偏差。