xyzbc-trt Web 数控仿真系统
设计任务书和技术方案

1. 项目目标

本项目建设一个 Web 数控仿真系统，功能和行为完全对标 LinuxCNC 真实运行配置 xyzbc-trt.ini。Web 系统不是展示页，而是首屏即进入数控仿真工作台，提供程序加载、预览、DRO、MDI、PyVCP 等价控件、五轴机床运动显示、switchkins 模式切换、刀具路径采样、执行过程记录和误差对比。

对标基线以已编译成功并能运行的 /home/mes123456/cnc_wams/linuxcnc 为准，历史旧 LinuxCNC 目录不再作为本方案的运行基线。

2. 原型系统运行证据

2.1 当前启动命令

/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment linuxcnc \
  /home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini

2.2 当前关键进程

2.3 当前界面截图

图 1：通过真实 LinuxCNC 会话抓取的 AXIS 主界面，包含预览、DRO、PyVCP SWITCHKINS 面板、程序区和状态栏。

图 2：桌面级运行截图，用于保留真实执行环境和窗口布局证据。

2.4 HAL 状态基线

3. 完全对标范围

4. Web 界面设计任务书

4.1 首屏布局

Web 应用启动后直接进入数控仿真界面，不设置营销式首页。首屏按 AXIS 的工作流组织：

• 顶部：文件、机器、视图、帮助菜单，以及急停、上电、打开文件、运行、暂停、单步、停止、视图方向、清扫轨迹等图标按钮。
• 左侧：Manual Control 与 MDI 标签页，包含 Joint 0 到 4 选择、连续/增量点动、Home、Touch Off、Tool Touch Off、主轴控制和倍率滑块。
• 中间：Preview/DRO/程序标签页，预览页显示 Three.js 五轴机床、工件、刀具、坐标轴、尺寸标注和刀具路径。
• 右侧：SWITCHKINS 面板，显示 0:IDENTITY、1:XYZBC、2:USERK，并提供 IDENTITY、TCP:XYZBC、userk、vismach-clear 按钮。
• 底部：G-code 程序区、Active G-Codes、状态栏、错误和日志输出。

4.2 视觉和交互要求

图 3：LinuxCNC 原型系统与 Web 仿真系统的模块级对标关系。

5. 技术方案

5.1 总体架构

5.2 switchkins 逻辑

Web 端必须复刻原型中的 switchkins 控制链路：PyVCP 按钮触发 halui.mdi-command-00/01/02，MDI 执行 M429/M428/M430，remap 子程序改变 motion.analog-out-03，再驱动 motion.switchkins-type。UI 当前模式由 kinstype.is-0/1/2 反向驱动，而不是由按钮直接写 UI 标签。

5.3 五轴运动学和模型

Web 端机床模型采用 XYZBC table rotary/tilting 结构。X 对应 table-x，Y 对应 saddle-y，Z 对应 spindle-z，B 对应 tilt-b，C 对应 rotate-c。运动学参数使用原型系统当前 HAL 值：x-offset=-20、z-offset=-15、旋转点均为 0、conventional-directions=false。刀具长度来自 motion.tooloffset.z。

三维模型不只显示程序预览曲线，还必须在执行时按采样点刷新桌台、转台、主轴和刀具姿态。执行暂停、复位、清轨迹、模式切换后，模型状态和 JSON 状态必须同步。

5.4 路径采样和 JSON 比对

图 4：刀具预览路径和执行路径 JSON 的同周期采样与逐点比对流程。

5.5 Evidence JSON 字段规范

{
  "schema": "xyzbc-trt-evidence/v1",
  "source": "linuxcnc-native | web-sim",
  "samplePeriodMs": 20,
  "linuxcncRoot": "/home/mes123456/cnc_wams/linuxcnc",
  "ini": "configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini",
  "program": "./demos/xyzbc_switchkins.ngc",
  "runtime": {
    "taskState": 1,
    "interpState": 1,
    "axisMask": 55,
    "kinstype": 0
  },
  "halPins": {
    "motion.switchkins-type": 0,
    "xyzbc-trt-kins.x-offset": -20,
    "xyzbc-trt-kins.z-offset": -15,
    "xyzbc-trt-kins.conventional-directions": false
  },
  "previewPath": {
    "coordinateSystem": "XYZBC",
    "samples": [
      {
        "sampleIndex": 0,
        "timeMs": 0,
        "line": 1,
        "joint": {"x": 0, "y": 0, "z": 0, "b": 0, "c": 0},
        "world": {"x": 0, "y": 0, "z": 0, "b": 0, "c": 0},
        "toolTip": {"x": 0, "y": 0, "z": 0},
        "toolAxis": {"i": 0, "j": 0, "k": 1},
        "kinstype": 0
      }
    ]
  },
  "executionPath": {
    "samples": []
  },
  "screenshots": []
}

5.6 对比报告字段

