Apply hierarchy node transforms relative to parents

2026-09-21 09:11:38 +08:00
parent 63f726dc32
commit a472911ad1
19 changed files with 181 additions and 113 deletions
--- a/docs/glb-machine-manager/02-项目程序开发详细步骤.md
+++ b/docs/glb-machine-manager/02-项目程序开发详细步骤.md
@@ -12,5 +12,6 @@
 10. `MGR-12`：按 GLB 原始 `Object3D.children` 显示树，支持根部件和内部节点拖放，选择节点显示父级局部原点；用 MILL700 六层结构验收。
 11. `MGR-14`：新增导入模型删除、树节点轴绑定和 XYZ/ABC 层级运动测试，输出局部/世界变换；MILL700 主轴链与工作台链验收。
 12. `MGR-15`：树选择关节后，将 XYZ 辅助轴挂在该节点局部原点，并验证轴系跟随关节及父链旋转。
+13. `MGR-16`：将根节点部件变换和内部节点 `nodeTransforms[path]` 分开保存；编辑当前节点相对父级的位置和姿态，验证子节点继承、父兄节点不受影响、拖放换父级后保持世界姿态，并验证组合 GLB 与 AC/BC 应用结果。

 每轮只推进任务矩阵中依赖已满足的任务。代码完成后必须同步更新 03、04、05；若改变数据契约或坐标定义，先更新 06。
--- a/docs/glb-machine-manager/03-推进台账.md
+++ b/docs/glb-machine-manager/03-推进台账.md
@@ -71,10 +71,11 @@
 - 当前任务：已完成。
 - 下一步：按新需求继续；本专项不重复执行。

-## R09 / 2026-09-21 / 部件平移与旋转实时同步
+## R09 / 2026-09-21 / 部件节点相对父级变换

- 用户反馈编辑器中的“部件平移”和“部件旋转”改变后，预览中的对应 GLB 部件没有稳定更新。
- 预览同步逻辑新增部件根节点变换步骤：每次状态同步都把 `translationMm` 转换为米写入导入部件根节点位置，把 `rotationDeg` 转换为弧度写入根节点姿态；当前选中内部关节时仍变换该关节所属的完整 GLB 部件。
- 轴运动诊断随后在部件装配姿态上叠加，不覆盖编辑器已经设置的部件变换；组合导出的 geometry userData 同步保存平移和旋转值。
- MILL700 输入 X 平移 100 mm、Z 旋转 20° 后，选中关节的世界原点和世界四元数均发生对应变化；8 部件 AC/BC 生产回归输入 X=10 mm、Z=15° 后，预览、导出和应用后的 geometry 分别保存 `translationMm[0]=10`、`rotationDeg[2]=15`。
+- 用户明确要求“部件平移”和“部件旋转”修改当前选中节点相对其父节点的位置和姿态。
+- 根节点继续使用部件级 `translationMm`、`rotationDeg`；GLB 内部节点使用稳定源路径保存到 `nodeTransforms[path]`。输入值是当前节点的父级局部位置（mm）和 XYZ 欧拉姿态（deg），旋转中心是节点自身原点。
+- 预览克隆、组合导出和应用运行场景统一应用同一组局部节点变换；父节点运动时子节点继承，编辑子节点不会错误移动整个 GLB 根部件。
+- 拖放内部节点后保存当前局部姿态并重新计算新的父级局部姿态，保持拖放前的世界姿态。
+- MILL700 选择 `MILL700-A-主轴-JT3`，输入 X=120 mm、RZ=25° 后，节点局部位置和四元数分别变为 `0.120 m` 和 `25°`；8 部件 AC/BC 生产回归、导出和应用继续通过。
 - MGR-16 verified；验收证据 E11。
