search

KSP-KOS / KOS

Fully programmable autopilot mod for KSP. Originally By Nivekk
Other
697 stars 230 forks source link

Heading-bearing-azimuth confusion #1482

Open hvacengi opened 8 years ago

hvacengi commented 8 years ago

I was working on a response to a reddit post and my research seems to imply some confusion surrounding the terms of "bearing" and "heading". It looks like we are using the term "bearing" to mean "relative bearing" (the angle relative to the forward facing direction) and "heading" to mean "absolute bearing" (the angle relative to the North direction vector). Both of which are based on the vector between the ship position, and the "target" position. Our documentation correctly identifies the concepts of relative and absolute, but people still seem to get hung up on the idea of heading vs bearing.

On top of that, there is an error in the binding documentation, because bearing is not a global alias. For that matter, heading (as it is defined) should not be on either. They are both defined as from the cpu vessel (ship) to "this target" vessel (whatever you're calling the suffix on). Since global bindings are called against the cpu_vessel, these should be returning the bearing from the cpu_vessel to the cpu_vessel.

Which brings us to the second point. On a ship:heading is always very nearly zero. In my testing, the value hovers around +/-2e-7, regardless of the direction of travel or facing. ship:bearing however varies, even though it shouldn't. For a heading of essentially zero, the bearing should also be essentially zero. Bearing represents the offset from your current ship's travel heading (a value not exposed directly by kOS) to the desired heading. Technically, both should probably be "undefined" because we're trying to find the angle between a vector and a zero length vector.

I wonder if we should consider exposing a new suffix AZIMUTH which would represent the angle from North of the current direction of travel, measured in the horizontal plane. Then we could leave the heading/bearing as zero on the cpu_vessel, and we would prevent people from trying to use ship:heading or ship:bearing when they are looking for the azimuth.

Dunbaratu commented 8 years ago

The terms date back to early days before I was involved in the mod and I never liked them for reasons you state.

Azimuth maybe should be called Compass, to be consistent with how the rest of the docs use the term (in HEADING(compass,pitch), for example). Which is another annoying terminology mixup. That HEADING doesn't mean the same thing as Vessel:HEADING, which is why we never exposed a Ship:Heading suffix to return a tuple of (compass,pitch) like I wished to do ages ago.

I had thought of making navball-centric suffixes of Direction, so you could do compass, pitch, bank, from your FACING, but the problem is that a Direction doesn't know which SoI Body it's supposed to refer to. The ship knows, but the Direction doesn't.