README

                                 EarthView
                               Version 0.2.1

   * Introduction
   * Features
   * System Requirements
   * Installation
   * Embedding EarthView into an HTML page
   * Known Bugs
   * Coverage
   * Copyright

Introduction

     EarthView is a Java(TM) program that draws an image of the earth from
     a freely selectable viewpoint.
     
Features

        * Draws an image of the earth using vector data.
        * Displays continents with hidden lines or filled areas.
        * Draws a map grid.
        * Can be used as an applet (embedded into a html page) or as a
          stand-alone application.
        * Images can be exported to EPS 88 files for manual refinement with
          vector drawing tools like Adobe Illustrator or Macromedia Freehand.
          (application mode only).
        * Images can be printed (application mode only).
     
System requirements

      This program was built with Java 2 (formerly code named JDK 1.2) in mind.
      This version of EarthView has been downgraded to work with any Java
      Runtime Environment that does comply to the JRE 1.1 specification.
      It needs only JRE 1.0.2 features of the AWT package.
	
Installation

    * On Windows 95/98/NT
        1) Install the Java 2 Runtime Environment Version 1.2.2 or above
           Download from http://www.javasoft.com/products/jdk/1.2/jre/index.html

        2) Download the "Ready to use for Windows" edition of EarthView.
           The file is called "earthview0.2.1win.zip"
           Download from http://www.randelshofer.ch/

        3) Unzip the file onto your C: drive using your favourite Zip tool.
           If everything goes well, this should create a directory called "EarthView"
           on your C: drive. It should look like this:

           c:\EarthView\readme.txt
                        changes.txt
                        earthview.lnk
                        lib\earthview.jar

        4) You can start EarthView in one of the following ways:

              * Double click on the file c:\earthview\lib\earthview.jar

              * Double click on the file c:\earthview\earthview.lnk
                (If you like, you can put earthview.lnk into your Start-menu).

              * Enter the following text onto the command line:

                java -jar c:\earthview\lib\earthview.jar

   * On Macintosh
        1) Install the Macintosh Runtime for Java (MRJ) Version 2.1.4 or above
           You can download it from http://developer.apple.com/java/index.html
           
        2) Download the "Ready to use for Macintosh" edition of EarthView.
           The file is called "earthview0.2.1mac.zip"
           You can download it from http://www.randelshofer.ch/download/index.html

        3) Decompress the file.
           This should create a folder with the following contents:

           > EarthView 0.2.1
               readme.txt
               changes.txt
               EarthView
           >   lib
                  earthview.jar

        4) Double click on the application icon "EarthView" to start EarthView.


   * Platform Independent Edition
           This Edition also includes the source code and documentation.

        1) Install Java 1.2 or Java 1.1 on your platform.
           The list of available platform ports can be found at
           http://www.javasoft.com/products/OV_jdkProduct.html
           http://www.javasoft.com/cgi-bin/java-ports.cgi

        2) Download the "Platform Independent" edition of EarthView.
           The file is called "earthview0.2.1.zip"
           Download from http://www.randelshofer.ch/

        3) Unzip the file using your favorite Zip tool.
           This should create a directory called "earthview".
           It should look like this:

           /earthview/readme.txt
                      changes.txt
                      lib/earthview.jar
                      src/...

        4) Enter the following text onto the command line to start EarthView:

           Java 1.2:
                java -jar /earthview/bin/earthview.jar

           Java 1.1:
                java -classpath $CLASSPATH;/earthview/bin/earthview.jar ch.werner_randelshofer.app.EarthView

Embedding EarthView into an HTML page

          To use EarthView as an Applet create a HTML file with the
          following contents:
          
          <html>
 	         <head>
                <title>EarthView</title>
             </head>
             <body>
                <applet
                   code=ch.werner_randelshofer.app.EarthView.class
                   codebase=earthview.jar
                   width=500
                   height=400
                   >
                </applet>
             </body>
          </html>


Known Bugs

      Fill mode
        * Since EPS 88 only supports polygons with up to 1000 edges I had to
          split up the borderlines of America and of Europa-Africa-Asia into
          smaller pieces. This is actually rather a feature than a bug. But
          I am not happy about that.
       
      Wireframe mode
        * The contours of America and Europa-Africa-Asia do have some
          unjoint points.

