Kids Cube/4_History.iso/fastmap/fastmap.doc

Text File | 1992-09-23 | 21KB | 453 lines

Copyright (c) 1992, Glen Okita.
------------------------------------------------------------------------
FILES

This distribution should contain the following files:
    FASTMAP.EXE    Fastmap program
    FASTMAP.DOC    Fastmap documentation (this file)
    FASTMAP.INI    Sample initialization file
    MWDBII.DOC     MWDBII format documentation
    MWDBII         Level 3 MWDBII map database
    CITY.DAT       City names and locations (694 cities)
    CITYSUB.DAT    City subset (223 cities)
    EXAMPLE.DAT    Example of user defined data

------------------------------------------------------------------------
HARDWARE AND SOFTWARE REQUIREMENTS

Fastmap requires 200K free memory, so a minimum of 384K installed
memory should be enough.  A mouse is required for a few features, but
you don't need one.  Should work with EGA/VGA, DOS 3.3 and up.  Developed
and tested with VGA and DOS 4.01.

Most helpful is a fast CPU and a fast disk.  A reasonable minimum is a
standard AT class machine (8 Mhz).

------------------------------------------------------------------------
LICENSE

The Fastmap program and accompanying documentation ("SOFTWARE") are
protected by United States and International copyright law.  With this
agreement, Glen Okita ("AUTHOR") grants you non-exclusive rights to use,
copy, and distribute SOFTWARE subject to the following restrictions:
   a)  SOFTWARE shall be for personal, non-commercial use.
   b)  SOFTWARE shall retain all copyright notices and this agreement.
   c)  SOFTWARE shall not be modified or incorporated in any derivative work.
   d)  SOFTWARE shall not be disassembled, decompiled, or reverse-engineered.
   e)  All copies of SOFTWARE shall be bound by the terms of this agreement.

The data files accompanying SOFTWARE are not subject to the above
agreement, but are covered by separate provisions.  See MWDBII.DOC.

NO WARRANTY:
SOFTWARE is provided "as is" with no warranties of any kind, express or
implied.  In no event shall AUTHOR, or any distributor of SOFTWARE, be
liable for any damages arising out of use or non-use of SOFTWARE, including
loss of monies, loss of data, or any incidental or consequential damages.

------------------------------------------------------------------------
SUMMARY

fastmap [option ...] [userFile [cityFile [mapFile]]]");

option is one of:
    -h   displays this help
    -m   calculates metric distances
    -s   swaps left and right mouse drag functions
    -F   forces floating point calculation for spherical projections
    -I   ignores input interrupt while drawing

mapFile must exist, userFile and cityFile are optional.  userFile
defaults to USER.DAT, cityFile defaults to CITY.DAT, and mapFile
defaults to MWDBII.

An optional file, FASTMAP.INI, can be used to customize display
colors.

Fastmap first looks for files in the current directory, otherwise
it looks in the program directory.

Note that because the user file and city file are optional, you can
use any file name as a placeholder even if the file does not exist.
For example, if you want to use a different city file MYCITY.DAT,
and you don't have a user file, you can type:
    fastmap d mycity.dat
Fastmap will look for a dummy file D, and won't find it (presumably),
and simply continue on.

Similarly, if you want to run fastmap without a city file, you can type:
    fastmap d d
Here, neither user file nor city file will be found, and Fastmap will
proceed with just the map database.

------------------------------------------------------------------------
INTRODUCTION

Fastmap draws a map of the world using a map database in MWDBII format.
An MWDBII file is a binary database of coordinates, with up to five
levels of detail.  A particular database may not actually contain all
five levels of detail.

Fastmap also draws locations specified in city and user files.  These
files are text files that you can create or add to.

You can select either a spherical projection or a cylindrical (flat)
projection.  The spherical and cylindrical projections maintain separate
sets of viewing parameters.  That is, you can pan, zoom, and change
detail in the cylindrical view without affecting the spherical view,
and vice-versa.

On startup, Fastmap does some simple checks to see if the files contain
good data.  If an error is encountered, Fastmap stops.  Otherwise, Fastmap
presents an initial display at minimum detail, and with a spherical
projection.  You can then enter commands by keyboard or mouse.

------------------------------------------------------------------------
KEYBOARD COMMANDS

