# XP.Hardware.Detector 工业探测器控制模块 | Industrial Detector Control Module --- ## 项目概述 | Project Overview XP.Hardware.Detector 是 XplorePlane X 射线检测系统的探测器控制模块，负责与工业 X 射线探测器进行通讯和控制。该模块采用策略模式和工厂模式设计，支持多种探测器型号的统一管理，提供完整的图像采集和校正功能。 ### 主要特性 | Key Features - 支持多种探测器型号（Varex、iRay、Hamamatsu 等） - 完整的探测器生命周期管理（初始化、采集、校正） - 单帧和连续采集模式 - 自动校正功能（暗场、增益、坏像素） - 实时状态监控 - 基于 Prism 事件聚合器的松耦合跨模块通讯 - 异步操作，不阻塞 UI 线程 - 完整的日志记录和异常处理 --- ## 框架架构 | Architecture ``` XP.Hardware.Detector/ ├── Abstractions/ # 抽象层 | Abstraction Layer │ ├── IAreaDetector.cs # 面阵探测器接口 │ ├── AreaDetectorBase.cs # 抽象基类 │ ├── DetectorResult.cs # 结果封装类 │ ├── DetectorInfo.cs # 探测器信息 │ ├── Enums/ # 枚举定义 │ │ ├── DetectorStatus.cs │ │ └── DetectorType.cs │ └── Events/ # Prism 事件定义 │ ├── ImageCapturedEvent.cs │ └── CorrectionCompletedEvent.cs ├── Implementations/ # 实现层 | Implementation Layer │ ├── VarexDetector.cs # Varex 探测器实现 │ └── IRayDetector.cs # iRay 探测器实现 ├── Factories/ # 工厂层 | Factory Layer │ ├── IDetectorFactory.cs # 工厂接口 │ └── DetectorFactory.cs # 探测器工厂 ├── Services/ # 业务服务层 | Service Layer │ ├── IDetectorService.cs # 服务接口 │ └── DetectorService.cs # 服务实现（单例） ├── Config/ # 配置层 | Configuration Layer │ ├── DetectorConfig.cs # 配置实体 │ ├── VarexDetectorConfig.cs │ ├── IRayDetectorConfig.cs │ └── ConfigLoader.cs # 配置加载器 ├── Module/ # Prism 模块 | Prism Module │ └── DetectorModule.cs # 模块注册 ├── ViewModels/ # 视图模型 | View Models └── Views/ # WPF 视图 | WPF Views ``` ### 设计模式 | Design Patterns - **策略模式**：`IAreaDetector` 接口定义统一操作，支持多种设备实现 - **工厂模式**：`IDetectorFactory` 根据设备类型动态创建实例 - **模板方法模式**：`AreaDetectorBase` 提供基础实现框架 - **单例模式**：`IDetectorService` 作为全局单例管理设备状态 - **依赖注入**：通过 Prism 容器管理服务生命周期 - **事件聚合器**：使用 Prism `IEventAggregator` 实现松耦合通讯 - **异步模式**：所有 I/O 操作采用 async/await --- ## 核心功能 | Core Features ### 1. 探测器初始化 | Detector Initialization ```csharp // 初始化探测器 DetectorResult result = await _detectorService.InitializeAsync(); if (result.IsSuccess) { // 获取探测器信息 DetectorInfo info = _detectorService.GetInfo(); Console.WriteLine($"型号: {info.Model}, 分辨率: {info.MaxWidth}x{info.MaxHeight}"); } ``` ### 2. 图像采集 | Image Acquisition ```csharp // 单帧采集 await _detectorService.AcquireSingleFrameAsync(); // 启动连续采集 await _detectorService.StartAcquisitionAsync(); // 停止采集 await _detectorService.StopAcquisitionAsync(); ``` ### 3. 自动校正 | Auto Correction ```csharp // 执行自动校正（暗场+增益+坏像素） await _detectorService.AutoCorrectionAsync(frameCount: 10); ``` ### 4. 状态监控 | Status Monitoring ```csharp // 检查探测器状态 DetectorStatus status = _detectorService.Status; // 获取错误信息 DetectorResult error = _detectorService.GetLastError(); ``` ### 5. 事件通讯 | Event Communication ```csharp // 订阅图像采集事件 _eventAggregator.GetEvent() .Subscribe(OnImageCaptured, ThreadOption.UIThread); // 订阅校正完成事件 _eventAggregator.GetEvent() .Subscribe(OnCorrectionCompleted, ThreadOption.UIThread); ``` --- ## 技术要求 | Technical Requirements ### 运行环境 | Runtime Environment - **.NET 8.0** (net8.0-windows7.0) - **Windows 操作系统**（WPF 依赖） - **Visual Studio 2022** 或更高版本 ### 核心依赖 | Core Dependencies | 依赖库 | 版本 | 用途 | |--------|------|------| | **Prism.Wpf** | 9.0.537 | MVVM 框架和依赖注入 | | **Serilog** | - | 结构化日志记录 | | **System.Configuration.ConfigurationManager** | - | 配置文件管理 | | **探测器 SDK** | - | 厂商提供的探测器驱动库 | ### 硬件要求 | Hardware Requirements - 支持的探测器型号： - Varex（当前支持） - iRay（预留） - Hamamatsu（预留） - 网络连接：TCP/IP 或 USB - 探测器驱动和 SDK --- ## 快速开始 | Quick Start ### 1. 配置文件设置 在 `App.config` 中添加： ```xml ``` ### 2. 注册模块 在 `App.xaml.cs` 中： ```csharp protected override void ConfigureModuleCatalog(IModuleCatalog moduleCatalog) { moduleCatalog.AddModule(); } ``` ### 3. 使用服务 在 ViewModel 中注入并使用： ```csharp public class YourViewModel : BindableBase { private readonly IDetectorService _detectorService; private readonly IEventAggregator _eventAggregator; public YourViewModel( IDetectorService detectorService, IEventAggregator eventAggregator) { _detectorService = detectorService; _eventAggregator = eventAggregator; SubscribeEvents(); } public async Task InitializeAsync() { DetectorResult result = await _detectorService.InitializeAsync(); if (result.IsSuccess) { // 初始化成功 } } } ``` --- ## 配置参数说明 | Configuration Parameters | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | Type | string | Varex | 探测器类型 | | IP | string | 192.168.1.200 | 探测器 IP 地址 | | Port | int | 50000 | 探测器端口号 | | SavePath | string | D:\Images | 图像存储路径 | | AutoSave | bool | true | 是否自动保存图像 | --- ## 探测器状态 | Detector Status ```csharp public enum DetectorStatus { Uninitialized = 0, // 未初始化 Initializing = 1, // 初始化中 Ready = 2, // 就绪 Acquiring = 3, // 采集中 Correcting = 4, // 校正中 Error = 5 // 错误 } ``` --- ## 异常处理 | Exception Handling 所有操作返回 `DetectorResult` 对象： ```csharp DetectorResult result = await _detectorService.AcquireSingleFrameAsync(); if (result.IsSuccess) { // 操作成功 } else { // 操作失败 string error = result.ErrorMessage; int errorCode = result.ErrorCode; Exception exception = result.Exception; _logger.Error(exception, $"操作失败: {error}, 错误码: {errorCode}"); } ``` --- ## 日志记录 | Logging 模块使用 Serilog 进行结构化日志记录： - **Debug**：详细的调试信息（帧采集、状态变化等） - **Info**：一般信息（初始化成功、采集开始等） - **Warn**：警告信息（状态异常、参数警告等） - **Error**：错误信息（操作失败、通讯异常等） - **Fatal**：致命错误（系统崩溃等） --- ## 资源释放 | Resource Disposal 在应用退出时探测器会自动停止采集并释放资源： ```csharp protected override void OnExit(ExitEventArgs e) { var detectorService = Container.Resolve(); // 服务会自动释放资源 base.OnExit(e); } ``` --- ## 扩展性 | Extensibility ### 添加新的探测器设备 1. 在 `Implementations/` 创建新类继承 `AreaDetectorBase` 2. 实现所有抽象方法 3. 在 `DetectorFactory.CreateDetector()` 添加新类型分支 4. 在配置文件中添加设备配置 ```csharp public class NewDetector : AreaDetectorBase { public override async Task InitializeAsync(CancellationToken cancellationToken = default) { // 实现初始化逻辑 } // 实现其他抽象方法... } ``` --- ## 文档索引 | Documentation Index - **[GUIDENCE.md](./GUIDENCE.md)** - 详细使用指南，包含完整代码示例 - **[README.md](./README.md)** - 本文档，项目概述和快速参考 - **[App.config.example](./App.config.example)** - 配置文件示例 --- ## 故障排查 | Troubleshooting ### 初始化失败 - 检查探测器 IP 地址和端口配置 - 确认探测器网络连接正常 - 验证探测器驱动已正确安装 ### 采集失败 - 确认已成功初始化 - 检查探测器状态是否为 `Ready` - 执行自动校正 ### 校正失败 - 确认探测器状态为 `Ready` - 增益校正前确保射线源已开启 - 增加采集帧数（建议 10 帧以上） 详细故障排查请参考 [GUIDENCE.md](./GUIDENCE.md) 第 13 节。 --- **最后更新 | Last Updated**: 2026-03-11