OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / wps / progs / pmglobe / pmglobe.doc < prev next >

Wrap

Text File | 1993-06-04 | 26.8 KB | 582 lines

PMGlobe 2.18 PMGlobe -- an OS/2 Presentation Manager World Globe =================================================== Copyright (c) International Business Machines Corporation, 1991, 1993. All rights reserved. Introduction """""""""""" PMGlobe is a program which displays the Earth as a globe using OS/2 Presentation Manager. You can choose to view the globe from any direction, or select one of a number of 'standard' views. In addition to simply displaying a picture of the world, PMGlobe will also let you light the globe as though by sunlight -- so you can see at a glance those areas of the globe where the sun has risen, and where it is night. Additional options add shading to the globe for a three-dimensional effect, and let you measure and track distances between two points on the globe. Other features are described in detail below. With the command interface included with PMGlobe, you can add markers, labels, and clocks to the globe and have more control over its actions. If you wish, you can use REXX (the scripting language included with OS/2) as a macro language for PMGlobe -- see PMGLOBEX.DOC for a description of the PMGlobe commands available; all of them can be used in a REXX macro. Installation """""""""""" PMGlobe is a 32-bit application, and therefore requires OS/2 Version 2. Only the file PMGLOBE2.EXE is needed, though you may wish to experiment with the sample macros (TEST.PMG, SPIN.PMG, and FASTSPIN.PMG) or your own macros. If using macros then they should be in the current working directory for PMGlobe. It is recommended that PMGlobe be started from a program object contained in a folder or on the desktop. One way of setting this up is: 1. Copy a 'Program' object template from the OS/2 Templates folder to your desired target folder. 2. On the new object, click mouse button 2, select the [->] button on 'Open', then select 'Settings'. This should open the settings notebook. 3. On the 'Program' page enter the path and file name of PMGLOBE2.EXE, and, for 'Working Directory', the directory in which you have placed the sample macros. 4. On the 'General' page, change the title to whatever you wish (e.g., PMGlobe), and un-check the 'Template' check box. 5. Close the settings notebook. Clicking on the Globe item should then start PMGlobe. If, for that program object, you choose the setting "Minimize window to desktop" (on the 'Window' page) then when minimized the globe will appear on the desktop as an icon, which will continue to be updated if (for example) you have selected sunlighting. Using the Mouse with PMGlobe """""""""""""""""""""""""""" When PMGlobe is the active window, mouse button 1 is used to select a geographical location on the globe, and mouse button 2 can be used to select a new point of view or pop up a menu of choices. Specifically: o Move the mouse pointer to any visible point on the globe, so that the cross-hair cursor appears, and click mouse button 1. This will cause the 'PMGlobe Position/Distance Calculator' window to appear (if not already visible). You can move the calculator anywhere on the screen, just like any other window. Then: a. The current position (Latitude and Longitude) of the mouse is displayed if the mouse is over the globe. b. A single click of mouse button 1 records the current point on the distance calculator. Up to two points can be recorded: if two are shown then the distance between them is also displayed, in kilometres and miles. (The distance shown is the 'Great Circle Distance', that is, the shortest distance between the points when moving over the surface of the globe.) c. A double click of mouse button 1 also records the current point on the distance calculator, and makes it a 'fixed' (or 'base') point. This keeps that point visible on the calculator while you select any number of other points. You can set a new fixed point by double-clicking mouse button 1 at another position. d. If two points are shown, the 'Track' button will be enabled. Pressing this will add the distance between the points to the 'Total Track' distance (which is then shown on the calculator), and also displays the new track (the line joining the two points) on the surface of the globe. You can clear all selected points, including the fixed point, by pressing the 'Reset' button on the calculator. This also resets the total track distance to zero, and erases any tracks displayed on the globe. The 'Cancel' button hides the calculator. o If the mouse pointer is over the window background (off the globe), then clicking mouse button 2 will show a popup menu of options in the usual OS/2 manner. This duplicates the menu bar choices; you can remove the menu bar using the 'options' menu. To change the view of the globe, move the mouse pointer over a point on the globe and click mouse button 2. The globe will then be redrawn with that point at the center of the view. Once you have found your preferred view, view selection by mouse button 2 can be disabled from the 'Views' menu, if you wish, to avoid accidental change of the view. Menu options """""""""""" The PMGlobe menu options can be selected from the Action Bar in the usual way, and fall into three groups (in addition to the Help panel index): 'Options' gives access to various miscellaneous settings 'Views' is used to select what is seen, and from where 'Lighting' is used to choose the lighting effects and colors. Each group (and each submenu in each group) has a summary 'Help' panel as its first selection. The other selections are as follows: ----- 'Options' -- miscellaneous settings ----- 'Run macro': displays an OS/2 file dialog to let you select a macro that is to be run. (Macros are programs, written in REXX and having a file extension of ".pmg", that let you do more complicated things than are possible using just menu selections--see PMGLOBEX.DOC for more details.) For example, if you installed all the files that came with PMGlobe, clicking on the file TEST.PMG would run that macro and show various cities and clocks on the globe. You might like to use the system editor to look at the macros supplied, to see how they work. 'Halt macro': is enabled when a macro is running. If selected, any macro that is running is halted. The Ctrl-Break key combination has the same effect. 'Make window square': makes the window fit the globe on all edges, if possible (it may not be possible on some narrow or low windows). This is an instantaneous action; the window size and position is not saved until you select 'Save windows' (see below), or PMGlobe is closed, or OS/2 is shut down. 'Make full screen': enlarges the window to fill the screen entirely, so that the title and action bars and the frame are just off the screen and so not visible. You can still use OS/2 key combinations to move the window, select action bar items, etc. For example: F10 followed by "O" and then "Q", will pull down the 'Options' menu and then make the window a quarter of the size of the screen. This is an instantaneous action; the window size and position is not saved until you select 'Save windows' (see below), or PMGlobe is closed or shut down. 'Make quarter screen': makes the window be centred and fill a quarter of the screen (useful as a quick recovery from Make Full Screen). This is an instantaneous action; the window size and position is not saved until you select 'Save windows' (see below), or PMGlobe is closed, or OS/2 is shut down. 'Make desktop': makes PMGlobe become (and remain) the bottom window; that is, puts it behind all other windows. Click anywhere visible to bring PMGlobe to the foreground (after confirmation). This does not change the size of the window. See below for more details. 'Show position and distance calculator': when selected, this makes the position and distance calculator appear (it will also appear automatically if you click on the window with mouse button 1). See above for information on how to use the calculator. 'Cross-hair cursor': when selected, this requests that a cross-hair cursor be used when the mouse pointer is over the globe itself. If not selected, the standard desktop pointer is used. 'Draw at low priority': requests that map drawing be carried out at lower than normal priority, to minimize impact on other applications. This is the default; if PMGlobe appears to halt drawing when (for example) a communications program is running in a DOS session, try de-selecting this option. 'Use menu bar': requests that the menu bar be shown below the globe title bar. This is the default. The menu of choices is always available by clicking mouse button 2 on the window background (off the globe), even if the menu bar is not shown. 'Set timezone': this pops up a dialog that lets you set the time zone information. You only need to do this for a 'sunlight' view, and even then only need to do it once. If no other program updates the current time zone information then you may also have to change it whenever you change the clock on your computer for daylight saving (summer or winter) time. PMGlobe assumes that your computer clock is set to local time; the timezone dialog describes your local time in terms of GMT (Greenwich Mean Time), and hence gives PMGlobe the information that it needs to calculate the sun's position. 'Set refresh time': this lets you choose how long PMGlobe will wait after completing a view of the globe before it redraws it. This takes effect for the 'Sunlight' view (which needs regular updating to give a useful picture) or if any clocks may be displayed. The refresh takes place shortly after the wall-clock time that is a multiple of the selected refresh interval (for example, if 'One Hour' is selected, the refresh should take place on the hour). 'Save settings': this saves the settings you have selected; they will then be used automatically when PMGlobe is next started. See below for details of which settings are saved; these are also saved automatically when OS/2 is shut down or PMGlobe is closed. 'Restore settings': restores settings to those last saved. 'Reset settings to defaults': sets settings to the defaults used when PMGlobe was first run. 'Save windows': this saves the position and size of the main PMGlobe window, and the position of the distance calculator. These will be used automatically when PMGlobe is next started, and are also saved automatically when OS/2 is shut down or PMGlobe is closed. 'Restore windows': restores the position and size of the windows to those last saved. 'Close': leaves PMGlobe. The settings, window positions, etc., are saved automatically (see below). ----- 'Views' -- where and what you see ----- 'Standard views': this gives you a choice of standard views (Europe & Africa, Americas, India & Asia, Pacific, and the two Poles). Use mouse button 2 (see above) to select any point to be placed at the center of the view. 'Grid line choices': lets you choose which grid lines (if any) are to be shown, and the color (one of fifteen) of the grid lines. 'Snap to equator': this leaves the Longitude of the center of view unchanged and sets the Latitude to zero (the equator). Globe drawing is faster when the Latitude of the center of view is zero than when globe is tilted. 'Snap to Greenwich': sets the Longitude of the center of to zero (the Prime Meridian) while leaving the Latitude unchanged. This has no effect on drawing time. 'Allow mouse button 2': if selected, lets you rotate and tilt the globe using Mouse Button 2 (see above). It can be de-selected to prevent accidental movement of the direction of view. ----- 'Lighting' -- how the globe is seen ----- 'Sunlight': asks for "sun lighting" of the globe. This lets you see at a glance which parts of the world are in daylight, and which are in the dark. This lighting is (of course) time dependent, so PMGlobe needs to know the time zone you are in, and will ask you for it if it is not already set. If Sunlight is selected, the globe will be redrawn at regular intervals (as selected via 'Set refresh time', under 'Options'). See below for notes on the accuracy of the time and sunlight information. 'Sunlight from space': is similar to 'Sunlight', except that it is more realistic -- you cannot see details on the dark side of the earth except where lit by twilight. For best realism, choose a black background, 3-D, astronomical twilight, and no grid lines (or perhaps low-key grid lines, such as GREY). This setting implies (sets) 'Sunlight'. 'Sunlight and starlight': shows the 'Sunlight from space' view, with the land masses on the "dark side" of the earth made visible, too. (If you cannot see them, turn up the brightness on your display.) '3-D': adds shading, to give the globe a "three-dimensional" appearance. On a VGA screen there are only two shades of green and blue available, so this will give a rather grainy and mottled appearance (especially if a Sunlight option is selected), so this setting may not give an acceptable display. On a BGA (8514), or better screen and adapter, much smoother shading is possible. 'Twilight settings': lets you select how much of the "dark side" of the globe is to be shown when sun lighting is in effect. When theoretical sunrise/sunset is selected, the globe is lit as though by a point source at the center of the sun: exactly half of the globe is lit. For the meaning of the other settings, see the detailed notes below. 'Land color': lets you select one of nine colors for land masses and islands. The default is Green, though Yellow and White are good alternatives. 'Water color': lets you select one of nine colors for lakes and seas. The default is Blue; Gray is an alternative. 'Background color': lets you select one of sixteen background colors. A black background gives a nice 'deep space background' effect, though may be a bit too much of a contrast for some tastes; you may prefer Dark Blue. Date and time limits and accuracy """"""""""""""""""""""""""""""""" The data used for presenting the globe are loaded in compressed form (a little less than 22 Kilobytes). The coastline and lake data were compiled from a number of different sources, with some manual editing to improve the representation in critical areas such as narrow straits and isthmuses. The accuracy of the coastline and other data is not guaranteed in any way, but is believed to be within 40km (25miles) in the worst case (near the equator) and significantly better in the East-West direction in Northern and Southern latitudes. When the distance calculator is used, the mouse position can only be determined to the nearest pel (picture element) on the screen. The longitude and latitude is then reported as being at the center of that pel. Distance calculations between the two positions thus reported are then calculated from those coordinates and should be accurate to the nearest unit (km or mile), or 0.2%, whichever is greater. The 0.2% limit is a consequence of assumption used in the calculation that the earth is spherical (which it is not). Time and sun position calculations are only important when one of the 'Sunlight' options is selected. In this case, PMGlobe needs to know the current date and time-of-day (taken from your computer's clock -- make sure it is set correctly). It also needs to know which time zone you are in: if not already set it will ask you to set it (you may also need to change it if your computer clock is changed for daylight saving, summer, or winter time). From the current time and time zone information, PMGlobe can determine apparent solar time (which is as much as 16 minutes different from the Civil time used for clocks) and hence the sun's position. This is then used to display the globe as though lit by the sun: the light/dark dividing line thus shows where the sun is rising or setting. The various calculations done should give an accuracy of sun position that leads to a sunset or sunrise indication that is correct to within twenty seconds of time. Actual sunset or sunrise times will be a little different because of atmospheric effects, which vary with the time of year, the weather, and latitude. However, PMGlobe does give a useful indication of sunrise and sunset, and of course lets you see at a glance which parts of the globe are in night or daylight. Note that results may be incorrect if you set your computer's date to be earlier than 1 January 1990. Also, the formulae used to calculate the sun's position may prove to be inaccurate at some time in the future, because the earth's movement is not entirely predictable. Twilight settings """"""""""""""""" The sun is not a point source of light, and the atmosphere scatters its light, too. Therefore, sunlight is seen on the "dark side" of the earth for some time before the sun rises and for some time after it sets. You can select to see all, part, or none of this twilight zone on the globe. Twilight, when shown, is always shown shaded. On a VGA (standard) screen it can appear mottled or granular, because there are only two shades of each color available to PMGlobe. The twilight settings provided only have an effect when 'Sunlight' is selected, and are: 'Theoretical sunrise/set': this lights the earth as though by a point source at the center of the sun; the sunrise/set line is shown as though light ceased when the center of the sun crossed the horizon, and so no twilight can be seen. 'Ideal sunrise/set': this is a practical and generally accepted definition (fifty minutes of angle after the theoretical sunrise/set) which allows for the diameter of the sun and common atmospheric effects. The line seen on the globe joins the points at which the disc of the sun will have just disappeared or be just about to appear, and encloses a very narrow band of twilight. 'Civil twilight': the boundary marks the end of "civil twilight" -- a convenient point used for legal purposes (for example, when it is too dark to carry out certain tasks). Please note that PMGlobe's rendering of this line must not be used for any critical or legal decisions; errors and bugs are always possible, and the definition used by PMGlobe (six degrees after the theoretical sunrise/set) may not match the legal definition used in your country. 'Naval twilight': the boundary indicates the points where it is dark for all practical purposes: the center of the sun is twelve degrees below the horizon. 'Astronomical twilight': there is no boundary; light fades to zero, where it is perfectly dark: no effects from sunlight can be detected. At this point, the center of the sun is eighteen degrees below the horizon. Performance considerations """""""""""""""""""""""""" PMGlobe is designed as a "32-bit" application, with heavy use of long (32-bit) integers. All computation is done using integers, so a math coprocessor is not required. In general, the simpler the image presented the faster it is drawn. Selecting sunlight, 3-D, and twilight all slow down the drawing (but 'sunlight in space' is usually faster than 'sunlight' alone). Non-equatorial (tilted) views take significantly longer to draw than equatorial views (hence the 'Snap to equator' option). As a rough guide, the simplest (flat lighting, equatorial view, no sunlight) image with a diameter of 400 picture elements should take about 4-6 seconds to draw on a 25MHz 386 PC or PS/2. The time taken is inversely proportional to the speed of the processor and proportional to the square of the image diameter. The most complicated drawing (3-D shading, non-equatorial view, sunlight) might take about four times longer. Saved settings """""""""""""" The following settings are saved (in the system file "OS2.INI") when 'Save settings' is selected. They are also automatically saved when PMGlobe is closed or if OS/2 is shut down while PMGlobe is running: Latitude and Longitude of the center point of the view Grid (Meridians and Parallels) selections and color Lighting selections (Sunlight, Sunlight from space, Starlight, 3-D) Twilight selection (degrees) Land, Water, and Background colors Refresh (re-draw) interval. Whether 'Desktop' is selected (globe will be bottom window) Whether 'Draw at low priority' is selected Whether mouse button two is active ('Allow mouse button 2') 'Restore settings' restores all of these to the last saved values. 'Reset settings to defaults' sets all of these to the PMGlobe defaults. The following settings are saved, also in OS2.INI, when 'Save windows' is selected, OS/2 is shut down, or PMGlobe is closed (unless the PMGlobe window is minimized or maximized): The position and size of the main (globe) window The position of the 'Position/distance calculator' window. The position of the 'Command dialog' window. 'Restore windows' restores these to the values used when PMGlobe was last started. The following setting is saved in OS2.INI when Mouse button 1 is double-clicked on the globe: The latitude and longitude of the current 'fixed point'. This is cleared when 'Reset' is selected in the Position/distance calculator. By default, all the settings are saved in the OS2.INI file under the application name "PMGlobe". You can extend this name (and hence control different instances of PMGlobe and its settings) by using the NAME parameter when starting PMGlobe. This parameter constructs the name used by adding the word you give (which should be from 1 to 25 characters long, with no blanks) to the stem "PMGlobe.". For example, if you run PMGlobe with the command: "start pmglobe name Fred" then the entries in the OS2.INI file will be stored under the name "PMGlobe.Fred". Note that the case of each letter is significant. The 'Make Desktop' setting """""""""""""""""""""""""" The Desktop setting requests that PMGlobe will keep itself at the bottom of all the windows on the screen. Under OS/2 2.x the desktop icons are part of the desktop, and so PMGlobe cannot get "underneath" them; selecting both 'Make Desktop' and 'Make full screen' is therefore not advised as it would hide the desktop icons (unless you have moved them off the desktop and into a different folder). Once on the desktop, the usual PMGlobe mouse functions are suspended. Clicking on PMGlobe will ask for confirmation before leaving the Desktop state. If leaving the desktop and the globe and background window fills or is larger than the screen then PMGlobe will revert to the Presentation Manager default size and position when it leaves the desktop. PMGlobe will remember the Desktop state (and window positions) when Shutdown by OS/2. It can also be forced to start up on the Desktop by specifying the parameter 'DESKTOP' when starting PMGlobe, for example: "start pmglobe desktop". To fill the screen, add the parameter 'FULLSCREEN' on startup. Do not start two applications (such as certain "wallpaper" programs, or two instances of PMGlobe) that both attempt to remain on the desktop. Time Zone interface details """"""""""""""""""""""""""" Personal computer operating systems have a variety of ways of holding timezone information (some compilers even build in a default geographical location!), but to date no standard mechanism has been defined. PMGlobe introduces a new mechanism for holding timezone information. The current timezone offset, daylight savings offset, and timezone name is held in the system file "OS2SYS.INI" in a general format that any application can use and which can easily be accessed by application programs (for example, by C or REXX programs). Specifically, the information is held as three words in the OS2SYS.INI file, under the name "TimeZone" with key "Active". This string holds at least three words separated by exactly one blank, and with no leading blanks. The third word will be followed by either a blank (to allow future extension) or the C 'end of string' null character. The three words are: base-time-offset-from-GMT summer-time-offset zone-abbreviation where the two times have the format [+|-][h]h[:[m]m[:[s]s]]] and the zone-abbreviation is either "???" (indicating unknown) or "xxx", where xxx are three or four uppercase alphabetics. For example: +0:00 +1:00 BST The total offset from GMT is the sum of the two time offsets. -------- Mike Cowlishaw, IBM UK Laboratories