[XP.Hardware.MotionControl] 新增 CoordinateCompensation.md：完整描述载物台坐标系补偿功能（坐标模型、像素到 mm 换算、Replace/Accumulate 记录模式与示例、接口说明、调用流程、边界注意事项、源码位置）

[XP.Hardware.MotionControl] README 文档目录树补齐全部文档条目并加入 CoordinateCompensation.md

XP.Hardware.MotionControl/Documents/App.config.example

@@ -46,7 +46,20 @@
 		<!-- SwingRadius: Pivot 到探测器感光面中心的距离，为 0 时退化为无摆动模型 -->
 		<!-- SwingRadius: Distance from Pivot to detector active area center, 0 = no swing model -->
 		<add key="MotionControl:Geometry:SwingRadius" value="0" />
+		<!-- 探测器像素物理尺寸（mm），用于像素→载物台距离换算及坐标系补偿：mmPerPixel = PixelSize / M -->
+		<!-- Detector pixel physical size (mm), for pixel-to-stage mapping and coordinate compensation -->
+		<add key="MotionControl:Geometry:DetectorPixelSizeX" value="0.139" />
+		<add key="MotionControl:Geometry:DetectorPixelSizeY" value="0.139" />
+		<!-- 像素方向系数（+1 或 -1）：对齐图像像素坐标方向与载物台运动方向 -->
+		<!-- Pixel direction coefficients (+1 or -1): align image pixel direction with stage movement -->
+		<add key="MotionControl:Geometry:PixelDirectionX" value="1" />
+		<add key="MotionControl:Geometry:PixelDirectionY" value="-1" />
 		<!-- 运行参数 | Runtime parameters -->
 		<add key="MotionControl:PollingInterval" value="100" />
-		<add key="MotionControl:DefaultVelocity" value="500" />
+		<add key="MotionControl:DefaultVelocity" value="100" />
+		<!-- 射线源与探测器Z轴联动配置 | Source-Detector Z-axis linkage config -->
+		<add key="MotionControl:SourceDetectorZLinkage:Enabled" value="false" />
+		<add key="MotionControl:SourceDetectorZLinkage:TriggerThreshold" value="1.0" />
+		<add key="MotionControl:SourceDetectorZLinkage:SpeedPercent" value="100" />
   </appSettings>
+</configuration>

XP.Hardware.MotionControl/Documents/Calibration_README.md