A keyboard command is one of the following keys:
      <left arrow>  move the view west by current grid size
     <right arrow>  move the view east by current grid size
        <up arrow>  move the view north by current grid size
      <down arrow>  move the view south by current grid size
                 z  zoom in by 1.5x (lowercase)
                 Z  zoom out by 1.5x (uppercase)
                 d  more detail (lowercase)
                 D  less detail (uppercase)
                 s  switch between spherical and cylindrical projection
                 r  reset to default display, keeps current projection
                 i  show info dialog
                 o  show display options dialog
                 a  show about dialog
  <return> <space>  redraw the current view
      Alt-F4 <esc>  exit with a dialog
             Alt-x  exit without asking

You can type a command key while Fastmap is drawing.  If you type a key
that isn't a command, drawing stops.  You can type <space> or <enter>
to redraw the display.

The following keys are used with dialog boxes:
     <tab> <right arrow> <down arrow>  move to next dialog entry
  Shift-<tab> <left arrow> <up arrow>  move to previous dialog entry
                              <space>  execute or toggle current entry
                             <return>  equivalent to OK button
                                <esc>  equivalent to Cancel button

The dialog boxes are:

Info dialog:  Displays the current projection type, latitude and
longitude offsets.  If any marks are present, the latitude and longitude
of each mark is displayed.  If there are 2 marks, their Great Circle
distance is displayed.  Note that a mouse is required to set marks.

Options dialog:  Displays the current visibility for each object in
the database.  You can change the visibility of an object by using arrow
keys to highlight the object and hitting the space bar.

About dialog:  Displays the version of Fastmap and copyright notice.
Also displays the state of each Fastmap option.  You can change any of
the options by highlighting it and hitting the space bar.

------------------------------------------------------------------------
MOUSE COMMANDS

Each button on the mouse has a different function depending on whether
it is dragged or clicked.  To click a button, simply press and release
it quickly.  To drag with a button, press a button and hold it down
while you move the mouse.

The mouse buttons are:

        | Left              | Middle (1)        | Right             |
  ------+-------------------+-------------------+-------------------+
  Click | Mark location     | Options dialog    | Info dialog       |
        |                   |                   |                   |
  ------+-------------------+-------------------+-------------------+
  Drag  | Drag view (2)     | Options menu      | Command menu (2)  |
        |                   |                   |                   |
        +-------------------+-------------------+-------------------+

notes: (1) only applicable for 3-button mouse
       (2) these functions are swapped with the -s option
           Assigning a popup menu to the right mouse button may seem odd,
           but some recent Windows programs seem to be using this convention
           and it is fairly common under UNIX windowing environments.

The mouse functions are:

Marking locations:  You can have up to 2 marks.  If the location
of the first mark corresponds to data in the city file or the user file,
the label for that location is displayed.  Otherwise, a large cross is
displayed.  A smaller cross is displayed for the second mark.  As you
make successive marks, the old second mark is discarded and the old
first mark becomes the second mark.  If you select the same location as
the first mark, all marks are removed.

View dragging:  When you are dragging the view, the cursor changes to a
hand and a large cross marks the location that you are dragging.  Use
the cursor's finger to indicate where this location should be displayed.
In spherical view, the "globe" is first rotated about the axis, then the
axis itself is tilted.  You cannot drag to or from a location off the
"globe".  Also, in spherical view, it may be impossible to display
the location at its desired place.  For example, no combination of
rotations and tilts can place the North Pole at 3 o'clock (or anywhere
off the vertical centerline).  In this case, you will find the axis
tilts in an unusual way.

You can reliably control the axis tilt by dragging up or down along the
vertical centerline of the screen, and by never crossing a pole while
you are dragging.  If you do cross a pole, the "globe" will rotate 180
degrees around its axis because rotation is applied before tilt.
Similarly, you can reliably control rotation about the axis by dragging
to a location at the same latitude.  This ensures that the axis tilt
stays the same.

Info dialog:  Equivalent to pressing the 'i' key.  One small difference
is that all mouse dialogs are displayed at the cursor, while keyboard
dialogs are displayed at the center of the screen.

Command menu:  Pretty much duplicates the functions available from the
keyboard.  The character at the right of the menu indicates the keyboard
equivalent, if any, for each menu entry.

Options dialog:  Equivalent to pressing the 'o' key.

Options menu:  A quick way to change the visibility of a single object.

------------------------------------------------------------------------
MISCELLANEOUS CONSIDERATIONS

If you have problems with your mouse, or Fastmap detects a mouse when
there isn't one, the -M option disables the mouse.

