[META] Flight Plan Management and Guidance

[beheh]

Problem

The default flight plan manager is severely limited in multiple ways:

• Departure and arrival segments are treated very different from the enroute segments
• It's a list of unconnected waypoints, not a list of legs, making special like arcs very hard
• There is no support for go around segments
• The default nav data is missing information like turn direction

As it uses native APIs to manage the flight plan, we cannot modify or improve it significantly.

First Approach: Working Title Flight Plan Manager

To fix that, we've been rewriting it and have started from the Working Title (WT) code (MIT-licensed) as the basis, but need to still adjust lots of parts in it and make specific to our aircraft. The WT implementation lays a lot of effort on keeping the flight plan manager API compatible with the default code, but this has various limitations.

It works like this:

• When loading a procedure, all legs are converted to waypoints, so they're essentially treated like TF legs (point-to-point)
• Waypoints are written to localStorage when they're added
• Whenever the flight plan is modified, a version SimVar is increased, and all related screens (MCDU, ND1, ND2) read from localStorage so they're in sync

While this is a significant improvement, we're still far from being able to write accurate guidance:

• Complex leg terminators (like altitude) are converted to static waypoints even though they need to move as the aircraft's performance changes
• When everything is a TF leg, we can't accurately construct the geometry for more complicated legs like DME arcs
• Arrival/Destination segments are still treated somewhat special.

Next Steps

Work is happening on the autopilot-fpm branch and being coordinated in #ata-22-fms on Discord.
Please indicate when you're starting work on a specific part here, so there is no conflicts! There could also be multiple people working on the same thing, it just needs to be coordinated.

Here's a list of specific tasks that can be picked up in the autopilot-fpm branch:

Flight Plan

• Store the flight plan as a list of waypoints with leg information. Rationale.

• After the above rework: Rewrite the flight plan page, from scratch. It's a total mess and still uses many of the original concepts like a separate arrival segment. It needs to support:

  • Discontinuities between arbitrary waypoints (also between origin/destination)
  • Ideally the page (and CDU) is very light on actual flight plan modification. So for example it would call a function to "sequence active leg" or "delete waypoint " or "insert waypoint ABC before DM123", and the flight plan manager does the rest.
  • How does the page discover the leg type? How are MANUAL legs encoded?
  • Can pseudo-waypoints be treated like a normal waypoint? Should they have a different format?
  • You should also think about how a new page supports things like a go around segment and an alternate segment, and how the SEC flight plan page could reuse the code

• Rework how waypoints are drawn on the ND (SvgWaypointElement). Right now they depend on the all-encompassing WayPoint object to hold some kind of reference to the SVG, but that isn't scalable and is broken right now. We need a different way to reliably draw a waypoint at a certain position, remove it when we no longer need it, and update e.g. it's text color.

• Improve the sequencing. Whenever we sequence (either automatically through NAV or manually, by clearing the FROM waypoint in selected heading) the active waypoint needs to advance, and the previous waypoint needs to be deleted. While advancing works, deleting waypoints is prone to breaking the flight plan, especially because the flight plan page panicks when the first waypoint is no longer an airport.

Guidance

• Implement turn anticipation distance for type 1 transitions. Right now, as soon as you've entered the type 1 transition segment we send a hard bank command to the autoflight systems. This is both extreme and unrealistic, as the aircraft can not go from level flight to fully. We need to start the turn earlier and rather than sending bank angle 0 -> 0 -> 25 -> 25 we need to construct a geometric path that actually turns the aircraft in (0 -> 5 -> 15 -> 25). This will make our curves smoother and more accurate.

• Start implementing type 2 transitions between legs. We need someone who doesn't shy away from physics and geometry to come up an implement formulas to construct the more complicated leg geometry. We have some basic logic for type 1 transitions, but type 2 is the complicated one. This type of transition happens when you overfly a waypoint and then turn sharply towards the path to the next waypoint, and then turn back again as you approach the path so you point at the new waypoint again. This geometry needs to be constructed based on ground speed.

