Gyroscopic Compass

[xstarlin]

Hi there, I am a fellow game designer and I was super curious how you went about coding the gyroscope compass in KSP? I've tried looking around on the web and doing some research and I haven't been able to find anything useful that explains how to get the 3D compass working, only ever cardinal direction compasses.

[ColdJ]

@xstarlin

Hi. I am happy for someone to correct me, but in non programming terms I think you have to think about it as, It is not the NAV Ball that is turning but rather your point of observation.

Just like in a 3D modeling program where you move around a model that is static in the centre of the workspace to see different  sides.

Due to the nature of the game requireing there to be an away from the planet, a towards the planet, an along this axis, an along that axis etc.

So as the Kerbal or the craft they are in changes directions in 3 dimensions, the NAV Ball stays orientated to the different axies. essentially it does not turn, you just see different sides based on your orientation, and by observing the different sides you can determine in which direction you are headed.

I know that is not code but hopefully it might give you an idea of what might need to be done.

[K^2]

I have no affiliation with Squad or Intercept, but you need very similar code for camera in a lot of games, and I have worked on that on a few projects.

First of all, you need to know how your asset is set up. I'm also going to assume we're going for a 3D look, rather than a similar 2D display used on some aircraft, so you have an actual 3D model, which is a sphere with all of the graphics textured onto it. For the sake of an example, lets say we're working in Unity and you want the compass model to be level with horizon and pointing North in its Identity orientation. That means you'll have 'S' painted on the +Z direction of the model (since you're looking at a sphere from -Z in its identity state), 'W' on the +X direction, and Y will be the up for the model. You can work with any other convention, of course, but I'm going to assume this one with the vector math below.

Your second point of reference is your craft. Again, there need to be a set of orientations. This will be different depending on how the capsule or probe core is oriented, so it doesn't really matter how that aligns with craft's XYZ. What's important, is that there will be a strictly defined Forward axis, which I'll denote as F, and an Up axis - U. We can also always get the side axis, which in a left-handed coordinate system (Unity) will be in the S = U x F direction.

Finally, you need to know where the craft is. Internally, KSP stores this in cartesian coordinates r = (x, y, z) and while this can be converted into polar coordinates with some trig, you really don't have to to make the compass work.

So now we can define the problem. You can picture the compass as being a physical object at craft's location. It floats in an imaginary fluid such that its Y direction points away from the planet's center and Z points North. We can define these directions. First, observe that radial direction R = r/||r|| - so just normalize craft's position. In KSP you don't have to worry about ||r|| = 0, but you might in some other games. So keep in mind that you'll need to handle this. Second, the North direction is parallel to the surface (so perpendicular to R) and in the direction of planet's axis (by astronomical convention). Call planet's axis A. Then the north direction N = A - R(A*R) / ||A - R(A * R)||. That is, we take A, subtract component of A along R (so that the resulting vector is perpendicular to R) and then normalize it. Note, again, that you might be dividing by zero if R and A are parallel. This happens at the North or South poles and you have to figure out what that means in your game, just like for the ordinary compass.

At this point, we basically have orientation of our imaginary compass in the world coordinates. I'm going to denote these with primes, so Y' = R = r/||r||, Z' = N = A - R(A*R) / ||A - R(A * R)||, and because X' has to be perpendicular to both of these and give us a left-handed coordinate system, X' = Z' x Y'. If you wanted to draw the compass inside the cockpit of this spacecraft, you'd be done, because these are body axes in the world coordinates, meaning the world rotation matrix for your compass would be (X', Y', Z')^T in row major notation. Or, in other words, X', Y', and Z' are your rotation matrix columns.

But if you want to show this on HUD, there's an extra step. Instead of rotation relative to the world, we need rotation relative to the craft. Namely, we want to know the rotation whose inverse will take Z' to F, Y' to U, and X' to S of the craft coordinates. The simplest way to get this is also with matrices. You can take the matrix (S, U, F)^T, which might actually be just the rotation matrix of whichever component you're using for "Control from here" on that craft at the moment (or it might need some adjustments, depending on the conventions the game uses - it's always worth to check to see if the Forward/Up are indeed defined this way.) In either case, what we're looking for a transformation matrix M that satisfies (X', Y', Z')^T = (S, U, F)^TM. The logic here is that if we transform our compass relative to the screen, then transform the screen to align with the craft, the compass on our HUD will match orientation with compass in the cockpit, which is the left hand side of that equation. Multiply both sides by inverse of (S, U, F)^T on both sides, and keeping in mind that for an orthogonal matrix the inverse is just a transpose, we get M = (S, U, F)(X', Y', Z')^T, and that's the rotation matrix you need to set up on HUD compass for it to have the correct orientation.

The precise math above makes assumptions that we're dealing with a game where you're always in one SoI or another, meaning there's a precisely defined "up" direction and "north" direction. This might not always be the case for some other games, and then you'll have to do a bit more work to figure out what exactly that means for your compass or any other world navigation display, but the logic is the same. See where the "up" and "forward" orientation of each relevant object is, make matrices out of these, and then multiply/divide these matrices until happy. It's good to work this out on paper to see if you see any optimizations or potentials for division by zero. Otherwise, though, the logic is always going to be roughly this.

[kerbiloid]

NavBall is the hyrocompass.

It doesn't  depend on magnetic field, illumination, radiation, or anything else. It just indicates your orientation in a fixed co-ordinate system, exactly what is an ideal hyrocompass purpose.

The hyroscopes just provide this functionality irl.