merge: 去掉真实物体 fragment 参考姿态依赖（默认轴约定替代）

CHANGELOG.md

@@ -1,5 +1,27 @@
 # NavisworksTransport 变更日志
 
+## [0.19.0] - 2026-08-05
+
+### ✨ 功能变更
+
+- **去掉真实物体 fragment 参考姿态依赖（默认轴约定替代）**：
+  - 背景：fragment 参考姿态提供的是物体在模型里的**原始摆放（CAD 朝向）**，不代表物流 forward——哪根局部轴沿路径是**业务语义，由用户定义**（不存在固定朝向）。且 fragment 有系统性隐患：盒内部分几何时代表帧漂移、嵌套实例不稳定、副实例坐标系误判连带。
+  - 修改：`TryCaptureRealObjectReferenceRotation` 不再解析 fragment，改用**默认轴约定**（forward=+X，up=宿主 up：YUp→+Y / ZUp→+Z）。用户通过“调整物体”窗口手工指定最终朝向（所见即所得）。
+  - 收益：
+    - **F1 Rail + 42" Diameter（此前失败场景）现可正常检测**（碰撞 1，对象识别成功）
+    - 消除全部 fragment 相关隐患（盒内 fragment 不完整/嵌套实例漂移/AutoDetect 坐标系）
+    - 集成测试 25/25 通过（真实物体动画 Ground/Hoisting/Rail 正常）
+
+### ⚠️ 语义变化（需注意）
+
+- 真实物体**初始姿态基准**从 fragment（物体 CAD 实际朝向）→ **默认约定**（forward=+X）
+- 用户通过“调整物体”手工指定最终朝向，功能不受影响（本来就相对路径/地面）
+- **已保存的角度修正数据**（ObjectRotationCorrection）相对基准变化，旧数据需重新调整
+
+### ✅ 已解决（0.18.1 已知问题）
+
+- ~~真实物体姿态链依赖 fragment 完整矩阵（Rail + 管道/嵌套实例类物体在副实例不可用）~~ → 已随去掉 fragment 依赖解决（42" Diameter Rail 路径检测成功）
+
 ## [0.18.1] - 2026-08-05
 
 ### 🐛 Bug 修复

VERSION.md

@@ -1,3 +1,3 @@
 # 版本号
 
-0.18.1
+0.19.0

src/Core/Animation/PathAnimationManager.cs

