
1. What is it ?
----------------
    gps3d is a set of utilities that lets you manipulate your GPS from
    your Linux/Win32 box, and visualize the output in 3D.

    If you do not own a GPS device, you can still use gps3d to play
    interactively with a 3D texture mapped model of earth.

    At the moment, gps3d only supports NMEA capable devices.

2. More precisely ?
-------------------

    gpsd:
    -----
	gpsd is a daemon that will monitor a serial port for messages sent by
	a GPS device and broadcast it on a TCP port (actually, it broadcasts
	anything that comes in on the serial port, so you could use gpsd to
	do an internet broadcast the output of any device: an atomic clock,
	an acquisition device, etc...).

	This allows you to have multiple processes listening to the same GPS at
	the same time. Also, a machine with a dedicated connection to the internet
	and a GPS unit attached to it can use this to permanently broadcast its
	position to anyone who wants to know.

	Finally, gpsd can also relay client requests to the GPS unit (it
	will write NMEA sentences received on a TCP socket to the GPS).
	Warning: there is no arbitration mechanism for write access to the GPS,
	so if two clients send requests at the same time, you're on your own:
	the only guarantee of atomicity is at the sentence level, that is
	gpsd will not mix two sentences.

    viz	:
    -----
	viz is an OpenGL utility that will connect to a gpsd daemon and
	display a 3D, texture-mapped earth with all kinds of GPS related stuff
	it reads off the daemon:
	    - current fix
	    - current track
	    - waypoints
	    - satellite trajectories
	viz can also download road maps from mapblast and patch them onto
	the earth model.

    gps	:
    -----
	gps is a simple example client for the gpsd daemon.
	It connects to a gpsd server, reads and parses the NMEA sentences
	and prints them in human readable form. This is not intended to
	be useful for anything other than debugging.
				  
3. What does it run on and what does it need
--------------------------------------------
    So far, it's been tested on the following systems:

	    Win95
	    Win98
	    Winnt4.0 SP5
	    Win2k
	    Linux RedHat 6.1 i386 (glibc 2.1)
	    Linux RedHat 6.0 alpha (glibc 2.1)

    On Linux, it needs to link against X11 and some kind of OpenGL
    On Win32, it needs to link against Winsock 2.2, OpenGL, and msvcrt.

    Chances are good it will work on other Unixe's

4. How do I install it ?
------------------------
    On Linux, extract the tarball and type make
    On Win32, if you have Visual C++ 6.0, there is a .dsw in the win32 sub-directory.
    Alternatively just grab the latest binaries from http://www.mgix.com/gps3d
    There is no install. You run it from where it's at.

5.  How do I use viz ?
----------------------
    Just launch ./viz.
    By default it will try to connect to a gpsd server on the localhost.
    If it can't connect, it will still let you play with the texture mapped earth,
    but won't display anything GPS related.

    If you want to, you can specifiy the host and port of the gpsd viz will
    try to connect to as follows:

	./viz gps.southpole.aq 1234

    When viz is up and running, press H, it will display a quick help.

    I've included an example Track file.
    It's a very small track, by earth proportions.
    Once it's loaded, you'll find it as a tiny speck, next to Los Angeles.
    (It's a sailing trip, hence the zigzags when tacking upwind)

    If you want to capture RAW NMEA gps output to build your own track files,
    you can use something along the lines of:

	./gps | grep -i '$GP'

6. How do I use gpsd ?
----------------------
    By default, gpsd connects to /dev/ttyS0 (COM1) at 19200 bauds, and
    broadcasts on TCP port 2222.

    These defaults can now be changed from the command line as follows:

	./gpsd -serial /dev/ttyS1 -speed 4800 -port 1234

    To test that gpsd can hear your GPS device, use the example client gps:
    it will dump everything it can read from gpsd.

7. How should I configure my gps ?
----------------------------------
    1. Connect it to a serial port. Preferably /dev/ttyS0 or COM1 since
       it is the default port gpsd connects to

    2. Configure your GPS to output NMEA messages on the serial connection,
       preferably at 19200 bauds (again, gpsd's default).

    3. If it doesn't work, read item b) of the Disclaimer below.

8. About maps of the earth
--------------------------
	1. If you want to use your own map of the earth.
	    - Get your map of of earth into the gimp
	    - Flip it (turn it upside down)
	    - Resize it to NxN, where N is a power of two.
	    - Save the result in PNM binary mode in map.pnm

	2. How big can my map be ?
	    The bigger you map is, the more detail you will get for the earth
	    surface, but the more Texture RAM will be eaten up on your OpenGL
	    accelerator. Typically, a 2048x2048 map requires 32Mb onboard RAM,
	    and a 1kx1k map will fit in 16Mb.

	    However, you should be able to feed viz real large map, because
	    it tries to resize the map down until it fits in texture RAM. But
	    a larger map will not buy any more quality than you OpenGL board
	    RAM can handle.

9. How come the satellites trajectories aren't ellipses ?
---------------------------------------------------------
    Actual GPS satellites orbits are indeed ellipses but in an absolute
    frame of reference, i.e whose axes are not moving wrt to, say, some distant stars.
    But, GPS3D displays stuff in an earthbound frame of reference (i.e. the
    frame rotates along with the planet). In that frame of reference,
    the satellite's trajectories are not *at all* ellipses. They look like
    a horse's saddle. See http://www.mgix.com/gps3d/orbits.jpg to see a plot.

10.  Disclaimer
---------------
    a) !!! DO NOT USE THIS SET OF TOOLS FOR ANY REAL-WORLD NAVIGATION !!!
       These tools are toys, and the various math formulas used throughout
       the software are based on a spherical earth model (which is *way* wrong),
       and are more than likely to contain errors.
	
    b) This set of utilities was developped and tested with a Magellan GPS 315,
       and has never been tested with any other GPS devices out there.

       If you own a garmin, there's three things you can do:
		- Get it to spit NMEA compatible stuff.
		- Change the code to handle it and send me the mods
		- Send me the garmin and I'll write the code to handle it
	

11. Who wrote it
----------------
    Emmanuel Mogenet <mgix@mgix.com>
    Feel free to send comments, bug, suggestions, etc...

12. Where can I find the latest
-------------------------------
    http://www.mgix.com/gps3d

13.  Copyright
---------------

    a) This code is 100% free.
       Not half-baked free as in the GPL.
       Free as in free: do whatever you want with it.

    b) There is no warranty whatsoever:

			    NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

