== Usage Scenarios Here are some scenarios describing how the location-in-air popup might be useful to you. (Note that the popup might better be called relocate-to-aloft, since it expects the destination to be aloft, but does not care whether you were previously aloft or previously parked on the ground.) Scenario 1: You want to practice landings. Using command-line options, you can initialize the system to 4 mile final and 1500 feet above the runway. You land OK, and want to try it again. For maximum realism, you should taxi back, take off, and fly the pattern. But for best use of lesson time, if all you care about is the landing, it would be nice to relocate to a final approach fix (at this airport or another) and take it from there. The location-in-air popup will do this for you. Note that you could accomplish the same thing by quitting out of the simulator and going wherever you like using the command-line options of a new invocation of the simulator, but the location-in-air popup is quicker and more elegant. Scenario 2: Same as above, except that you are practicing instrument approaches. The time savings are even greater, because the distances involved are often greater. The initial approach fix could be 20 or 30 miles from the airport. Scenario 3: You make a mistake enroute, and would like to "back up" a few miles and try it again. In this case it is particularly valuable to define the reference point as an offset relative to "here" i.e. relative to the aircraft's present position. Scenario 4: You are on a long, boring leg, and would like to "fast forward" a few miles to get closer to a more interesting part of the journey. == Instructions 1) In the top half of the popup, there are six different ways in which you can specify the /reference point/. (_) Airport _____ runway _____ (_) latitude _____ longitude _____ (_) VOR _____ (_) NDB _____ (_) Waypoint _____ (_) Here You should select one, push its radio button, and fill in the details. If you choose an airport, enter all capitals (e.g. KSFO 10R, not ksfo 10r). (In contrast, VORs, NDBs, and waypoints are case-insensitive.) VORs and NDBs are specified by their 3-letter ID. Waypoints usually have a 5-character ID. If an identifier is non-unique, the /closest/ one will be used. (Note that there are eight different BRAVO intersections in the database, and two different RBV VORs.) Details associated with /unselected/ radio buttons are ignored. 2) In the bottom half of the dialog, the first row allows you to specify an optional /offset/ relative to the reference point. Offset _____ nm Course _____ deg mag If the offset is blank, that's the same as zero. If the offset is zero, the course direction doesn't matter. The course line runs through the reference point selected by the radio buttons as discussed above. Negative offset values are allowed, and are often useful, notably when you are going /toward/ the reference point. For example, if you select a course of 090, negative offsets represent points west of the reference (such as the runway 9 approach course), while positive offsets represent points east of the reference (such as the runway 9 departure course). The course is specified in degrees /magnetic/. (This differs from the --azimuth option on the command line, which uses degrees /true/.) You also have the option of specifying altitude, heading, and airspeed. *) If you leave the altitude blank, it defaults to your present altitude. *) If you leave the airspeed blank, it defaults to your present airspeed. *) If you leave the heading blank, it defaults to your present heading. 3) Near the bottom of the dialog are some numbers that tell you the present position of the controls (aileron, elevator, and rudder) and, more importantly, the trim settings. These are of relatively little interest if you are already airborne, but are often useful if you are relocating /from the ground/ into the air. Trim is important, and some aircraft in the simulator fleet lack trim indicators. == Hints *) Altitude is specified in feet MSL. If you want height above the ground, or height above the intended airport, you will have to do the arithmetic yourself. *) If you are relocating from a non-flying situation to a flying situation, you need to make sure you are ready. Hint: Run the before-takeoff checklist. For example, if the trim is not properly set, you will have a few moments of excitement dealing with the mis-trimmed aircraft after the relocation. == Known bugs and frequently-requested features *) Apparently the c++ backend refuses to apply an offset if the reference point is a lat/lon. This is broken both in jsbsim and larcsim. There does not seem to be an easy way to work around this in the xml; the Right Thing is to fix the backend. *) The previous item also breaks offsets relative to "Here". *) Magnetic variation should be calculated at the /reference point/ (not at the current position, as we do now, which is quick and dirty, but quite accurate in the usual situation where the relocation doesn't move you very far.) *) The "glideslope" variable appears in the dialog, but I doubt it does anything useful. This is related to another cluster of bugs in the backend. *) If your new altitude is different from your old altitude, the VSI is likely to be offscale for many seconds before it recovers. *) It would be nice to make the airport and runway ID case-insensitive. == Internals NOTE: This section is addressed to developers, not pilots. The location-in-air popup is implemented as follows: It fills in some variables, and then invokes a "reset" routine provided by the flight dynamics model (FDM). The key routine seems to be called "presets-commit". All evidence indicates that the function being called was not designed to be used this way. It was supposed to be used once, during initial startup ... not used in flight and not used repeatedly. There are numerous problems that need to be fixed. I don't much care how they get fixed, including -- defining and implementing a new "relocate" function; or -- robustifying the old "reset" or "preset" function so that it can handle a wider range of uses; or -- whatever. The location-in-air.xml code goes to considerable lengths to work around some of the problems with the existing presets-commit routine. It sure would be nice to fix the underlying problems, and then remove the workaround code from the location-in-air.xml code. Specific problems include: 1) If the property "/sim/presets/trim" is "true" when presets-commmit is called, it attempts to "trim" the aircraft. I'm not sure what is the objective of such trimming, but by its own standards the procedure often fails. It prints error messages on the console complaining about various kinds of failures. Observations suggest that repeated calls to the "presets-commit" progressively increase the probability of failure. That is, the failure /probability per call/ is increasing. 2) Even if the "trim" function succeeds, it messes with the throttle settings. This is weird and undesirable in the not-uncommon situation where there is a hardware throttle, because it creates a conflict between where the FDM thinks the throttle is and where the hardware throttle is. To prevent problem (2) and reduce problem (1), location-in-air.xml coerces /sim/presets/trim to be false. 3) One particularly weird thing is the behavior of the offset-azimuth and offset-distance properties. Observations indicate that they allow an offset relative to the reference point /if/ the reference point is an airport, VOR, or NDB ... but, strangely, not if the reference point is a lat/lon. In the latter case, it just relocates to the lat/lon and ignores the offset. This seems like a bug. It is significant, because relocating relative to "here" occurs in many use-cases, and is implemented in terms of the lat/lon of the present position. 4) The presets-commit routine turns off the magnetos. This is clearly not desired behavior if all I'm trying to do is relocate. 5) Similarly, the presets-commit routine zeros the settings for aileron trim, elevator trim, rudder trim, view angles, PoV position, landing gear, throttle setting, and who-knows-what else. Again, this is clearly not desired behavior. There is code in location-in-air.xml to save & restore these variables, to protect them from the ravages of presets-commit.