using System;
using System.Threading;
using System.Threading.Tasks;
using XP.Hardware.Detector.Abstractions.Enums;

namespace XP.Hardware.Detector.Abstractions
{
    /// <summary>
    /// 面阵探测器通用接口 | Area detector common interface
    /// 定义所有探测器必须实现的核心能力
    /// </summary>
    public interface IAreaDetector : IDisposable
    {
        /// <summary>
        /// 探测器状态 | Detector status
        /// </summary>
        DetectorStatus Status { get; }

        /// <summary>
        /// 探测器类型 | Detector type
        /// </summary>
        DetectorType Type { get; }

        /// <summary>
        /// 初始化探测器 | Initialize detector
        /// </summary>
        /// <param name="cancellationToken">取消令牌 | Cancellation token</param>
        /// <returns>操作结果 | Operation result</returns>
        Task<DetectorResult> InitializeAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// 启动连续采集 | Start continuous acquisition
        /// </summary>
        /// <param name="cancellationToken">取消令牌 | Cancellation token</param>
        /// <returns>操作结果 | Operation result</returns>
        Task<DetectorResult> StartAcquisitionAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// 停止采集 | Stop acquisition
        /// </summary>
        /// <param name="cancellationToken">取消令牌 | Cancellation token</param>
        /// <returns>操作结果 | Operation result</returns>
        Task<DetectorResult> StopAcquisitionAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// 单帧采集 | Single frame acquisition
        /// </summary>
        /// <param name="cancellationToken">取消令牌 | Cancellation token</param>
        /// <returns>操作结果 | Operation result</returns>
        Task<DetectorResult> AcquireSingleFrameAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// 暗场校正 | Dark field correction
        /// </summary>
        /// <param name="frameCount">采集帧数 | Frame count</param>
        /// <param name="cancellationToken">取消令牌 | Cancellation token</param>
        /// <returns>操作结果 | Operation result</returns>
        Task<DetectorResult> DarkCorrectionAsync(int frameCount, CancellationToken cancellationToken = default);

        /// <summary>
        /// 增益校正（亮场校正）| Gain correction (bright field correction)
        /// </summary>
        /// <param name="frameCount">采集帧数 | Frame count</param>
        /// <param name="cancellationToken">取消令牌 | Cancellation token</param>
        /// <returns>操作结果 | Operation result</returns>
        Task<DetectorResult> GainCorrectionAsync(int frameCount, CancellationToken cancellationToken = default);

        /// <summary>
        /// 自动校正（暗场+增益+坏像素）| Auto correction (dark + gain + bad pixel)
        /// </summary>
        /// <param name="frameCount">采集帧数 | Frame count</param>
        /// <param name="cancellationToken">取消令牌 | Cancellation token</param>
        /// <returns>操作结果 | Operation result</returns>
        Task<DetectorResult> AutoCorrectionAsync(int frameCount, CancellationToken cancellationToken = default);

        /// <summary>
        /// 坏像素校正 | Bad pixel correction
        /// </summary>
        /// <param name="cancellationToken">取消令牌 | Cancellation token</param>
        /// <returns>操作结果 | Operation result</returns>
        Task<DetectorResult> BadPixelCorrectionAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// 获取探测器信息 | Get detector information
        /// </summary>
        /// <returns>探测器信息 | Detector information</returns>
        DetectorInfo GetInfo();

        /// <summary>
        /// 应用探测器参数（Binning/PGA/帧率）| Apply detector parameters (Binning/PGA/FrameRate)
        /// </summary>
        /// <param name="binningIndex">Binning 索引 | Binning index</param>
        /// <param name="pga">PGA 灵敏度值 | PGA sensitivity value</param>
        /// <param name="frameRate">帧率 | Frame rate</param>
        /// <param name="cancellationToken">取消令牌 | Cancellation token</param>
        /// <returns>操作结果 | Operation result</returns>
        Task<DetectorResult> ApplyParametersAsync(int binningIndex, int pga, decimal frameRate, CancellationToken cancellationToken = default);

        /// <summary>
        /// 获取校正能力描述 | Get correction capabilities
        /// </summary>
        /// <returns>校正能力描述 | Correction capabilities</returns>
        CorrectionCapabilities GetCorrectionCapabilities();

        /// <summary>
        /// 显式失效校正数据（参数变更后调用）| Explicitly invalidate correction data (called after parameter change)
        /// </summary>
        void InvalidateCorrectionData();
    }
}