## XplorePlane 平面CT软件

### 系统目标

XplorePlane 系统用于控制平面 CT 设备的各个子系统（射线源、探测器、运动控制、相机）并完成采集图像的处理与分析，为研发与调试提供统一的软件平台。

### 总体架构

- 客户端框架: WPF + Prism MVVM（目标框架 net8.0-windows）
- 图像处理内核: `XP.ImageProcessing.Processors`，基于 Emgu.CV
  - `Core/`：包含 `ImageProcessorBase`、`ProcessorParameter` 及 ROI/对齐等核心模型和算子基类
  - 各功能目录：包含图像变换、滤波、增强、边缘检测、检测分析和模板匹配等具体算子
  - `ImageProcessingService`：负责算子程序集扫描、反射发现、注册及执行
  - 统一使用 16 位图像处理通道，并通过适配器兼容 8 位算子
- 相机控制: XP.Camera（Basler pylon SDK 封装，支持软件触发、参数读写）
- 硬件抽象: XP.Common + XP.Hardware.RaySource（射线源控制）
- 日志: Serilog
- UI 组件: Telerik RadRibbonView、Fluent.Ribbon

### 解决方案结构

```
XplorePlane.sln
├── XplorePlane/                         # 主应用程序（WPF + Prism）
├── XP.Common/                           # 公共基础库：日志、数据库、Dump、通用控件等
├── XP.Camera/                           # 相机控制库（Basler / Hikvision 等）
├── XP.Hardware.Detector/                # 探测器硬件抽象与实现
├── XP.Hardware.MotionControl/           # 运动控制模块
├── XP.Hardware.PLC/                     # PLC 通信模块
├── XP.Hardware.PLC.Sentry/              # PLC 信号监控 / Sentry 工具
├── XP.Hardware.RaySource/               # 射线源控制模块
├── XP.Hardware.RaySource.Comet.Host/    # Comet 射线源独立 Host 进程
├── XP.Hardware.RaySource.Comet.Messages/# Comet Host 通信消息定义
├── XP.ImageProcessing.Processors/       # 图像处理核心与具体算子实现
│   ├── Core/                            # 算子基类、参数模型、ROI/对齐模型
│   ├── 图像变换/                         # 灰度、旋转、镜像、阈值等
│   ├── 滤波处理/                         # 滤波算子
│   ├── 图像增强/                         # 增强算子
│   ├── 边缘检测/                         # 边缘检测算子
│   ├── 检测分析/                         # BGA、QFN、空洞率及测量算子
│   └── 定位识别/                         # 模板匹配和定位算子
├── XP.ImageProcessing.RoiControl/       # ROI 绘制与测量控件
├── XP.Scan/                             # 扫描模式相关模块
├── XP.Calibration/                      # 校准模块
├── XP.ReportEngine/                     # 报告生成模块
├── XplorePlane.Tests/                   # 单元测试项目（不一定参与当前 sln 构建）
├── ExternalLibraries/                   # 外部 DLL、模板、模型等运行依赖
├── ReleaseFiles/                        # 已整理的发布文件快照
└── bin/                                 # 当前主程序构建输出目录（由 XplorePlane.csproj 配置）
```