@@ -258,10 +258,32 @@ public class AnotherViewModel
 }
 ```
 
+### 6.1 两种用途辨析：点击居中 vs 坐标系补偿 | Click-to-Center vs Coordinate Compensation
+
+`MoveStageByPixelOffset` 与坐标系补偿接口都基于相同的像素→mm 换算（内部统一由私有方法 `TryConvertPixelToStageMm` 计算），但用途不同：
+
+| 用途 | 接口 | 是否记录补偿 | 说明 |
+|------|------|--------------|------|
+| 点击居中 | `MoveStageByPixelOffset(dx, dy)` | 否 | 用户点击图像某点，一次性把该点移到中心，不影响后续运动 |
+| 坐标系补偿 | `ApplyPixelOffsetCompensation(dx, dy)` | 是 | 主框架坐标匹配后记录补偿并修正到位，后续定点运动可叠加补偿 |
+
+坐标系补偿的完整说明见 `MotionControl_Design.md` 第 14 节与 `GUIDENCE.md` 第 11 节。
+
 ---
 
 ## 7. 版本变更说明 | Change Log
 
+### v2.1（2026-07-28）
+
+**新增坐标系补偿功能**
+
+- **新增** `IMotionControlService` 坐标系补偿接口：`ApplyPixelOffsetCompensation`、`RecordPixelOffsetCompensation`、`GetStageCompensation`、`SetStageCompensation`、`ResetStageCompensation`
+- **新增** `CompensationMode` 枚举（`Replace` 默认 / `Accumulate`）
+- **新增** `StageCompensationChangedEvent` 事件
+- **变更** `MoveToTarget` / `MoveAllToTarget` 增加 `applyCompensation` 参数（默认 `false`），仅对 StageX/StageY 叠加补偿
+- **重构** 将 `MoveStageByPixelOffset` 的像素→mm 换算抽为私有方法 `TryConvertPixelToStageMm`，供补偿接口复用（对外行为不变）
+- 补偿功能复用现有几何配置，无需新增 App.config 参数
+
 ### v2.0（2026-07-01）
 
 **重大变更：从手动标定改为基于几何配置的直接计算**

XP.Hardware.MotionControl/Documents/CoordinateCompensation.md

@@ -0,0 +1,280 @@
+# 载物台坐标系补偿功能 | Stage Coordinate Compensation
+
+> 文档版本：v1.0
+> 创建日期：2026-07-28
+> 适用模块：XP.Hardware.MotionControl
+
+---
+
+## 1. 功能概述 | Overview
+
+在平面 CT 检测中，工件在载物台上的实际摆放位置常与程序假定的"名义位置"存在偏差。主框架通过图像坐标匹配可计算出工件当前的**像素偏移** `(dX, dY)`（可为负）。
+
+坐标系补偿功能负责：
+
+1. 将主框架传入的像素偏移换算为载物台的**物理位移（mm）**，记录为**补偿值**；
+2. 执行修正移动，使工件对齐到位；
+3. 后续任意"移动到名义位置"的指令，可选择**自动叠加**该补偿值，使工件在整个检测流程中持续对齐。
+
+补偿值在软件启动时初始化为 `(0, 0)`。
+
+---
+
+## 2. 坐标模型 | Coordinate Model
+
+### 2.1 补偿值的本质
+
+补偿值是载物台 `StageX / StageY` 坐标系上的一个**物理偏移向量（mm）**，表示"工件实际位置"与"程序名义位置"之间的差。
+
+作用链条：
+
+```
+名义 home 位置 → 工件特征在图像里偏了 (dX, dY) 像素
+      ↓ 按当前放大比换算
+需要载物台移动 (stageDx, stageDy) mm 才能把特征移正
+      ↓ 记录
+补偿值 comp = (stageDx, stageDy)
+      ↓ 后续
+"移动到名义位置 P" → 实际目标 = P + comp，工件特征始终对齐
+```
+
+### 2.2 为什么存 mm 而非像素
+
+像素偏移与放大比绑定，一旦放大比变化就失效；而**物理 mm 偏移代表工件的真实错位，与放大比无关**，在后续任何放大比下都成立。因此补偿值以 mm（Stage 坐标系）存储。
+
+### 2.3 作用范围
+
+补偿仅作用于 `StageX / StageY`。`SourceZ / DetectorZ / 旋转轴` 不参与补偿。
+
+---
+
+## 3. 像素 → mm 换算 | Pixel-to-mm Conversion
+
+补偿的换算逻辑与 `MoveStageByPixelOffset` 一致，内部统一由私有方法 `TryConvertPixelToStageMm` 实现：
+
+```
+mmPerPixelX = DetectorPixelSizeX / M
+mmPerPixelY = DetectorPixelSizeY / M
+dxMm = dxPixels × mmPerPixelX × PixelDirectionX
+dyMm = dyPixels × mmPerPixelY × PixelDirectionY
+```
+
+| 参数 | 来源 | 说明 |
+|------|------|------|
+| `DetectorPixelSizeX/Y` | App.config（`MotionControl:Geometry:*`） | 探测器单像素物理尺寸（mm），由探测器规格书获取 |
+| `PixelDirectionX/Y` | App.config | 对齐图像像素方向与载物台运动方向（+1 或 -1） |
+| `M` | `GetCurrentGeometry()` 实时计算 | 当前放大倍率（FDD / FOD） |
+
+换算失败的情形（返回失败结果）：
+- 探测器像素尺寸未配置（`DetectorPixelSizeX/Y <= 0`）
+- 当前放大倍率无效（`M` 为 NaN 或 `<= 0`）
+
+> 补偿功能**复用现有几何配置**，不引入新的 App.config 参数。
+
+---
+
+## 4. 记录模式 | Compensation Mode
+
+补偿的记录方式由 `CompensationMode` 枚举控制：
+
+| 模式 | 语义 | 适用场景 |
+|------|------|----------|
+| `Replace`（默认） | `comp = 本次换算值` | 每次都从同一名义参考位置测量、每位置只记录一次的**一次性对位** |
+| `Accumulate` | `comp += 本次换算值` | 在同一位置**迭代修正残差**的闭环逼近 |
+
+### 4.1 如何选择
+
+判断标准是**主框架每次传入的 `dX, dY` 代表什么**：
+
+- 传入的是"**这次还差多少**"（残差/增量）→ 用 `Accumulate`
+- 传入的是"**离名义原点一共差多少**"（绝对总量）→ 用 `Replace`
+
+### 4.2 覆盖模式的重要前提
+
+`ApplyPixelOffsetCompensation` 的移动为**相对移动**。覆盖模式假设"每次测量都从同一名义参考位置开始、每位置只调用一次"。
+
+若在同一位置**连续多次**修正而不回到参考位置，覆盖模式只保证补偿值不累积，但相对移动会重复叠加，导致物理位置与补偿值不一致。此时应改用 `Accumulate`。
+
+### 4.3 累加 vs 覆盖示例
+
+前提：`1 像素 = 0.01mm`（当前放大比下）。
+
+**场景 A：闭环迭代残差（用 Accumulate）** —— 每轮都在当前位置重新测残差：
+
+| 轮次 | 测得残差 | 换算 mm | 相对移动 | Accumulate comp | Replace comp |
+|------|------|------|------|------|------|
+| 第 1 轮 | +200px | +2.0mm | +2.0 | 2.0 ✓ | 2.0 |
+| 第 2 轮 | +30px | +0.3mm | +0.3 | **2.3 ✓** | 0.3 ✗ |
+| 第 3 轮 | +2px | +0.02mm | +0.02 | **2.32 ✓** | 0.02 ✗ |
+
+台子实际总共走了 2.32mm，只有累加能记成真实总偏移。
+
+**场景 B：绝对总量（用 Replace）** —— 每次都相对固定名义原点给出总偏移：
+
+| 时刻 | 测得总偏移 | 换算 mm | Accumulate comp | Replace comp |
+|------|------|------|------|------|
+| 第 1 次 | +200px | +2.0mm | 2.0 | 2.0 ✓ |
+| 第 2 次重测 | +205px | +2.05mm | 4.05 ✗ | **2.05 ✓** |
+
+第 2 次的 205px 已包含第一次的 200px，累加会重复计入。
+
+---
+
+## 5. 接口说明 | API Reference
+
+全部定义在 `IMotionControlService`（单例）。
+
+| 方法 | 说明 |
+|------|------|
+| `ApplyPixelOffsetCompensation(dxPixels, dyPixels, mode = Replace)` | 换算像素→mm，按模式记录补偿，并以相对移动方式驱动 StageX/StageY 修正到位（记录 + 移动，一步完成） |
+| `RecordPixelOffsetCompensation(dxPixels, dyPixels, mode = Replace)` | 仅换算并记录补偿，不移动（预览/仅计算） |
+| `GetStageCompensation()` | 返回当前补偿值 `(Xmm, Ymm)` |
+| `SetStageCompensation(xMm, yMm)` | 直接以物理量（mm）设置补偿值 |
+| `ResetStageCompensation()` | 补偿值清零 |
+| `MoveToTarget(axisId, target, speed = null, applyCompensation = false)` | 单轴定点移动；`applyCompensation = true` 时仅对 StageX/StageY 叠加补偿 |
+| `MoveAllToTarget(targets, applyCompensation = false)` | 多轴联动移动；`applyCompensation = true` 时仅对字典中的 StageX/StageY 目标叠加补偿 |
+
+### 5.1 补偿值生命周期
+
+- 补偿值随软件运行保持，存储在 `MotionControlService` 单例中。
+- **`HomeAll()` / `HomeAllAsync()` 回零不会清零补偿**，补偿的清零仅通过 `ResetStageCompensation()`。
+- 换工件、重新装夹时应由主框架显式调用 `ResetStageCompensation()`（覆盖模式下也可依赖新值直接冲掉旧值，但显式清零语义更明确）。
+
+### 5.2 边界校验
+
+`MoveToTarget` / `MoveAllToTarget` 叠加补偿后，**仍执行原有的 `Min/Max` 边界校验**。若补偿把目标推出行程范围，命令会被拒绝。
+
+### 5.3 线程安全
+
+补偿值以 `_compXmm / _compYmm` 字段存储，读写通过 `_compLock` 加锁保护，以应对轮询线程与 UI/命令线程的并发访问。
+
+### 5.4 事件通知
+
+补偿值被记录、设置或清零时，发布 `StageCompensationChangedEvent`：
+
+```csharp
+public record StageCompensationData(double Xmm, double Ymm);
+public class StageCompensationChangedEvent : PubSubEvent<StageCompensationData> { }
+```
+
+UI 可订阅该事件实时显示当前补偿量。
+
+---
+
+## 6. 典型调用流程 | Typical Usage
+
+### 6.1 主框架：坐标匹配后记录并修正
+
+```csharp
+public class CoordinateMatcher
+{
+    private readonly IMotionControlService _mc;
+
+    public CoordinateMatcher(IMotionControlService mc) => _mc = mc;
+
+    // 坐标匹配得到像素偏移后，一步完成"记录补偿 + 修正移动"（默认覆盖）
+    public void OnMatchCompleted(double dxPixels, double dyPixels)
+    {
+        var result = _mc.ApplyPixelOffsetCompensation(dxPixels, dyPixels);
+        if (!result.Success)
+            _log.Warn($"补偿失败：{result.ErrorMessage}");
+    }
+
+    // 同一位置迭代修正残差时，使用累加模式
+    public void OnResidualMatch(double dxPixels, double dyPixels)
+    {
+        _mc.ApplyPixelOffsetCompensation(dxPixels, dyPixels, CompensationMode.Accumulate);
+    }
+}
+```
+
+### 6.2 其他类库：定点移动叠加补偿
+
+```csharp
+// 单轴：仅 StageX/StageY 生效
+_mc.MoveToTarget(AxisId.StageX, 100.0, applyCompensation: true);
+_mc.MoveToTarget(AxisId.StageY, 50.0,  applyCompensation: true);
+
+// 多轴联动一次性带补偿
+_mc.MoveAllToTarget(new Dictionary<AxisId, double>
+{
+    { AxisId.StageX, 100.0 },
+    { AxisId.StageY, 50.0 }
+}, applyCompensation: true);
+```
+
+### 6.3 查询、设置与清零
+
+```csharp
+// 查询当前补偿值
+var (compX, compY) = _mc.GetStageCompensation();
+
+// 直接设置（如从历史记录恢复）
+_mc.SetStageCompensation(1.25, -0.80);
+
+// 换工件时清零
+_mc.ResetStageCompensation();
+```
+
+### 6.4 订阅补偿变化事件
+
+```csharp
+eventAggregator.GetEvent<StageCompensationChangedEvent>()
+    .Subscribe(data =>
+    {
+        // 更新 UI 显示
+        CompensationText = $"补偿: X={data.Xmm:F4}mm, Y={data.Ymm:F4}mm";
+    }, ThreadOption.UIThread);
+```
+
+---
+
+## 7. 点击居中 vs 坐标系补偿 | Click-to-Center vs Compensation
+
+两者基于相同的像素→mm 换算，但用途不同：
+
+| 用途 | 接口 | 是否记录补偿 | 说明 |
+|------|------|--------------|------|
+| 点击居中 | `MoveStageByPixelOffset(dx, dy)` | 否 | 用户点击图像某点，一次性把该点移到中心，不影响后续运动 |
+| 坐标系补偿 | `ApplyPixelOffsetCompensation(dx, dy)` | 是 | 坐标匹配后记录补偿并修正到位，后续定点运动可叠加补偿 |
+
+`MoveStageByPixelOffset` 保持原有行为不变，继续服务点击居中场景。
+
+---
+
+## 8. 边界与注意事项 | Edge Cases & Notes
+
+| 情况 | 处理方式 |
+|------|----------|
+| 探测器像素尺寸未配置 | 换算失败，返回 `MotionResult.Fail`，不记录、不移动 |
+| 当前放大倍率无效（NaN 或 ≤ 0） | 换算失败，返回 `MotionResult.Fail` |
+| 补偿后目标越界 | 移动被 `Min/Max` 边界校验拒绝 |
+| `SetStageCompensation` 传入 NaN/Infinity | 返回 `MotionResult.Fail`，补偿值不变 |
+| 回零（HomeAll） | 补偿值**不变**，需显式 `ResetStageCompensation()` 清零 |
+| 覆盖模式同位置连续修正 | 物理移动会重复叠加，应改用 `Accumulate` |
+
+---
+
+## 9. 相关代码位置 | Source Locations
+
+| 内容 | 文件 |
+|------|------|
+| 补偿模式枚举 | `Abstractions/Enums/CompensationMode.cs` |
+| 补偿变化事件 | `Abstractions/Events/StageCompensationChangedEvent.cs` |
+| 接口定义 | `Services/IMotionControlService.cs`（"坐标系补偿"区域） |
+| 实现（含 `TryConvertPixelToStageMm`、`_compXmm/_compYmm`、`_compLock`） | `Services/MotionControlService.cs`（"坐标系补偿"区域） |
+
+---
+
+## 10. 关联文档 | Related Documents
+
+| 文档 | 说明 |
+|------|------|
+| `MotionControl_Design.md` | 运动控制模块设计文档（第 14 节补偿设计） |
+| `GUIDENCE.md` | 外部集成指南（第 11 节坐标系补偿） |
+| `Calibration_README.md` | 像素-载物台映射子模块 |
+| `GeometryWithDetectorSwing.md` | FOD/FDD/放大倍率几何计算模型 |
+
+---
+
+**最后更新 | Last Updated**: 2026-07-28

XP.Hardware.MotionControl/Documents/GUIDENCE.md

@@ -215,6 +215,38 @@ public class YourController
         MotionResult result = _mc.MoveToSafePosition();  // 所有轴移动到配置的安全点
     }
 
+    // 坐标系补偿 | Coordinate compensation
+    // 主框架坐标匹配得到像素偏移 (dX, dY) 后，一步完成"记录补偿 + 修正移动"（默认覆盖模式）
+    // After coordinate matching, record compensation and perform corrective move in one step (Replace by default)
+    public void ApplyCompensation(double dxPixels, double dyPixels)
+    {
+        // 默认覆盖模式；同一位置迭代修正残差时用 CompensationMode.Accumulate
+        MotionResult result = _mc.ApplyPixelOffsetCompensation(dxPixels, dyPixels);
+
+        // 仅记录补偿、不移动（预览/仅计算）
+        _mc.RecordPixelOffsetCompensation(dxPixels, dyPixels);
+
+        // 查询当前补偿值（mm）
+        var (compX, compY) = _mc.GetStageCompensation();
+
+        // 换工件/维护时清零补偿（HomeAll 回零不会清补偿）
+        _mc.ResetStageCompensation();
+    }
+
+    // 定点移动并叠加补偿（仅 StageX/StageY 生效，补偿后仍过边界校验）
+    // Move to target with compensation (only StageX/StageY, boundary check still applies)
+    public void MoveWithCompensation()
+    {
+        _mc.MoveToTarget(AxisId.StageX, 100.0, applyCompensation: true);
+
+        var targets = new Dictionary<AxisId, double>
+        {
+            { AxisId.StageX, 100.0 },
+            { AxisId.StageY, 50.0 }
+        };
+        _mc.MoveAllToTarget(targets, applyCompensation: true);
+    }
+
     // Jog 点动 | Jog
     public void JogAxis()
     {
@@ -371,6 +403,13 @@ public class YourMonitor
             {
                 Console.WriteLine($"几何反算请求: SourceZ={data.SourceZTarget}, DetectorZ={data.DetectorZTarget}");
             }, ThreadOption.UIThread);
+
+        // 载物台坐标系补偿变化（记录/设置/清零时触发）| Stage compensation changed
+        eventAggregator.GetEvent<StageCompensationChangedEvent>()
+            .Subscribe(data =>
+            {
+                Console.WriteLine($"补偿值: X={data.Xmm:F4}mm, Y={data.Ymm:F4}mm");
+            }, ThreadOption.UIThread);
     }
 }
 ```
