Display_D_HP/TeamAAS-VM/Interfaces/ICameraCalibrationService.cs

using MathNet.Numerics.LinearAlgebra;
using OpenCvSharp;
using System;
using System.Drawing;
using System.Threading;
using System.Threading.Tasks;
using TeamAAS_VP.Models;
using TeamAAS_VP.Models.Calibration;
using TeamAAS_VP.Models.Robot;

namespace TeamAAS_VP.Interfaces
{
    /// <summary>
    /// 提供相机标定与像素坐标系/机器人坐标系变换的服务接口。
    /// 注意：此接口只定义方法签名与文档，具体算法与实现由实现类提供。
    /// </summary>
    public interface ICameraCalibrationService : IDisposable
    {
        /// <summary>
        /// 触发相机拍照并进行图像处理的回调函数
        /// 在标定过程中需要获取图像特征点时调用此回调
        /// Tuple 字段含义：
        /// Item1 - IsSuccess: 拍照及图像处理是否成功；
        /// Item2 - X: 图像处理后得到的机器人目标 X（mm）；
        /// Item3 - Y: 图像处理后得到的机器人目标 Y（mm）；
        /// Item4 - U: 图像处理后得到的机器人目标 U（工具朝向）。
        /// </summary>
        Func<Task<(bool IsSuccess, double X, double Y, double U,int ImageWidth,int ImageHeight)>> CaptureAndProcessCallback { get; set; }

        /// <summary>
        /// 固定向下相机校准工具坐标。
        /// 该方法用于在相机固定、朝下安装且工具不随 J4 移动的情况下标定相机与机器人工具坐标系之间的关系。
        /// </summary>
        /// <param name="calibrationInfo">包含标定时所需的相机参数、图像处理配置与标定点信息的对象。</param>
        /// <param name="robot">实现了 <see cref="IRobot"/> 的机器人抽象，用于获取/移动机器人位姿。</param>
        /// <param name="cancellationToken">用于取消操作的标记。</param>
        /// <returns>
        /// 一个包含以下字段的元组：
        /// IsSuccess - 标定是否成功；
        /// Matrix<double> - 图像与像素坐标系之间的旋转（或仿射）矩阵（行列顺序与具体实现约定）；
        /// ToolX - 标定得到的工具坐标系在机器人基坐标系下的 X（单位与机器人一致）；
        /// ToolY - 标定得到的工具坐标系在机器人基坐标系下的 Y（单位与机器人一致）；
        /// PixelScaleX - 像素到物理距离在 X 方向的缩放因子（如 mm/px）；
        /// PixelScaleY - 像素到物理距离在 Y 方向的缩放因子（如 mm/px）。
        /// </returns>
        Task<(bool IsSuccess, Matrix<double> RotationMatrix, double ToolX, double ToolY, double PixelScaleX, double PixelScaleY)> CalibrateFixedDownCameraTool(CalibrationInfo calibrationInfo, IRobot robot,CancellationToken cancellationToken);

        /// <summary>
        /// J4 移动的向下相机校准工具坐标。
        /// 用于相机或工具随机器人第 4 轴（J4）运动时的标定，需考虑 J4 引入的偏转影响。
        /// </summary>
        /// <param name="calibrationInfo">标定所需配置信息。</param>
        /// <param name="robot">机器人接口。</param>
        /// <param name="cancellationToken">用于取消操作的标记。</param>
        /// <returns>同 <see cref="CalibrateFixedDownCameraTool"/> 的返回约定。</returns>
        Task<(bool IsSuccess, Matrix<double> RotationMatrix, double ToolX, double ToolY, double PixelScaleX, double PixelScaleY)> CalibrateJ4MovingDownCameraTool(CalibrationInfo calibrationInfo, IRobot robot, CancellationToken cancellationToken);

        /// <summary>
        /// 固定向上相机校准工具坐标。
        /// 该方法用于相机固定、朝上安装的情况，标定过程与向下相机类似但需要考虑图像翻转/镜像等差异。
        /// </summary>
        /// <param name="calibrationInfo">标定配置信息。</param>
        /// <param name="robot">机器人接口。</param>
        /// <param name="cancellationToken">用于取消操作的标记。</param>
        /// <returns>同 <see cref="CalibrateFixedDownCameraTool"/> 的返回约定。</returns>
        Task<(bool IsSuccess, Matrix<double> RotationMatrix, double ToolX, double ToolY, double PixelScaleX, double PixelScaleY)> CalibrateFixedUpCameraTool(CalibrationInfo calibrationInfo, IRobot robot, CancellationToken cancellationToken);

        /// <summary>
        /// 通过未标定的相机校准工具坐标。
        /// 当相机内参未知或未可靠标定时，通过已知机器人位姿与图像特征的对应关系反推工具坐标与像素尺度。
        /// </summary>
        /// <param name="calibrationInfo">标定配置信息（可能包含初始猜测或参考点）。</param>
        /// <param name="robot">机器人接口。</param>
        /// <param name="cancellationToken">用于取消操作的标记。</param>
        /// <returns>同 <see cref="CalibrateFixedDownCameraTool"/> 的返回约定。</returns>
        Task<(bool IsSuccess, Matrix<double> RotationMatrix, double ToolX, double ToolY, double PixelScaleX, double PixelScaleY)> CalibrateUncalibratedCameraTool(CalibrationInfo calibrationInfo, IRobot robot, CancellationToken cancellationToken);

