The CREATEORBIT(pos, vel, body, ut) method has the vec:y and vec:z values reversed

[Ren0k]

The docs description mentions:

position (relative to center of body, NOT the usual relative to current ship most positions in kOS use. Remember to offset a kOS position from the body’s position when calculating what to pass in here.)

However you will not get the result when using ship:position-body:position in the place of pos if you want to create an orbit with the position being the ship's position. In addition, you will not get the ship's velocity vector when using ship:velocity:orbit as the vel value.

You DO get the correct result, if you reverse the vec:y and vec:z values. As an example, you can create an orbit from your current position using:

createOrbit( -V(ship:body:position:x, ship:body:position:z, ship:body:position:y), V(ship:velocity:orbit:x, ship:velocity:orbit:z, ship:velocity:orbit:y), ship:body, timestamp():seconds).

Note here how for BOTH the orbit and velocity vectors, the vec:y and vec:z values are reversed for input.

Perhaps this is intentional, the thought being that the SOI for this method inclused some sort of celestial up orientation. Regardless I think this adds unnecessary complexity to the method.

[Ren0k]

In addition to above: See the example provided in the Docs:

SET myOrbit TO CREATEORBIT(V(2295.5, 0, 0), V(0, 0, 70000 + Kerbin:RADIUS), Kerbin, 0).

This example has the pos and vec values reversed. The outcome of this example is a polar orbit (if you reverse the pos and vec values).

[Dunbaratu]

KSP, for some unknown reason, when talking about planetary values transposes y and z axes and kOS has to constantly be aware of those weird cases and correct for them. It's not enough to just rotate or translate to go between reference frames, it literally has to swap axes to do it. This is apparently such a case and it wasn't made clear because KSP mod devs already know this weird ugly misfeature in KSP but most kOS users are protected from it.

Fixing this will break it for the person who originally submitted the PR, who is probably used to it working this weird way, but I think it should be fixed anyway. The broken flipped y and z 'planetary' frame isn't exposed to kOS users anywhere else so it shouldn't be here either.

Side note: Please stop calling the docs a Wiki. They are not. The difference matters because there actually IS a wiki page with some kOS docs, on the Wikia site, and it's all guesswork from the days when users had to piece together guesses. It's important to distinguish the real docs (which are not a wiki because they can't be edited from the user-facing side) from those old wrong docs (which are a wiki).

[Farsyte]

[original comment is on #3009, so "here" is really "there"]

So I encountered the symptom and was drawn here by the great search engine in the sky, and did not find quite enough specific information to do a workaround ... but with a bit of digging I think this comes down to swapping the Y and Z values in each of the vectors seemed to be the solution that allowed me to round trip from an orbit, to position and velocity, and back to another orbit.

Adding my findings as a comment in this issue, so that anyone else following up on the same symptom can use these specifics.

I'll totally adopt the term 'swizzle' for this specific change in coordinate axes ;)

To make CREATEORBIT(position,velocity,body,time) work correctly, swizzle the position and velocity vectors by swapping the Y and Z axis values in each. You can use this function:

// swizzle: swap Y and Z axes of the vector so it can be used
// as the position or velocity in a createorbot(r,v,b,t) call.
function swizzle { parameter vec. return V(+VEC:X,+VEC:Z,+VEC:Y). }

I will include my test file (swizzle.ks) as an attachment (had to name it swizzle.txt to attach it, rename to swizzle.ks and run inside kOS). It starts with some orbital parameters (actually taken from a contract from KSP), creates an orbit from them, extracts current position and velocity, and round-trips that back to a second orbit. Selected values are compared between the orbits. I as mostly interested in the angular momentum vector (perpendicular to the orbital plane), so I include the angle between them (which is what tipped me off to the original problem).

My original search led me to #3009, and I did a bunch of tinkering over there, before finding this issue which would have ... I could say "saved me some time" but as it turns out, digging out the fact that it was just a Y-to-Z swap was fun.

swizzle.txt