QI Mingxuan
357 lines
9.5 KiB
Markdown
357 lines
9.5 KiB
Markdown
# 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<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` 中添加：
|
||
|
||
```xml
|
||
<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` 中：
|
||
|
||
```csharp
|
||
protected override void ConfigureModuleCatalog(IModuleCatalog moduleCatalog)
|
||
{
|
||
moduleCatalog.AddModule<DetectorModule>();
|
||
}
|
||
```
|
||
|
||
### 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<IDetectorService>();
|
||
// 服务会自动释放资源
|
||
|
||
base.OnExit(e);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 扩展性 | Extensibility
|
||
|
||
### 添加新的探测器设备
|
||
|
||
1. 在 `Implementations/` 创建新类继承 `AreaDetectorBase`
|
||
2. 实现所有抽象方法
|
||
3. 在 `DetectorFactory.CreateDetector()` 添加新类型分支
|
||
4. 在配置文件中添加设备配置
|
||
|
||
```csharp
|
||
public class NewDetector : AreaDetectorBase
|
||
{
|
||
public override async Task<DetectorResult> 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
|