@@ -536,4 +575,55 @@ MotionResult result = _motionControlService.MoveToSafePosition();
 
 ---
 
-**最后更新 | Last Updated**: 2026-07-06
+## 11. 坐标系补偿 | Coordinate Compensation
+
+用于将主框架坐标匹配得到的图像像素偏移换算为载物台物理补偿，并让后续定点运动自动叠加补偿，保持工件对齐。
+
+### 11.1 补偿模型
+
+- 补偿值以物理量 mm 存储（Stage 坐标系，放大比无关），初始 `(0,0)`
+- 仅作用于 `StageX / StageY`，其余轴不补偿
+- `HomeAll()` 回零**不会清零补偿**；仅 `ResetStageCompensation()` 显式清零
+
+### 11.2 记录模式（CompensationMode）
+
+| 模式 | 语义 | 适用场景 |
+|------|------|----------|
+| `Replace`（默认）| `comp = 本次换算值` | 每次从同一名义参考位置测量、每位置只记录一次 |
+| `Accumulate` | `comp += 本次换算值` | 在同一位置迭代修正残差 |
+
+> `ApplyPixelOffsetCompensation` 的移动为相对移动。覆盖模式假设"同参考位置、每位置一次"；同位置迭代修正请用 `Accumulate`，否则物理移动会重复叠加。
+
+### 11.3 接口一览
+
+| 方法 | 说明 |
+|------|------|
+| `ApplyPixelOffsetCompensation(dx, dy, mode = Replace)` | 记录补偿 + 执行相对修正移动 |
+| `RecordPixelOffsetCompensation(dx, dy, mode = Replace)` | 仅记录补偿，不移动 |
+| `GetStageCompensation()` | 获取当前补偿值 `(Xmm, Ymm)` |
+| `SetStageCompensation(xMm, yMm)` | 直接以 mm 设置补偿值 |
+| `ResetStageCompensation()` | 清零补偿（换工件/维护时调用） |
+| `MoveToTarget(..., applyCompensation: true)` | 单轴定点移动叠加补偿（仅 StageX/StageY） |
+| `MoveAllToTarget(targets, applyCompensation: true)` | 多轴定点移动叠加补偿（仅 StageX/StageY） |
+
+### 11.4 调用示例
+
+```csharp
+// 主框架坐标匹配后：记录补偿并修正到位（默认覆盖）
+_mc.ApplyPixelOffsetCompensation(dxPixels, dyPixels);
+
+// 后续定点运动叠加补偿
+_mc.MoveAllToTarget(new Dictionary<AxisId, double>
+{
+    { AxisId.StageX, 100 }, { AxisId.StageY, 50 }
+}, applyCompensation: true);
+
+// 换工件清零
+_mc.ResetStageCompensation();
+```
+
+补偿值变化时发布 `StageCompensationChangedEvent`（见第 6 节）。补偿功能复用现有几何配置（`DetectorPixelSizeX/Y`、`PixelDirectionX/Y`），无需新增 App.config 参数。
+
+---
+
+**最后更新 | Last Updated**: 2026-07-28