--- a/docs/glb-machine-manager/04-任务矩阵.md
+++ b/docs/glb-machine-manager/04-任务矩阵.md
@@ -17,4 +17,4 @@
 |MGR-13 WebGL 资源稳定性|verified|MGR-10,MGR-12|禁用超限 MSAA；drawing buffer 按 GPU 上限和像素预算缩放；零尺寸/context lost 不连续绘制；短视口 DPR3 无警告|
 |MGR-14 层级运动验证|verified|MGR-12,MGR-13|模型删除；树节点轴绑定；XYZ mm、A/B/C deg 输入驱动局部层级；local/world 变换和 MILL700 父子联动验收|
 |MGR-15 关节局部坐标系|verified|MGR-12,MGR-14|选中树节点时局部 XYZ 辅助轴挂在节点 `(0,0,0)`，随关节和父链变换，不重建 WebGL|
-|MGR-16 部件平移旋转同步|verified|MGR-05,MGR-14|编辑“部件平移/部件旋转”后对应 GLB 部件根节点实时改变位置和姿态；内部关节选择不改变变换归属；预览、导出和 AC/BC 应用保持一致|
+|MGR-16 部件节点相对父级变换|verified|MGR-05,MGR-14|编辑树中当前节点的“部件平移/部件旋转”后，该节点相对父级的位置和姿态改变；父节点与兄弟节点不被误改；子节点继承；预览、导出和 AC/BC 应用保持一致|
--- a/docs/glb-machine-manager/05-验收证据.md
+++ b/docs/glb-machine-manager/05-验收证据.md
@@ -12,12 +12,12 @@
 - 命令：`PLAYWRIGHT_MODULE=/home/mes006/.npm/_npx/e41f203b7505f1fb/node_modules/playwright/index.mjs node scripts/test_machine_manager_browser.mjs`
 - report_id：`GLB-MGR-E01`
 - 报告：`coverage/glb-machine-manager/browser.report.json`
- SHA-256：`486108398c757421d59fd5311239675b82d6c688458975b7c613118920ceafbf`
+- SHA-256：`a24ae854c1817f13b2c6c4fc03d33b855952e92eaa54f900482eaba9f3acd6de`
 - 状态：verified；浏览器错误 0。
 - 覆盖：8 部件导入和预览、原点显隐、数值/TransformControls 变换、组合 GLB 导出、AC/BC 应用、底座 userData、物理零点、非法层级拒绝、BC 五轴程序。
 - 截图：
-  - `coverage/glb-machine-manager/manager-ac-config.png`，SHA-256 `b2fc2e00497ddb1e72e3170ee83ed54c21c8da9099036d84eeb4d6d6eef8619b`
-  - `coverage/glb-machine-manager/managed-bc-running.png`，SHA-256 `4b2d76cd505f1e31847d09650b052a0a9c393515cb7c71ad55ac649072634005`
+  - `coverage/glb-machine-manager/manager-ac-config.png`，SHA-256 `ddfc10ebc03d0c72860ce4f21a3c7e290f9c8eeaa9dcaa97ff0a1c8b3e2bc860`
+  - `coverage/glb-machine-manager/managed-bc-running.png`，SHA-256 `f05cd2f3701c68fe82c5c57d6aa92b54c92d6783d1a395efb5fe96ec5a9bfe4f`

 ## E03 / R02 / 生产构建浏览器闭环

@@ -25,12 +25,12 @@
 - 命令：`MACHINE_MANAGER_SOURCE_MODULES=0 ... node scripts/test_machine_manager_browser.mjs`
 - report_id：`GLB-MGR-E02`
 - 报告：`coverage/glb-machine-manager/browser-production.report.json`
- SHA-256：`7ea2ba7c09a2480973e63aedb8da1b8b0d46914eb86519781d99b718c5d3fca6`
+- SHA-256：`9549e8e731803c86780b1113afda3adb78e8846626bf4b6006d8c9241ac457a9`
 - 状态：verified；生产资产执行 AC/BC UI 应用和 BC WASM 程序运动，浏览器错误 0。

 ## E04 / R02 / 回归与静态契约

- `node scripts/test_axis_control_inventory.mjs`：verified，99 个文档化控件。
+- `node scripts/test_axis_control_inventory.mjs`：verified，114 个文档化控件。
 - `node web/react/src/test_dual_canvas_contract.mjs`：verified。
 - `node web/react/src/test_xyzac_threejs.mjs`：verified。
 - `npm --prefix web/react run typecheck`：通过。
