// =============================================================================
// File:        Geodysseus Readme
// Summary:     Geodysseus development snapshot 0-1-7a installation notes
// Author:      Nicholas Shea
// Copyright:   (c) Nicholas Shea 2011     
// Web:         http://www.neolithicsphere.com/geodysseus/index.htm    
// =============================================================================

GEODYSSEUS.

OpenGL interactive map projection, navigation and geodetic utilities.


INSTALLING AND RUNNING GEODYSSEUS UNDER LINUX

Unarchive the zip to your chosen directory.
Start the program from a console/shell
so that the program can find its Data directory. Eg:
    
./Geodysseus


INSTALLING AND RUNNING GEODYSSEUS UNDER MICROSOFT WINDOWS

This 32 bit build was tested on Microsoft Windows XP and Microsoft Windows 7.

Simply unarchive the zip to a chosen directory. The program does not touch the
Windows registry. Beware that some older Zip utilities on MS Windows truncate
long files names when extracting, so please ensure that your Zip program
preserves the full file name, otherwise the world map will fail to load.


LEFT MOUSE BUTTON

Pick a traverse in either Globe or Map mode. Key modifiers:
Hold down Control key to enter Latitude and Longitude manually.
Hold down Shift key to clear previous traverse(s).

      
MIDDLE MOUSE BUTTON

Rotates the Globe. This will also rotate a Map Projection which is projected in
the plane Z=0. To reset the view, click the small white sphere at the origin of
the camera frame icon on the far left of the Navigator window.

    
MAP PROJECTIONS

The Map Projection can only be changed when in Map mode.
Choose menu Projection->Set Map Projection. Current implementations are:

CYLINDRICAL: Standard Mercator, Transverse Mercator, Equidistant. 
CONIC: Lambert Conformal.
AZIMUTHAL: Orthographic, Stereographic, Gnomonic.

If a traverse is clipped on the Map Projection, it might need re-plotting after
performing an inverse projection back to the Globe.
    
If you pick a long East-West traverse on the Mercator projection, the line will
wrap round. In this instance it is best to change the Central Meridian to a
suitable mid point.

If a loxodrome leg is uninitialzed during an inverse projection (from map to
globe), a warning dialogue will appear. This results in a message such as:
"Windspeed >= TAS". Simply keep the return key held down to dismiss.


    
PICKING

You may pick on the Reference Ellipsoid (life size) or on the Unit Sphere. The
default is Unit Sphere. When changing between these pick options, the OpenGL
environment and fog depth cue are changed accordingly. When picking on the life-
size Reference Ellipsoid, you can see the separation between normal sections on
long lines between high and low latitudes, but be sure to hide the geodesic.
When picking on the Unit Sphere, all internal computations are done as if you
picked on the Reference Ellipsoid.

Note: when using the menu option "Pick on Actual Ellipsoid" in Map mode, it is
sometimes necessary to move the camera back slightly after performing a
re-projection.


CUSTOM ELLIPSOIDS

Make sure the menu "Pick on Actual Ellipsoid" is checked for this to work. This
was a debug option, but is left enabled for advanced users. This option was
implemented to plot tracks on ellipsoids with large flattening values, and so
check the behaviour of Geodesic and Normal Sections. Choose what to plot from
the Nav menu. Rememeber, the default plot resolution is one vertex every 1000
meters, so please ensure your minor and major axes are large enough.


TRAVERSE LIST

Select menu Windows->Traverse List.
Before a traverse can be modified it must be unlocked by clicking the padlock.
Then you can name it by clicking the Traverse name button. Change Start and End
points by clicking A or B. The small pencil button re-logs output to the Log
window. Track attributes for Geodesic, Loxodrome amd Normal Section may be
changed by clicking the track name. The distance and bearings for each Leg (both
geodesic and loxodrome), are printed to the Log window. Additional navigation
parameters will be logged, according to the Traverse Mode, Land, Sea or Air.

Preliminary code for 'Traverse Mode Air' is implemented in Geodysseus-0.1.5
and later.


