2当前可运行机型
XYZAC / XYZBC
分别以 A 或 B 倾转轴配合 C 回转轴，使用现有 TRT 正解、逆解和 RTCP。
+GLB-MGR-FRS-001 · v1.1 · 2026-09-22
三维机床管理
详细功能文档
本网页是“三维机床管理”详细功能文档。它把 GLB 部件、层级、局部原点、RTCP 标定、物理零点、WASM 关节快照和五轴机床案例放进同一条可追溯工作流。
管理器负责装配和校准；Three.js 只做视觉投影。正式程序、Jog、RTCP 和轴值始终由 LinuxCNC WASM 快照驱动。
01 · OVERVIEW
从文件到运行模型
用户把多个自包含 GLB 部件装配为可预览、可标定、可保存、可重新打开并可交给 LinuxCNC Web/WASM 运行的机床模型。源文件不被原地修改，草稿只有在校验通过后才进入控制器。
+
+8结构角色
从底座到工件
底座、X、Y、Z、刀具、A/B、C、工件是控制参考角色；新版单 GLB 完成五轴绑定即可应用。
+4运行元数据
URDF + 几何 + 关节 + 编辑
四类 userData 一起保存，源文件哈希和节点路径可追溯。
+02 · WORKBENCH
工作台如何使用
+
图 1 · 工作台与单自由度绑定（MGR-18 验收）。一个 GLB 的内部节点完成五轴绑定；页签、轴总览和校验区均可见。 
MILL700：Z-up 网格、层级树与局部原点。历史截图中的六分量编辑已被单自由度输入替代。
+
XYZBC 实时跟随：轴值来自 WASM snapshot。
+
+
+
+四个页签
| 页签 | 主要操作 | 安全限制 |
|---|---|---|
| 结构 | 导入、搜索、拖放、删除、显隐、原点 | 不能绕过树生成任意控制链 |
| 运动 | 单自由度、方向、正负、试动、跟随 | 试动不发送 Jog |
| 标定 | C 原点、A/B 偏置、物理零点 | 不能用视觉平移代替 RTCP |
| 文件与恢复 | 名称、说明、GLB 下载、本地库 | 不覆盖源部件 |
用户操作顺序
- 选择设计机型 XYZAC 或 XYZBC。
- 导入自包含 GLB，确认 SHA-256 和树结构。
- 整理父级和显隐，检查源模型的局部原点与零姿态。
- 为每个运动节点绑定一个轴和方向。
- 输入 RTCP 几何、物理零点并试动。
- 校验通过后应用、导出或保存。
- 控制面板重新回零，再加载匹配程序。
03 · REQUIREMENTS
详细功能需求
以下需求对应 Markdown 功能规格、实现任务和验收证据。
FR-01
机型选择。 新建时选择 XYZAC/XYZBC；机型写入草稿，切换时清除不兼容倾转绑定并可撤销。
FR-02
GLB 导入。 只接受自包含 GLB，记录文件名、大小、SHA-256 和源路径；外部资源拒绝。
FR-03
树与装配。 按 Object3D.children 显示，支持根部件和内部节点拖放，拒绝自指、循环和跨文件内部挂接。
FR-04
局部变换。 查看相对父级的零姿态；现行版只编辑绑定轴的单个运动量，固定节点锁定。源 GLB 不修改。
FR-05
坐标辅助。 原点轴挂在节点局部 (0,0,0)，随父链继承，不冒充世界轴。
FR-06
单自由度。 每节点最多一个 XYZABC 轴、每轴最多一个节点；方向在父坐标系定义。
FR-07
试动与跟随。 试动只改草稿；实时跟随锁定输入，轴值只来自完整 WASM snapshot。
FR-08
RTCP 标定。 固定使用 C 原点 P、倾转偏置 D、T=P+D、U=-D、work=-P 的映射。
FR-09
物理零点。 模型运动量为 sign × (WASM实际值 - physicalZero)，不修改控制器回零。
FR-10
预览渲染。 Z-up、视图预设、网格、PBR 补光、受限 DPR 和 context lost 恢复。
FR-11
校验应用。 先校验结构、角色、轴、标定、URDF 和 Schema，再通过配置事务交给 Worker；失败保留旧模型。
FR-12
保存恢复。 导出完整 GLB，同时下载并写入 IndexedDB；打开时重建源树再应用覆盖，避免双重偏移。
FR-13
机型与程序。 跨 AC/BC 加载目标默认程序；错轴程序在加载、运行、单步和继续入口拒绝。
FR-14
撤销取消。 草稿历史至少 30 步；选择器取消不关闭父对话框；打开和应用都是可回滚事务。
+
+坐标与单位
UI 平移、局部原点、C 原点和偏置使用 mm；UI 旋转和物理旋转轴零点使用 deg；GLB 节点位置使用 m、旋转使用四元数；JSON 的 zero.positionMm 使用 mm；URDF 使用 m/rad。
+安全门控
完整 GLB 保存/应用要求五轴绑定完整、输入和标定有效；实时快照缺失只暂停模型跟随，不改动正在运行的控制器。
+FUNCTIONAL SPECIFICATION
逐项功能说明与验收条件
以下描述按照现行管理器与 MGR-17～22 契约整理。每项给出操作、规则和可观察结果；展示能力与控制器动作分别说明。
+FR-01 机型与设计文档
入口为机床预览区“三维机床管理”。设计机型独立于控制面板当前机型；首次新建可沿用面板默认值。
操作与输入
- 选择 XYZAC 或 XYZBC，查看目标轴集合和控制面板当前类型。
- XYZAC 显示 X/Y/Z/A/C，XYZBC 显示 X/Y/Z/B/C；另一倾转轴不可选。
- 更换设计机型保留模型及通用轴；清除不兼容 A/B 绑定并重新检查标定。
规则与异常
- 设计类型进入草稿撤销历史；切换控制面板不能无提示覆盖草稿。
- 完整 GLB 打开恢复文件机型；其它案例只展示源码资料，未适配选项禁用。
验收：从 AC 草稿切换 BC，原 A 绑定被清除且不自动改名为 B；撤销能恢复原配置。
+FR-02 自包含 GLB 导入与资产管理
普通几何文件使用“导入 GLB 部件”；完整设计文件使用“打开已保存机床”。当前单文件上限为 64 MiB，支持仓库中约 34 MiB 的 OP30 机床资产；设备显存和节点数量仍可能限制预览性能。
操作与输入
- 解析 GLB 并检查资源自包含性；记录文件名、大小和 SHA-256。
- 生成部件 ID 和稳定源路径，显示原有 Object3D 层级。
- 多文件作为多个独立部件；同名文件不应覆盖已有 ID。
规则与异常
- 损坏文件、外部依赖或超限文件显示具体错误，保留旧草稿。
- 源字节、几何、材质和节点原始姿态不原地改写。
- 删除的是整个导入模型；仍被撤销历史引用的资源保留，失去全部引用后释放。
验收：成功导入单个 MILL700 和多个部件；错误文件不清空当前树；删除后可撤销。
+FR-03 层级、搜索与父级关系
结构页展示原始树和当前装配覆盖；节点身份使用 ID/路径，名称仅用于显示。
操作与输入
- 输入节点名称搜索并展开结果；选择树节点查看装配局部坐标和世界位置。
- 根部件可选择其它部件为装配父级；同一 GLB 内部节点支持拖放换父级。
- 内部节点拖放应维持世界姿态，再计算新父级下的局部变换；根部件父级选择按部件装配关系生效。
规则与异常
- 禁止把节点挂到自己或后代；拒绝缺失父级和跨 GLB 的内部节点重挂。
- 同名节点必须可以独立选中，不能按名称猜测绑定。
- 源路径保持稳定；覆盖记录与原始层级分开存储。
验收：深层树搜索能定位；拖放后子节点随父级，错误拖放回滚；源 GLB 哈希不变。
+FR-04 局部原点、零姿态与单轴编辑
局部原点是节点自身 (0,0,0)；装配位置是该原点在父坐标系中的位置；世界位置包含全部父链。
操作与输入
- 展开“零姿态与当前坐标”，读取装配位置 mm、姿态 deg 和当前世界原点。
- 先绑定唯一自由度，再通过单个“位移/转角”字段验证节点运动。
- 固定节点不能输入独立运动量，但随父节点正常运动。
规则与异常
- 当前版不提供绕过单自由度约束的六分量自由编辑或 TransformControls。
- 历史文件中的局部装配覆盖可以恢复；试动值不能保存成新的设计零姿态。
- 模型坐标由文件提供，Z-up 通过相机和辅助坐标呈现，不隐式修改源节点。
验收：固定节点字段禁用；绑定 Z 后只能输入该轴量；子节点继承且父节点/兄弟节点不被误改。
+FR-05 局部坐标轴、显示与定位
结构页提供模型显隐和坐标原点开关；预览工具包括整机适配、定位选中、正视和俯视。
操作与输入
- 选择节点，在其自身原点查看 X 红、Y 绿、Z 蓝坐标轴。
- 切换“显示导入模型”“显示坐标原点”以观察遮挡和父子关系。
- 左键旋转相机、滚轮缩放、右键平移；使用定位选中查看小部件。
规则与异常
- 辅助轴是节点的子对象，局部位置为零并继承完整父链；不能只复制一次世界坐标。
- 辅助对象属于预览，不作为机床几何导出。
- 相机操作不改变模型设计、试动值或控制器状态。
验收：父关节旋转后辅助轴一起旋转；关闭辅助再打开不重建全部 WebGL 资源。
+FR-06 唯一自由度与轴向映射
运动节点配置 axis、direction、sign；机型完整性由五个唯一绑定轴检查。
操作与输入
- 选择 X/Y/Z 平移或 A/B/C 旋转，固定部件选择“固定（无自由度）”。
- 指定父坐标系方向 x/y/z 以及正向 +1 或反向 −1。
- 在绑定总览检查五轴是否齐全，通过轴按钮定位对应节点。
规则与异常
- 同一个轴不能绑定两个节点；每个节点最多一个自由度。
- direction 属于父坐标系；例如父级已旋转时不能把它误认为世界 X。
- 单 GLB 的多个内部节点也能完成五轴绑定；八个独立文件不再是前提。
验收：重复绑定被校验阻止；正负号可反转视觉运动；固定节点跟随父链但不响应其它轴。
+FR-07 诊断试动与实时关节跟随
手动验证使用相对物理零点的试动量，不向 LinuxCNC 发送运动命令。
操作与输入
- 输入轴值或选择 0.1/1/10 步长进行正负步进；支持本轴归零和全部复位。
- 检查局部/世界诊断值，先单轴再复合运动，区分自身运动和父链继承。
- 控制面板机型匹配且快照有效时开启实时跟随，查看 WASM tick。
规则与异常
- 跟随时配置编辑、手动关节输入和应用锁定；取消后回到手动验证状态。
- 实时数据暂不可用时保持最后姿态，允许用户取消跟随；缺少任意轴不做部分更新。
- 每次从 zero 求绝对变换，不做累计旋转，临时姿态不进入保存文件。
验收：同一关节值重复更新 100 次不漂移；快照缺失不出现部分轴跳动；试动不改变控制器读数。
+FR-08 TRT 几何与旋转中心标定
标定长度均为 mm。C 原点 P 对应 rot-point；倾转偏置 D 对应 offset。
操作与输入
- 填写 C 轴原点 P=(Px,Py,Pz) 和 A/B 到 C 偏置 D=(Dx,Dy,Dz)。
- 确认 AC 的 Dx=0、BC 的 Dy=0；非零值超过实现容差时拒绝应用。
- 生成控制参考链：倾转原点 T=P+D、C 关节相对原点 U=−D、工件固定原点=−P。
规则与异常
- 标定需经现有配置重载进入 WASM；移动视觉网格不能代替运动学参数。
- 几何元数据写入运行场景和底座，完整文件保留标定。
- 现有 AC/BC TRT 参数不能直接套用于双摆头、MAX5、机器人和并联平台。
验收：保存/打开参数等价；AC 非法 X 偏置、BC 非法 Y 偏置能定位错误；有效参数进入模型和控制框架。
+FR-09 物理零点与控制器坐标区别
physicalZero 表示模型 zero 对应的实际关节读数；线性单位 mm，角度单位 deg。
操作与输入
- 分别录入当前机型 X/Y/Z/A或B/C 的零姿态读数。
- 实时跟随使用 d=sign×(q−q0)；例如 q=25 mm、q0=5 mm、sign=−1，模型运动量为 −20 mm。
- 手动试动输入已是相对零位量，不再把 q0 重复扣除。
规则与异常
- 不修改 INI 回零位置、G54、G92 或刀补；这些各有独立语义。
- 所有值必须有限；界面只展示当前机型五轴，序列化 physicalZero 保留 xyzabc 六个键。
验收：实际读数等于 q0 时回到模型零姿态；改变 q0 只改变可视化标定，不伪造控制器实际位置。
+FR-10 渲染、照明与资源生命周期
管理器独立 Three.js 预览采用 Z-up，相机朝向与模型原始轴向分开处理。
操作与输入
- 通过整机适配查看完整模型，用正视/俯视核对安装方向。
- PMREM 环境、曝光和多向补光保证金属材质可辨认。
- 按设备最大尺寸和 4096² 像素预算限制 drawing buffer，处理高 DPR 与窄屏。
规则与异常
- 不覆盖导入材质颜色、金属度和纹理来改善照明。
- 零尺寸或 context lost 暂停绘制；恢复或重开不应丢失设计草稿。
- 删除/关闭/撤销的资源清理遵守历史引用，不能释放仍需恢复的模型。
验收：高金属度模型可辨认；矮视口、高 DPI 下无连续 WebGL 错误；相机不改变 WASM tick。
+FR-11 配置校验与应用到控制器
应用要求关机、程序空闲、无待处理事务、未实时跟随、输入有效且目标五轴绑定完整。
操作与输入
- 先检查 ID、父级、无环、轴集合、零姿态、标定和元数据版本。
- 生成运行场景深复制、URDF 控制参考链及视觉关节映射，避免节点被驱动两次。
- 通过既有 LOAD_WORKSPACE / PROGRAM_LOAD 流程更新机型、参数和程序；完成后重新回零。
规则与异常
- 新版按五轴映射校验；旧八部件格式保留严格角色链兼容路径。
- 校验失败不替换已应用模型；配置加载失败显示诊断并由已有恢复流程处理。
- 应用不等于磁盘保存；应用后仍应导出 GLB 才能跨会话携带设计。
验收：单 GLB 完整五轴可应用；未绑定五轴不可应用；跨机型后程序与轴集合匹配。
+FR-12 完整保存、下载与重新打开
保存 GLB 要求绑定完整；导出 JSON 是辅助参数文件，不能替代包含几何的完整 GLB。
操作与输入
- 在“文件与恢复”填写模型名称（最多 80 字符）和设计说明（最多 2000 字符）。
- 点击“保存机床模型 GLB”，先生成并由标准导入器校验，再尝试写入 IndexedDB 并发起下载。
- 在本地库查看时间、机型、大小和哈希，选择打开配置、下载 GLB 或删除副本。
- 再次打开先重建原始多部件拓扑，再施加覆盖；恢复机型、轴向、标定和显隐。
规则与异常
- 每次保存形成独立版本；网页只知道发起下载，不知道最终磁盘路径或是否取消下载。
- 本地库存储仅限同浏览器/同源地址，清理站点数据会删除副本；存储失败仍可下载。
- 不完整草稿、撤销历史、相机视角和试动值不跨刷新自动保存。
- 旧 GLB 缺编辑元数据时恢复可用配置，不能声称精确恢复丢失的多文件分组。
验收：保存→刷新→库打开→再次保存后几何和配置等价；库失败仍有下载；删除副本不删除当前草稿或磁盘文件。
+FR-13 机型、程序和运行一致性
程序字母与设计/运行机型保持一致；Worker 对入口再次进行轴兼容检查。
操作与输入
- 同机型应用保留兼容程序；跨 AC/BC 先取得目标机型默认程序再提交切换。
- 确认程序路径、源文本、预览和控制面板机型一致。
- 加载、运行、单步和继续都检查错误倾转轴；不以 A/B 字符串替换完成适配。
规则与异常
- 注释和参数名称中的 A/B 不等同轴指令，完整语法仍由 LinuxCNC 解释器处理。
- 不能从“字母都是 XYZBC”推断 MAX5 与 BC TRT 运动学一致。
验收：AC↔BC 双向切换通过；同机型保留用户兼容程序；错轴文件在 Worker 拒绝。
+FR-14 草稿历史、取消与失败恢复
撤销历史是本会话配置快照，最多保留 30 步，源资产按引用共享。
操作与输入
- 导入、类型切换、绑定和文档打开等设计修改进入历史，按撤销/重做恢复。
- 关闭管理器保留本会话草稿；刷新只恢复显式保存的完整版本。
- 文件选择器取消或窗口回焦时保持父对话框、焦点和配置。
规则与异常
- 新建或打开文件不能偷偷应用到正在运行的控制面板。
- 无效输入保持原有效模型姿态，并可定位第一个错误字段。
- 忙碌或实时跟随时禁用冲突配置动作；相机观察仍独立于控制状态。
验收：新建后撤销找回原草稿；取消三类文件选择器均不关闭父对话框；导入失败没有资源残留。
+MACHINE STRUCTURES
先看旋转轴安装在哪里
典型五轴铣削通常由三平移轴与两姿态轴构成。相同 XYZBC 字母可以对应不同机械链，轴在刀具侧还是工件侧、父子顺序和旋转中心都决定运动学。参考 LinuxCNC 五轴运动学说明。
+
双转台 / 台台型
两个旋转轴位于工件侧。案例：AC/BC TRT 与 AB 双转台。当前可运行 AC/BC；AB 需管理器适配。
+双摆头 / 头头型
两个姿态轴位于刀具侧，工件无需随姿态一起旋转。案例：Bridge Mill / 5axiskins；含 W 与重复 Y 的配置需独立适配。
+摆头 + 转台 / 头台型
一个姿态轴在刀具侧、另一个在工件侧。案例：MAX5，B 倾转头配合 C 转台；不能用 BC TRT 直接替代。
+图示只表示姿态轴在刀具/工件两侧的分布，不表示机床尺寸、具体轴正向或可制造的结构。
| 区分维度 | 如何判断 | 本项目案例 |
|---|---|---|
| 运动学结构 | 双转台、双摆头、头台、串联、并联 | 按各自求解器和参数建模 |
| 床身外形 | 立式、卧式、桥式/龙门 | AC/BC 桁架 GLB 是同一 TRT 求解器的外形变体 |
| 加工方式 | 3+2 定位与连续五轴是程序/插补方式 | 不能只看五个字母就确认联动与 RTCP |
| 车铣复合 | 还涉及主轴/C 轴切换和复合工艺 | 当前目录没有完整已接通案例；XYZCW 基线不能作为车铣能力证明 |
| 轴数与关节数 | 例如双 Y 多一个驱动关节但没有增加独立加工自由度 | XYZYA 是五关节基线，不是通常的三平移+两旋转五轴铣床 |
范围：下文覆盖仓库案例目录的全部 13 项，另补齐三类常见姿态结构的对应关系；不声称穷尽所有工业机床结构。六自由度及映射基线均单独标明。
+04 · FIVE-AXIS CATALOG
每种类型的五轴机床案例
案例与 LinuxCNC 配置、运动学源码和 G 代码一致。绿色为当前 Web/WASM 已接通；原生 XYZAC/XYZBC 使用 TRT 运行链，其余案例使用通用 WASM 运动学桥接。Hexapod/PUMA 等六自由度案例按各自关节结构运行，不伪装成 TRT 铣床。
显示 13 / 13 个案例
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
XYZAC · 转台倾转
当前支持- 结构
- 工件转台 A/C
- 坐标
- XYZAC · 5 关节
- 运动学
- xyzac-trt-kins
- RTCP
- native
A 绕 X 倾转、C 绕 Z 回转；配置 C 原点、A 到 C 偏置、刀长和物理零点。
案例：AC 叶轮 / 小船仿真
机械链：刀具参考链：底座→X→Y→Z→刀具；工件参考链：底座→A→C→工件。
配置要点：C 轴旋转点、倾转轴到 C 轴偏置、工具偏置、物理零点。
验证路径：先做 A、C 单轴验证，再运行 boat-xyzac 或 impeller-7bl-xyzac，检查程序点、刀尖和工件附着路径。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
展开配置、源码与程序路径
- linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
- linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/boat-xyzac.ngc
- linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/impeller-7bl-xyzac.ngc
- linuxcnc/configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/xyzac-trt.ini
- linuxcnc/configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/examples/boat-xyzac.ngc
- linuxcnc/configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/examples/impeller-7bl-xyzac.ngc
- linuxcnc/configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/examples/test-xyzac.ngc
- linuxcnc/src/emc/kinematics/xyzac-trt-kins.c
XYZBC · 转台倾转
当前支持- 结构
- 工件转台 B/C
- 坐标
- XYZBC · 5 关节
- 运动学
- xyzbc-trt-kins
- RTCP
- native
B 绕 Y 倾转、C 绕 Z 回转；与 AC 共用流程，但倾转轴、程序和标定严格隔离。
案例：BC 小船 / 五轴测试程序
机械链：刀具参考链保持 XYZ；工件参考链为底座→B→C→工件。
配置要点：C 轴旋转点、倾转轴到 C 轴偏置、工具偏置、物理零点。
验证路径：先做 B、C 单轴验证，加载 boat-xyzbc 或 test-xyzbc；切入 BC 时检查程序中的倾转轴为 B。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
展开配置、源码与程序路径
- linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini
- linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/boat-xyzbc.ngc
- linuxcnc/configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/examples/test-xyzbc.ngc
- linuxcnc/configs/sim/gmoccapy/non_trivial_kinematics/table-rotary-tilting/examples/boat-xyzbc.ngc
- linuxcnc/src/emc/kinematics/xyzbc-trt-kins.c
XYZAB · 双转台
需适配- 结构
- 双转台 A/B
- 坐标
- XYZAB · 5 关节
- 运动学
- xyzab_tdr_kins
- RTCP
- LinuxCNC 原生
两个转轴叠加在工件侧，配置旋转点、X/Z 偏置和 TCP。
案例：双转台 TCP 演示
机械链：以本地 TDR Vismach/HAL 的 A/B 轴序、转点和偏置为准。
配置要点：旋转点 X、旋转点 Y、旋转点 Z、X 偏置、Z 偏置、工具偏置、物理零点。
验证路径：原生运行 xyzab-tdr-demo.ngc；Web 接入前增加 XYZAB 能力、专用运动学参数和正逆解对照。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
Bridge Mill · 5axiskins
需适配- 结构
- 桥式 + 姿态头
- 坐标
- XYZBCWY · 7 关节
- 运动学
- 5axiskins
- 特点
- 重复轴 / W
验证多关节映射、双 Y 和 W 刀具方向；需保存重复轴关系。
案例：桥式双摆头与双 Y
机械链：B/C 位于刀具姿态链；W 是刀具方向坐标，源码将其纳入 XYZ 运动；示例还有重复 Y。
配置要点：关节/坐标映射、重复轴映射、刀具方向坐标、工具偏置、物理零点。
验证路径：核对 7 关节映射和 pivot_length；运行 5axisgui.ngc 对照姿态。不能把 W 误画成必需的独立物理执行器。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
MAX5 · maxkins
需适配- 结构
- 转台 + 摆头
- 坐标
- XYZBC · 6 关节
- 运动学
- maxkins
- 用途
- 非恒等五轴
maxkins 与 trivkins 对照案例，适合验证旋转轴顺序和工具方向。
案例：桌面头台式五轴
机械链：B 倾转主轴头；C 在工件转台。源码提示 B 轴方向与通常约定相反。
配置要点：旋转轴顺序、旋转中心、UVW 变换、工具偏置、物理零点。
验证路径：对照 max5kins.ini / max5triv.ini，检查 pivot_length、UVW 项和 B 正负；不能重用 TRT 几何参数。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
Pentapod · pentakins
需适配- 结构
- 五支链并联
- 坐标
- XYZAB · 5 关节
- 运动学
- pentakins
- 参数
- base / effector
使用支链几何和迭代求解，不能直接套普通树形 XYZABC。
案例：五支链 TCP 定位
机械链：平台姿态由五条支链长度共同决定，支链关节值并不是 X/Y/Z/A/B 逐项对应。
配置要点：基座连接点、末端几何、工具偏置、收敛条件、物理零点。
验证路径：用 kinematics.hal / README 中的几何起步，对照正逆解、收敛失败和支链极限；本地条目未提供独立 NGC。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
Hexapod · genhexkins
需适配- 结构
- 六支链并联
- 坐标
- XYZABC · 6 关节
- 运动学
- genhexkins
- 参数
- 基座/平台连接点
六自由度平台可承载五轴姿态任务，需要独立支链、螺杆和迭代适配。
案例：六支链 Stewart 平台
机械链：基座和动平台各有连接点；六支链长度约束 XYZABC 六自由度。
配置要点：基座连接点、平台连接点、主轴偏置、螺杆导程、迭代限值、物理零点。
验证路径：检查基座/平台点、主轴偏置、迭代参数；用原生配置验证收敛与支链运动，不套串联树求解。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
PUMA · pumakins
需适配- 结构
- 六关节串联
- 坐标
- XYZABC · 6 关节
- 运动学
- pumakins
- 边界
- 不是 TRT 铣床
适合五轴刀具姿态和 TCP 视觉验证，需要连杆、限位和机器人适配器。
案例：PUMA 立方体 TCP 轨迹
机械链：六个旋转关节形成串联连杆；工作空间 XYZABC 与关节角不是相同数据。
配置要点：A2、A3、D3、D4、工具偏置、物理零点。
验证路径：使用 puma_cube.ini 和 puma_cube.ngc，检查连杆尺寸、可达性及运动学分支；需关节反馈适配。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
PUMA 560 · genserkins
需适配- 结构
- DH 串联
- 坐标
- XYZABC · 6 关节
- 运动学
- genserkins
- 参数
- DH、限位、刀长
用 DH 参数描述关节链，不能直接套用 AC/BC TRT 标定。
案例：PUMA 560 的 DH 配置
机械链：每一节连杆由 DH 参数描述，工具和基座坐标变换独立。
配置要点：DH 参数、关节限位、工具偏置、物理零点。
验证路径：对照 puma560_dh.hal，验证六关节与末端姿态；关节限位、TCP 和奇异位形不能从 TRT 参数推断。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
XYZAB · trivkins
映射基线- 结构
- 直角坐标 + 两旋转
- 坐标
- XYZAB · 5 关节
- 运动学
- trivkins
- RTCP
- 无非线性 RTCP
验证 GLB 树、轴序、重复轴和显示映射，不提供 TRT 求解。
案例：五轴字母映射回归
机械链：坐标与关节按恒等映射配置；没有用于旋转补偿的非线性 RTCP 求解。
配置要点：坐标顺序、重复轴映射、物理零点。
验证路径：对比 qtdragon / woodpecker 的轴序和 GUI；显示正确不等于能执行 AC/BC TRT 补偿。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
案例：C/W 非标准字母映射
机械链：C 为旋转字母，W 为附加线性字母；五个坐标不等于典型五轴铣削姿态结构。
配置要点：坐标顺序、刀具方向坐标、物理零点。
验证路径：检查 gmoccapy_XYZCW.ini 的轴序和单位；只能作为坐标与关节映射测试案例。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
XYZYA · trivkins
映射基线- 结构
- 双 Y + 旋转 A
- 坐标
- XYZYA · 5 关节
- 运动学
- trivkins
- 用途
- 重复/非标准轴序
验证重复 Y、轴序和界面映射，不能声明具备非线性 RTCP。
案例：双 Y 龙门映射回归
机械链：同一 Y 轴由两个关节描述，另有旋转 A；不能从关节数量推断加工自由度。
配置要点：坐标顺序、重复轴映射、物理零点。
验证路径：检查 qtdragon_multi_joint 与 woodpecker 对重复 Y 的配置、显示与关节区分。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
SCORBOT · scorbot-kins
需适配- 结构
- 五关节串联
- 坐标
- XYZAB · 5 关节
- 运动学
- scorbot-kins
- 边界
- 机器人案例
验证机器人装配边界和关节限位，不按 TRT 生成 C 原点或 A/B 偏置。
案例：五关节机器人
机械链：五关节串联结构；XYZAB 是任务坐标声明，不表示常规五轴铣床机械链。
配置要点：机器人连杆参数、关节限位、工具偏置、物理零点。
验证路径：对照 scorbot.ini 和源码连杆参数验证末端姿态、限位与可达范围；缺少完整 Web 接入验收。
参数名称来自案例目录，具体 HAL/INI 字段及单位以该案例源码为准。示意图非比例，未适配案例不可直接应用到当前管理器。
没有匹配案例。可尝试输入 XYZAC、XYZBC、桥式或 trivkins。
+WORKED EXAMPLES
从装配到恢复的完整案例
案例 A：八个示例部件 → AC TRT
- 新建 XYZAC，导入床身、XYZ、刀具、A、C、工件部件。
- 按机械父链放置固定与运动部件，绑定 X/Y/Z/A/C；只有真实运动节点绑定自由度。
- 基于模型实测原点录入 P、D 和 q0，AC 的 Dx 必须为 0；不要照抄其它机床数值。
- 分别试动 X、Y、Z、A、C，确认下级随动和正负方向；临时量复位。
- 保存 GLB，关机且空闲时应用，重新回零并运行匹配 AC 程序。
案例 B：单个 MILL700 → 五轴模型
- 导入本地 MILL700-U_1.glb，在树内定位各滑台和旋转节点。
- 给主轴/工作台相应节点绑定五轴，固定外壳保持无自由度；同名节点用稳定路径区分。
- 检查父链和节点原点。零姿态来源于模型，不用试动值修正建模错误。
- 若改作 BC 演示，先切换设计类型，再重新绑定 B，核实轴向和结构是否匹配 BC TRT。
- 完整保存，再从文件打开，核对 5/5 绑定与标定是否一致。
MILL700 的 AC/BC 配置是仓库软件验收场景；不代表该型号实机可以不改机械结构直接互换 AC/BC。
| 动作 | 影响当前草稿 | 影响控制器 | 刷新后恢复 |
|---|---|---|---|
| 试动 / 改相机 | 仅临时展示 | 无 | 不保存 |
| 绑定 / 标定 / 树修改 | 设计快照，可撤销 | 应用前无 | 未保存时不可恢复 |
| 应用机床 | 标记已应用 | 更新运行配置，需重新回零 | 不等于保存设计文件 |
| 保存 GLB | 记录保存状态 | 不自动应用 | 磁盘文件或库副本可打开 |
| 导出 JSON | 参数辅助输出 | 无 | 不含完整几何 |
| 删除本地库副本 | 不删除当前草稿 | 无 | 只删除对应库记录 |
05 · DATA & SAFETY
数据、坐标与安全边界
+
+
四类元数据
| 字段 | 职责 |
|---|---|
linuxcncMachine | 现有严格 URDF 与运行控制框架 |
linuxcncMachineGeometry | C 原点、倾转偏置、物理零点 |
linuxcncJointModel | 父链、零姿态、轴映射、方向和正负 |
linuxcncMachineEditor | 名称、说明、源部件和编辑覆盖 |
视觉运动映射
q = WASM 实际轴值 +q0 = physicalZero +s = +1 或 -1 +e = 父坐标系中的 x / y / z + +d = s × (q - q0) +平移：p[m] = zero.positionMm / 1000 + e × d / 1000 +旋转：Q = Quaternion(e, d × π/180) × zero.quaternion + +子节点继承父级矩阵；每帧从零姿态绝对计算。+
+
+应用前门控
- 机型为 XYZAC 或 XYZBC。
- 新版要求五轴唯一绑定、节点树无环；旧八部件格式按原角色链校验。
- 每轴最多一个节点，每节点最多一个自由度。
- 标定、零点、四元数和资源数据有限。
- 目标程序和 Worker 轴序一致。
错误后的保证
- 外部资源 GLB：拒绝导入，旧草稿不变。
- 非法输入：保留上一个有效值，不驱动模型。
- 缺少 snapshot 轴值：保持上一帧姿态。
- 应用或存储失败：不替换已应用模型。
- WebGL context lost：暂停渲染，控制器不变。
错误与恢复矩阵
| 触发条件 | 界面响应 | 可恢复操作 |
|---|---|---|
| GLB 超过 64 MiB、损坏或外部资源 | 报告文件错误，保留原草稿 | 重新导出自包含轻量 GLB，再导入 |
| 父级循环 / 跨文件内部节点挂接 | 拒绝变更，不改源文件 | 选择有效父级，或把部件作为独立根装配 |
| 数值为空、非有限 / 非法偏置 | 保留原有效姿态，定位字段，阻止保存/应用 | 修正输入后重新校验 |
| 关节绑定缺失 / 重复 | 列出配置阻塞原因 | 到绑定总览定位并补齐五轴 |
| 机型不匹配 / 实时数据缺失 | 无法开始跟随或保持最后姿态 | 退出跟随；核对机型与数据连接 |
| 本地库配额或写入失败 | 提示库副本未保存，继续发起下载 | 从磁盘 GLB 打开，清理库后另存 |
| 程序含错误机型轴字 | Worker 拒绝加载/执行入口 | 加载目标机型程序，不替换字母伪造适配 |
| 文件选择取消 | 保留管理器、焦点和原配置 | 继续编辑或再次选择文件 |
字段字典与转换边界
| 字段 | 类型 / 单位 | 校验和用途 |
|---|---|---|
| schema / coordinates | 版本字符串 / XYZAC 或 XYZBC | 未知版本不得猜测解析 |
| controller.axisOrder | 五个轴名 | 与机型顺序一致；通过轴名映射视觉关节 |
| axisMap | 轴名 → 稳定节点 ID | 必须与节点 joint 一致，不依赖显示名称 |
| nodes[].id / parentId | 字符串 / 字符串或 null | 唯一 ID、有效父级、无环；当前模型 1～12000 条记录 |
| nodes[].zero.positionMm | 三个有限数，mm | 相对父级零姿态；传给 Three.js 时除以 1000 |
| nodes[].zero.quaternion | [x,y,z,w] | 归一化，顺序不可误用为 wxyz |
| nodes[].zero.scale | 三个正数 | 保留源比例，不是显示单位切换 |
| joint.axis/type/unit | XYZABC / prismatic或revolute / mm或deg | 机型、轴类型和单位一致 |
| joint.direction/frame/sign/dof | x/y/z；parent；±1；1 | 在父坐标系中施加单自由度运动 |
| calibration.cOriginMm / tiltOffsetMm | 两个三分量向量，mm | AC 不接受 X 偏置，BC 不接受 Y 偏置 |
| calibration.physicalZero | xyzabc 六字段；mm/deg | UI 编辑当前机型五轴，运行 q−q0 |
| source.file/hash/path | 字符串 | 追溯源文件和稳定源节点路径 |
| editor.info.name/description | 80 / 2000 字符上限 | 人可读文档描述，不作轴绑定身份 |
关节 Schema：linuxcnc.joint-model/1；完整样例：XYZAC JSON / XYZBC JSON。
A/B/C 字母常用于绕 X/Y/Z 的旋转，但可视化配置的 direction 指父坐标方向；具体符号以原生求解器、GLB 零姿态和实际测试为准。GLB 节点旋转存四元数，不能把 UI 欧拉角直接当作四元数数组。
06 · ACCEPTANCE
验收与后续适配
+
功能验收清单
以下为验收项目清单，历史通过情况以证据文档为准；本次仅验证 HTML 文档。
- AC/BC 多部件装配、应用和实时运动
- 树搜索、拖放、删除和循环拒绝
- 局部原点、父子继承和 Z-up 预览
- 单自由度、方向、正负和物理零点
- RTCP 参数保存与重新打开
- 完整 GLB 导出与 IndexedDB 恢复
- 跨机型默认程序和错轴门控
- 取消选择器和失败回滚
案例状态含义
当前支持 已有真实 Worker/WASM 正解、逆解和 RTCP 证据。
需适配 有 LinuxCNC 本地案例，需要新的运动学适配器。
映射基线 用于树、轴序、重复轴或界面校验，不提供非线性 RTCP。
新机型必须先加入 five-axis-machine-catalog.json，记录 coordinates、joints、kinematics、案例路径、参数和能力状态。
工程与非功能验收
- 坐标：使用父级旋转、非单位零姿态四元数、正负方向和非零 physicalZero 测试，比较 local/world；不能只检查画面非空。
- 保存往返：相同配置的几何和关节映射应等价；保存时间和版本 ID 可以变化，不要求整个 GLB 字节相同。
- 资源：重复导入、删除、撤销、重开后正确回收无引用资产，保留历史仍引用的场景。
- 响应式：桌面、窄屏、矮屏可访问预览、页签和底部操作；错误字段可定位。
- 兼容性：旧 GLB/URDF 仍可读取；缺失编辑元数据应说明恢复精度，不静默制造丢失信息。
- 控制边界：相机与手动模型试动不修改 Worker；正式运动以实际关节快照为源。
- 项目证据：TypeScript、构建、数学验证与浏览器报告按影响范围执行，具体历史结果见验收证据，不用截图替代数据断言。
本版本范围以外
云端共享、多人协作、角色审批、碰撞与刚体动力学、切削材料去除、真实硬件控制、任意视觉树自动生成逆解，以及尚未接通案例的完整机床运行，都不属于当前管理器交付范围。
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ ![AXIS]({axisIcon("axis-24x24.png")})
AXIS
