提交当前项目改动

2026-07-02 08:01:34 -04:00
parent 83075c4b96
commit c4a721f6cf
274 changed files with 157294 additions and 1394 deletions
--- a/web-rtcp-5axis-xyzbc-trt-sim-plan/working/01-项目功能内容.md
+++ b/web-rtcp-5axis-xyzbc-trt-sim-plan/working/01-项目功能内容.md
@@ -0,0 +1,189 @@
+# 01-项目功能内容
+
+## 目标
+
+对标 LinuxCNC `xyzbc-trt` 当前运行配置，在 Web 中实现 XYZBC table rotary/tilting 五轴数控系统仿真界面。界面基于 HTML/JavaScript，文件和会话持久化基于 OPFS，CNC 核心能力通过 `wasm-port` 的 LinuxCNC-derived WASM/SDK 边界提供。
+
+Native 对标基线：
+
+- 后续以 `/home/mes123456/cnc_wams/linuxcnc` 作为 LinuxCNC `xyzbc-trt` 源码与真实执行基线。
+- Web 数控仿真界面和逻辑必须根据该路径编译后执行 `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini` 的真实运行结果设计。
+- native evidence 采集脚本应通过 `/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment` 启动/连接 LinuxCNC，而不是继续依赖 `/home/mes123456/linuxcnc-master`。
+- `/home/mes123456/cnc_wams/linuxcnc` 已完成 run-in-place 编译，并已验证 `scripts/rip-environment`、`scripts/linuxcnc`、`bin/axis`、`bin/xyzbc-trt-gui`、`bin/milltask`、`bin/linuxcncsvr`、`bin/halui`、`rtlib/xyzbc-trt-kins.so`、`rtlib/tpmod.so`、`lib/python/linuxcnc.so` 存在可用。后续可以基于该路径重新生成真实 native JSON。
+
+完全对标要求：
+
+- `working` 下的设计、任务和验收必须逐项覆盖 `doc/xyzbc-trt-runtime-files.md` 中记录的运行进程、启动顺序、INI 配置、AXIS 界面行为、PyVCP、POSTGUI HAL、basic_sim、Vismach、switchkins/remap、G-code 子程序、tool table、parameter file、kinematics HAL pins、轴/关节限制和 JSON 执行证据。
+- Web 不只展示五轴场景，还必须具备与 LinuxCNC 配置等价的运行状态、按钮行为、文件 staging、HAL/task 反馈、刀具预览路径、刀具执行路径和 native/Web JSON 对比闭环。
+- 无法在浏览器中一比一复用的 LinuxCNC 桌面组件，例如 AXIS/Tk/PyVCP/Vismach 窗口，必须在 Web 中提供同语义等效实现，并在 evidence JSON 中说明替代边界。
+
+## 对标文件
+
+主对标文档：
+
+```text
+web-rtcp-5axis-xyzbc-trt-sim-plan/doc/xyzbc-trt-runtime-files.md
+```
+
+LinuxCNC 目标配置：
+
+```text
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.xml
+configs/sim/axis/vismach/5axis/table-rotary-tilting/switchkins_postgui.hal
+configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/428remap.ngc
+configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/429remap.ngc
+configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/430remap.ngc
+configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/xyzbc_switchkins_sub.ngc
+configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/centering.ngc
+configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/helix_bc.ngc
+configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/xyzbc_switchkins.ngc
+configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/boat-xyzbc.ngc
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.tbl
+configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc.var
+lib/hallib/basic_sim.tcl
+src/hal/user_comps/vismach/xyzbc-trt-gui.py
+src/emc/usr_intf/axis/scripts/axis.py
+src/emc/kinematics/xyzbc-trt-kins.c
+```
+
+## 功能清单
+
+| 功能 | Web 实现方式 | 当前状态 |
+| --- | --- | --- |
+| XYZBC 机型默认进入 | `app/src/state/store.js` 默认 profile 为 `xyzbc-trt` | 已落地 |
+| INI 配置解析 | `linuxcnc-ini-runtime.js` 解析 vendored `xyzbc-trt.ini` | 已落地 |
+| PyVCP switchkins 面板 | `xyzbc-trt` profile 复用并改写 PyVCP schema：`IDENTITY`、`TCP:XYZBC`、`userk`、`vismach-clear` | 已落地 |
+| M428/M429/M430 remap | profile 映射 remap 文件和 switchkins type；WASM interp/remap 由 `wasm-port` 支撑 | Web staging 已完成；真实 WASM 执行需 artifact |
+| `motion.switchkins-type` | profile 描述 `motion.analog-out-03 => motion.switchkins-type` | 已落地 |
+| XYZBC kinematics | `wasm-port/runtime/sdk/src/linuxcnc-kinematics.js` 支持 `xyzbc-trt` 和 `linuxcnc_xyzbc_trt_kinematics.wasm` | SDK 已支持，当前缺 build artifact |
+| Vismach 等效三维仿真 | Web canvas/Three 风格五轴场景替代 Python Vismach GUI，显示机床参考、刀路、TCP、刀轴 | 参考 app 已移植 |
+| OPFS 机器文件 staging | `web-rtcp-5axis-xyzbc-trt-sim-plan/machines/xyzbc-trt/...` | 已落地 |
+| Tool table | `xyzbc-trt.tbl` staged 并进入 Web tool DB 仿真 | 已落地 |
+| Parameter file | INI 指向 `xyzbc.var`；已从真实运行树导入 `wasm-port/vendor` 并加入 manifest | 已落地 |
+| 默认程序 | `xyzbc_switchkins.ngc` 作为 `xyzbc-trt` 默认程序 | 已落地 |
+| task/HAL runtime | `linuxcnc-task-hal-runtime.js` 连接 `wasm-port` task/HAL SDK | 代码已接入，需 artifact 验收 |
+| 刀具预览路径 JSON | native 与 Web 在预览阶段输出统一结构的 `previewPath` 曲线采样 | 待补充采集脚本 |
+| 刀具执行路径 JSON | native 与 Web 在真实执行阶段输出统一结构的 `executionPath` 曲线采样 | 待补充采集脚本 |
+| 预览/执行路径对比 | `compare-xyzbc-trt-evidence.json` 对 `previewPath` 和 `executionPath` 逐点/误差统计比对 | 待补充 compare 规则 |
+| AXIS 主界面等效 | Web 首屏必须是可操作 CNC 仿真界面，包含程序、坐标、状态、override、工具、MDI/switchkins 控制 | 待全量验收 |
+| POSTGUI HAL 等效 | Web 需复现 `pyvcp.* -> halui.mdi-command-* -> M428/M429/M430` 连接关系 | 待补充 JSON 检查 |
+| basic_sim 等效 | Web task/HAL runtime 需提供模拟回零、manual toolchange、spindle、joint feedback 基础仿真语义 | 待 WASM/task-HAL 验收 |
+| Vismach 模型等效 | Web 3D 模型需按 `table-x/saddle-y/spindle-z/tilt-b/rotate-c/tool-offset/x-offset/z-offset` 驱动 | 待补充模型 pin 验收 |
+| Ngcgui 子程序 | Web 需 stage 并可运行 `xyzbc_switchkins_sub.ngc`、`centering.ngc`、`helix_bc.ngc` | 待补充子程序验收 |
+| 演示程序全集 | Web 需 stage `xyzbc_switchkins.ngc` 和 `boat-xyzbc.ngc`，默认打开前者 | 待补充 boat 验收 |
+| 速度/限制/坐标显示 | Web 需对标 `GEOMETRY/JOG_AXES/POSITION_FEEDBACK/MAX_*`、TRAJ 和 AXIS/JOINT 限制 | 待补充 UI/JSON 检查 |
+| Kinematics HAL pins | Web 需 expose/record `x-offset/z-offset/tool-offset/rot-point/conventional-directions` | 待补充 HAL pin 检查 |
+
+## 刀具预览与执行路径 JSON 要求
+
+目标：把 LinuxCNC 真实系统和 Web 仿真系统中的刀具预览路径、刀具执行路径都写入 evidence JSON，并在 compare JSON 中做同周期曲线比对。
+
+统一采样规则：
+
+- 对比采样周期固定为 `samplePeriodMs = 20`，即 50 Hz。
+- native 和 Web 可以保留各自原始采样，但写入 `previewPath.samples`、`executionPath.samples` 前必须重采样到同一个周期。
+- 两侧样本必须使用相同的 `sampleIndex` 和 `timeMs` 序列，方便逐点比较。
+- 曲线开始点以程序开始执行或预览路径第一段有效运动为 `timeMs = 0`。
+- 对于 `G0/G1/G2/G3` 等不同插补段，JSON 中必须记录 `motionType`，用于区分快移、直线、圆弧和 remap/switchkins 前后的路径段。
+
+native/Web evidence JSON 中都应增加：
+
+```json
+{
+  "pathSampling": {
+    "samplePeriodMs": 20,
+    "timeBase": "program-relative-ms",
+    "resampling": "linear-position-slerp-or-axis-linear",
+    "coordinateSystem": "machine-xyzbc-and-tcp"
+  },
+  "previewPath": {
+    "source": "linuxcnc-preview-or-web-preview",
+    "sampleCount": 0,
+    "samples": []
+  },
+  "executionPath": {
+    "source": "linuxcnc-stat-or-web-task-hal",
+    "sampleCount": 0,
+    "samples": []
+  }
+}
+```
+
+每个 sample 至少包含：
+
+```json
+{
+  "sampleIndex": 0,
+  "timeMs": 0,
+  "line": 0,
+  "motionType": "G0|G1|G2|G3|remap|unknown",
+  "activeKinematics": "identity|xyzbc-tcp|userk|unknown",
+  "tool": {
+    "id": 0,
+    "length": 0,
+    "diameter": 0
+  },
+  "joint": {
+    "x": 0,
+    "y": 0,
+    "z": 0,
+    "b": 0,
+    "c": 0
+  },
+  "tcp": {
+    "x": 0,
+    "y": 0,
+    "z": 0
+  },
+  "toolAxis": {
+    "i": 0,
+    "j": 0,
+    "k": 1
+  },
+  "feed": 0,
+  "spindle": 0
+}
+```
+
+compare JSON 应增加 `pathComparison`：
+
+- `previewVsPreview`：native 预览路径与 Web 预览路径对比。
+- `executionVsExecution`：native 执行路径与 Web 执行路径对比。
+- `previewVsExecutionNative`：LinuxCNC 预览与真实执行之间的偏差。
+- `previewVsExecutionWeb`：Web 预览与 Web 执行之间的偏差。
+- 误差统计至少包含 `maxTcpErrorMm`、`rmsTcpErrorMm`、`maxJointError`、`rmsJointError`、`maxToolAxisAngleDeg`、`sampleCountDelta`、`missingSamples`。
+
+## WASM 是否满足
+
+结论：`wasm-port` 已经具备满足 `xyzbc-trt` Web 仿真的主要语义边界，但当前工作区没有 `wasm-port/build/wasm` 构建产物，导致完整浏览器运行需要先执行 WASM 构建。
+
+已具备的证据：
+
+- `wasm-port/runtime/sdk/src/linuxcnc-kinematics.js` 注册 `xyzbc-trt`，目标文件为 `linuxcnc_xyzbc_trt_kinematics.wasm`。
+- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_xyzbc_trt_kinematics_probe.cpp` 覆盖 `xyzbc-trt-kins` forward/inverse/switchkins。
+- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_5axis_remap_execute_harness.cpp` 包含 `xyzbc-trt.ini`、`xyzbc_switchkins.ngc`、`boat-xyzbc.ngc` 执行路径。
+- `wasm-port/docs/compatibility-validation.md` 记录 `xyzbc-trt` kinematics、remap、browser interp 覆盖。
+- 当前环境已经安装并可调用 `emcc 6.0.2`，后续缺口从“安装 Emscripten”转为“执行 WASM 构建并复跑证据”。
+
+当前缺口：
+
+- `wasm-port/build/wasm/kinematics`、`core`、`tp`、`task-hal` 目录当前不存在。
+- 因此本轮已完成 native 真实执行、Web OPFS/staging/readiness、JSON 对比验证；完整 browser worker WASM 执行需先构建 artifact。
+
+## Native/Web JSON 对比结论
+
+证据文件：
+
+```text
+working/evidence/native-xyzbc-trt-evidence.json
+working/evidence/web-xyzbc-trt-evidence.json
+working/evidence/compare-xyzbc-trt-evidence.json
+```
+
+当前结果：
+
+- native `xyzbc-trt` 通过 LinuxCNC Python API 真实执行 `xyzbc_switchkins.ngc`，采集到 1462 个执行事件。
+- Web 侧已完成 profile、INI、OPFS staging、PyVCP XML、remap、tool table、parameter file、默认程序覆盖。
+- 对比 12 项检查中 11 项通过。
+- 唯一失败项：`required WASM artifacts available`，缺少 `wasm-port/build/wasm/...` 的 kinematics/core/tp/task-hal `.js/.wasm` 文件。