QI MingxuanXP.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
// 初始化探测器
DetectorResult result = await _detectorService.InitializeAsync();
if (result.IsSuccess)
{
// 获取探测器信息
DetectorInfo info = _detectorService.GetInfo();
Console.WriteLine($"型号: {info.Model}, 分辨率: {info.MaxWidth}x{info.MaxHeight}");
}
2. 图像采集 | Image Acquisition
// 单帧采集
await _detectorService.AcquireSingleFrameAsync();
// 启动连续采集
await _detectorService.StartAcquisitionAsync();
// 停止采集
await _detectorService.StopAcquisitionAsync();
3. 自动校正 | Auto Correction
// 执行自动校正（暗场+增益+坏像素）
await _detectorService.AutoCorrectionAsync(frameCount: 10);
4. 状态监控 | Status Monitoring
// 检查探测器状态
DetectorStatus status = _detectorService.Status;
// 获取错误信息
DetectorResult error = _detectorService.GetLastError();
5. 事件通讯 | Event Communication
// 订阅图像采集事件
_eventAggregator.GetEvent<ImageCapturedEvent>()
.Subscribe(OnImageCaptured, ThreadOption.UIThread);
// 订阅校正完成事件
_eventAggregator.GetEvent<CorrectionCompletedEvent>()
.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 中添加：
<appSettings>
<!-- 探测器类型 -->
<add key="Detector:Type" value="Varex" />
<!-- 网络配置 -->
<add key="Detector:IP" value="192.168.1.200" />
<add key="Detector:Port" value="50000" />
<!-- 图像存储配置 -->
<add key="Detector:SavePath" value="D:\Images" />
<add key="Detector:AutoSave" value="true" />
</appSettings>
2. 注册模块
在 App.xaml.cs 中：
protected override void ConfigureModuleCatalog(IModuleCatalog moduleCatalog)
{
moduleCatalog.AddModule<DetectorModule>();
}
3. 使用服务
在 ViewModel 中注入并使用：
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
public enum DetectorStatus
{
Uninitialized = 0, // 未初始化
Initializing = 1, // 初始化中
Ready = 2, // 就绪
Acquiring = 3, // 采集中
Correcting = 4, // 校正中
Error = 5 // 错误
}
异常处理 | Exception Handling
所有操作返回 DetectorResult 对象：
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
在应用退出时探测器会自动停止采集并释放资源：
protected override void OnExit(ExitEventArgs e)
{
var detectorService = Container.Resolve<IDetectorService>();
// 服务会自动释放资源
base.OnExit(e);
}
扩展性 | Extensibility
添加新的探测器设备
- 在
Implementations/创建新类继承AreaDetectorBase - 实现所有抽象方法
- 在
DetectorFactory.CreateDetector()添加新类型分支 - 在配置文件中添加设备配置
public class NewDetector : AreaDetectorBase
{
public override async Task<DetectorResult> InitializeAsync(CancellationToken cancellationToken = default)
{
// 实现初始化逻辑
}
// 实现其他抽象方法...
}
文档索引 | Documentation Index
- GUIDENCE.md - 详细使用指南，包含完整代码示例
- README.md - 本文档，项目概述和快速参考
- App.config.example - 配置文件示例
故障排查 | Troubleshooting
初始化失败
- 检查探测器 IP 地址和端口配置
- 确认探测器网络连接正常
- 验证探测器驱动已正确安装
采集失败
- 确认已成功初始化
- 检查探测器状态是否为
Ready - 执行自动校正
校正失败
- 确认探测器状态为
Ready - 增益校正前确保射线源已开启
- 增加采集帧数（建议 10 帧以上）
详细故障排查请参考 GUIDENCE.md 第 13 节。
最后更新 | Last Updated: 2026-03-11