Reference Frames

If you’re going to write a program that reads where your spacecraft is, or tells it which way to point, there’s one idea you can’t get around: space needs an agreed-upon way to describe “where” and “which way.” That’s all a reference frame is. It sounds like heavy orbital-mechanics vocabulary, but the actual concept is something you already use every day.

This page is intended to be the gentle version, no equations, no code… just some pictures that hopefully make things click. If you take one thing away, remember the frame called CCI, because that’s the primary one you’ll be using with your vessels!

If you want the full and probably more correct explanation you should read the excellent Celestial Coordinate Frames KSA Forum post by developer gravhoek

What a “frame” actually is

Imagine you tell a friend, “the coffee shop is three blocks east of here.” That sentence only works because you both silently agreed on two things: where “here” is, and which way “east” is. Change either one and the directions fall apart. Give the same instructions to someone standing in a different city, or someone who thinks “east” is the other way, and they’ll end up nowhere near the coffee.

A reference frame is just those two agreements, written down and made precise:

• an origin: the one point everything is measured from (“here”), and
• three directions: arrows we call X, Y, and Z that tell us which way is which.

That’s the whole trick. Pick an origin and three arrows, and suddenly “where” and “which way” have exact answers. Every frame you’re about to meet is just a different choice of where’s the center and which way do the arrows point.

The three arrows always follow the same “handedness” so the math stays consistent: the classic right-hand rule. Point your right hand’s fingers along X, curl them toward Y, and your thumb points along Z:

You don’t need to memorize that. Just know that when you see X, Y, and Z on the pictures below, they’re a tidy little set of “which way” arrows, and they hang together like the fingers of one hand.

Diagram credit

The frame diagrams on this page come from the Kitten Space Agency developers’ own write-up on how the game keeps track of positions and orientations. They’re the clearest illustrations of these ideas around, so we’re using them here with thanks.

The whole-system map: ECL

Zoom all the way out to the entire star system. Where would you put the center? The obvious choice is the star itself, sitting in the middle with all the planets looping around it. Flatten the arrows onto the plane the planets roughly orbit in, and you get the Ecliptic frame, or ECL:

Think of ECL as the wall map of the solar system: great for questions like “where is each planet right now?” It’s centered on the star, and it never spins or drifts, so it’s a stable backdrop for the whole system.

ECL is useful, but it’s a bit like using a map of the entire country when all you want to do is park the car. When you’re actually flying a spacecraft near a planet, you want something more local.

The one that matters: CCI

Here’s the star of the show. Slide the origin off the star and plant it right at the center of the planet (or moon) you happen to be near. Keep the arrows pinned to the distant stars so they never rotate. That’s CCI: Celestial-Centered Inertial:

Read the arrows off the picture:

• Z points straight up through the planet’s north pole.
• X points at a fixed spot in the sky: the diagram calls it the vernal point, but you can think of it as an arrow taped to the far wall of the universe. It doesn’t move.
• Y is just the third arrow that completes the set (that right-hand rule again).

The word doing the heavy lifting is inertial: a fancy way of saying these arrows do not spin with the planet. The planet turns underneath, day and night roll by, but the X arrow keeps pointing at that same distant spot in the sky. That stillness is exactly what makes CCI the sane place to do anything involving motion: an orbit traced in CCI just sits there as a steady ring, instead of smearing around as the world rotates.

This is the frame gatOS hands you everything in. When you read your ship’s position, its velocity, or which way its nose is pointing, the numbers are in CCI. When you tell the flight computer to point somewhere, you’re speaking CCI. Learn to picture this one and you’re 90% of the way there.

The one trick worth stealing

Because CCI’s origin sits at the planet’s center, the position numbers gatOS gives you have a lovely hidden meaning: they’re literally the arrow that points from the planet’s center out to your ship.

Which leads to the single most useful shortcut in the whole system. Say you want to point your ship at the planet: straight down toward the surface. You could reach for trigonometry… or you could notice that “toward the planet” is just “away from the planet, backwards.” Your position is the arrow out to you; flip it around and you’ve got the arrow back down to the planet. No math, just a minus sign:

planet center = the origin

your ship

position (planet → ship)

aim = −position (ship → planet)

That “just negate the position” move is the entire idea behind the Point at parent tutorial. It only works because CCI is centered on the planet: which is a pretty good advertisement for understanding your frames.

CCI’s confusing cousin: CCF

There’s a second planet-centered frame, and mixing it up with CCI is the classic beginner trap, so let’s defuse it now. Same center (the planet’s core), same up (Z through the north pole): but this one’s X arrow is bolted to the ground and spins with the planet. It’s called CCF, Celestial-Centered Fixed, where “fixed” means fixed to the planet’s surface:

In CCF the X arrow points at a specific place on the planet (where the prime meridian crosses the equator), so as the planet turns, X sweeps around with it like the hand of a clock. That makes CCF perfect for questions about spots on the surface: latitude and longitude, where a launch pad is, where a city sits. It makes CCF terrible for orbits, because a steady orbit would appear to wobble and drift as the ground spins beneath it.

The two frames share the same north pole, so the only difference is how far their X arrows have drifted apart: and that gap is simply how far the planet has rotated since the two lined up. The developers even gave that gap a name, the “hour angle,” but you can just read it as “the planet has turned this much”:

The easy way to remember it

CCI is pinned to the stars: it holds still while the planet spins inside it. Use it for flying and orbits. CCF is glued to the ground: it turns with the planet. Use it for places on the surface. Same center, same north pole; the difference is whether the sideways arrows spin.

So which one do I use?

For almost everything you’ll do in gatOS: reading where your ship is, checking how fast it’s going, and aiming it: the answer is CCI, every time. It’s the frame behind the numbers you read and the directions you write. Whenever a value or a control in gatOS mentions cci, now you know exactly what it means: measured from the planet’s center, against arrows that hold still while the world turns.

You’ll bump into the surface frame (CCF) only when you’re dealing with actual ground locations : latitude and longitude are reported there. And there are a couple more specialized frames in the family (one built around a single orbit’s shape, another that keeps the ecliptic’s tilt while centered on a planet) that you can happily ignore until you go looking for them. If you ever want the full, formal rundown, the developers document every frame in detail: but you don’t need it to start flying.

That’s the whole map. Origin plus three arrows; CCI for flying; CCF for the ground. With that in your back pocket, head over to Point at parent and put CCI to work: you’ll watch a ship swing around to face its planet using nothing but the “flip the arrow” trick from up above.