# 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`，减少中心约定偏差。