> 当前主程序 [XplorePlane/XplorePlane.csproj](XplorePlane/XplorePlane.csproj) 通过 `BaseOutputPath=..\bin\` 将输出放在解决方案根目录的 `bin/` 下，而不是 `XplorePlane/bin/` 下。`XP.App/` 是旧输出路径，不再作为当前主程序输出目录使用。

### 运行时目录与数据存储

运行时产生的数据统一放在源码仓库外的 `D:\XPData`，避免数据库、日志、采集图像、Dump 和报告污染 `D:\XplorePlane` 源码目录。

XPData 的分类结构以文档末尾的 [XPData 分类](#xpdata-分类) 为准，本节只说明运行时根目录和配置，不再重复列出目录树。

默认配置见 [XplorePlane/App.config](XplorePlane/App.config)：

```xml
<add key="XpData:RootPath" value="D:\XPData" />
<add key="Serilog:LogPath" value="D:\XPData\Runtime\Diagnostics\Logs" />
<add key="Sqlite:DbFilePath" value="D:\XPData\Runtime\DataBase\XP.db" />
<add key="Detector:SavePath" value="D:\XPData\Results\DetectorImages" />
<add key="Dump:StoragePath" value="D:\XPData\Runtime\Diagnostics\Dumps" />
<add key="Report:OutputDirectory" value="D:\XPData\Results\Reports" />
```

`XplorePlane.Services.Storage.XpDataPathService` 会确保上述受管目录存在。发布目录 [ReleaseFiles/](ReleaseFiles/) 中的 `App.config` 与 `XplorePlane.dll.config` 也应保持同样的运行时路径。

源码目录下旧的运行数据目录（如 `DataBase/XP.db`、`DetectorImages/`、`Diagnostics/`、`Reports/`）不应提交到 Git，已在 [.gitignore](.gitignore) 中忽略。

### 项目专用文件格式

项目文件使用专用后缀区分 CNC 程序、图像处理流水线和检测方案，当前约定如下：

| 后缀 | 类型 | 作用 |
|---|---|---|
| `.xpcnc` | CNC 程序文件 | 保存 CNC 节点序列、运动控制、图像采集、检测和执行流程。 |
| `.xppipe` | 图像处理流水线文件 | 保存图像处理算子及其参数，用于实时图像处理、检测识别和配方复用。 |
| `.xppool` | 检测池任务计划 | 保存检测池场景的 Ball 分析、Block 分组、编号规则、采集计划和判定参数，可作为 CNC 中的检测池任务子程序使用。 |
| `.xpmap` | 检测地图文件 | 保存检测位置、坐标映射及相关检测区域信息。 |
| `.xpmatrix` | CNC 检测矩阵文件 | 保存 CNC 程序的矩阵编排、阵列布局及其关联程序配置。 |
| `.xpz` | CNC 可移植打包文件 | 用于迁移 CNC 程序及其图像、模板等资源；包内程序文件名为 `program.xpcnc`，同时包含 `manifest.json`。 |

其中，`.xppipe` 负责图像处理与识别，`.xppool` 负责检测池任务编排，`.xpcnc` 负责完整 CNC 执行流程；三者职责不同，不应混用。

### XplorePlane 主项目结构

```
XplorePlane/
├── App.xaml / App.xaml.cs          # 应用入口 + DI 容器配置（AppBootstrapper）
├── Views/
│   ├── Main/
│   │   ├── MainWindow.xaml         # 主窗口（Telerik Ribbon + 三栏布局）
│   │   ├── NavigationPropertyPanelView.xaml  # 相机实时预览面板
│   │   └── MotionControlPanelView.xaml       # 运动控制面板
│   ├── Cnc/                        # CNC 编辑器 / 矩阵编排视图
│   ├── ImageProcessing/            # 图像处理面板视图
│   └── CameraSettingsWindow.xaml   # 相机参数设置对话框
├── ViewModels/
│   ├── Main/
│   │   ├── MainViewModel.cs                      # 主窗口 ViewModel
│   │   └── NavigationPropertyPanelViewModel.cs   # 相机预览 ViewModel
│   ├── Cnc/                        # CNC / 矩阵 ViewModel
│   └── ImageProcessing/            # 图像处理 / 流水线 ViewModel
├── Services/
│   ├── AppState/                   # 全局状态管理（线程安全）
│   ├── Camera/                     # 相机服务
│   ├── Cnc/                        # CNC 程序服务
│   ├── Matrix/                     # 矩阵编排服务
│   ├── Measurement/                # 测量数据服务
│   ├── Pipeline/                   # 流水线执行 / 持久化
│   └── Recipe/                     # 检测配方服务
├── Models/                         # 数据模型（State、CNC、Matrix、Pipeline 等）
├── Events/                         # Prism 事件
├── Libs/
│   ├── Hardware/                   # 硬件库 DLL（XP.Common、XP.Hardware.RaySource）
│   └── Native/                     # 原生依赖库
└── Assets/Icons/                   # 工具栏图标
```

### 相机集成

相机实时影像集成在主窗口左下角的 NavigationPropertyPanelView 中：

- 连接/断开相机（Basler，通过 ICameraController）
- 开始/停止采集（软件触发模式）
- 实时预览（Live View，勾选"实时"复选框）
- 鼠标悬停显示像素坐标
- 相机参数设置对话框（曝光时间、增益、分辨率、像素格式）
- 主界面 Ribbon 硬件栏提供"相机设置"快捷按钮

相机控制逻辑移植自 ImageProcessing 项目，使用 XP.Camera.PixelConverter 进行像素数据转换，通过 Application.Dispatcher.Invoke 保证 UI 线程安全。

### 依赖注入（DI）

使用 Prism + DryIoc，在 AppBootstrapper.RegisterTypes() 中统一注册：

- ICameraFactory / ICameraController / ICameraService（单例）
- IRaySourceService / IRaySourceFactory（单例）
- IAppStateService（单例，线程安全状态管理）
- NavigationPropertyPanelViewModel（单例，相机预览共享实例）
- 各 Service 和 ViewModel（按需注册）

### 构建与输出

本解决方案采用“入口程序、硬件与 Native 依赖项目固定 x64，纯托管类库保持 Any CPU”的平台策略，避免一刀切把所有类库强制为 x64。

[ReleaseFiles/](ReleaseFiles/) 是发布文件快照，不是普通编译输出目录；清理或更新运行依赖时需要同步检查该目录。

```bash
# Debug
dotnet build XplorePlane.sln -c Debug -p:Platform=x64