GRATICULE

Select menu Windows->Graticule.
Set attributes for East/West meridians and North/South parallels. Attributes are
persistent and may be saved as groups.


DISTANCE CALCULATIONS

Use Vincenty or Rainsford. Helmert and Rudoe currently only work for endpoints
within a quadrant (< 90). These methods were programmed for my own interest
and for comparison tests. Anti-podal points are trapped when entering points
with the mouse, as are tracks along a meridian.


EXPORT

Map projections can cen saved as PostScript which should open in Gimp, Okular,
Adobe Illustrator and other PostScript capable programs. When rendering a PS
file in Gimp, be aware that dashed lines take longer to process if antialiasing
is turned on. Only visible elements are exported.


HTML LATITUDE TRANSFORMATION TABLES

If you select a latitude transformation from the Tables menu on the Log window,
you will be presented with a "Save as..." dialog before the table is logged.
If you click cancel, the table is just output to the Log window; but if you
enter a valid file name with an html extension, the table is saved so that it
may be viewed in a web browser.


MULTISAMPLING (ANTIALIASING in OpenGL)
OpenGL Multisampling (antialiasing) is turned off by default but the globe
renders better if Multisampling is turned on. You can turn on Multisampling via
the Preferences dialog.

If you turn on Multisampling via the Preferences dialog and the app stalls
during the next launch, please read 'Multisampling-Prefs-Switch.txt' for a
solution. If Multisampling does not work, either your card does not support it
or Antialiasing settings for your driver are not set to 'Application Controlled'.


UNIT TESTS
    
Geodesy module passes Rainsford's Standard Test Lines.

Unit Tests for the map projections pass examples given in:
'Map Projections a Working Manual'
by John P Snyder US Geological Survey Professional Paper No. 1395, 1987.

Log Tables match those given in:
'Map Projections a Reference Manual'
by Lev M. Bugayevkskiy and John P Snyder.
Output tallies with data in the WGS 1984 official document.


Reference Ellipsoids implemented:
---------------------------------
Airy 1830
Modified Airy
Australian National 1965
Bessel 1841
Bessel 1841 Namibia
Clarke 1866
Clarke 1880
Everest 1830
Modified Everest
Fischer 1960 (Mercury)
Modified Fischer 1960 (South Asia)
Fischer 1968
GRS 1967
GRS 1980
Helmert 1906
Hough
International 1924  same as Hayford 1909
Krasovskii 1940
South American 1969
WGS 1960
WGS 1966
WGS 1972
WGS 1984


BUGS
    
The following is a known glitch...
1. Pick some traverses in Map mode.
2. Turn off "Plot Loxodrome"
3. Pick some more traverses.
4. Inverse project to the sphere.
5. The loxodromes picked prior to 2 are not re-projected.

If you find any bugs please fill out bug 'ticket' on the Geodysseus project page
at Sourceforge.

I have disabled "Feedback" for this program as it is still early beta, but bug
reports are welcome.


REFERENCES
    
