NavisworksTransport/.agents/skills/geometry-transform/SKILL.md

name	description
geometry-transform	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/CoordinateSystem/RealObjectPlanarPoseSolver.cs
• src/Utils/CoordinateSystem/FragmentRepresentativePoseHelper.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.
• Real-object planar pose solving must stay in host coordinates and should keep the reference-pose source injectable so fragment-derived representative pose can be wired in later.
• Real-object planar pose solving should prefer fragment-derived representative pose when available; original Transform is only an explicit fallback, not the primary source.
• 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.