If you are running under Windows or other multi-tasker, you may get
a modest speed increase by using -I to ignore drawing interrupts.
This is because checking for a key event can be much slower under
Windows than directly from DOS.  On my system, the improvement is
marginal.

You can force floating point (-F) for spherical projections.  This
option has no effect for cylindrical projections, which always uses
scaled integers.  You can see an increase in accuracy when you are
at maximum zoom, because the slightly crooked grid lines are much
straighter with floating point on.  If you specify floating point,
Fastmap is about ten times slower.  If you also specify ignore
interrupts (-I), there is no way to stop Fastmap as it draws.  You
may end up waiting awhile.

If you dislike the wrapped (upside down) cylindrical projection, you
can be disable it by supplying the -W option.  It provides a marginal speed
improvement.

------------------------------------------------------------------------
KNOWN BUGS AND LIMITATIONS

1. The grid size changes as you zoom.  The maximum grid size is 20
   degrees, the smallest is 0.5 degree.  However, near the poles
   the grid becomes coarse to avoid drawing too many grid lines.
   This may cause the grid to change unexpectedly as you pan around
   the poles.

2. Single locations in the city file and user file do not get drawn in the
   wrapped (upside down) cylindrical view.  However, connected lines in
   these files are drawn in both the normal view and the wrapped view.

3. You cannot mark locations in the wrapped part of the cylindrical view.

4. Scaled integer math is only accurate to about 1 in 8000.  Since VGA
   resolution is 640x480, this is no problem when zoomed out.  However,
   if you zoom in more than 5 times from default (about 10x
   magnification), the points will not be drawn with full precision.

------------------------------------------------------------------------
ABOUT THIS STUFF

What makes Fastmap fast?  Partly because it uses scaled 32-bit integers
instead of floating point.  For spherical projections, though, the
details of the integer computation are a little convoluted.  First,
instead of trying to calculate a location on the sphere directly, the
latitude and longitude coordinates are converted to XYZ rectangular
coordinates, which are then transformed with a 3D rotation matrix.  This
saves a couple of trigonometric transcendental calls over the
"straightforward" way.

Furthermore, the sin() and cos() functions required to convert from
polar to rectangular are also integer functions.  This is done by
quadratic interpolation.  Amazingly enough, a coefficient array of
about 16 elements provides more than 4 digit precision.  A conventional
linear interpolation would require a much bigger array for the same
precision.

The integer computation could be even faster on 386s if it took
advantage of fast 32-bit integer multiplication.  To do this, I need a
reliable way of detecting 386/486 machines.

The other reason Fastmap is fast comes from a simple (at least
conceptually) indexing scheme.  Fastmap starts by determining the
bounding box for each object in the MWDBII database.  The file offset
for that object is associated with each object.  This is done only once.
Fastmap then determines the bounding box corresponding to the borders
of the current screen.  This must be done after each zoom or pan.  When
drawing, Fastmap skips each object that does not appear in the view
bounding box.  When it encounters an object that is within the box, it
does a direct access disk seek to the object and starts drawing from
that location.  Each coordinate in the object is then tested against
the view box.  Only the coordinates within the view box are transformed
(using the integer calculations described above).

One optimization I've thought of, but not implemented, takes advantage
of the multi-level detail of the MWDBII format.  Fastmap could test
just the minimum detail points against the view box.  The intervening
points of greater detail would only be tested and transformed if the
minimum detail points on either side were visible.  In a zoomed out
view, with the axis tilted so that a pole is visible, this would
significantly improve performance.  However, when zoomed way in there
would be little improvement since most points would be clipped by the
entire object's bounding box.  In fact, it could even be a little slower
due to maintaining and checking detail levels.

I then noticed that when I was zoomed in all the way, and there were
no objects visible, Fastmap still seemed sluggish.  It turns out that
interrupt checking (checking for a key hit) is relatively slow.  And it
is even slower when running under Windows.  This was masked when there
were many points to draw because the time spent checking for a key was
only about 10% when drawing the entire globe.  When zoomed all the way
in, however, it was about 50%.  To speed this up Fastmap checks for a
key only once for every 100 objects or coordinates.  On slower machines,
though, it may now be sluggish in responding to a key press.

Finally, to those of you with 8086s and slower 286s, I'm sure you will
find that Fastmap is far from really fast.  All I can say is that
Fastmap is about 20 times faster than a straightforward implementation.

