using System;
using System.Threading.Tasks;
using OpenCvSharp;
using TeamAAS_VP.Models;

namespace TeamAAS_VP.Interfaces
{
    /// <summary>
    /// 提供相机标定与像素坐标系/机器人坐标系变换的服务接口。
    /// 注意：此接口只定义方法签名与文档，具体算法与实现由实现类提供。
    /// </summary>
    public interface ICameraCalibrationService : IDisposable
    {
        /// <summary>
        /// 使用一组棋盘格或标定图像执行相机标定。返回是否成功。
        /// </summary>
        /// <param name="images">用于标定的灰度或彩色图像阵列。</param>
        /// <param name="patternSize">棋盘格内角点数（cols, rows）。</param>
        /// <param name="squareSize">物理上每格的尺寸（单位：毫米或用户约定单位）。</param>
        /// <returns>如果标定成功，返回标定结果对象；否则返回 null 或抛出异常（视实现而定）。</returns>
        Task<CameraCalibrationResult> CalibrateAsync(Mat[] images, OpenCvSharp.Size patternSize, double squareSize);

        /// <summary>
        /// 根据已标定的相机参数，将像素坐标转换到相机坐标系（例如相机局部三维坐标）。
        /// </summary>
        /// <param name="pixel">像素坐标（x,y）。</param>
        /// <param name="depth">该像素的深度（或Z）值，若无则由实现者定义默认行为。</param>
        /// <returns>相机坐标系下的三维点。</returns>
        System.Numerics.Vector3 PixelToCameraPoint(System.Numerics.Vector2 pixel, double depth = 1.0);

        /// <summary>
        /// 将相机坐标系中的三维点变换到机器人坐标系，使用当前估计的外参/变换矩阵。
        /// </summary>
        /// <param name="cameraPoint">相机坐标系三维点。</param>
        /// <returns>机器人坐标系三维点。</returns>
        System.Numerics.Vector3 CameraToRobotPoint(System.Numerics.Vector3 cameraPoint);

        /// <summary>
        /// 将机器人坐标系中的三维点变换到相机坐标系。
        /// </summary>
        /// <param name="robotPoint">机器人坐标系三维点。</param>
        /// <returns>相机坐标系三维点。</returns>
        System.Numerics.Vector3 RobotToCameraPoint(System.Numerics.Vector3 robotPoint);

        /// <summary>
        /// 估算相机中心（相机在机器人坐标系下的位置），通常基于标定得到的外参或一组已知对应点。
        /// </summary>
        /// <returns>机器人坐标系下的相机中心位置。</returns>
        System.Numerics.Vector3 EstimateCameraCenter();

        /// <summary>
        /// 获取当前标定结果（如果存在）。
        /// </summary>
        CameraCalibrationResult CurrentCalibration { get; }

        /// <summary>
        /// 清除/重置当前的标定结果与内部状态。
        /// </summary>
        void Reset();
    }
}