@@ -61,7 +61,7 @@
 - 节点选择：`MILL700-A-主轴-JT2` 显示相对父节点原点 `-3.969 / -204.276 / 405.633 mm`。
 - 拖放：`MILL700-A-门1-JT1` 拖到 `MILL700-A底座` 后，草稿父路径等于目标稳定源路径；原始 GLB SHA-256 保持 `bf37130681cc6462412e52744519516e8ade2a3212dd69153c0b1b3e415bcf66`。
 - 八个独立 GLB 的根树节点拖放通过；随后 AC/BC 应用、导出和程序运动回归仍通过。
- 控件契约：101 个控件，新增 `machine-tree-node` 和 `machine-tree-origin`；TypeScript、生产构建、双画布测试通过，浏览器错误 0。
+- 控件契约：114 个控件，包含节点相对位置/姿态输入 `machine-manager-translation`、`machine-manager-rotation`；TypeScript、生产构建、双画布测试通过，浏览器错误 0。

 ## E08 / R06 / WebGL framebuffer 稳定性

@@ -87,12 +87,12 @@
 - 三轴箭头组的局部 position=(0,0,0)、quaternion=identity，父对象为所选 GLB 节点；X 红/Y 绿/Z 蓝且按整机尺寸缩放，表示关节自己的局部轴并继承完整父链。
 - 节点选择和轴值驱动期间 `context-generation=1`，浏览器 warning/error=0。

-## E11 / R09 / 部件平移旋转同步
+## E11 / R09 / 部件节点相对父级变换

 - MILL700 命令：`PLAYWRIGHT_MODULE=/home/mes006/.npm/_npx/e41f203b7505f1fb/node_modules/playwright/index.js MACHINE_MANAGER_URL=http://127.0.0.1:5180/ node scripts/test_machine_manager_mill700_browser.mjs`。
- MILL700 report_id：`GLB-MGR-E05`；报告 SHA-256：`1a9489e9df2633f54de395a4a116d4726a56cc0bfc8f2115681e7340e52b9fbf`。
- MILL700：输入部件 X 平移 `100 mm` 后，选中根节点世界 X 坐标增加 `0.1 m`；输入 Z 旋转 `20°` 后，选中根节点世界四元数发生变化；132 节点、126 网格和局部坐标系检查继续通过，浏览器 warning/error=0。
+- MILL700 report_id：`GLB-MGR-E05`；报告 SHA-256：`d76e64bd946af2a2c5ea0b2e93230a62cd7455d547db041223ba3a77f1c8ae29`。
+- MILL700：先验证根节点 X 平移 `100 mm`、Z 旋转 `20°`；再选择内部节点 `MILL700-A-主轴-JT3`，输入相对父级 X=`120 mm`、RZ=`25°`，预览发布的 selected transform 为 local X=`0.120 m`、local quaternion 对应 `25°`；132 节点、126 网格和局部坐标系检查继续通过，浏览器 warning/error=0。
 - AC/BC 生产回归命令：`PLAYWRIGHT_MODULE=/home/mes006/.npm/_npx/e41f203b7505f1fb/node_modules/playwright/index.js MACHINE_MANAGER_SOURCE_MODULES=0 MACHINE_MANAGER_URL=http://127.0.0.1:5180/ node scripts/test_machine_manager_browser.mjs`。
