diff --git a/.agents/skills/geometry-transform/SKILL.md b/.agents/skills/geometry-transform/SKILL.md new file mode 100644 index 0000000..a6007d1 --- /dev/null +++ b/.agents/skills/geometry-transform/SKILL.md @@ -0,0 +1,53 @@ +--- +name: geometry-transform +description: NavisworksTransport 几何与姿态专用技能，用于坐标系变换、物体旋转平移、虚拟物体定位、通行空间几何和相关单元测试；处理 Navisworks 中的姿态问题时优先使用。 +--- + +# Geometry & Transform + +Use this skill for any work involving coordinate-system transforms, object pose, rotation, translation, virtual-object placement, passage-space geometry, and the tests that lock those behaviors down. + +## Scope + +- Keep host coordinates, internal canonical coordinates, and asset coordinates distinct. +- Prefer existing helpers over ad hoc math. +- Protect the object-start, restore, and playback chains from regressions. +- Treat geometry changes as test-first work whenever practical. + +## Expected Ownership + +- `src/Utils/CoordinateSystem/HostCoordinateAdapter.cs` +- `src/Utils/CoordinateSystem/ModelAxisConvention.cs` +- `src/Utils/CoordinateSystem/RotatedObjectExtentHelper.cs` +- `src/Utils/CoordinateSystem/CanonicalPlanarPoseBuilder.cs` +- `src/Utils/CoordinateSystem/CanonicalRailPoseBuilder.cs` +- `src/Utils/CoordinateSystem/CanonicalTrackedPositionResolver.cs` +- `src/Utils/ModelItemTransformHelper.cs` +- `src/Core/Animation/PathAnimationManager.cs` +- `src/Core/VirtualObjectManager.cs` +- `src/UI/WPF/ViewModels/AnimationControlViewModel.cs` +- geometry-focused tests under `UnitTests/CoordinateSystem/` + +## Invariants + +- UI, logs, and user inputs/output stay in host coordinates. +- Internal pose solving stays in canonical space. +- Asset coordinates only apply to plugin-owned assets such as the virtual object and the unit cylinder/reference rod. +- Do not assume `BoundingBox.Center` is a stable pose anchor after rotation unless the flow explicitly proves it. +- Do not add temporary force-sync or fallback logic unless it is removed after the root cause is fixed. +- Do not mix virtual-object behavior into real-object behavior through shared mutable mode flags. + +## Working Rules + +1. Identify which coordinate system each value lives in before changing code. +2. Reuse project helpers first. +3. If a rotation change affects position, extents, or restore behavior, update the corresponding tests in the same change. +4. For Navisworks API details and examples, also consult the `nw-api` skill and `doc/design/2026/NavisworksAPI使用方法.md`. + +## Test Expectations + +- Add or update host-type coverage for both `YUp` and `ZUp` when the change touches transforms. +- Lock baseline pose, rotated pose, and restore behavior. +- For passage-space or footprint changes, verify extents after rotation, not just orientation. +- For virtual objects, verify scale preservation and CAD restore behavior. + diff --git a/.agents/skills/geometry-transform/agents/openai.yaml b/.agents/skills/geometry-transform/agents/openai.yaml new file mode 100644 index 0000000..4b1ab6a --- /dev/null +++ b/.agents/skills/geometry-transform/agents/openai.yaml @@ -0,0 +1,8 @@ +interface: + display_name: "Geometry Transform" + short_description: "坐标、姿态、位移与通行空间专用技能" + brand_color: "#2E8B57" + default_prompt: "Use $geometry-transform to analyze or implement a geometry, transform, or coordinate-system fix in NavisworksTransport." + +policy: + allow_implicit_invocation: true diff --git a/.agents/skills/geometry-transform/references/geometry-debug-checklist.md b/.agents/skills/geometry-transform/references/geometry-debug-checklist.md new file mode 100644 index 0000000..946bfc2 --- /dev/null +++ b/.agents/skills/geometry-transform/references/geometry-debug-checklist.md @@ -0,0 +1,53 @@ +# 几何问题排查清单 + +## 先问自己 + +1. 这是虚拟物体还是真实物体？ +2. 路径类型是 `Ground / Hoisting / Rail` 哪一种？ +3. 错的是： + - 旋转轴 + - 起点位置 + - 逐帧位置 + - 通行空间 + - 终点诊断 + +## 日志优先看什么 + +### 平面路径 + +- `[移动到起点] 路径方向yaw` +- `[动画姿态入口] ... 目标姿态` +- `[模型增量姿态] ... 当前/目标/增量` + +### Rail + +- `[移动到起点] Rail旋转姿态` +- `RailPathPoseHelper` 相关诊断 + +### 虚拟物体 + +- `[虚拟物体姿态] 应用前` +- `[虚拟物体姿态] 应用后` +- 关注 `BoundingBox.Center` 是否符合资源原点预期 + +## 需要同步检查的链 + +出现几何问题时，至少对齐这几条： + +1. 起点落位 +2. 逐帧位置 +3. 通行空间 +4. 终点诊断 + +如果其中一条使用的是“原始高度”，另一条使用的是“旋转后法线尺寸”，就很容易出现看起来互相矛盾的问题。 + +## 测试建议 + +至少补一个最短链测试： + +- `YUp` 或 `ZUp` +- 指定单一路径类型 +- 指定单个旋转轴 +- 验证尺寸或姿态的关键不变量 + +能测数学层，就不要先靠现场猜。 diff --git a/.agents/skills/geometry-transform/references/navisworks-transform-patterns.md b/.agents/skills/geometry-transform/references/navisworks-transform-patterns.md new file mode 100644 index 0000000..48b47b6 --- /dev/null +++ b/.agents/skills/geometry-transform/references/navisworks-transform-patterns.md @@ -0,0 +1,34 @@ +# Navisworks Transform Patterns + +## Use These First + +- Use `HostCoordinateAdapter` for host <-> canonical coordinate conversion. +- Use `ModelAxisConvention` only when the object really has an asset axis convention. +- Use `RotatedObjectExtentHelper` for rotated footprint/height calculations. +- Use `CanonicalTrackedPositionResolver` for contact-point -> center-point conversion. + +## Real Objects + +- Real objects do not have their own asset coordinate system. +- Treat UI angle input as host-axis rotation. +- Keep the pose solve stable in canonical space, then apply the host-axis correction on the host-side result. + +## Virtual Objects + +- Virtual objects do have an asset coordinate system. +- Preserve current scale when moving or rotating the virtual object. +- When returning to CAD position, reset permanent transforms first, then restore the expected scale state. + +## Common Pitfalls + +- Do not use `BoundingBox.Center` as a stable anchor after rotation unless the flow has already been validated for that case. +- Do not infer height from the raw unrotated axis when the visual footprint already depends on the rotated extents. +- Do not mix host-axis correction and canonical correction in the same branch unless the branch semantics require it. + +## Testing Checklist + +- Verify `YUp` and `ZUp`. +- Verify zero-correction baseline first. +- Verify rotated extents and start-position compensation together. +- Verify that restore-to-CAD returns the object to the original state, not just an approximate pose. + diff --git a/.agents/skills/geometry-transform/references/navisworks-transform-rules.md b/.agents/skills/geometry-transform/references/navisworks-transform-rules.md new file mode 100644 index 0000000..d56a718 --- /dev/null +++ b/.agents/skills/geometry-transform/references/navisworks-transform-rules.md @@ -0,0 +1,58 @@ +# Navisworks 变换与旋转规则 + +本文件只记录和本项目最相关的结论。 + +## 关键结论 + +1. `Rotation` 不是“绕物体中心旋转”，而是和整体变换组合后共同决定结果。 +2. `ResetPermanentTransform` 会清掉覆盖变换，后续 `BoundingBox()` 与 `Transform` 都会回到设计文件原始状态。 +3. `OverridePermanentTransform` 与 `SetModelUnitsAndTransform` 会直接改变当前模型覆盖变换。 +4. 对真实模型做完整姿态时，要特别区分： + - 目标姿态算得对不对 + - 还是增量/绝对应用方式把正确姿态弄坏 +5. 对虚拟物体做完整姿态时，若尺寸依赖缩放实现，应用姿态时必须明确是否保留当前缩放。 + +## 本项目里的常见坑 + +### 1. UI 轴和内部轴混用 + +- UI `X/Y/Z` 一律是宿主坐标系 +- 内部坐标系只用于数学求解 +- 不要把 UI 输入直接当成资产坐标系角度 + +### 2. 通行空间和真实物体使用不同尺寸语义 + +如果出现： + +- 通行空间对，物体位置错 +- 或物体对，通行空间错 + +优先检查： + +- 是否一边用了原始高度 +- 另一边用了旋转后的法线尺寸 + +### 3. 虚拟物体资源原点问题 + +若虚拟物体在“原点”时 `BoundingBox.Center` 不是 `(0,0,0)`： + +- 先检查 `unit_cube.nwc` 是否为最新资源 +- 再查代码 + +不要一上来怀疑移动逻辑。 + +### 4. Rail 角度修正 + +`Rail` 不能像平面路径那样在宿主空间直接补转。 + +必须： + +- 先并入 `canonical -> rail pose` 链 +- 再落位 + +## 推荐排查顺序 + +1. 先确认资源文件是否正确 +2. 再确认日志里的目标姿态/目标位置是否合理 +3. 最后才看 Navisworks 应用变换的方法是否有问题 +