The main references for programming the Geodesy module were:

  'Map Projections a Working Manual'
   John P Snyder
   US Geological Survey Professional Paper No. 1395, 1987.
      Referenced in source code as: MPAWM-Snyder-1987
    
  'Map Projections a Reference Manual'
   Lev M. Bugayevkskiy and John P Snyder
   Taylor Fancis 1995.
      Referenced in source code as: MPARM-Bugayevkskiy-Snyder-1995

  'Mathematical Models for Navigation Systems'
   P. D. Thomas, Scientific Staff Assistant
   Marine Sciences Department
   U. S. Naval Oceanographic Office. October, 1965.
      Referenced in source code as: MMNS-Thomas-1965

  'Geodesy'
   A.R. Clarke
   Clarendon Press
      Referenced in source code as: Geodesy-Clarke-1866

  'Geodesy'
   Brigadier G. Bomford
   Clarendonm Press 1962
      Referenced in source code as: Geodesy-Bomford-1962.

  'Geodesy'
   G.L. Hosmer.
      Referenced in source code as: Geodesy-Hosmer-1919.

  'Geometric Geodesy Part B'
   R.E. Deakin and M.N. Hunter
      Referenced in soource code as: Geodesy-Part-B-Deakin-Hunter-2010

  'Conformal Projections in Geodesy and Cartography'
   Paul D. Thomas [Senior Mathematician]
   US Department of Commerce [Charles Sawyer, Secretary]
   Coast and Geodetic Survey [ Robert F. A. Studds, Director]
   Special Publication no. 251
   UNITED STATES GOVERNMENT PRINTING OFFICE WASHINGTON : 1952
   Document: QB275U35no2511952.pdf
      Referenced in source code as: CPGC-Thomas-1952

   'Latitude Developments Connected with Geodesy and Cartography'
    Oscar S. Adams
    US Coast and Geodetic Survey
    Special Publication no. 67
    WASHINGTON GOVERNMENT PRINTING OFFICE: 1921
    Document: QB275U35no671921.pdf
      Referenced in source code as: LDCGC-Adams-1921
  
   'Geodetic Reference System 1980'
    H. Moritz

   'The Defense Mapping Agency DMA TR 8350.2'
    Second Edition, 1 September 1991.
    DEPARTMENT OF DEFENSE WORLD GEODETIC SYSTEM 1984
    Report prepared by the DMA WGS 84 Development Committee
      Referenced in source code as DMA-WGS-1984


DOCUMENTATION
    
Present documentation pertains to program operation only and is not as
extensive as I would like.


TRADEMARKS

Microsoft and Windows are registered trademarks of Microsoft Corporation.
UNIX is a registered trademark of the X/Open Group, Inc. 
OpenGL is a registered trademark of Silicon Graphics, Inc. 
MacOS is a registered trademark of Apple Computers, Inc.


COPYRIGHT

Geodysseus is copyright (c) 2011 by Nicholas Shea.
    
    
CREDITS
-----------------------------------------------------------------------------
WildMagic3 library by David Eberly: www.geometrictools.com
-----------------------------------------------------------------------------
FLTK-1.1.7 (Fast Light Toolkit) by Bill Spitzak Michael Sweet and others:
www.fltk.org
-----------------------------------------------------------------------------
Flu_Tree_Browser widget by Jason Bryan.
-----------------------------------------------------------------------------
The country files were extracted from the free MaxMind database:
'WorldCitiesPop.txt' at www.maxmind.com.
Thanks to MaxMind for providing this database.
-----------------------------------------------------------------------------
Our Airports database:

The database files in the folder Data/OurAiports is in the public domain and
was downloaded from: http://www.ourairports.com

Thanks to David Megginson  for making this very
extensive database public domain.
-----------------------------------------------------------------------------
Global Airports - DAFIF ap (FGDC) / Global Airports - DAFIF (ISO)
http://www.pdc.org/geodata/world/airports_dafif.zip

Distribution Liability: Although NIMA makes no copyright claim under
Title 17 U.S.C., NIMA claims copyrights under other legal regimes.
NIMA hereby grants to each user of DAFIF a license to use and distribute the
product, and develop derivative works. NIMA requests that products developed
using DAFIF acknowledge the source of the data with the following statement:
"This product was developed using DAFIF, a product of the National Imagery
and Mapping Agency." When product developers and other customers acknowledge
DAFIF as the source of the data, please be aware that under the United States
Code, 10 U.S.C. 425, the names of the National Imagery and Mapping Agency or
the former Defense Mapping Agency, their respective initials, or seals cannot
be used to imply that a product is approved, endorsed, or authorized by the
Secretary of Defense. Fortunately, a simple disclaimer to the effect that,
"This product has not been endorsed or otherwise approved by the National
Imagery and Mapping Agency, or the United States Department of Defense
(10 U.S.C. 425)," is sufficient to resolve any ambiguity. Finally, NIMA
requires that product developers and manufacturers include warranty
disclaimers as follows: a. Under 10 U.S.C. 456, no civil action may be
brought against the United States on the basis of the content of a
navigational aid prepared or disseminated by either the former
Defense Mapping Agency (DMA) or the National Imagery and Mapping Agency
(NIMA). b. The DAFIF product is provided "as is," and no warranty, express
or implied, including, but not limited to the implied warranties of
merchantability and fitness for particular purpose or arising by statute
or otherwise in law or from a course of dealing or usage in trade,
is made by NIMA as to the accuracy and functioning of the product. c.
Neither NIMA nor its personnel will be liable for any claims, losses,
or damages arising from or connected with the use of this product.
The user= agrees to hold harmless the United States National Imagery
and Mapping Agency. The user's sole and exclusive remedy is to stop
using the DAFIF product.

