feat: ROI 对齐工具与 TM_Result 位姿扩展

- Core: Pose2D、Point2D、RoiAlignment、AlignmentRecipe（示教多边形→运行图刚体变换）

- Processors: TemplateMatchAlignmentExtensions.ToPose2D / 四角与中心一致性校验

Co-authored-by: Cursor <cursoragent@cursor.com>

XP.ImageProcessing.Core/Alignment/AlignmentRecipe.cs

@@ -0,0 +1,21 @@
+namespace XP.ImageProcessing.Core.Alignment;
+
+/// <summary>
+/// 示教阶段保存的对齐配方：基准位姿 + 示教图像素坐标下的检测 ROI。
+/// </summary>
+public sealed class AlignmentRecipe
+{
+    /// <summary>示教图上的基准位姿（建议示教图自匹配得到，或与模板 ROI 中心 + 角度 0 一致）。</summary>
+    public Pose2D ReferencePose { get; set; }
+
+    /// <summary>示教图上的 ROI 多边形顶点（至少 3 点）。</summary>
+    public List<Point2D> RoiPoints { get; set; } = new();
+
+    /// <summary>将示教 ROI 变换到运行图坐标。</summary>
+    public Point2D[] TransformRoi(Pose2D measuredPose)
+        => RoiAlignment.TransformPolygon(RoiPoints, ReferencePose, measuredPose);
+
+    /// <summary>变换为整型顶点，供检测算子注入。</summary>
+    public (int X, int Y)[] TransformRoiToInt(Pose2D measuredPose)
+        => RoiAlignment.TransformPolygonToInt(RoiPoints, ReferencePose, measuredPose);
+}

XP.ImageProcessing.Core/Alignment/Point2D.cs

@@ -0,0 +1,4 @@
+namespace XP.ImageProcessing.Core.Alignment;
+
+/// <summary>图像像素平面上的点（与 WPF/Emgu 解耦）。</summary>
+public readonly record struct Point2D(double X, double Y);

XP.ImageProcessing.Core/Alignment/Pose2D.cs

@@ -0,0 +1,18 @@
+namespace XP.ImageProcessing.Core.Alignment;
+
+/// <summary>
+/// 图像平面上的刚体位姿：绕 <see cref="X"/>/<see cref="Y"/> 旋转 <see cref="AngleDegrees"/>（度）。
+/// 与 TemplateMatchLib 的 CenterX/CenterY/Angle 约定一致。
+/// </summary>
+public readonly record struct Pose2D(double X, double Y, double AngleDegrees)
+{
+    /// <summary>示教/标准姿态（角度 0，中心由调用方指定）。</summary>
+    public static Pose2D IdentityAt(double x, double y) => new(x, y, 0);
+
+    /// <summary>
+    /// 由模板学习 ROI 矩形估计示教位姿中心（pattern 几何中心），角度默认 0。
+    /// 更稳妥的做法是在示教图上自匹配得到 <see cref="Pose2D"/>。
+    /// </summary>
+    public static Pose2D FromTemplateRoiCenter(int roiX, int roiY, int roiWidth, int roiHeight, double angleDegrees = 0)
+        => new(roiX + roiWidth * 0.5, roiY + roiHeight * 0.5, angleDegrees);
+}

XP.ImageProcessing.Core/Alignment/RoiAlignment.cs

