Moving Map for PSX
[All following text is essentally the same as for v.01, minus the POLLINTV references]
While paring down the old PSX_Tellurium to PSX_Wheramium*, a "mere" moving map with no 3D views, I have been plagued by numerous computer crashes (uncommanded reboots, to be precise), and so far have not been able to determine the precise cause. It may well be that the problem is with my system (e.g. driver issues) and not the program itself (I have similar issues with PSX_Tellurium** on this box, while others are still using it without trouble).
Therefore I'll ignore my scruples and make Wheramium available to the Cognoscenti "as is"(!), in the hope that their mileage may vary.
* pronounced classically
or more colloquially (or if you don't speak IPA)
"Where am I? Umm...". (See also Question 1 below.)
** See the PSX forum for some more details.
! Caveat 1
As most potential PSX_Wheramium users will already have been PSX_Tellurium users before, this document assumes that you are familiar with the PSX_Tellurium documentation.
It therefore describes only the features which have changed or are new.
If you do not know PSX_Tellurium yet, please read its documentation first, to learn about the basics.
! Caveat 2
While Tellurium was released as a beta version (and perhaps still is one), Wheramium may possibly better be described as alphabet(a), depending on how it behaves on other computers than mine. See Caution above, you have been warned. Continue to expect weirdness and surprises.
!! Caveat 3
"Wheramium"?? What's in the name...?
Our Branding Dept (a.k.a. the "Strategy Boutique" a.k.a. the Whale Song and Joss Stick Brigade) needed several sessions on this one. The first working title was Helium (because Tellurium "lite", geddit?). But that had to be discarded because FAA, EASA, etc. intervened: Pilots might henceforth misinterpret the ATC instruction to "squawk 4711", and instead of keying in the numbers might start "Helium" the app, take a deep breath, and then squawkily speak "four seven one one".
The next try was PSX_Lunarium: If Earth = Tellus, then what is nearest by and similar but smaller with less features? Correct.
(Besides, it did drive me crazy, too.)
This was however deemed too oblique an allusion. (Branding lives in permanent dread of over-estimating the users' intelligence.)
Hence, eventually, "PSX_Wheramium", in order to succinctly capture the typical use case.
(Originally it was actually the more classic-looking spelling "PSX_Veramium" but this would be understood only by people being aware that certain other people shtill haff zis terrribbel Cherman acktsent.)
Here are the essential differences to Tellurium:
Wheramium can fetch data only from the PSX "BOOST" server.
Essentially the same as before:
...which is to say that only Firefox (v.73 to v.78) have been tested. Other browsers may also work. (Or not.)
Unpack the ZIP archive to any folder
! Make sure that on extracting the archive, the sub-folder
.../cesium_min is created;
so check that "use folder names" or similar options are activated in your unpacking tool.
PSX_Wheramium.inifile, and edit as required:
port on which the PSX server is listening for clients
(For the PSX Boost server the default is 10749.)
This parameter is very important both for performance / smoothness of the map, and on the other hand for CPU (over)load / temperature.
! Do not set them too low! E.g. the smallest REQINTV value which my box (i7-8700, 3.2 GHz, 6 cores) ) with Windows 10 could (barely) manage was 50 ms (20 Hz).
This would need more investigation and actual testing: you cannot really expect that the program will achieve precisely those theoretical update rates in practice. It may even differ from one system to another.
Note also that this interval is related to the update rate of the map/image, but not 1:1. Even at low values (high frequency of requests) you may still see (considerable) stuttering; keep also in mind that the maps/images come from external servers; thus net lag, bandwidth etc. also play a role.
So you'll have to experiment (at your own risk) to find the proper balance between small values, for smoothness of movement, vs. larger ones so as not to overload the CPU.
Start Wheramium in the same way(s) as Tellurium.
*.jarfiles and Java.
java -jar PSX_Wheramium.jar
Tip: While perhaps not entirely "user-friendly" (esp. if you are not comfortable with command lines and consoles :-), this may well be the best method to use.
The advantage is that you can see any messages emitted by the Java program, which will otherwise remain invisible: The server will report that it has started; and perhaps even more importantly, it will notify you if/when it exits, either intentionally or accidentally. This is now more important than before as there is no longer a visible user interface for the Java program (such as the "camera control" widget in Tellurium). So you have no direct way to determine if the program ist still running or not (unless you use Task Manager, Process Explorer, or similar tools).
And most importantly: if something goes wrong (as it will), you will be able to see any error messages in the console window (and, once the program has started, only there).
http://localhost:10314/PSX_Wheramium.htmlinto your browser.
PSX_Wheramium.htmldirectly by simply "dragging" the file into the browser, or by using the browser's
File > Open...menu items.
file:///..., you will have by-passed the HTTP protocol, the server, and the proper data processing, and it just won't work.
As a "simplified" descendant of Tellurium, Wheramium has less features; it is essentially "nothing but" a 2D moving map, always displayed in top-down view (but see the Tip below).
The only control you still have is the zoom slider. Formerly this was the "altitude correction" slider, for only minor changes; but it had now to take over the full zoom slider role as the old one (on the "camera control" widget) no longer exists.
This slider is a bit more sophisticated than it looks, so it still deserves its own chapter.
The slider scale is (still) logarithmic: in the middle, the zoom factor will change slowly; at the ends of the scale it will change rapidly.
As with Tellurium, finding a useful zooming range was a bit tricky, because two different uses for the moving map could be imagined, with somewhat different requirements: support for taxying (which I suspect is what most people want this application for), and general orientation (or sightseeing) during the actual flight phases.
An additional interesting issue is that even for taxying only, appropriate zoom factors diverge quite a lot depending on airport altitude; the extreme cases EHAM (ca -13 ft MSL) and SLLP (ca +13,300ft MSL) were used for testing.
The current implementation tries this compromise:
In any case, these "zoom factors" should be regarded as only relative measures. What they really mean (e.g. in terms of simulated viewer altitude) depends on the (unknown) spec.s of the "camera" producing the view.
(To demonstrate: Put yourself above some geographical spot, at the same nominal viewer altitude, first in Google Maps, then in some Cesium demo. You will find that the actual field of view (or visible area) is considerably different between both.)
The above slider range seems to be good enough for both taxying on the ground and flight at CRZ level. However, there may be surprises. E.g. EHAM with its altitude below sea level is good for one, as always. If you start there with the initial zoom value (1x) you will see a wildly flickering blur (you're in effect "too close to the ground"). This can however easily be fixed by simply zooming out a bit. Other airports may appear "too small" initially, but that is less alarming, and can be solved by zooming in.
Remember that zooming may require the external map data servers to deliver (possibly lots of) new map "tiles" of a different resolution, which takes time; it depends on Internet connection speed, etc. Experiment a bit so that you get a feeling for the amount of rapidly "zooming around" which your setup can handle, and for how much zooming is acceptable esp. in critical (flight) situations where every second matters.
(Nota bene: As Tellurium before, Wheramium does of course not slow down or in any way interfere with the PSX simulation; you can still rely on your instruments. It's only that the map (in the Wheramium webpage) may get "out of sync" if the tile delivery cannot keep up with things.)
! It is your responsibility to make sure that you do not zoom into terrain (a.k.a. CZIT)! If you are zooming in towards the Earth and suddenly realize "My God — it's full of stars!" (real ones, too, not the type Donald Duck or Wile E. Coyote so often see), then you are not in the wrong movie but have zoomed in too far...
The Wheramium webpage uses the elegant minimalist style which Steve Hose supplied some time ago for Tellurium. Your position is thus marked by an unobtrusive triangle (always in the centre of the map).
However, if you miss the cute (and possibly kitschig) original little blue airplane, you can get it back simply by renaming two files:
iconMap_blue_SH.png(or any other name)
The small button in the upper right corner of the webpage opens a dialog to let you select which type of map or image you want to use; three variants (all Bing Maps from Microsoft) are available:
Tip: As described above, in principle the map is displayed "HDG up" and in top-down view. You can thus not freely change the viewing direction, as you can in Tellurium. However, there are two options which you still have, e.g. to improve your situational (geographical) awareness:
1. You can of course temporarily disconnect the Wheramium webpage from PSX (use the "Disconnect", not the "EXIT" button!). Then it is possible to freely rotate and tilt the map/image by directly manipulating it with the mouse:
— left mouse button + drag to pan;
— CTRL + left mouse button + drag to rotate and tilt;
(middle mouse button + drag does the same).
— You can also zoom in and out (right mouse button + drag; or mousewheel).
(Remember, though, that meanwhile, PSX is still happily proceeding along its route unless you have put it into MOTION or PAUSE mode!).
On re-connecting, the map will of course "catch up" immediately.
2. The PSX Boost server sends coordinates, altitude, heading, pitch and bank values. Coordinates and heading are of course applied by Wheramium, which is why you cannot pan or rotate the map while connected to PSX — any manual input will at once be overridden by the next set of data arriving from PSX.
However: Wheramium ignores the PSX pitch value, which means that even while connected you can tilt the map manually (it may be a bit fiddly) and thus achieve a kind of forward "cockpit view". But keep in mind that there will be no 3D terrain to enjoy (or fear).
Abandoning Tellurium's "Belly Cam Control" widget presented an interesting new challenge: Users can still start Wheramium (the Java program) by double-clicking the JAR file, but how can they then stop it again? CTRL-ALT-DEL? Pulling the power plug? Re-installing Windows? Formatting C: ?
The "solution" to this is the new EXIT button on the webpage. It sends a special request to the webserver, which will then gracefully close down the Java program. Or so it is hoped. Note that it can work only while the webpage is still connected to the Wheramium webserver.
It is however not quite clear how reliable this mechanism is; most of the time it works, but (very) occasionally the stop message seems to get overlooked. In itself that is not a big deal; the problem is that the user has no direct way to determine if the Java program is still running or not. I did not want to create a new Java GUI especially and exclusively for that purpose, as it might increase the CPU load etc. further, and quite unnecessarily.
After clicking on the EXIT button, the bottom of the webpage should look like this:
If you however still have the "Connect" option (and can in fact re-connect to the webserver), like this...
... it means that the Exit button message has been ignored and Wheramium is actually still running.
To make perfectly sure if Wheramium ist still active or not, run it in a Command Prompt window, or check in Task Manager or Process Explorer, and kill the process there if required.
Caution: The Wheramium process is labelled
javaw.exe. (In Task Manager, check the "Details" tab to see this.)
Do not kill
java.exe, for that is PSX!
Finally, if you restart Wheramium later on, you must also reload the webpage.
To the right of the coordinate indications, there is now another, intentionally inconspicuous field labelled "Conn:"
As long as the connection to the webserver is working, this will show rapidly changing numbers. Their value as such is not important (it is the "millisecond modulo 1000" part of the records sent by the Boost server); the point is to indicate that data from PSX via the webserver are indeed being received, and that Wheramium is thus still running fine.
This is important esp. in situations where the coordinates do not change, e.g. when stationary on the ground, or with PSX in PAUSE or MOTION mode. In these cases you would not be able (unless you have a Command Prompt window to look at) to determine if the connection is still OK and the aircaft is just not moving; or if the connection has broken down. So these numbers serve merely as a kind of "heartbeat" function.
Finally, some general hints for Wheramium usage...
Don't take them too strictly: Much will depend on the specific circumstances of your system (Internet connection speed, CPU and graphics card power, etc.) and also external factors (esp. the current load on the map servers). So, experiment a bit to find out what can and cannot be achieved in your specific setup.
As already mentioned above: Do not load the file
PSX_Wheramium.html directly into the browser (by dragging or via the menu
File > Open) — if you see
file:///X:/<your path>/PSX_Wheramium.html in the browser's address bar, it won't work.
The Cesium code in the page has to come from a built-in webserver. The address bar should indicate that the HTTP protocol is used:
Always start PSX first, and Wheramium next. Only then open the browser interface, via a bookmark or using an URL like
http://127.0.0.1:10314/PSX_Wheramium.html, and connect to the Wheramium application.
If the browser tells you "This webpage is not available" or similar, it means that you have not yet started Wheramium (and thus there is no server running yet to supply the webpage interface).
You can in principle switch to other situ files in PSX "on the fly", i.e. without disconnecting Wheramium first. However, give it some time to load the new scenery; depending on conditions it may take a few seconds. In complicated cases it may still be better to disconnect Wheramium before the situ change and then reconnect.
When starting up Wheramium or when switching situs, put PSX in MOTION freeze first. Again, depending on circumstances this may not be absolutely necessary, but it's generally a good idea to give Wheramium (or rather the map serving process) some time to "catch up" and stabilise, without having to cope, at the same time, with a constant stream of new data from PSX. Just try it out and see what your specific setup can stand.
If you want to close Wheramium, click the Exit button while still being connected to the webserver.
(Otherwise the server will not get the "stop" message. D'oh.)
Occasionally, weirdness may occur: E.g. you may find yourself underground, gazing at a black sky full of stars. This may look dramatic but is mostly harmless; it generally means simply that you have placed yourself below ground level, usually because of the discrepancy between the PSX MSL and Cesium "WGS84 Ellipsoid" altitudes. It may also be caused by inappropriate zooming values.
Admittedly, lots of quirks and potential issues remain in Wheramium; and on other systems, more will be discovered. But to iron all those out would demand a lot of time and work (or might be impossible altogether). Hence the "permanent alphabet(a)" status, to sort out what the users (if any) can live with, and what would really need fixing... :-)
Thanks and credits go to
Cesium is under the Apache 2.0 License, see file
README.md in the
(This folder contains a subset of the full Cesium installation: demos etc. have been omitted.)
Licenses for the various third party components of Cesium are listed in the file
LICENSE.md, also in
As to PSX_Wheramium itself, I dunno. Do no evil.
PSX_Wheramium is free, but I reserve the Copyright (© Martin Erdelen 2020).
Don't make money from it, don't use it commercially (not always the same thing), and don't distribute modifications without contacting me first. (This latter restriction is for technical rather than for legal reasons... ;-))
End of document
updated for "v.02" 13.08.2020: version 2
© Martin Erdelen 2020