XP.Hardware.MotionControl/Documents/GeometryWithDetectorSwing.md

@@ -309,7 +309,7 @@ Dz = Pz - R × cos(θ) = DetectorZ_abs + SwingPivotOffset - R × cos(θ)
 | 参数 | 键名 | 默认值 | 单位 | 说明 |
 |------|------|--------|------|------|
 | 轮询周期 | `MotionControl:PollingInterval` | 100 | ms | PLC 状态轮询周期，每个周期读取所有轴位置并重新计算几何参数 |
-| 默认速度 | `MotionControl:DefaultVelocity` | 500 | - | 未指定速度时使用的默认运动速度 |
+| 默认速度 | `MotionControl:DefaultVelocity` | 100 | - | 未指定速度时使用的默认运动速度（代码默认 100） |
 
 ---
 

XP.Hardware.MotionControl/Documents/MotionControl_Design.md

@@ -152,6 +152,13 @@ PlcLinearAxis        PlcRotaryAxis        PlcSafetyDoor
 - `ApplyGeometry(fod, fdd)` — 根据 FOD/FDD 反算并移动
 - `GetCurrentGeometry()` — 获取当前 FOD/FDD/M
 - `MoveStageByPixelOffset(dxPixels, dyPixels, executeMove)` — 根据图像像素偏移驱动载物台移动（自动计算放大比和物理距离）
