- Available Reference Frames
- Custom Reference Frames
- Converting Between Reference Frames
- Visual Debugging
All of the positions, directions, velocities and rotations in kRPC are relative to something, and reference frames define what that something is.
A reference frame specifies:
- The position of the origin at (0,0,0)
- the direction of the coordinate axes x, y, and z
- the linear velocity of the origin (if the reference frame moves)
- The angular velocity of the coordinate axes (the speed and direction of rotation of the axes)
KSP and kRPC use a left handed coordinate system
The following gives some examples of the position of the origin and the orientation of the coordinate axes for various reference frames.
The reference frame obtained by calling
for Kerbin has the following properties:
- The origin is at the center of Kerbin,
- the y-axis points from the center of Kerbin to the north pole,
- the x-axis points from the center of Kerbin to the intersection of the prime meridian and equator (the surface position at 0° longitude, 0° latitude),
- the z-axis points from the center of Kerbin to the equator at 90°E longitude,
- and the axes rotate with the planet, i.e. the reference frame has the same rotational/angular velocity as Kerbin.
This means that the reference frame is fixed relative to Kerbin – it moves with the center of the planet, and also rotates with the planet. Therefore, positions in this reference frame are relative to the center of the planet. The following code prints out the position of the active vessel in Kerbin’s reference frame:
For a vessel sat on the launchpad, the magnitude of this position vector will be roughly 600,000 meters (equal to the radius of Kerbin). The position vector will also not change over time, because the vessel is sat on the surface of Kerbin and the reference frame also rotates with Kerbin.
Another example is the orbital reference frame for a vessel, obtained by calling
Vessel.orbital_reference_frame. This is fixed to the vessel (the origin
moves with the vessel) and is orientated so that the axes point in the orbital
- The origin is at the center of mass of the vessel,
- the y-axis points in the prograde direction of the vessels orbit,
- the x-axis points in the anti-radial direction of the vessels orbit,
- the z-axis points in the normal direction of the vessels orbit,
- and the axes rotate to match any changes to the prograde/normal/radial directions, for example when the prograde direction changes as the vessel continues on its orbit.
Another example is
Vessel.reference_frame. As with the previous example,
it is fixed to the vessel (the origin moves with the vessel), however the
orientation of the coordinate axes is different. They track the orientation of
- The origin is at the center of mass of the vessel,
- the y-axis points in the same direction that the vessel is pointing,
- the x-axis points out of the right side of the vessel,
- the z-axis points downwards out of the bottom of the vessel,
- and the axes rotate with any changes to the direction of the vessel.
Reference frames move and rotate relative to one another. For example, the reference frames discussed previously all have their origin position fixed to some object (such as a vessel or a planet). This means that they move and rotate to track the object, and so have a linear and angular velocity associated with them.
For example, the reference frame obtained by calling
CelestialBody.reference_frame for Kerbin is fixed relative to
Kerbin. This means the angular velocity of the reference frame is identical to
Kerbin’s angular velocity, and the linear velocity of the reference frame
matches the current orbital velocity of Kerbin.
kRPC provides the following reference frames:
Relative and hybrid reference frames can also be constructed from the above.
Custom reference frames can be constructed from the built in frames listed above. They come in two varieties: ‘relative’ and ‘hybrid’.
A relative reference frame is constructed from a parent reference frame, a fixed
position offset and a fixed rotation offset. For example, this could be used to
construct a reference frame whose origin is 10m below the vessel as follows, by
applying a position offset of 10 along the z-axis to
Vessel.reference_frame. Relative reference frames can be constructed by
A hybrid reference frame inherits its components (position, rotation, velocity
and angular velocity) from the components of other reference frames. Note that
these components need not be fixed. For example, you could construct a reference
frame whose position is the center of mass of the vessel (inherited from
Vessel.reference_frame) and whose rotation is that of the planet being
orbited (inherited from
reference frames can be constructed by calling
The parent reference frame(s) of a custom reference frame can also be other custom reference frames. For example, you could combine the two example frames from above: construct a hybrid reference frame, centered on the vessel and rotated with the planet being orbited, and then create a relative reference that offsets the position of this 10m along the z-axis. The resulting frame will have its origin 10m below the vessel, and will be rotated with the planet being orbited.
kRPC provides utility methods to convert positions, directions, rotations and velocities between the different reference frames:
References frames can be confusing, and choosing the correct one is a challenge in itself. To aid debugging, kRPCs drawing functionality can be used to visualize direction vectors in-game.
Drawing.add_direction() will draw a direction vector, starting from the
origin of the given reference frame. For example, the following code draws the
direction of the current vessels velocity relative to the surface of the body it
The client must remain connected for the line to continue to be drawn, hence the infinite loop at the end of this example.
The following examples demonstrate various uses of reference frames.
This example demonstrates how to make the vessel point in the various orbital
directions, as seen on the navball when it is in ‘orbit’ mode. It uses
This code uses the vessel’s orbital reference frame, pictured below:
This example demonstrates how to point the vessel in the ‘prograde’ direction on the navball, when in ‘surface’ mode. This is the direction of the vessels velocity relative to the surface:
This code uses the
This example demonstrates how to get the orbital and surface speeds of the vessel, equivalent to the values displayed by the navball.
To compute the orbital speed of a vessel, you need to get the velocity relative
to the planet’s non-rotating reference frame
CelestialBody.non_rotating_reference_frame). This reference frame is
fixed relative to the body, but does not rotate.
For the surface speed, the planet’s reference frame
CelestialBody.reference_frame) is required, as this reference frame
rotates with the body.
This example demonstrates how to get the velocity of the vessel (as a vector), relative to the surface of the body being orbited.
To do this, a hybrid reference frame is required. This is because we want a reference frame that is centered on the vessel, but whose linear velocity is fixed relative to the ground.
We therefore create a hybrid reference frame with its rotation set to the
vessel’s surface reference frame (
all other properties (including position and velocity) set to the body’s
reference frame (
CelestialBody.reference_frame) – which rotates with
This example computes the angle between the direction the vessel is pointing in, and the direction that the vessel is moving in (relative to the surface):
Note that the orientation of the reference frame used to get the direction and
velocity vectors does not matter, as the angle between two vectors is the same
regardless of the orientation of the axes. However, if we were to use a
reference frame that moves with the vessel, the velocity would return
(0,0,0). We therefore need a reference frame that is not fixed relative to
CelestialBody.reference_frame fits these requirements.