- AC/BC report_id：`GLB-MGR-E02`；报告 SHA-256：`7ea2ba7c09a2480973e63aedb8da1b8b0d46914eb86519781d99b718c5d3fca6`；浏览器错误 0。
- 8 部件验证：输入部件 X 平移 `10 mm`、Z 旋转 `15°` 后，预览中的选中部件位置和姿态变化；应用生成的 geometry userData 保存 `translationMm[0]=10`、`rotationDeg[2]=15`，随后 XYZAC 切换 XYZBC 和 BC 五轴 WASM 程序运行通过。
- 截图：`coverage/glb-machine-manager/mill700/mill700-studio-lighting.png`，SHA-256 `2b40f1e6a92e09d54bde17543686cc2fcecee3e2b7d7d3d71296a63737a85c8d`；AC 配置 `coverage/glb-machine-manager/manager-ac-config.png`，SHA-256 `b2fc2e00497ddb1e72e3170ee83ed54c21c8da9099036d84eeb4d6d6eef8619b`。
+- AC/BC report_id：`GLB-MGR-E02`；报告 SHA-256：`9549e8e731803c86780b1113afda3adb78e8846626bf4b6006d8c9241ac457a9`；浏览器错误 0。
+- 8 部件验证：根部件输入 X 平移 `10 mm`、Z 旋转 `15°` 后，预览中的根节点位置和姿态变化；应用生成的 geometry userData 保存 `translationMm[0]=10`、`rotationDeg[2]=15`，随后 XYZAC 切换 XYZBC 和 BC 五轴 WASM 程序运行通过。
+- 截图：`coverage/glb-machine-manager/mill700/mill700-studio-lighting.png`，SHA-256 `d422f2f19525d772cfb15c817f943fed6da2b183cfaa3dd9fc626cabed25a365`；AC 配置 `coverage/glb-machine-manager/manager-ac-config.png`，SHA-256 `ddfc10ebc03d0c72860ce4f21a3c7e290f9c8eeaa9dcaa97ff0a1c8b3e2bc860`。
--- a/docs/glb-machine-manager/06-决策记录.md
+++ b/docs/glb-machine-manager/06-决策记录.md
@@ -52,6 +52,6 @@ GLB 树节点 ID 使用导入时的子节点索引路径，不使用可能重复

 选中关节的坐标辅助必须作为该节点子对象放在局部 `(0,0,0)`，不可复制世界位置或使用整机坐标轴冒充。这样关节本身旋转时辅助轴同步旋转，父关节运动时又能自然继承父链，符合 GLB 层级矩阵语义。

-## D14 / 部件编辑变换作用于 GLB 部件根节点
+## D14 / 部件编辑变换作用于当前树节点的父级局部空间

-“部件平移”和“部件旋转”属于导入 GLB 的装配变换，作用对象是该 GLB 的外层部件根节点，因此选中内部关节时也移动或旋转该关节所在的完整部件。内部关节自己的轴绑定和 XYZ/ABC 诊断运动在此装配姿态之上叠加，不能把编辑器值误写到内部节点或用诊断输入覆盖编辑器值。导出和应用复用同一组 `translationMm`、`rotationDeg`，保证预览、组合 GLB 和运行机床保持一致。
+“部件平移”和“部件旋转”编辑当前选中的树节点。根节点的值保存为部件级 `translationMm`、`rotationDeg`；内部节点的值按稳定源路径保存为 `nodeTransforms[path]`，直接表示该节点相对当前父节点的位置和姿态。节点自身局部原点是旋转中心，子节点自然继承父节点变换，父节点和兄弟节点不因编辑子节点而改变。拖放改变父级后，先保持世界姿态，再重新计算局部值。导出和应用复用同一套局部变换，保证预览、组合 GLB 和运行机床一致。
--- a/docs/glb-machine-manager/README.md
+++ b/docs/glb-machine-manager/README.md
@@ -11,7 +11,7 @@

 现有整机 GLB + 内嵌 URDF 导入能力继续保留。新管理器生成与现有 `linuxcnc.machine/1` 相同的严格结构，再通过已有配置、Worker、WASM 和 Three.js 投影链运行。

-当前状态：MGR-01 至 MGR-16 全部 verified，MILL700 实测覆盖照明、Z-up、132 节点树、拖放、节点原点、关节局部坐标系、部件平移旋转同步、模型删除、轴绑定、XYZ/AC 层级运动和 WebGL 资源降级。最新台账 R09，证据 `GLB-MGR-E01/E02/E05/E07/E08/E09/E10/E11` 位于 `coverage/glb-machine-manager/`。
+当前状态：MGR-01 至 MGR-16 全部 verified，MILL700 实测覆盖照明、Z-up、132 节点树、拖放、节点原点、关节局部坐标系、节点相对父级平移旋转、模型删除、轴绑定、XYZ/AC 层级运动和 WebGL 资源降级。最新台账 R09，证据 `GLB-MGR-E01/E02/E05/E07/E08/E09/E10/E11` 位于 `coverage/glb-machine-manager/`。

 文档：