+- `MoveToSafePosition()` — 所有轴移动到配置的安全点位置
+- `MoveToTarget(axisId, target, speed, applyCompensation)` / `MoveAllToTarget(targets, applyCompensation)` — 定点移动，`applyCompensation=true` 时对 StageX/StageY 叠加坐标系补偿
+- `ApplyPixelOffsetCompensation(dx, dy, mode)` — 记录像素偏移补偿并执行修正移动（默认覆盖）
+- `RecordPixelOffsetCompensation(dx, dy, mode)` — 仅记录补偿不移动（默认覆盖）
+- `GetStageCompensation()` / `SetStageCompensation(xMm, yMm)` / `ResetStageCompensation()` — 补偿值查询/设置/清零
+
+> 坐标系补偿的完整设计见第 14 节。
 
 ### 4.2 GeometryCalculator
 
@@ -497,3 +504,66 @@ Abstractions/Events/
 | P2 | MotionControlView.xaml（宽350 UserControl） |
 | P3 | MotionControlModule 注册 |
 | P3 | 多语言资源文件 |
+
+---
+
+## 14. 图像坐标系补偿设计 | Coordinate Compensation Design
+
+### 14.1 功能目标
+
+主框架在坐标匹配过程中会计算出工件位置的图像像素偏移 `(dX, dY)`（可为负）。本模块负责：
+
+1. 将像素偏移换算为载物台物理位移（mm），记录为**补偿值**（初始 `(0,0)`）；
+2. 执行修正移动，使工件对齐；
+3. 后续任意"移动到名义位置"的指令，可选择自动叠加该补偿值，保证工件持续对齐。
+
+### 14.2 补偿值模型
+
+- **单位**：物理量 mm（Stage 坐标系），**放大比无关**。像素偏移随放大比变化，但对应的物理错位是固定的，因此存 mm 而非像素。
+- **作用范围**：仅 `StageX / StageY`，其余轴不补偿。
+- **存储位置**：`MotionControlService`（单例）私有字段 `_compXmm / _compYmm`，用 `_compLock` 保护跨线程（轮询线程 / UI 线程）读写。
+- **生命周期**：随软件运行保持；`HomeAll` 回零**不清补偿**；仅 `ResetStageCompensation()` 显式清零（换工件/维护时由主框架调用）。
+
+### 14.3 记录模式（CompensationMode）
+
+| 模式 | 语义 | 适用场景 |
+|------|------|----------|
+| `Replace`（默认）| `comp = 本次换算值` | 每次从同一名义参考位置测量、每位置只记录一次的一次性对位 |
+| `Accumulate` | `comp += 本次换算值` | 在同一位置迭代修正残差的闭环逼近 |
+
+> 注意：`ApplyPixelOffsetCompensation` 的移动为**相对移动**。覆盖模式假设"同参考位置、每位置一次"；若在同一位置连续修正而不回参考点，请改用 `Accumulate`，否则物理移动会重复叠加。
+
+### 14.4 像素→mm 换算
+
+复用像素偏移换算逻辑（私有方法 `TryConvertPixelToStageMm`），与 `MoveStageByPixelOffset` 一致：
+
+```
+mmPerPixelX = DetectorPixelSizeX / M
+mmPerPixelY = DetectorPixelSizeY / M
+dxMm = dxPixels × mmPerPixelX × PixelDirectionX
+dyMm = dyPixels × mmPerPixelY × PixelDirectionY
+```
+
+其中 `M` 为当前放大倍率（由 `GetCurrentGeometry()` 实时计算）。
+
+### 14.5 典型调用流程
+
+```csharp
+// 主框架坐标匹配完成后：一步完成"记录补偿 + 修正移动"（默认覆盖）
+_mc.ApplyPixelOffsetCompensation(dxPixels, dyPixels);
+
+// 其他类库定点运动并叠加补偿（仅 StageX/StageY 生效，补偿后仍过边界校验）
+_mc.MoveAllToTarget(new Dictionary<AxisId, double>
+{
+    { AxisId.StageX, 100 }, { AxisId.StageY, 50 }
+}, applyCompensation: true);
+
+// 换工件时清零补偿
+_mc.ResetStageCompensation();
+```
+
+补偿值变化时发布 `StageCompensationChangedEvent(StageCompensationData(Xmm, Ymm))`，供 UI 显示当前补偿量。
+
+### 14.6 无需新增配置
+
+补偿功能复用现有几何配置（`DetectorPixelSizeX/Y`、`PixelDirectionX/Y`）与实时放大比，不引入新的 App.config 参数。

