README for SaVi distribution
============================
# $Id: README,v 1.17 2004/03/29 00:43:29 lloydwood Exp $

SaVi is software written to facilitate the visualization and analysis
of satellite constellations.  This software is freely and publicly
available.  We request that any images produced by the software
credit SaVi and The Geometry Center.

Copyright (c) 1995-1997 by The Geometry Center.
See the textfile COPYRIGHT for full details.

The original authors could be contacted at: savi@geom.umn.edu
The current maintainer can be reached at: L.Wood@ee.surrey.ac.uk

See the SaVi webpages:

http://savi.sourceforge.net/
http://www.ee.surrey.ac.uk/Personal/L.Wood/software/SaVi
http://www.geom.uiuc.edu/locate/SaVi

Known bugs and possible future features of SaVi are discussed
in the textfile BUGS.



REQUIREMENTS
============

SaVi requires:

 - an ANSI C compiler, e.g. gcc from http://www.gnu.org/software/gcc/
   - tested and builds with egc variants: gcc 2.95, 3.2 and 3.3.1.

 - Tcl and Tk, from http://www.tcl.tk/
   - most recently tested with Tcl/Tk 8.4; use of Tk color picker and
     load/save file dialogs demands a minimum of Tcl/Tk 7.6/4.2.
     Tcl/Tk 8.x gives increased performance, and is recommended.


SaVi has been successfully compiled and run on the following machines
and operating systems:

 - Intel x86 / Linux (Red Hat 6.x, 7.0, 7.2; Mandrake 9.0)
 - Sun SPARC / Solaris (2.4 and later)
 - SGI / Irix5
 - Intel x86 / Cygwin (1.5.7-1. You may also need to edit tcl/Makefile
   for use of a custom tclsh executable, and compiling Tcl/Tk
   for use of SaVi with Geomview together in an X display window is
   recommended. Use of the fisheye view currently requires SaVi's
   windows to live in an X display.)

SaVi can optionally use Geomview for 3D rendering of Earth and satellites.

SaVi can be run either as a stand-alone program, or as an "external module"
for the Geomview program.  The latter mode enables three-dimensional
visualization of the satellite constellations, but also needs
the Geomview program.

Geomview is available from:
	http://www.geomview.org/
	http://geomview.sourceforge.net/

Geomview 1.6 or later is recommended for texture mapping.
SaVi was most recently tested with Geomview 1.8.1.

Although SaVi compiles fine with gcc 3.2 and later, Geomview 1.8.1
requires a patch to its source in order to build on systems using gcc 3.2,
such as Red Hat 8.0 and later. That patch is available from:
	http://sourceforge.net/tracker/?group_id=9736&atid=30973

Further discussion of building Geomview on various platforms and with various
compilers can be found in the geomview-users mailing list archives:
	http://lists.sourceforge.net/lists/listinfo/geomview-users


Geomview, like SaVi, was originally available from the Geometry Center:
	http://www.geom.uiuc.edu/software/download/geomview.html

The Geometry Center was at the University of Minnesota (umn), and
its webserver is now hosted at the University of Illinois at
Urbana-Champaign (uiuc).

Geomview is now maintained by Geometry Technologies;
        http://www.geomtech.net/



INSTALLATION INSTRUCTIONS FOR SAVI
==================================


For the remainder of this file, we shall refer to the directory
originally containing this file, the root of the SaVi tree, as $SAVI.


1.) In $SAVI/src/Makefile_defs.ARCH, (ARCH is linux, sun, irix, or cygwin)
    you may need to edit some variables to suit your system.  If your system
    is current with recent versions of Tcl and Tk installed, and everything
    is in its usual place, the generic defs file called "Makefile_defs." may
    work perfectly, and typing 'make' will be sufficient.

    If not, choose the file most suitable for your system and:

	- edit the variables that give the locations of the
		Tcl/Tk libraries and include files.

	- edit the variables that point to the X11 libraries and
		include files.

	- set the CC variable to an ANSI C compiler, e.g. gcc

2.) Type e.g. "make ARCH=linux" (or sun, or irix, or cygwin) in the topmost
    $SAVI directory. Typing just 'make' will use the default
    Makefile_defs. file.

3.) You may also need to edit the locations of the Tcl and
    Tk libraries in $SAVI/savi at the TCL_LIB and TK_LIB lines
    when linking dynamically.



RUNNING THE SOFTWARE
====================

We shall refer to the directory containing this file as $SAVI.

1.) To run SaVi standalone, without needing Geomview,
    in the $SAVI directory type:

	./savi

    Or from any other directory,

	$SAVI/savi

    To load in a satellites tcl scriptfile directly, type:

	./savi filename

    SaVi supports a number of command-line switches, many related to
    use with Geomview. To see these, type:

	./savi -help

2.) To run SaVi as a module within Geomview, for 3D rendering,
    when in the $SAVI directory start up Geomview:

	geomview

    and then select "SaVi" from Geomview's scrollable list of external
    modules.  Or invoke directly:

	geomview -run savi [flags] <script filename>

    Or from any directory where you can start Geomview, try

	geomview -run savi [flags] <script filename>

    You might invoke a saved one-line script, to pass parameters through
    to SaVi:

	geomview -run savi [always-on flags] $*


3.) To make SaVi accessible to other users, you can copy the "savi"
    script in $SAVI to some directory in other users' search
    paths such as /usr/local/bin, so they needn't add SaVi's own
    directory to their own path.  If you do, edit the "savi" script,
    inserting the full path name of $SAVI as indicated in
    the script itself:

# If you move this script away from the SaVi installation,
# then you should uncomment the following line:
# SAVI=/usr/local/savi
# and replace /usr/local/savi with the location of
# your SaVi installation.

    You can also make SaVi accessible from Geomview's scrollable list of
    external modules.  Assuming Geomview is installed in
    /usr/local/Geomview, say:

   	cd /usr/local/Geomview/modules/sgi

    Create a file here called ".geomview-savi" containing e.g.:

        (emodule-define  "SaVi"  "/usr/local/savi1.2.3/savi")

    where the right-hand side is the absolute path name for the savi
    script.



VERSION HISTORY
===============

1.2.x  These developments bring together a variety of contributions
       in a single package, 2001 and onwards.

1.1    Diverse versions with various modifications,
       not widely released, 1999.

1.0    First public release of SaVi binaries and source code, 1997.



ACKNOWLEDGEMENTS
================

Martin Lo, Polly Estabrook and David Bell at
NASA's Jet Propulsion Lab inspired the SaVi project.

Patrick Worfolk and Robert Thurman created the SaVi project
while at the Geometry Center, with support from the Geometry Center
technical staff, especially Stuart Levy, Lori Thomson and Nicolas Vera.

Gregory LaCoste contributed coverage interval decay and other code to
the SaVi project.

Matthias Foehl contributed assistance with file dialogs and Cygwin.

Lloyd Wood has contributed simulations of commercial constellations and
other code to the SaVi project, and now maintains SaVi at SourceForge.