@@ -0,0 +1,96 @@
+namespace XP.ImageProcessing.Core.Alignment;
+
+/// <summary>
+/// 将示教图（模板坐标系）上的 ROI 点变换到运行图坐标。
+/// 旋转中心与模板匹配一致：绕 <see cref="Pose2D.X"/>/<see cref="Pose2D.Y"/>（pattern 中心）。
+/// </summary>
+public static class RoiAlignment
+{
+    /// <summary>
+    /// 刚体变换：示教图点 → 运行图点。
+    /// <paramref name="reference"/>：示教图上的基准位姿；
+    /// <paramref name="measured"/>：运行图匹配位姿。
+    /// </summary>
+    public static Point2D TransformPoint(Point2D point, Pose2D reference, Pose2D measured)
+    {
+        double dTheta = DegreesToRadians(measured.AngleDegrees - reference.AngleDegrees);
+        double cos = Math.Cos(dTheta);
+        double sin = Math.Sin(dTheta);
+        double dx = point.X - reference.X;
+        double dy = point.Y - reference.Y;
+        return new Point2D(
+            measured.X + cos * dx - sin * dy,
+            measured.Y + sin * dx + cos * dy);
+    }
+
+    public static Point2D TransformPoint(double x, double y, Pose2D reference, Pose2D measured)
+        => TransformPoint(new Point2D(x, y), reference, measured);
+
+    /// <summary>变换多边形顶点（顺序不变）。</summary>
+    public static Point2D[] TransformPolygon(IReadOnlyList<Point2D> templatePoints, Pose2D reference, Pose2D measured)
+    {
+        if (templatePoints == null || templatePoints.Count == 0)
+            return Array.Empty<Point2D>();
+
+        var result = new Point2D[templatePoints.Count];
+        for (int i = 0; i < templatePoints.Count; i++)
+            result[i] = TransformPoint(templatePoints[i], reference, measured);
+        return result;
+    }
+
+    /// <summary>变换后四舍五入为整型顶点，供 BGA 等算子 PolyX/PolyY 注入。</summary>
+    public static (int X, int Y)[] TransformPolygonToInt(
+        IReadOnlyList<Point2D> templatePoints,
+        Pose2D reference,
+        Pose2D measured)
+    {
+        var transformed = TransformPolygon(templatePoints, reference, measured);
+        var result = new (int X, int Y)[transformed.Length];
+        for (int i = 0; i < transformed.Length; i++)
+        {
+            result[i] = (
+                (int)Math.Round(transformed[i].X, MidpointRounding.AwayFromZero),
+                (int)Math.Round(transformed[i].Y, MidpointRounding.AwayFromZero));
+        }
+
+        return result;
+    }
+
+    /// <summary>变换轴对齐矩形为四个顶点（左上、右上、右下、左下）。</summary>
+    public static Point2D[] TransformRect(double x, double y, double width, double height, Pose2D reference, Pose2D measured)
+    {
+        var corners = new[]
+        {
+            new Point2D(x, y),
+            new Point2D(x + width, y),
+            new Point2D(x + width, y + height),
+            new Point2D(x, y + height)
+        };
+        return TransformPolygon(corners, reference, measured);
+    }
+
+    /// <summary>
+    /// 校验匹配结果四角质心是否与 Center 一致（用于确认库的中心/角度约定）。
+    /// </summary>
+    public static bool IsMatchCenterConsistentWithCorners(
+        double centerX,
+        double centerY,
+        double ltX,
+        double ltY,
+        double rtX,
+        double rtY,
+        double rbX,
+        double rbY,
+        double lbX,
+        double lbY,
+        double tolerancePixels = 1.0)
+    {
+        double cx = (ltX + rtX + rbX + lbX) * 0.25;
+        double cy = (ltY + rtY + rbY + lbY) * 0.25;
+        double dx = cx - centerX;
+        double dy = cy - centerY;
+        return dx * dx + dy * dy <= tolerancePixels * tolerancePixels;
+    }
+
+    private static double DegreesToRadians(double degrees) => degrees * (Math.PI / 180.0);
+}

XP.ImageProcessing.Processors/定位识别/TemplateMatchAlignmentExtensions.cs

@@ -0,0 +1,27 @@
+using XP.ImageProcessing.Core.Alignment;
+
+namespace XP.ImageProcessing.Processors;
+
+/// <summary>
+/// 将 TemplateMatchLib 匹配结果转换为对齐工具使用的 <see cref="Pose2D"/>。
+/// </summary>
+public static class TemplateMatchAlignmentExtensions
+{
+    public static Pose2D ToPose2D(this TM_Result result)
+        => new(result.CenterX, result.CenterY, result.Angle);
+
+    /// <summary>四角质心是否与 Center 一致（容差默认 1 像素）。</summary>
+    public static bool IsCenterConsistentWithCorners(this TM_Result result, double tolerancePixels = 1.0)
+        => RoiAlignment.IsMatchCenterConsistentWithCorners(
+            result.CenterX,
+            result.CenterY,
+            result.LtX,
+            result.LtY,
+            result.RtX,
+            result.RtY,
+            result.RbX,
+            result.RbY,
+            result.LbX,
+            result.LbY,
+            tolerancePixels);
+}