XplorePlane/XP.ImageProcessing.Core/Alignment/RoiAlignmentIntegrationGuide.md

ROI 对齐接入说明（给流水线）

本文用于把 RotatedTemplateMatching 的结果接到 ROI 对齐，再把对齐后的 Poly* 注入到下游检测算子（如 VoidMeasurement、QfnLeadPadVoid）。

1. 最小流程

1. 先执行模板匹配（RotatedTemplateMatching）。
2. 读取匹配位姿（CenterX/CenterY/Angle）。
3. 用 AlignmentRecipe 做 ROI 变换。
4. 把变换后的 PolyCount/PolyX*/PolyY* 写入下游检测参数。
5. 再执行下游检测算子。

2. 推荐调用方式（最少代码）

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 的输出字典拷贝到下游检测参数，可用：

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