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

