# 5 轴数控系统 Web 仿真程序具体实施文档 生成时间：2026-06-20 CST ## 1. 实施目标 本文件用于指导后续正式编写 5 轴数控系统 Web 仿真程序。第一版目标是做出一个可运行、可验证、可继续扩展的浏览器前端： - 界面风格按 `gmoccapy_5_axis.png` 实现； - 前端使用原生 HTML/CSS + TypeScript/JavaScript ES modules； - 3D 预览使用 Three.js； - G-code 执行、五轴运动学、RTCP/TCP 相关计算必须来自 LinuxCNC/WASM 或 source-derived 边界； - 不引入 React/Vue/Angular/Svelte； - 不把 Python GUI、GTK/Glade、Tk/OpenGLTk、native HAL process 直接作为浏览器 runtime。 ## 2. 第一版完成定义 第一版完成时应具备： - 一个可启动的 Web app； - gmoccapy 风格布局：黑底 3D 预览、大号绿色 DRO、G-code 列表、右侧模式按钮、override/spindle/coolant 区、底部运行控制； - 至少一个 5 轴 profile：优先 `xyzac-trt`； - 能加载 representative G-code； - 能显示 X/Y/Z/A/B/C、joint pose、TCP pose、RTCP state、kins type； - Three.js 视口非空，能显示机床、刀具、刀路； - browser smoke 能截图、检查 canvas 非空、检查关键 DOM 区域存在； - 文档明确 LinuxCNC source references 和 unsupported runtime boundary。 ## 3. 推荐目录结构 后续直接在本目录中扩展： ```text web-rtcp-5axis-sim-plan/ app/ index.html package.json tsconfig.json src/ main.ts state/ store.ts events.ts ui/ gmoccapy-shell.ts gmoccapy-dro-panel.ts gmoccapy-gcode-panel.ts gmoccapy-status-sidebar.ts gmoccapy-override-panel.ts gmoccapy-spindle-coolant-panel.ts gmoccapy-bottom-controls.ts gmoccapy-info-tabs.ts visualization/ five-axis-scene.ts machine-model.ts toolpath-layer.ts camera-controls.ts runtime/ simulation-runtime.ts frame-builder.ts playback-controller.ts linuxcnc-adapter.ts profiles/ index.ts xyzac-trt.ts xyzbc-trt.ts panel-schema/ controls.ts pyvcp-reference.ts workers/ linuxcnc-worker.ts styles/ gmoccapy.css core/ linuxcnc_kinematics_wasm/ tests/ browser/ node/ ``` ## 4. 实施顺序 ### Step 1：Web shell 目标： - 创建 `app/index.html`； - 创建 CSS layout； - 创建 `gmoccapy-shell.ts`； - 页面静态呈现 gmoccapy 风格区域。 必须有的 DOM 区域： ```text data-region="titlebar" data-region="preview" data-region="dro" data-region="gcode" data-region="status-sidebar" data-region="info-tabs" data-region="override" data-region="spindle-coolant" data-region="bottom-controls" ``` 验收： - 浏览器打开页面非空； - 页面区域与 `gmoccapy_5_axis.png` 基本一致； - 无 React/Vue 依赖。 ### Step 2：状态模型 目标： - 实现 `GmoccapySimulationState`； - 实现 `createStore()`、`getState()`、`subscribe()`、`dispatch()`； - UI 面板从 state 渲染，不直接互相读写 DOM。 初始 state： ```text machineProfile=xyzac-trt runState=idle rtcpState=off kinsType=identity axisPose={X,Y,Z,A,B,C} jointPose=[] tcpPose={x,y,z,toolAxisVector} ``` 验收： - Node smoke 验证 store 更新； - DOM renderer 能响应 state 变化。 当前 M2 已实现： ```text app/src/runtime/rtcp-frame.js app/src/profiles/xyzac-trt.js tests/node/verify_rtcp_store.mjs ``` 状态模型已经输出： ```text axisPose jointPose tcpPose toolAxisVector rtcpFrame feed spindle coolant preview operatorMessage ``` 当前 RTCP frame 已支持双来源： ```text apiName=web-rtcp-5axis-motion-frame fixture fallback: sourceMode=fixture-ui-only semanticBoundary=fixture_frame_ui_plumbing_not_linuxcnc_kinematics_proof linuxCncKinematicsReady=false promotionAllowed=false LinuxCNC kinematics proof: sourceMode=source-derived-kinematics-wasm semanticBoundary=linuxcnc_kinematics_wasm_c_abi linuxCncKinematicsReady=true promotionAllowed=true for kinematics frame source only ``` 这表示 Web 仿真已经具备 RTCP 状态链路、TCP pose 显示、刀轴向量显示和控制按钮切换；Node proof 路径已通过 `createLinuxCncKinematicsSdk({ moduleId: "xyzac-trt" })` 加载 LinuxCNC kinematics WASM 并生成 frame。浏览器 smoke 仍保留 fixture fallback，不把 fallback 冒充 LinuxCNC runtime proof。 ### Step 3：gmoccapy UI 组件 目标： - DRO； - G-code panel； - right status sidebar； - override panel； - spindle/coolant panel； - bottom controls； - info tabs。 要求： - 按 gmoccapy 风格做大按钮、大数字、黑底预览、灰色面板； - 所有按钮先连接仿真 action，不连接真实机床控制； - 文本不能溢出按钮或面板。 验收： - browser smoke 检查关键按钮、DRO、G-code rows； - `Run/Stop/Pause/Step` 能改变仿真 state。 当前 M2 已接入的 UI action： ```text RUN STOP PAUSE STEP SET_KINS_TYPE SET_VIEW RESET_VIEW CLEAR_PREVIEW ADJUST_OVERRIDE ADJUST_SPINDLE_OVERRIDE TOGGLE_COOLANT RELOAD_PROGRAM HOME TOGGLE_FULLSCREEN ``` 这些 action 只改变 Web 仿真状态，不连接真实机床控制。 当前 M5 已补齐 operator workflow： ```text TOGGLE_POWER ESTOP RESET SET_MODE(auto/manual/jog/mdi) JOG RUN_MDI LOAD_PROGRAM ``` 实现状态： - 右侧按钮栏提供 POWER、E-STOP、RESET、AUTO、MANUAL、JOG、MDI； - 底部控制栏提供 Open、Run/Stop/Pause/Step/Home、JOG X/Y、MDI； - Open 使用浏览器 FileReader 读取本地 G-code 文本并进入 `LOAD_PROGRAM`； - G-code 面板显示当前程序来源、当前执行行和高亮行； - preview 区域显示刀具预览卡； - RUN/STEP 仍是 fixture line playback，不是 LinuxCNC interpreter execution proof。 ### Step 4：Three.js 五轴预览 目标： - 创建基础五轴机床模型； - 显示坐标轴、工作空间、刀具、TCP 点、刀路； - 支持 fit/reset/clear path。 模型优先参考： ```text qtvismach_5axis_gantry.png lib/python/vismach.py src/hal/user_comps/vismach/5axisgui.py src/hal/user_comps/vismach/xyzac-trt-gui.py src/hal/user_comps/vismach/xyzbc-trt-gui.py ``` 验收： - canvas 非空； - tool marker 可见； - path points 非零； - 视口尺寸变化不破坏布局。 当前 M3 已实现： ```text app/src/vendor/three/three.module.js app/src/vendor/three/three.core.js app/src/visualization/five-axis-scene.js ``` 当前 Three.js 预览会渲染基础五轴工作区、工作台、刀具/TCP marker、刀轴和刀路，并消费： ```text tcpPose toolAxisVector rtcpState rtcpFrame.apiName preview.selectedView ``` browser smoke 已检查 canvas nonblank、scene objects、path points、RTCP on/off 同步和 STEP 后 TCP pose 更新。 ### Step 5：profile 和 panel schema 目标： - 建立 `xyzac-trt` profile； - 后续补 `xyzbc-trt`； - 把 PyVCP XML 和 HAL 绑定整理成 Web panel schema。 `xyzac-trt` 必须记录： ```text iniPath coordinates=XYZAC kinematics=xyzac-trt-kins remap=M428/M429/M430 halPins=motion.switchkins-type, xyzac-trt-kins.tool-offset, y-offset, z-offset samplePrograms sourceReferences ``` 验收： - Node smoke 验证 profile 完整； - UI 能显示 profile title、coordinates、kins type、source references。 当前 M4 已实现： ```text app/src/profiles/xyzac-trt.js app/src/profiles/source-reference-map.js app/src/panel-schema/xyzac-trt-pyvcp.js tests/node/verify_profile_boundary.mjs ``` `xyzac-trt` profile 现在记录： ```text iniPath pyvcpXmlPath postguiHalPath generatedHalPath toolTablePath coordinates=XYZAC kinematics=xyzac-trt-kins sparm=identityfirst remaps=M428/M429/M430 switchkinsTypes=identity/TCP:XYZAC/USERK halPins offsets samplePrograms sourceReferences ``` `xyzac-trt-switchkins-pyvcp` panel schema 记录 SWITCHKINS multilabel、IDENTITY/TCP:XYZAC/USERK/vismach-clear buttons、HAL nets 和对应 MDI commands。 ### Step 6：LinuxCNC adapter 目标： - 第一阶段可接现有 interpreter WASM SDK； - 若未接入完整 WASM，则先用明确标记的 fixture frame 验证 UI，不声称 CNC semantics pass； - 所有 runtime result 必须带 `sourceMode` 字段。 允许： ```text sourceMode=linuxcnc-wasm sourceMode=source-derived-kinematics-wasm sourceMode=fixture-ui-only ``` 禁止： ```text sourceMode=js-cnc-semantics ``` 验收： - UI-only fixture 不能被标记为 LinuxCNC pass； - LinuxCNC/WASM 接入后更新 traceability。 当前 M4 已实现 adapter 接入点： ```text app/src/runtime/linuxcnc-boundary-adapter.js apiName=web-rtcp-5axis-linuxcnc-boundary-adapter readinessApi=web-rtcp-5axis-linuxcnc-boundary-readiness semanticBoundary=adapter_entrypoint_only_runtime_not_connected | linuxcnc_kinematics_wasm_runtime_connected linuxCncKinematicsReady=false for fixture fallback, true for loaded kinematics WASM promotionAllowed=true only for kinematics frame source proof fullLinuxCncProgramExecutionReady=false until interpreter/remap is connected ``` store 已输出： ```text linuxCncBoundaryAdapter linuxCncBoundaryReadiness ``` info tabs 和 browser smoke 会检查 adapter、panel schema、source map 和 boundary readiness。Node smoke 已验证 kinematics-only runtime ready；interpreter/remap 仍显示为 missing，不得声明 full LinuxCNC program execution ready。 ### Step 7：RTCP/kinematics frame 目标： - 定义 `FiveAxisMotionFrame`； - 将 canonical event 和 kinematics output 转成统一 frame； - 显示 RTCP on/off、TCP pose、tool axis vector。 M2 阶段先落地 `web-rtcp-5axis-motion-frame` 的 fixture contract，M6 阶段已加入 LinuxCNC kinematics WASM frame contract： ```text profileId sourceMode semanticBoundary activeLine kinsType rtcpState axisPose jointPose tcpPose toolAxisVector compensation readiness ``` 后续 LinuxCNC/source-derived kinematics WASM 接入时，必须替换 frame builder 的运动学来源，并把 `sourceMode` 从 `fixture-ui-only` 改为明确的 LinuxCNC/WASM 边界值。 当前 Node proof 已使用 `linuxCncKinematicsResult.forward.pose` 和 `linuxCncKinematicsResult.inverse.joints` 填充 `tcpPose` / `jointPose`，并输出 `kinematicsModuleId`、forward/inverse rc、flags 和 `linuxcnc_kinematics_wasm_c_abi`。 验收： - Node smoke：frame schema； - Browser smoke：DRO 和 Three.js 同步显示同一 frame； - fixture fallback 必须显示 pending；Node LinuxCNC kinematics proof 必须显示 ready；interpreter/remap 未接入时仍不得显示 full program execution ready。 ### Step 8：测试和验收 至少需要： - `git diff --check`； - Node profile/store/frame smoke； - Browser shell smoke； - Browser canvas nonblank smoke； - 文档 traceability 检查。 ## 5. 禁止事项 - 不在 JavaScript 中实现 G-code 解释器。 - 不在 JavaScript 中实现 LinuxCNC 五轴运动学公式作为最终语义源。 - 不把 gmoccapy Python/GTK runtime 移植进浏览器。 - 不把 Python remap/tool DB/external user-M process 伪装成已支持。 - 不用 UI fixture 结果冒充 LinuxCNC runtime proof。 ## 6. 开工建议 当前已完成 Step 1 到 Step 7 的 Node 侧 LinuxCNC kinematics proof。下一轮应把 browser asset copy/worker 接入完成，让真实浏览器也能加载 kinematics WASM；或继续推进 interpreter/remap/planner，使 program execution 从 fixture line playback 升级。