linuxcncWebWASM/docs/glb-machine-manager/01-项目功能内容.md

项目功能内容

目标

在 Web LinuxCNC 控制面板的机床预览区增加“三维机床管理”按钮。对话框内完成机床部件装配和坐标标定，最终生成可由现有 XYZAC/XYZBC TRT 运行链使用的机床模型。

功能范围

1. 对话框包含独立的 Three.js 三维预览，实时显示正在配置的机床。
2. 支持逐个导入自包含 .glb 机床部件，不允许依赖外部纹理或网格文件。
3. 每个部件可绑定 底座、X、Y、Z、刀具、A/B、C、工件 角色，并编辑父级关系。可运行结构必须满足：
   • 刀具链：底座 → X → Y → Z → 刀具。
   • 转台链：底座 → A/B → C → 工件。
4. 每个部件可定义局部坐标原点。模型网格相对该原点偏移，运动关节围绕该原点运动。
5. 每个部件可独立显示或隐藏原点坐标轴辅助线。
6. 每个部件可用数值和 Three.js 操纵器平移、旋转；变换只修改装配配置，不修改原 GLB 字节。Three.js 管理器通过 camera.up.set(0, 0, 1) 使用机床 Z-up 场景，机床 XY 为地面平面；导入 GLB 的节点、几何、材质、内部层级和原始变换保持不变。
7. 可定义 C 轴原点位置和 A/B 到 C 的运动学偏置。应用时写入底座场景节点及整机场景的 userData.linuxcncMachineGeometry，同时生成 URDF：
   • C 原点 P = (x-rot-point, y-rot-point, z-rot-point)。
   • A/B 偏置 D = (x-offset, y-offset, z-offset)。
   • 倾转关节原点 T=P+D，C 关节原点 U=-D，工件固定原点 -P。
8. 可定义 X/Y/Z/A或B/C 的物理零点。模型运动量为 LinuxCNC 实际关节值减去配置的物理零点。
9. 应用后，控制面板程序执行、Jog、RTCP 切换和刀长变化继续以 Worker/WASM 快照为唯一运动输入；模型不得在 React 中重新计算刀尖逆解。
10. 导入 GLB 后，若模型已有 Object3D.children 层级，右侧必须按原结构显示为树。树节点名称可拖放：GLB 根节点之间管理部件装配父级，同一 GLB 内部节点之间管理内部父级；循环和跨 GLB 内部节点拖放必须拒绝。
11. 选择任意树节点时，显示其相对父节点的局部原点 XYZ 坐标。层级和原点读取自解析后的 GLB，导入过程不修改源场景；拖放结果保存为草稿覆盖。
12. 导入的整机或部件可删除；删除后释放其 GLB 几何、材质和纹理，移除树及预览引用。
13. 树节点可绑定 X/Y/Z/A或B/C 轴角色。层级运动测试输入 XYZ 毫米值和旋转轴角度后，按节点实际父子关系施加局部位移/旋转，并输出各绑定节点的局部位置、世界位置和四元数，用于验证子节点是否正确跟随父节点。
14. 选择任意关节树节点时，三维预览在该节点自己的局部 (0,0,0) 显示局部 XYZ 坐标系。坐标轴作为该节点子对象，自动继承该节点和所有父节点的变换，不显示成整机世界坐标轴。

数据和单位

• UI 中平移、局部原点、C 原点和偏置使用毫米；旋转和物理旋转轴零点使用度。
• GLB 遵循 glTF 米制、Y-up；生成的 URDF 使用米和弧度、Z-up。
• 部件源文件、哈希和原始场景保持不变；运行装配使用深复制后的几何与材质。显式“导出组合 GLB”会生成新文件，并将标定数据同时写入整机场景和底座节点 userData。
• 底座 userData 至少保存 schema、机型、C 原点、A/B 偏置、物理零点和部件装配摘要。

安全边界

• 当前只生成项目已有求解器支持的 XYZAC 或 XYZBC 双分支 TRT 结构。
• 层级编辑器允许建立关系，但“应用到控制器”前必须严格验证两条受支持机械链、角色唯一性和无环结构。
• 未完成八个角色时允许预览和保存草稿，不允许应用到控制器。
• 模型外观变换不能代替 INI/运动学参数；C 原点和 A/B 偏置必须通过现有配置重载进入 WASM。
• 不做碰撞、质量、刚体动力学或任意 URDF 求解。

验收结果

• AC 与 BC 均能由八个独立部件建立结构并应用。
• 对话框预览、原点辅助、平移/旋转和层级变化实时可见。
• 底座 userData 含完整几何及物理零点字段。
• 运行控制面板后，X/Y/Z/A或B/C Jog 和五轴程序驱动对应部件；工件路径继续附着 C 轴，刀具长度来自 WASM。
• 非法层级、重复角色、缺失部件、错误机型和外部资源 GLB 明确拒绝，已生效模型不改变。