# 09 单位换算与 Three.js 米单位场景完成记录

生成时间：2026-06-22

## 本轮目标

解决英寸、毫米、米之间的单位换算问题，重点覆盖：

- 实时轴值显示；
- 刀具路径预览；
- 刀具执行轨迹；
- Three.js 绘图坐标统一使用米。

## 完成情况矩阵

| 项目 | 完成状态 | 代码落点 | 验证 |
| --- | --- | --- | --- |
| 公共线性单位换算 | 已完成 | `app/src/runtime/linear-units.js` | `verify_linear_unit_conversion.mjs` |
| mm/inch/m 到米转换 | 已完成 | `linearValueToMeters()`、`axesToSceneMeters()` | `25.4mm == 1inch == 0.0254m` |
| 执行计时距离归一到毫米 | 已完成 | `app/src/runtime/execution-timing.js` | inch 段长 `1 inch -> 25.4 mm` |
| 执行计时进给归一到 mm/min | 已完成 | `app/src/runtime/execution-timing.js` | inch feed `1 inch/min -> 25.4 mm/min` |
| G20/G21 程序单位解析 | 已完成 | `app/src/runtime/linuxcnc-interpreter-runtime.js` | G20 motion 标记 `inch`，G21 motion 标记 `mm` |
| 刀具路径预览使用米 | 已完成 | `app/src/visualization/five-axis-scene.js` | motion axes 经 `axesToSceneMeters()` |
| 刀具执行轨迹使用米 | 已完成 | `app/src/visualization/five-axis-scene.js` | timing samples 携带/继承 motion 单位 |
| 当前刀位 marker 使用米 | 已完成 | `app/src/visualization/five-axis-scene.js` | runtime feedback linearUnits 参与转换 |
| Three.js 机床参考模型使用米尺度 | 已完成 | `app/src/visualization/five-axis-scene.js` | 参考模型尺寸从任意倍率改为米尺度 |
| 2D fallback 使用米尺度 | 已完成 | `app/src/visualization/five-axis-scene.js` | fallback scale 改为米坐标范围 |
| 轴值实时显示 | 已确认边界 | `store.axisPose` / DRO | 保留机床/程序单位，不改成米 |

## 关键设计结论

实时轴值显示不应强制转换为米。DRO/axisPose 表示当前机床或程序坐标单位，应保留 LinuxCNC/INI/G-code 的语义；Three.js 预览层才统一转换为米。

Three.js 场景现在通过 dataset 暴露：

```text
data-three-scene-units="m"
data-three-linear-units="<mm|inch|m>"
data-three-linear-unit-scale-to-meters="<factor>"
```

## 已执行验证

```text
node web-rtcp-5axis-sim-plan/tests/node/verify_linear_unit_conversion.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_rtcp_store.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_real_linuxcnc_5axis_program_cases.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_linuxcnc_ini_runtime.mjs
npm --prefix web-rtcp-5axis-sim-plan/app run build
```

结果均通过。

## 后续工作

1. 增加浏览器截图证据，确认米尺度 Three.js 画面在 desktop/mobile 下不空白、不偏移。
2. 如果后续接入真实 task/motion HAL feedback，需要确认 feedback 坐标是否已经按 INI 单位输出，并继续填充 `programRuntimeFeedback.linearUnits`。
3. 可继续补 G-code 中途 G20/G21 切换的多段浏览器端预览用例。