The XYZ coordinate grid of Kerbal Space Program[]
There will be times when knowing how to write a script in KOS will depend on knowing what the underlying XYZ coordiante grid of Kerbal Space Program looks like. Getting a velocity vector from KOS like V(121.1,230,2015.01) doesn't tell you much if you don't know what direction X, Y, and Z are in. This topic is an attempt to explain the system.
Caveat: : This information was gathered from trial and error from typing commands at the Kosscript terminal and guesswork. It is possible for it to be in error.
The difference between a Direction and a Vector.[]
Firstly it's important to understand the difference in KOS between a Direction and a Vector. Both of them are tuples of 3 numbers so it's easy to get them confused.
A Vector is expressed in 3D space using X,Y,Z coordinates and can have a magnitude anywhere from 0 to infinity. (Although a vector with a magnitude of zero is really just a point and has no direction, so using it can cause the math to get screwy.) A vector is a line segment starting at the origin (0,0,0) and extending to a tip (x,y,z) that represents both a direction and a numerical size in that direction. For example the vectors V(1,1,1) and V(2,2,2) are both in the same direction, but the second one has twice the magnitude as the first. The topic of vector math is too complex to explain here, but it is a standard mathematical concept and further research can be spent on Wikipedia.
The following are Vectors in KOSscript:
VELOCITY:ORBIT VELOCITY:SURFACE V(1,2,3)
The following is meant to be a vector and looks like one when printed out but it is currently bugged and should be avoided
VELOCITY
(VELOCITY is meant to be a synonym for VELOCITY:ORBIT, but it isn't at the moment.)
A Direction has no information about length. It merely defines a direction being pointed at. The three numbers of a direction just define the angles of rotation that offset from a vector pointing along the Z axis to get to the desired direction vector.
The following are Directions in KOSscript:'
PROGRADE RETROGRADE UP NORTH R(30,20,0). Q(1,1,0,45).
Any time a variable is assigned to a Direction in Kosscript, it is always converted into a Euler rotation expressed as R(a,b,c) even if that is not how it was set.
The shorthand to remember this:
- A Vector is a set of coordiantes in XYZ
- A Direction is a set of angles rotating AROUND X,Y,Z axes.
The XYZ system[]
To use the information that is given as vectors, it's handy to know where the X, Y, and Z axes really are. In Kerbal Space Program (KSP), the native coordinate grid can be confusing to understand because its meaning keeps changing on the fly, and its frame of reference does as well.
KSP puts the origin nearby to avoid overly large numbers[]
In KSP, in order to keep calculations sensible and quick to calculate, a coordinate grid with an origin near the current vessel is needed. If the origin is at the Sun, and you're all the way out by Eeloo counting your coordinates in units of meters, then your coordinates will all be extremely large numbers and therefore they will have a lot of floating point error in them. Computerized floating point numbers become more imprecise the farther away from zero they are. Trying to calculate how the parts of the vessel are moving, for example, when one part has an x coordinate of 500000000000.73 meters and the next part has an x coordinate of 500000000001.13 meters doesn't work when the computer can't store numbers that precisely at that magnitude.
So KSP uses the following trick: When giving velocities, the XYZ coordiante system's frame of reference always shifts to whichever main gravitational body the vessel happens to be in the sphere of influence of at the moment. If you are orbiting Kerbin, then the origin of the XYZ grid for the purposes of velocity is the center of Kerbin. If you are orbiting the Mun then the origin of the XYZ grid for the purpose of velocity is the center of the Mun. This is why the game has a slight pause when shifting from one sphere of influence to another. It's re-setting all the coordinates of everything it's tracking to the new frame of reference.
CONFUSING shift of reference for velocities versus positions[]
The previous section used the phrase "for the purposes of velocity" numerous times. This is because of a very strange feature that MAY be a feature of KSP itself or it may be a feature of kOS only: That is this: POSITIONS in kOS are reported using a frame of reference centered on your ship, while VELOCITIES in kOS are reported using a frame of reference centered on the body your ship is orbiting. In other words, if you are currently in orbit in Kerbin's SOI, and you ask kOS to tell you "print Mun:POSITION.", you'll get a vector from YOUR SHIP to the Mun, whereas if you ask kOS to tell you "print Mun:VELOCITY.", you'll get a vector of the Mun's velocity relative to Kerbin, not relative to your ship. The most obvious manifestation of this difference is that "print Body(body):VELOCITY." is always zero ( V(0,0,0) ) because it's giving you the velocity of your orbit body relative to itself, while "print Body(body):POSITION" is always NONzero because it's giving you the position of your orbit body relative to your ship. If they were both using the frame of reference of the orbital body, they'd both be zero. If they wee both using the frame of reference of your ship, they'd both be nonzero. That one is zero and one is nonzero is proof that they are not in the same frame of reference as each other.
Thankfully, both of these frames of reference appear to use the exact same rotational orientation of the XYZ axes, so converting between them is just a matter of adding or subtracting an offset vector (which is the position vector between you and your body's center). But if you weren't aware of the need for such a translation you'd get some very strange results for some calculations.
The orientation of the XYZ grid[]
Okay, so the two different frames of reference (the one used for POSITION versus the one used for VELOCITY) don't have the same origin point, but they DO have the same axis orientation. The description below describes the axis orientation in the body-centered frame of reference used for VELOCITY. But if you just read this description and then move the origin point of those axes to your ship, you have the frame of reference of the ship-based POSITION vectors.
The orientation of the XYZ coordinate system is always thus:
- The Y axis is the planet or moon's own day-rotation axis, such that positive Y is the direction from the core to the north pole, and negative Y is the direction from the core to the south pole.
- The plane created by the X and Z axes is the equator of the planet or moon, such that both the X axis and the Z axis exit the body at its equator, at points that are exactly 90 degrees of longitude apart from each other.
However, the *exact* position of the X and Z axes with regard to the longitude of the planet keeps changing. One time the X axis might exit the planet at longitude 40.12 E. Maybe a few hours later you check again and it exits at longitude 124 W instead, or 85 E... and so on. This shifting of location is caused by the following trick KSP does:
There are two different ways KSP sets the origin at the body's center. Sometimes the XYZ axes rotate with the planet's day, such that they remain fixed to the same longitude of the planet. But other times they remain fixed to the space around the planet and the planet rotates relative to the axes. Which is used depends on the altitude of the focused vessel. When the vessel is closer to the planet the planet becomes fixed in place to reduce calculations on its terrain, and the universe rotates around the planet. When the vessel is higher up, the universe stops rotating and the planet starts rotating instead. It's this shifting between modes that causes the X and Z axes to change where they're exiting the planet from.
The clue as to how far the XZ axes are rotated off from the planet's longitude is contained inside the Up Directional parameter. The Yaw component of your current Up Direction tells you where you are relative to the Z axis of the XZ plane. By comparing UP:YAW to your current LONGITUDE, you can work out how far your longitude lines are rotate off from the Z axis.
A presentation from Squad at Unite 2013, it contains info about solutions they used which affects data in KSP