6. 开发任务分解

7. 验收标准

8. 风险和控制措施

9. 附录：对标文件清单

10. xyzbc-trt 程序逻辑全量分析

下面按“文件装载 - 运动学 - HAL - 界面 - 执行 - 证据”的顺序，把 xyzbc-trt 的实际逻辑拆开说明。这里不是抽象架构，而是与当前源码、HAL pin 和界面行为一一对应的执行逻辑。

10.1 启动入口逻辑

这个启动链路的关键点是：界面不是单独运行的，而是被 INI 文件和 HAL 图驱动。Web 端要完全对标，就不能把预览、模式切换、DRO、刀具、执行按钮做成彼此割裂的前端组件，而要让它们共享同一个运行态和信号总线。

10.2 配置装载逻辑

10.3 switchkins 运动学逻辑

xyzbc-trt-kins 通过 switchkinsSetup() 绑定三个运动学分支：

• type0：在当前配置里被重定义为 identity，用于启动后的关节直接操控。
• type1：xyzbc-trt-kins 本体，执行 XYZBC table rotary/tilting 的 TCP 运动学。
• type2：用户自定义运动学 userk。

源码里明确设置了 kinsname = "xyzbc-trt-kins"、halprefix = "xyzbc-trt-kins"、required_coordinates = "xyzbc"、allow_duplicates = 1，这意味着它既是一个五轴模块，也是一个允许坐标字母重复映射的 switchkins 模块。identityfirst 参数把启动默认值切换成 identity，而不是让机床类型本体成为 type0，这正是 sim 配置的关键差异。

图 5：`xyzbc-trt` 程序逻辑总图，展示从文件装载到证据采样的完整执行链。

switchkins 内部的逻辑顺序很重要：先由 rtapi_app_main() 创建 HAL 组件和输出 pin，再调用 kinematicsSwitch(0) 设定初始模式，然后把三个 setup 函数分别执行一遍，最后 hal_ready()。这意味着 Web 端在启动时也必须先完成状态总线和模式初始化，再挂载界面和三维模型，不能反过来。

10.4 正逆运动学逻辑

在当前配置里，B/C 轴是主运动学轴，A/U/V/W 只是可选字母。前向解使用主关节 JX/JY/JZ/JB/JC 计算 TCP 位姿；逆解再根据目标位姿回算这些主关节。这个路径对 Web 端非常关键，因为预览路径不能只画“刀尖折线”，还要把每个采样点对应的关节姿态也算出来，否则无法和真实系统逐点比对。

10.5 HAL 和状态逻辑

switchkins.c 的实现说明了一个很重要的行为：模式切换后先清除 use_lastpose，再根据当前模式把对应的 kinstype.is.N 置位。也就是说，Web 仿真不能把“当前模式”当作普通表单状态，它必须是一次完整状态机切换，切换后还要在 UI 上立即反映。

10.6 UI 与三维模型逻辑

axis.py 的行为说明 AXIS 窗口里存在“轴模式”和“关节模式”的切换；当配置处于非 trivkins 或特殊 kinstype 时，按钮和焦点会根据当前运动模式自动切换到关节/轴对应控件。Web 端要对标的不只是布局，还有这个控件激活规则。

xyzbc-trt-gui.py 则把 Vismach 模型拆成可响应的 HAL 变换链：tool-offset 作用于刀具，spindle-z 作用于主轴头，tilt-b 作用于倾斜轴，rotate-c 作用于回转台，table-x 和 saddle-y 则驱动横向与纵向运动。这个顺序决定了几何层级关系，所以 Web 端模型必须按同样层级搭建，而不是把每个零件独立摆放。

10.7 程序执行与同步逻辑

同步逻辑是这个程序最容易被误解的地方：切换模式不是单独改一个 pin 就结束了，必须让解释器和 motion 同步，否则 G-code 看到的坐标语义和 motion 看到的坐标语义会不同。这个要求在文档中已经被固化为“预览路径和执行路径统一采样周期，并在切换时强制同步”。

10.8 异常和约束逻辑

• 如果 motion.switchkins-type 没有连接，只有 type0 默认运动学可用，这属于兼容旧配置的行为。
• 如果切换到身份不匹配的运动学类型，程序逻辑必须在 G-code 中先检查 kinstype.is.N 或等价输入，再决定是否继续。
• 如果当前系统的坐标偏置、刀补、外部偏置在切换后不一致，必须先清理或重置偏置，再切换模式。
• 如果 Web 端和 LinuxCNC 真实系统的采样周期不一致，则即使图形看起来接近，也不能通过对标验收。

总的来说，xyzbc-trt 的逻辑不是“一个五轴模型 + 一个预览窗口”，而是“配置驱动的状态机 + 可切换运动学 + HAL 事件 + 三维可视化 + 路径证据”的组合。Web 端要做到完全对标，必须把这五件事统一成一条链。