Coverage

     The story of EarthView began in September 1984 with an issue of the
     magacine "HC - Mein Home Computer". It featured the source code of a
     Basic program called "Globus". This program was able to plot magnificient
     hidden-line outputs of the earth from freely selectable viewpoints.
     At that time I was a young whippersnapper spending too much of my spare
     time with playing, programming and hacking on my hard earned Commodore 128
     computer. The usual thing I did with interesting source code was porting
     it to my machine - no matter of how many pages I hat to type out, no
     matter of how much time I needed to figure out differences between
     Basic dialects and whether I did or did not understand how a piece of
     code worked.
     This is what happened to Globus: First I ported it to my Commodore 128,
     then I ported it to the PC of my father, and later I ported it to the
     Amiga computer of my brother...
     Well, the day came when I wanted to figure out how Globus worked. So I
     started to read many clever books and created my own version in the
     language Oberon 2. And that should have been the end of the story.
     But some time later I saw the program XEarth on a Macintosh Computer.
     This program did the same like Globus - and a lot more - but used much
     better detailed data than Globus did. I could not stand the temptation,
     I had to have this data in my own program. Since I did not have access
     to the source code of XEarth at the time, I ripped the map data out of the
     compiled program.
     One or two years later my brother bought a Macintosh - and guess what I
     did - I wrote a port for AppleScript. This program created EPS 88 output
     files that could be loaded into drawing tools like Adobe Freehand and
     Macromedia Illustrator. There were some drawbacks though. Since Globus
     was designed for plotter output, my AppleScript clone could only create
     hidden-line drawings. This is excellent for plotters and for screens, but
     is a nightmare if you want to use the output of the program to create a
     shaded picture of the earth in a drawing program. I had to write something
     better, something that could create filled areas of continents, ilands,
     and lakes. So I started to fix this and some other problems with a
     programming language that I had aquired recently: Java!
     That's how EarthView was born. It was my first Java program I have done.
     By consequence I called the program "Hello World" (usually the first thing
     everyone does when he tries out a new programming language, is to write
     a small programm that prints the text "Hello World" onto the screen).
     Since that name was misleading I do call the program now "EarthView".

Copyright

     EarthView Copyright (C) 1999 Werner Randelshofer,
     Staldenmattweg 2, CH-6405 Immensee, Switzerland
     All rights reserved
 	 http://www.randelshofer.ch/
    
         Permission to use this preliminary release of EarthView for
         evaluation purposes is hereby granted without fee provided that
         the complete copyright notice and this permission notice appear
         in all copies and in supporting documentation.

     Parts of the source code were originally based on the program Globus.

         Globus
         for PC 1500 or PC2 from Tandy
         created by the Casio-Sharp-Software-Club Berlin
         published in HC Ð Mein Home Computer, Nb. 9 - September 1984

     The map data was derived from xearth (for Unix) from Kirk Lauritz Johnson.
      
         XEarth (Unix) Copyright (C) 1989,1990,1993,1994,1995 Kirk Lauritz Johnson

         Parts of the source code from XEarth (Unix) are
             Copyright (C) 1989, 1990, 1991 by Jim Frost
             Copyright (C) 1992 by Jamie Zawinski jwz@lucid.com

         Permission to use, copy, modify and freely distribute xearth for
         non-commercial and not-for-profit purposes is hereby granted
         without fee, provided that both the above copyright notice and
         this permission notice appear in all copies and in supporting
         documentation.

         The map information used in xearth was derived from the "CIA World
         Data Bank II map database", as taken from some "cbd" files that
         were apparently originally generated by Brian Reid at DEC WRL.

     Parts of the program (as marked) are derived from the Java 2D packages of
     Java 2 (formerly code named JDK 1.2) from Javasoft.
     This code was integrated into Hello World to make it work on JRE 1.1
     compliant virtual machines. It will be removed in a future version of EarthView.

         Java Copyright (C) 1996-1998 by Sun Microsystems, Inc.,
         901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
         All rights reserved
 	     http://www.javasoft.com/