home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d2xx / d229 / drawmap.lha / DrawMap / drawmap.doc < prev    next >
Text File  |  1989-07-20  |  9KB  |  191 lines
  1.                                   Drawmap
  2.  
  3.        A program for drawing representations of the Earth's surface.
  4.  
  5.                                     by
  6.  
  7.                                 Bryan Brown
  8.  
  9.                                  06/26/89
  10.  
  11. I.  Distribution
  12.  
  13.      This program is released into the public domain (FREEWARE), and is
  14. freely distributable as long as this document file, source code, header files
  15. and map files are included in their entirety.  The source may be modified for
  16. personal use, but is NOT for commercial use.  I would, however, appreciate
  17. receiving credit for the implementation of the ideas embodied in the program.
  18. Donations are welcome, but not at all necessary since I do this stuff for fun.
  19.  
  20. II.  Introduction
  21.  
  22.      Drawmap is a program that draws several different views of the Earth's
  23. surface.  In my work we regularly display views of the orbits of Earth-
  24. orbiting satellites superimposed on one of several different types of maps. 
  25. Even though I am not involved with the development of graphics displays, the
  26. quality of the displays generated on our IRIS workstations finally induced me
  27. to try my hand at similar graphics on the Amiga.  While a stock Amiga cannot
  28. generate displays as fast as the IRIS systems, the quality of the displays it
  29. can generate are quite respectable.
  30.  
  31.      The user interface is exclusively through pop-up menus, as implemented
  32. by Derek Zahn on Fish disk 96 and used in Bob Corwin's rotating globe
  33. demonstration on Fish disk 151.  The IRIS systems have a similar interface,
  34. and make for a very professional appearance.
  35.  
  36.      The executable code was built using Aztec C, Version 3.6a.  I have no
  37. idea what modifications would be necessary to build it with Lattice C, but
  38. they should not be extensive.  Included is a simple batch file for building
  39. the executable from source.
  40.  
  41.  
  42. III.  Files Provided
  43.  
  44.    drawmap         - the executable file
  45.    drawmap.c       - the source code
  46.    drawmap.doc     - this document file
  47.    drawmap.h       - header file containing necessary non-menu definitions
  48.    drawmap-menu.h  - header file with menu definitions
  49.    pop-drawmap.c   - source for pop-up menus, modified for this application
  50.                      to initialize the special mouse pointer
  51.    map.bin         - map data file (see below)
  52.    map-trig.bin    - map data file (see below)
  53.    makepop-drawmap - batch file for compiling pop-drawmap.c
  54.    makedrawmap     - batch file for building executable from source
  55.    pop.c           - original source for pop-up menus
  56.    pop.doc         - original documentation for the pop-up menus
  57.    popmenu.h       - header file needed by pop.c and pop-drawmap.c
  58.  
  59.  
  60. IV.  Map Files
  61.  
  62.      Land masses (referred to as regions here) are represented as closed
  63. polygons.  Each vertex of such a polygon is represented as an ordered pair of
  64. numbers, the first being the latitude and the second the longitude.  Latitude
  65. runs from -90 degrees (the South pole) to +90 degrees (the North pole), while
  66. longitude runs from -180 degrees to +180 degrees.  The end of a region is
  67. indicated by a point with values (0, 0).
  68.  
  69.      There are two binary files loaded into memory during program
  70. initialization.  The first file, "map.bin", consists of 8859 of these
  71. (latitude, longitude) pairs, packed into short integers (16 bits each) to
  72. conserve memory and disk space.  The second file, "map.trig.bin", also
  73. consists of short integers, each pair being packed representations of the
  74. cosine and sine of the latitude of the corresponding point in "map.bin". 
  75. These values were pre-computed in order to speed up the drawing of the globe
  76. views described below.  The latitude and longitude values are accurate to
  77. 0.01 degree each.  The sines and cosines of the latitude are only accurate to
  78. 4 or 5 decimal places, but this is more than accurate enough for this
  79. application.
  80.  
  81.  
  82. V.  Usage and Features
  83.  
  84.      To run the program, you can either
  85.  
  86. - enter "run drawmap" from the CLI, or
  87. - click on the DrawMap icon from the Workbench,
  88.  
  89. either of which brings up a blank, high resolution interlaced window.  The
  90. user communicates with the program entirely via the mouse.  Messages and
  91. instructions to the user appear in the window title bar.  Pressing the menu
  92. button brings up a pop-up window with the following user options:
  93.  
  94. o Color-Fill - An on-off switch indicating whether or not regions are to be
  95.   color-filled.  A checkmark in the pop-up menu indicates that color-fill is
  96.   on.
  97.  
  98. o Flat - Generate a "Flat" map.  A "Flat" map is just a plot of the latitude
  99.   and longitude pairs, without any attempt to preserve areas or make the
  100.   representation conformal.  This type of map is therefore not usually used
  101.   by cartographers.
  102.  
  103. o Mercator - Generate a Mercator map, color-filling the continents.  This is
  104.   the standard conformal map.
  105.  
  106. o Globe - Generate a view of one entire hemisphere of the Earth.  If the last
  107.   view drawn was neither a Flat nor Mercator map, a Flat map is first drawn. 
  108.   The user is then prompted (in the window title bar) to press the mouse
  109.   selection button to choose the point on the Earth's surface to appear at
  110.   the center of the globe view.  Note that this is a representation of how
  111.   the Earth would look (without clouds, of course) to an observer infinitely
  112.   far away, but with a very powerful telescope.
  113.  
  114. o Orbital - Generate a view of the Earth as seen from an altitude of 300
  115.   kilometers.  As above, press the mouse select button to choose the point to
  116.   appear at the center of the globe view.  Because of perspective effects,
  117.   the continents and larger islands appear distorted in this view compared to
  118.   the previous globe view.
  119.  
  120. o Zoom In - Generate an orbital view as above, but halve the altitude from
  121.   which the view is seen.  The resulting altitude appears in the title bar. 
  122.   The minimum allowed altitude is 10 kilometers.
  123.  
  124. o Zoom Out - Generate an orbital view as above, but double the altitude from
  125.   which the view is seen.  The resulting altitude appears in the title bar.
  126.  
  127. o Box - Draw a map of all regions overlapping a rectangular box.  As the
  128.   window title bar indicates, press and drag the mouse select button to
  129.   define the box desired.
  130.  
  131. o Grid - Superimpose a latitude-longitude grid on the currently-drawn map. 
  132.   This option is not allowed for the Box view.
  133.  
  134. o Flood Fill - Color-fill an area of the map currently displayed.  As the
  135.   window title bar indicates, press the mouse select button to select the
  136.   area to be color-filled.  Note that only if the area being color-filled is
  137.   of the same color as the oceans does color-filling actually occur.  In
  138.   other words, the black sky background in the globe and orbital views cannot
  139.   be color-filled.
  140.  
  141. o Colors - Modify the colors used to display land masses and bodies of water.
  142.  
  143. o Clear - Clear the Screen.
  144.  
  145.  
  146. VI.  Notes
  147.  
  148. o The time required to complete a globe view is longer than I would have
  149.   liked.  Pre-computing the sines and cosines of the latitudes helped, but
  150.   with a stock Amiga about 35 seconds is still required to plot a typical
  151.   globe view.
  152.  
  153. o In the globe views, the blue globe is drawn using the DrawEllipse and Flood
  154.   functions.  I originally used the AreaEllipse and AreaEnd functions, but
  155.   for reasons unknown to me the resulting blue globe had horizontal black
  156.   spikes running across it.  I would appreciate receiving an explanation of
  157.   this phenomenon.
  158.  
  159. o For the Flat, Mercator and Globe views the grid lines are spaced 20 degrees
  160.   in latitude and 30 degrees in longitude.  For the Orbital views, above 1200
  161.   kilometers the grid lines are spaced as above, but below 1200 kilometers
  162.   they are spaced 10 degrees in latitude and 15 degrees in longitude so that
  163.   they can be more easily seen.
  164.  
  165. o Regions that wrap around the limb of the Earth in the Globe and Orbital
  166.   views, or that cross the boundaries in the Box view, are not color-filled. 
  167.   The algorithm I have for doing this depends on the (sometimes complex)
  168.   topology of the set of rim points that arise during the drawing of a given
  169.   region.  Mapping the rim point coordinates to screen coordinates introduces
  170.   a discreteness which makes the algorithm very sensitive to truncation and
  171.   roundoff.  For the time being I have left these partial regions un-filled. 
  172.   In any case, the Flood Fill function can be used to tidy up.
  173.  
  174.  
  175. VII.  Conclusion
  176.  
  177.      If you have any questions, recommendations, gripes, etc., about this
  178. program, I can be reached at the following address:
  179.  
  180.  
  181.                               Dr. Bryan Brown
  182.  
  183.                        Computer Sciences Corporation
  184.  
  185.                                     c/o
  186.  
  187.                          Flight Dynamics Facility
  188.                                 Code 553.1
  189.                         Goddard Space Flight Center
  190.                             Greenbelt, MD 20771
  191.