# Release
dotnet build XplorePlane.sln -c Release -p:Platform=x64

# 只构建主程序
dotnet build XplorePlane/XplorePlane.csproj -c Release -p:Platform=x64
```

当前解决方案面向 x64 平台，主程序输出目录由 [XplorePlane/XplorePlane.csproj](XplorePlane/XplorePlane.csproj) 配置为：

```text
D:\XplorePlane\bin\<Platform>\<Configuration>\net8.0-windows\win-x64\
```

当前 Debug 生成目录格式：

```text
D:\XplorePlane\bin\x64\Debug\net8.0-windows\win-x64\
```

当前生成目录结构：

```text
D:\XplorePlane\bin\
└── x64\
    └── Debug\
        └── net8.0-windows\
            └── win-x64\
                ├── XplorePlane.exe
                ├── XplorePlane.dll
                ├── XplorePlane.dll.config
                ├── Host\                    # Comet Host 输出目录
                ├── runtimes\                # NuGet / runtime 原生依赖
                └── ...                      # 其他程序集、资源与运行依赖
```

Comet Host 编译后会复制到当前主程序输出目录的 `Host/` 子目录：

```text
D:\XplorePlane\bin\x64\Debug\net8.0-windows\win-x64\Host\
```

### 平台配置策略


### 检测池持久化约定

`PoolTaskPlan` 是检测池唯一的持久化模型，正式计划统一保存到 `D:\\XPData\\Plans\\InspectionPool\\*.xppool`。`InspectionDefinition` 只在运行时由计划映射生成，不再写入独立 `Definitions` 目录。`D:\\XPData\\Results\\Inspection\\PoolRuns\\{TaskId}` 保存任务运行记录；`Legacy\\GeneratedDefinitions` 仅归档历史生成文件，不参与 CNC 插入列表。

### XPData 分类

```text
D:\XPData
├── Runtime\
│   ├── DataBase\       # SQLite 数据库，例如 XP.db
│   ├── Calibration\    # 标定数据
│   └── Diagnostics\    # Logs / Dumps 故障诊断数据
├── Plans\
│   ├── CncPrograms\    # .xpcnc / .xpz CNC 程序及迁移包
│   ├── Pipelines\      # .xppipe 图像处理流水线
│   └── InspectionPool\ # 检测池计划及运行配置
├── Assets\
│   ├── Templates\      # 模板资源
│   ├── Models\         # 算法模型
│   └── References\     # 其他参考资源
└── Results\
    ├── Inspection\    # CNC / 检测池 / 矩阵执行结果
    ├── DetectorImages\ # 探测器采集图像
    ├── Reports\        # 报告输出
    └── Video\          # 录制视频
```

### 版本记录

- [查看 XplorePlane 版本变更说明](ReleaseFiles/XplorePlane-ReleaseNotes.html)
- [版本记录网页源码](doc/release-notes/index.html)

### TO-DO List

- [x] 软件基于 WPF + Prism 基础的框架
- [x] 日志库的引用（通过 XP.Common.dll）
- [x] 按推荐的 DLL 目录结构进行修改
- [x] 通过库依赖的方式调用日志功能
- [x] 界面的布局
- [x] 相机实时影像集成（连接、采集、Live View、像素坐标显示）
- [x] 相机参数设置对话框（曝光、增益、分辨率、像素格式）
- [x] 主界面硬件栏相机设置按钮
- [x] 打通与硬件层的调用流程
- [x] 打通与图像层的调用流程
- [ ] CNC的执行、存储逻辑的开发测试
- [ ] 涉及到图像校准，矩阵