# Coordinate Model

PlanetX does not overload one World coordinate with every meaning. It uses explicit frames for distinct responsibilities.

## Coordinate spaces

| Coordinate | Meaning |
| --- | --- |
| World | Transform in the current Unreal World |
| Planet Local | 3D position relative to the Planet Actor origin |
| Canonical Geo | Latitude, Longitude, and AltitudeCm |
| Section Local | Tangent frame of a specific Section |
| Surface Frame | East, North, and Up basis |
| FPlanetXTransform | Canonical pose carrying Planet ID/Binding and rotation |

`FPlanetXCoordinateConvention` defines the North Pole and longitude axes. Geo altitude is measured in centimeters from Planet Radius.

## Coordinate Component authority

When `UPlanetXCoordinateComponent.CoordinateMode` is Unreal, the owner's World Transform is authoritative and the PlanetX snapshot is captured from it. In PlanetX mode, `FPlanetXTransform` is authoritative and Apply produces the World Transform. Capture and Apply are explicit operations.

Reference resolution prefers Reference Planet Actor, then Reference Planet ID. An explicit Section ID makes that Section frame authoritative.

## Vector conversion

Positions use point conversion; movement input uses vector conversion. With Surface Frame in `ConvertCoordinateVectorToWorld`, X/Y/Z represent East/North/Up. Surface movement can enable `bProjectToSurfaceTangent` to remove the Up component.

## Failure handling

Do not inspect only the boolean return value. Read `FPlanetXTransformResolveResult` or the detailed query status to distinguish invalid versions, unregistered planets, ambiguous bindings, unsupported planet scale, and invalid Sections.