Reference Frames

Positions, velocities, directions and rotations are given in a reference frame. Vehicles and bodies provide the frames, and every one is right-handed. This script gets the active vehicle’s velocity relative to the surface, and relative to the stars:

body = vehicle.orbit.body
surface = vehicle.velocity(body.reference_frame)
orbital = vehicle.velocity(body.non_rotating_reference_frame)
print(f"Surface velocity {surface}")
print(f"Orbital velocity {orbital}")

The Frames

Frame	Origin	Axes
Body.ReferenceFrame	The body’s center	Fixed to the body: z to the north pole, x to latitude and longitude zero, y to latitude zero and longitude 90 degrees east.
Body.NonRotatingReferenceFrame	The body’s center	z to the north pole, x and y fixed relative to the stars.
Vehicle.ReferenceFrame	The vehicle	Fixed to the vehicle’s control point: x forward, y right, z down.
Vehicle.SurfaceReferenceFrame	The vehicle	The surface below it: x east, y north, z up. Rotates with the body.
Vehicle.OrbitalReferenceFrame	The vehicle	Its orbit: x prograde, y along the orbit normal, z radially outward.

Positions are in meters, velocities in meters per second and angular velocities in radians per second. A rotation is a quaternion (x, y, z, w).

Directions and Attitude

Vehicle.Direction is the unit vector the vehicle points in. In the surface frame, its pitch and heading are those Flight reports:

east, north, up = vehicle.direction(vehicle.surface_reference_frame)
pitch = math.degrees(math.asin(up))
heading = math.degrees(math.atan2(east, north)) % 360
print(f"Pitch {pitch:.1f}, heading {heading:.1f}")
print(f"Flight reports {vehicle.flight.pitch:.1f}, {vehicle.flight.heading:.1f}")

Pitch is positive above the horizon, and heading is clockwise from north. Roll is zero with the vehicle’s z axis toward the ground.

Converting Between Frames

TransformPosition, TransformDirection, TransformRotation and TransformVelocity convert a vector or rotation from one frame to another:

# The direction straight up from the vehicle, in the frame of the body it orbits
up = ksa.transform_direction(
    (0, 0, 1), vehicle.surface_reference_frame, vehicle.orbit.body.reference_frame
)
print(f"Up is {up}")

A velocity depends on the position it is measured at in a rotating frame, so TransformVelocity also takes the position. Frames convert through the game’s ecliptic frame, which every vehicle and body can convert to.