XplorePlane/XP.Hardware.Detector/Services/IDetectorService.cs

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

namespace XP.Hardware.Detector.Services
{
    /// <summary>
    /// 探测器服务接口 | Detector service interface
    /// 提供无厂商耦合的通用服务方法
    /// </summary>
    public interface IDetectorService : IDisposable
    {
        /// <summary>
        /// 当前探测器状态 | Current detector status
        /// </summary>
        DetectorStatus Status { get; }

        /// <summary>
        /// 当前探测器类型 | Current detector type
        /// </summary>
        DetectorType? Type { get; }

        /// <summary>
        /// 探测器是否已连接（已初始化）| Whether detector is connected (initialized)
        /// </summary>
        bool IsConnected { get; }

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

        /// <summary>
        /// 断开探测器连接 | Disconnect detector
        /// </summary>
        /// <returns>操作结果 | Operation result</returns>
        Task<DetectorResult> DisconnectAsync();

        /// <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 = 10, 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 = 10, 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>
        /// 执行自动校正（暗场+增益+坏像素）| Execute 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 = 10, CancellationToken cancellationToken = default);

        /// <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>
        /// 保存当前配置到文件 | Save current configuration to file
        /// </summary>
        /// <param name="binningIndex">Binning 索引 | Binning index</param>
        /// <param name="pga">PGA 灵敏度值 | PGA sensitivity value</param>
        /// <param name="frameRate">帧率 | Frame rate</param>
        /// <param name="avgFrames">帧合并数 | Average frame count</param>
        void SaveParameters(int binningIndex, int pga, decimal frameRate, int avgFrames);

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

        /// <summary>
        /// 获取最后的错误信息 | Get last error information
        /// </summary>
        /// <returns>错误结果 | Error result</returns>
        DetectorResult GetLastError();

        /// <summary>
        /// 获取当前探测器配置 | Get current detector configuration
        /// 用于 UI 层获取探测器类型相关的参数选项
        /// </summary>
        /// <returns>探测器配置，未初始化时返回 null | Detector config, null if not initialized</returns>
        DetectorConfig GetCurrentConfig();

        /// <summary>
        /// 获取当前探测器的校正能力描述 | Get correction capabilities of current detector
        /// </summary>
        /// <returns>校正能力描述，未初始化时返回默认值 | Correction capabilities, default if not initialized</returns>
        CorrectionCapabilities GetCorrectionCapabilities();
    }
}