Limitations of use: The product name -- DAFIF -- is a registered trademark
of the National Imagery and Mapping Agency, and may only be used to refer
to the source of the data. Although NIMA makes no copyright claim under
Title 17 U.S.C., NIMA claims copyrights under other legal regimes.
NIMA hereby grants to each user of DAFIF a license to use and distribute
the product, and develop derivative works. The distribution of DAFIF is
based on the International Civil Aviation Organization (ICAO)
Aeronautical Information Regulation and Control (AIRAC) cycle of every 28 days.
Use of this product outside of its specified 28 day window is not authorized
and could result in Air Traffic Control violations and international
airspace/procedural violations. Its inappropriate use could cause serious
concerns for Safety of Flight.
-----------------------------------------------------------------------------
The vector map for Geodysseus was traced over high resolution Blue Marble images
owned by NASA. Thanks to the Visible Earth team for providing these images.
Visible Earth URL: http:visibleearth.nasa.gov/
-----------------------------------------------------------------------------
And of course, thanks to Sourceforge for hosting this project.
-----------------------------------------------------------------------------


DISCLAIMER

Geodysseus is distributed in the hope that it will be interesting or possibly
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


LICENSE

The license I had in TsConfig.h was...

 =============================================================================
 GEODYSSEUS LICENSE AND CONDITIONS OF USE

 1. This software is provided 'as-is', without any express or implied warranty.
 In no event shall the author be held liable for any damages arising from the
 use of this software. Bug reports or fixes may be sent to the author, who may
 or may not act on them as desired.
 2. You may not include this software in a program or other software product
 without supplying the full source, or without informing the end-user that the
 full source is available for no extra charge.
 3. The origin of this software must not be misrepresented; you must not claim
 that you wrote the original software. If you use this software in a product,
 an acknowledgment in the product documentation is required. Just because this
 software is free does not mean I ascribe no value to it.
 4. Altered source versions must be plainly marked as such, and must not be
 misrepresented as being the original software. If you modify this software,
 you should include a notice giving the name of the person performing the
 modification, the date of modification, and the reason for such modification.
 5. This notice may not be removed or altered from any source distribution.
 =============================================================================

This program is dedicated to Brian Morgan, Susan Cooley and Dr. Hugh Jones and
is part of a summer project that is a lifetime too late.


IMPORTANT - Pending...

Please note, the only 'encryption' code used in Geodysseus is the zlib library
for compression. This is required by the third-party png library. Both of these
libraries are open source. I am not sure if compression algorithms count as
encryption by the US government. However, Sourceforge recommends that developers
apply for a license from: https:snapr.bis.doc.gov/snapr. Because I do not wish
to violate any US laws, I have applied for an 'export' license from this
institution, even though I live the UK. (Because Geodysseus is hosted by the US
Sourceforge server). I am currently awaiting a reply and futher instructions
from https:snapr.bis.doc.gov/snapr. I assume, (perhaps unwisely), from the
Flow Chart no. 2, "Classifying under an ECCN in Category 5, Part 2"...

   Q. Is the item publicly available encryption source code?
   A. Yes.
   -> Self Classify as 5D002.
   -> See License Exception TSU (740.13(e)) for notification requirement.