Add geometry transform skill metadata
This commit is contained in:
parent
eaf24420b7
commit
48de5aa921
53
.agents/skills/geometry-transform/SKILL.md
Normal file
53
.agents/skills/geometry-transform/SKILL.md
Normal file
@ -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.
|
||||
|
||||
8
.agents/skills/geometry-transform/agents/openai.yaml
Normal file
8
.agents/skills/geometry-transform/agents/openai.yaml
Normal file
@ -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
|
||||
@ -0,0 +1,53 @@
|
||||
# 几何问题排查清单
|
||||
|
||||
## 先问自己
|
||||
|
||||
1. 这是虚拟物体还是真实物体？
|
||||
2. 路径类型是 `Ground / Hoisting / Rail` 哪一种？
|
||||
3. 错的是：
|
||||
- 旋转轴
|
||||
- 起点位置
|
||||
- 逐帧位置
|
||||
- 通行空间
|
||||
- 终点诊断
|
||||
|
||||
## 日志优先看什么
|
||||
|
||||
### 平面路径
|
||||
|
||||
- `[移动到起点] 路径方向yaw`
|
||||
- `[动画姿态入口] ... 目标姿态`
|
||||
- `[模型增量姿态] ... 当前/目标/增量`
|
||||
|
||||
### Rail
|
||||
|
||||
- `[移动到起点] Rail旋转姿态`
|
||||
- `RailPathPoseHelper` 相关诊断
|
||||
|
||||
### 虚拟物体
|
||||
|
||||
- `[虚拟物体姿态] 应用前`
|
||||
- `[虚拟物体姿态] 应用后`
|
||||
- 关注 `BoundingBox.Center` 是否符合资源原点预期
|
||||
|
||||
## 需要同步检查的链
|
||||
|
||||
出现几何问题时，至少对齐这几条：
|
||||
|
||||
1. 起点落位
|
||||
2. 逐帧位置
|
||||
3. 通行空间
|
||||
4. 终点诊断
|
||||
|
||||
如果其中一条使用的是“原始高度”，另一条使用的是“旋转后法线尺寸”，就很容易出现看起来互相矛盾的问题。
|
||||
|
||||
## 测试建议
|
||||
|
||||
至少补一个最短链测试：
|
||||
|
||||
- `YUp` 或 `ZUp`
|
||||
- 指定单一路径类型
|
||||
- 指定单个旋转轴
|
||||
- 验证尺寸或姿态的关键不变量
|
||||
|
||||
能测数学层，就不要先靠现场猜。
|
||||
@ -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.
|
||||
|
||||
@ -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 应用变换的方法是否有问题
|
||||
|
||||
Loading…
Reference in New Issue
Block a user