XP.Hardware.MotionControl/Documents/README.md

@@ -13,6 +13,7 @@ XP.Hardware.MotionControl 是 XplorePlane 平面CT工业检测系统的核心运
 - 4个直线轴 + 3个旋转轴统一管理（策略模式）
 - 安全防护门控制（联锁检查、状态机）
 - FOD/FDD/放大倍率几何正算与反算
+- 图像坐标系补偿（像素偏移→载物台物理补偿，支持覆盖/累加两种模式）
 - 多轴联动移动（原子性边界检查）
 - Jog 点动调试（虚拟摇杆控制）
 - 100ms 周期 PLC 状态轮询
@@ -92,7 +93,8 @@ XP.Hardware.MotionControl/
 │   │   ├── AxisId.cs         # 直线轴标识
 │   │   ├── RotaryAxisId.cs   # 旋转轴标识
 │   │   ├── AxisStatus.cs     # 轴状态
-│   │   └── DoorStatus.cs     # 门状态
+│   │   ├── DoorStatus.cs     # 门状态
+│   │   └── CompensationMode.cs # 坐标系补偿记录模式（Replace/Accumulate）
 │   └── Events/               # Prism 事件定义
 │       ├── AxisStatusChangedEvent.cs
 │       ├── DoorStatusChangedEvent.cs
