# 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