        /// <summary>
        /// 自动识别机器人与相机图像坐标系的旋转矩阵。
        /// 使用若干已知的机器人位姿与对应图像坐标点，估计二者之间的旋转变换与像素尺度。
        /// </summary>
        /// <param name="calibrationInfo">包含用于识别的点集与图像处理配置。</param>
        /// <param name="robot">机器人接口，用于获取对应位姿或移动机器人到指定位置以采集数据。</param>
        /// <param name="cancellationToken">用于取消操作的标记。</param>
        /// <returns>
        /// 元组字段：
        /// IsSuccess - 是否成功识别；
        /// Matrix<double> - 旋转（或仿射）矩阵；
        /// PixelScaleX - X 方向像素尺度（如 mm/px）；
        /// PixelScaleY - Y 方向像素尺度（如 mm/px）。
        /// </returns>
        Task<(bool IsSuccess, Matrix<double> RotationMatrix, double PixelScaleX, double PixelScaleY)> AutoIdentifyRobotCameraRotationMatrix(CalibrationInfo calibrationInfo, IRobot robot, CancellationToken cancellationToken);

        /// <summary>
        /// 根据图像上的三个点计算图像坐标系的旋转矩阵。
        /// 通常通过已知三点在像素坐标系中的位置计算出局部旋转/仿射变换，用于后续坐标换算。
        /// </summary>
        /// <param name="P0">图像中的点 0（像素坐标）。</param>
        /// <param name="P1">图像中的点 1（像素坐标）。</param>
        /// <param name="P2">图像中的点 2（像素坐标）。</param>
        /// <returns>表示图像旋转或仿射变换的 3x3 或 2x2 矩阵（具体尺寸由实现决定）。</returns>
        Matrix<double> CalculateImageRotationMatrix(PointF P0, PointF P1, PointF P2);

        /// <summary>
        /// 自动移动机器人至图像中心点位置。
        /// 典型用例为将相机视野中心对应的工作点转换为机器人坐标并移动机器人到该点以便校准或抓取。
        /// </summary>
        /// <param name="robot">机器人接口，用于执行移动命令并返回当前位置。</param>
        /// <param name="matrix">图像坐标系到机器人坐标系的转换矩阵（旋转/仿射）。</param>
        /// <param name="PixelScaleX">像素到物理距离在 X 方向的缩放因子（如 mm/px）。</param>
        /// <param name="PixelScaleY">像素到物理距离在 Y 方向的缩放因子（如 mm/px）。</param>
        /// <param name="cancellationToken">用于取消操作的标记。</param>
        /// <returns>
        /// 元组字段：
        /// IsSuccess - 是否成功移动到图像中心；
        /// X - 移动后机器人在基坐标系下的 X；
        /// Y - 移动后机器人在基坐标系下的 Y；
        /// U - 移动后机器人的朝向（工具角度）。
        /// </returns>
        Task<(bool IsSuccess, double X, double Y, double U)> AutoMoveRobotToImageCenter(IRobot robot, Matrix<double> matrix, double PixelScaleX, double PixelScaleY, CancellationToken cancellationToken);

        /// <summary>
        /// 自动九点标定。
        /// 使用 9 个采样点进行仿射/透视变换求解，以提高标定精度并生成验证用的九点数据结构。
        /// </summary>
        /// <param name="calibrationInfo">九点标定的配置信息（点列、采集顺序、图像处理参数等）。</param>
        /// <param name="robot">机器人接口。</param>
        /// <param name="cancellationToken">用于取消操作的标记。</param>
        /// <returns>
        /// 元组字段：
        /// IsSuccess - 标定是否成功；
        /// AffineTransformationMaterial - 求解得到的仿射变换矩阵；
        /// NinePoint - 九点标定结果封装（像素点与对应的机器人位姿）；
        /// Result - 详细的标定结果与统计信息（误差、残差等）。
        /// </returns>
        Task<(bool IsSuccess, Matrix<double> AffineTransformationMaterial, RobotPixelPoint[] NinePoint, CalibrationResult Result)> AutoNinePointCalibration(CalibrationInfo calibrationInfo, IRobot robot, CancellationToken cancellationToken);

        /// <summary>
        /// 执行校准验证。
        /// 使用当前标定参数在一组验证点上计算误差并返回测试结果，用于评估标定质量。
        /// </summary>
        /// <param name="calibrationInfo">用于验证的点集与验收标准配置。</param>
        /// <param name="robot">机器人接口，用于在验证过程中获取或移动到参考位姿。</param>
        /// <param name="cancellationToken">用于取消操作的标记。</param>
        /// <returns>元组字段：IsSuccess 表示验证是否通过；Result 包含详细的验证统计与误差分析。</returns>
        Task<(bool IsSuccess, CalibrationTestResult Result)> ExecuteCalibrationValidation(CalibrationInfo calibrationInfo, IRobot robot, CancellationToken cancellationToken);

    }
}