@@ -100,7 +102,8 @@ XP.Hardware.MotionControl/
 │       ├── GeometryUpdatedEvent.cs
 │       ├── GeometryApplyRequestEvent.cs
 │       ├── JoystickActiveEvent.cs
-│       └── MotionErrorEvent.cs
+│       ├── MotionErrorEvent.cs
+│       └── StageCompensationChangedEvent.cs
 ├── Implementations/           # PLC 实现层
 │   ├── PlcLinearAxis.cs      # 基于 PLC 的直线轴实现
 │   ├── PlcRotaryAxis.cs      # 基于 PLC 的旋转轴实现
@@ -133,8 +136,14 @@ XP.Hardware.MotionControl/
 │   ├── Resources.zh-TW.resx      # 繁体中文
 │   └── Resources.en-US.resx      # 英文
 └── Documents/                 # 文档
-    ├── README.md                  # 本文档
-    └── GUIDENCE.md                # 外部集成指南
+    ├── README.md                     # 本文档
+    ├── GUIDENCE.md                   # 外部集成指南
+    ├── MotionControl_Design.md       # 模块设计文档
+    ├── GeometryWithDetectorSwing.md  # 探测器摆动几何计算模型
+    ├── Calibration_README.md         # 像素-载物台映射子模块
+    ├── CoordinateCompensation.md     # 载物台坐标系补偿功能
+    ├── AxisControlView_PLC_Communication.md # AxisControlView PLC 通信机制
+    └── App.config.example            # 配置示例
 ```
 
 
@@ -142,7 +151,7 @@ XP.Hardware.MotionControl/
 
 | 接口 | 用途 | 注册方式 |
 |------|------|----------|
-| `IMotionControlService` | 业务控制（移动、停止、回零、Jog、开关门、几何计算） | 单例 |
+| `IMotionControlService` | 业务控制（移动、停止、回零、Jog、开关门、几何计算、像素偏移驱动、坐标系补偿） | 单例 |
 | `IMotionSystem` | 底层状态读取（轴位置、状态、门状态、摇杆状态、轴复位） | 单例 |
 | `MotionControlConfig` | 配置参数（轴范围、几何原点、轮询周期） | 实例 |
 | `GeometryCalculator` | 几何正算/反算工具 | 单例 |
@@ -158,6 +167,7 @@ XP.Hardware.MotionControl/
 | `GeometryApplyRequestEvent` | `GeometryApplyRequestData(SourceZTarget, DetectorZTarget, ...)` | 几何反算结果填入请求（DebugWindow → MotionControlViewModel） |
 | `JoystickActiveEvent` | `bool` | 实体摇杆激活状态变化（true=激活, false=未激活） |
 | `MotionErrorEvent` | `MotionErrorData(AxisId, ErrorMessage)` | 轴进入 Error/Alarm 状态 |
+| `StageCompensationChangedEvent` | `StageCompensationData(Xmm, Ymm)` | 载物台坐标系补偿值被记录、设置或清零 |
 
 ---
 
@@ -201,4 +211,4 @@ PLC 信号名称硬编码在 `MotionSignalNames.cs` 中，信号定义在 `PlcAd
 
 ---
 
-**最后更新 | Last Updated**: 2026-05-11
+**最后更新 | Last Updated**: 2026-07-28