@@ -5391,43 +5391,39 @@ namespace NavisworksTransport.Core.Animation
 
             try
             {
-                var doc = NavisApplication.ActiveDocument;
+                // 不再依赖 fragment 参考姿态（物体在模型里的原始摆放不代表物流 forward，
-                if (!RealObjectReferencePoseResolver.TryResolveFromModelItem(sourceObject, doc, out var referencePose))
+                // fragment 在盒内部分几何时代表帧漂移）。
-                {
+                // 使用默认轴约定：forward=+X，up=宿主 up（YUp→+Y，ZUp→+Z）。
-                    LogManager.Warning($"[真实物体参考姿态] {sourceObject.DisplayName} fragment 姿态解析失败");
+                // 用户通过“调整物体”窗口手工指定最终朝向（所见即所得），无需 fragment。
-                    return false;
+                var adapter = CoordinateSystemManager.Instance.CreateHostAdapter();
-                }
 
-                referenceRotation = referencePose.Rotation;
+                referenceRotation = Quaternion.Identity;
-                _realObjectReferenceRotation = referenceRotation;
+                _realObjectReferenceRotation = Quaternion.Identity;
-                _realObjectReferenceAxisX = referencePose.RawAxisX;
+                _realObjectReferenceAxisX = Vector3.UnitX;
-                _realObjectReferenceAxisY = referencePose.RawAxisY;
+                _realObjectReferenceAxisY = Vector3.UnitY;
-                _realObjectReferenceAxisZ = referencePose.RawAxisZ;
+                _realObjectReferenceAxisZ = Vector3.UnitZ;
-                _realObjectReferenceHostWorldXAxisLocalAxis = referencePose.HostWorldXAxisLocalAxis;
+
-                _realObjectReferenceHostWorldYAxisLocalAxis = referencePose.HostWorldYAxisLocalAxis;
+                LocalAxisDirection hostUpLocal = adapter.HostType == CoordinateSystemType.YUp
-                _realObjectReferenceHostWorldZAxisLocalAxis = referencePose.HostWorldZAxisLocalAxis;
+                    ? LocalAxisDirection.PositiveY
-                _realObjectReferenceHostSemanticXAxisLocalAxis = referencePose.HostSemanticXAxisLocalAxis;
+                    : LocalAxisDirection.PositiveZ;
-                _realObjectReferenceHostSemanticYAxisLocalAxis = referencePose.HostSemanticYAxisLocalAxis;
+
-                _realObjectReferenceHostSemanticZAxisLocalAxis = referencePose.HostSemanticZAxisLocalAxis;
+                _realObjectReferenceHostUpLocalAxis = hostUpLocal;
-                _realObjectReferenceHostUpLocalAxis = referencePose.HostUpLocalAxis;
+                _realObjectReferenceHostWorldXAxisLocalAxis = LocalAxisDirection.PositiveX;
+                _realObjectReferenceHostWorldYAxisLocalAxis = LocalAxisDirection.PositiveY;
+                _realObjectReferenceHostWorldZAxisLocalAxis = LocalAxisDirection.PositiveZ;
+                _realObjectReferenceHostSemanticXAxisLocalAxis = LocalAxisDirection.PositiveX;
+                _realObjectReferenceHostSemanticYAxisLocalAxis = hostUpLocal;
+                _realObjectReferenceHostSemanticZAxisLocalAxis = LocalAxisDirection.PositiveZ;
                 _hasRealObjectReferenceRotation = true;
 
                 LogManager.Info(
-                    $"[真实物体参考姿态] {sourceObject.DisplayName} 使用 fragment 代表姿态: " +
+                    $"[真实物体参考姿态] {sourceObject.DisplayName} 使用默认轴约定（不再依赖 fragment）: " +
-                    $"RawX=({_realObjectReferenceAxisX.X:F4},{_realObjectReferenceAxisX.Y:F4},{_realObjectReferenceAxisX.Z:F4}), " +
+                    $"forward=+X, up={hostUpLocal}");
-                    $"RawY=({_realObjectReferenceAxisY.X:F4},{_realObjectReferenceAxisY.Y:F4},{_realObjectReferenceAxisY.Z:F4}), " +
-                    $"RawZ=({_realObjectReferenceAxisZ.X:F4},{_realObjectReferenceAxisZ.Y:F4},{_realObjectReferenceAxisZ.Z:F4}), " +
-                    $"宿主世界X对应本地轴={referencePose.HostWorldXAxisLocalAxis}, 宿主世界Y对应本地轴={referencePose.HostWorldYAxisLocalAxis}, 宿主世界Z对应本地轴={referencePose.HostWorldZAxisLocalAxis}, " +
-                    $"宿主语义X=({referencePose.AxisX.X:F4},{referencePose.AxisX.Y:F4},{referencePose.AxisX.Z:F4}), " +
-                    $"宿主语义Y=({referencePose.AxisY.X:F4},{referencePose.AxisY.Y:F4},{referencePose.AxisY.Z:F4}), " +
-                    $"宿主语义Z=({referencePose.AxisZ.X:F4},{referencePose.AxisZ.Y:F4},{referencePose.AxisZ.Z:F4}), " +
-                    $"宿主语义X对应本地轴={referencePose.HostSemanticXAxisLocalAxis}, 宿主语义Y对应本地轴={referencePose.HostSemanticYAxisLocalAxis}, 宿主语义Z对应本地轴={referencePose.HostSemanticZAxisLocalAxis}, " +
-                    $"宿主Up对应本地轴={referencePose.HostUpLocalAxis}, fragment数量={referencePose.FragmentCount}, Fragment默认Up={referencePose.FragmentDefaultUpAxis}, 模型Up={referencePose.HostUpAxis}");
                 return true;
             }
             catch (Exception ex)
             {
-                LogManager.Warning($"[真实物体参考姿态] 从 fragment 提取代表姿态失败: {ex.Message}");
+                LogManager.Warning($"[真实物体参考姿态] 应用默认轴约定失败: {ex.Message}");
                 return false;
             }
         }