This project started as a way to learn about the idiosyncrasies of PC
programming.  It's grown to about 10,000 lines of C++.  At this
point I'm fairly sick of it, so I figure it's time to inflict it upon
the rest of the world.  I'm not inclined to make any promises regarding
support or enhancements, but if you have any bright ideas you may
contact me at:
Glen Okita, 1327 Maria Way, San Jose, CA 91157-3618

I did toy briefly with the idea of shareware, but I really think you'd
be better off spending your hard earned money on a good globe or atlas.

------------------------------------------------------------------------
ACKNOWLEDGEMENTS

Although its internal design is entirely original, this program was
inspired by another MWDBII map drawing program written by Steve Sampson
and distributed by Public Software Library.

The MWDBII format and map data is code placed in the public domain
by Fred Pospeschil and Antonio Riveria.  Original coordinate data
was created by the Central Intelligence Agency.

Additional information about MWDBII format and map data may be obtained
from Micro Doc, 3108 Jackson St., Bellevue, NE 68005.

The city locations were converted from files in GeoClock format.  I
downloaded those files from a local BBS.

------------------------------------------------------------------------
APPENDIX: MWDBII

In MWDBII format, higher numbered detail levels imply a lower level
of drawn detail.  This may be counter-intuitive, but a level 3 map
database has more points in it than a level 5 map.

The level 3 database included in this distribution contains 26,160
coordinates.  It is a subset of a map database distributed by Micro Doc.
The complete level 1 database from Micro Doc contains 178,068 coordinates.
Each database with a higher level number is a strict subset of the level 1
database.

Micro Doc also distributes map data for US states and counties, as well
as much more detailed world and US map data.  No claims are made regarding
the suitability of Fastmap for high resolution maps -- it is likely to be
too slow, and you may run out of memory.

For full MWDBII documentation, see the file MWDBII.DOC.

------------------------------------------------------------------------
APPENDIX: CITY AND USER FILE FORMAT

The user and city data files let you add data to be drawn on the map.
If the file contains syntax errors, Fastmap displays an error message and
stops.  The format of the file is comma delimited fields of:
    "label", latitude, longitude, code, action  ; semicolon starts comments

Quotes cannot appear in a quoted label, but quotes are optional.  If the
label is not quoted, the characters until the first comma are taken to
be the label.

Latitude and longitude are integers specifying degrees in minutes
(multiply degrees by 60 to get minutes).  Positive numbers are north
and east, respectively.

The code specifies the kind of object at the latitude and longitude
location.  The code values are:
    1 for Coast lines             10 for Capital cities
    2 for Country boundries       11 for State capitals
    4 for State boundries         12 for Other cities
    5 for Islands                 13 for User data 1
    6 for Lakes                   14 for User data 2
    7 for Rivers

The action specifies what to do at the location.  The possible actions
are:
    1 to draw a big marker
    2 to draw a medium marker
    3 to draw a small marker
    4 to draw a tiny marker
    5 to draw nothing
Adding 64 to the action value draws a line from previous location to
the current location.  That is, an action value of 66 draws a line with
a big marker at each point, or an action of 69 just draws lines.

See CITY.DAT or EXAMPLE.DAT for examples.  You can see the contents
of EXAMPLE.DAT by running:
   fastmap example.dat

------------------------------------------------------------------------
APPENDIX: FASTMAP.INI FORMAT

This file allows you to customize the color for each object.  If there is
any error in the initialization file, Fastmap displays an error message and
stops.  The format is a sequence of lines:
    object = color  ; semicolon starts comments
The object and color may be in any combination of upper or lower case.

The objects and their default color settings are:
    coastlines = white
    borders = yellow
    stateBorders = yellow
    islands = white
    lakes = lightBlue
    rivers = cyan
    capitals = red
    stateCapitals = red
    otherCities = red
    userData1 = magenta
    userData2 = green
    grid = darkGray
    uiBkgnd = lightGray    ; menu background
    uiDark = darkGray      ; lower right of "raised" menu
    uiLight = white        ; upper left of "raised" menu
    uiText = black         ; menu text
    uiGray = darkGray      ; menu "grayed" text
    uiMark = red           ; marks

The allowed colors are:
    black       blue       green     cyan
    red         magenta    brown     yellow
    white       lightGray  darkGray  lightBlue
    lightGreen  lightCyan  lightRed  lightMagenta

See FASTMAP.INI for examples.

(end of fastmap.doc 5/92)