• Implement our first flight plan solver. This is the speed/altitude/energy management part (VNAV) and the backbone of managed flight. It needs to take all kinds of inputs, and propose a plausible trajectory, which means it needs to be able to predict a certain altitude and speed at every step of the flight plan. This is the system that will be run whenever the flight plan is fully entered, and populate the flight plan page with altitude/speeds at every waypoint. It also needs to be able to tell where the pseudo-waypoints (like DECEL, SPD LIMIT are), which are then overlayed on top the flight plan.

[CBGonzalez]

You say "The default nav data is missing information like turn direction" but as far as I have seen, the legs are fully encoded (including turn direction when relevant). I´ve been looking into the nav data (directly in the BGL files) but haven´t found a way to access it from within the sim...
There´s probably a loss of data when it goes to the built-in gps thingy (noticeable, for example, by the lack of RF legs in displayed approaches, although they are encoded in the BGL)

[Benjozork]

That is precisely the issue. The navdata APIs from inside the sim are lacking and do not provide all the information stored in the bgl.

[pareil6]

Implement turn anticipation distance for type 1 transitions. Right now, as soon as you've entered the type 1 transition segment we send a hard bank command to the autoflight systems. This is both extreme and unrealistic, as the aircraft can not go from level flight to fully. We need to start the turn earlier and rather than sending bank angle 0 -> 0 -> 25 -> 25 we need to construct a geometric path that actually turns the aircraft in (0 -> 5 -> 15 -> 25). This will make our curves smoother and more accurate.

Apologies if anyone else has already looked at this, but I got nerd-sniped by this problem last night (having tried to solve it in the past but never having got very far) - and ended up with a quick and dirty empirical algorithm for doing it. I'm writing this here for the sake of not losing it (in case it ends up being useful), but will not be offended if someone has a cleaner solution!

The current implementation was my solution last time I tried to solve this (pick a turn radius, form a circle arc between the entry and exit points, then turn around the centre of that circle maintaining a fixed radius), and given it's relatively easy to implement, I tried smoothing the turn by increasing the turn radius as we enter it and decreasing it as we exit it. A quick example for a 90 degree turn, with the black line being a fixed-radius curve, and the grey lines being various smoothed versions of it:

(Advance warning: there's some actual maths here, and also note that anywhere I'm talking about an angle, it's being calculated in radians, even if I talk about it in degrees, since degrees are easier for most people to visualise).

The empirical bit: as we go through the turn, we want to extend the radius initially to a peak half way through the turn, then pull the radius back in as we bank out of the turn - which happens to be roughly the shape we'd get from an offset inverted cosine (and happens to be the only function I can think of with the properties we want, having slept through a lot of my maths lectures at university...).

So - for an initial turn radius of r_0, a turn angle of \theta_0, a current 'turn' angle of \theta (ie. the angle between the radius line and horizontal on the graph above) and a smoothing gain k, we end up with something like:

What value for k? It depends - too small and we end up turning quickly anyway, but too large and we end up turning away first (ie. the cosine term becomes larger than the base radius term). There's some fun maths involved in figuring out what that limit is - but eventually you end up at k being between zero and (\theta_0 / 2\pi)^2, with zero giving no correction (we're back to just flying a circle arc) and (\theta_0 / 2\pi)^2 giving us the maximum correction this algorithm allows without turning the wrong direction first. For a 90 degree turn (\pi/2 radians) we end up with a limit of 1/16 for k, which gives us the right-most curve in that graph above.

The second part of this (which I didn't do) was calculating the target heading at each point on that curve - I know how to calculate it, I just haven't done the work yet. Once I have, I'll look at doing a PR adding this unless anyone has a better solution before then.

(Also, I never thought I'd find myself wanting LaTeX equation formatting in a GitHub comment...)

[tracernz]

@pareil6 The other consideration is wind. If that isn't accounted for we may end up well off track by the end of a long turn.

[BlueberryKing]

I think this is no longer relevant with all of the changes that have been made to the FMS in the meantime. I will close this issue, but feel free to reopen if you feel it's justified.