---
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/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.