== 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 its details. If you choose an airport, specifying the runway is optional. When specifying an airport and/or runway, 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, not by their name. 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.) It is harmless but unnecessary to specify the details of the five unselected options. Details associated with unselected radio buttons are ignored. 2) In the bottom half of the dialog, the first two rows allow you to specify an optional /offset/ relative to the reference point. Offset _____ nm Radial from ref: _____ deg mag X Bearing to ref: _____ deg mag The radial is always the reciprocal of the bearing. If you change one, the other automagically changes accordingly. If the offset is blank, that's the same as zero. If the offset is zero, the radial and bearing don't matter. The course line runs through the reference point selected by the radio buttons as discussed above. Negative offset values are allowed. However, it is equivalent, and easier, and more consistent with aviation conventions, to leave the offset as a positive number and just exchange the "radial from" with the "bearing to". You can make this exchange by pushing the X on the popup. The radial and bearing are specified in degrees /magnetic/. (This differs from the --azimuth option on the command line, which uses degrees /true/.) If you leave the radial and bearing blank, the default is to use a bearing equal to the heading, in particular the new heading as described below. On subsequent lines, you have the option of specifying the new 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) The location-in-air popup collects some interesting numbers and puts them in the property tree. Assuming you have the http server turned on, you can access them via: http://localhost:5400/sim/gui/dialogs/location-in-air In particular, prior (pre-relocation) values of some cockpit controls etc. are at http://localhost:5400/sim/gui/dialogs/location-in-air/prior Note that this piece of the property table does not exist until the first time you use the location-in-air popup, and reflects the values of the variables as of the most recent time you started the popup, not the current values. If desired, you can always populate these properties by starting the popup and then immediately dismissing it (via the key). Among others, there are some numbers that tell you the prior position of the controls (aileron, elevator, and rudder) and trim settings. These are of relatively little interest if you are already airborne, but are often useful if you wish to relocate _from the ground_ into the air, and need to set the trim properly before relocating. 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.) If you are moving a long ways, rather than using a large offset, consider using a two-step process. Relocate to a fix in the vicinity, and then relocate again to apply a _small_ offset if necessary. *) The FDM is documented to have a feature to initialize a position along a glideslope, but it doesn't work, and has not worked for years. This part of the popup is marked "INOP". If you want this to work, you have to fix the FDM. *) 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 in the property tree (the "presets") and then invokes the "presets-commit" routine provided by the flight dynamics model (FDM). 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 likes to coerce /sim/presets/trim to be false. On the other hand, as of Dec 2008, turning off presets/trim makes things worse! The FDM loses its mind, and puts the aircraft in an upside-down attitude. 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. Note the presets-commit code appears to completely delete the old FDM instance and create a new one from scratch. If so, that would explain some of the weird behavior, including imtes (4) and (5).