README for SaVi distribution
============================
# $Id: README,v 1.40 2006/07/18 22:09:06 lloydwood Exp $

This README supplied with the SaVi satellite visualization software
contains the following sections:

1. Introduction to SaVi
   - SaVi is described and places to obtain the latest SaVi are given.
2. Requirements for SaVi
   - SaVi's use of Tcl/Tk is described.
3. SaVi and Geomview
   - SaVi's optional use of Geomview for 3D rendering is outlined.
4. Installation instructions for SaVi
   - how to make SaVi correctly. You must read and follow this section.
5. Running the SaVi software
   - how to launch SaVi with or without Geomview. Read this section.
6. Version history of SaVi
   - a brief overview of major developments in SaVi.
7. Acknowledgements for SaVi
   - a list of contributors to the SaVi project.



1. INTRODUCTION TO SAVI
=======================

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.

A webpage user manual for SaVi is in the manual/ directory.

SaVi is originally 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: lloydwood@users.sourceforge.net

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

SaVi is not a polished or finished product. SaVi is not guaranteed to
be fit for any purpose. Bugs in the SaVi software are still being
discovered and addressed. Users of SaVi are responsible for verifying
for themselves that their simulations are sufficiently accurate to be
useful for their purposes.

Known bugs and possible future features of SaVi are discussed
in the textfile BUGS. Please report problems with your use of SaVi
to lloydwood@users.sourceforge.net.



2. REQUIREMENTS FOR SAVI
========================

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, 3.3.3, 3.4.4.

 - 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.
     If an existing installation of Tcl does not include header files,
     e.g. /usr/include/tcl.h, you may be able to add these by
     installing the tcl-devel package.

SaVi can optionally use:

- the zlib compression library, from http://www.gzip.org/zlib/
  - most recently tested with zlib 1.2.3. To build with zlib to
    compress dynamic texturemaps that are sent to Geomview, remove the 
    -DNO_ZLIB flag from src/Makefile.

- Geomview, discussed below. Geomview requires an X Window installation.


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

 - Intel x86 / Linux (Red Hat 6.x, 7.0, 7.2; Fedora Core 2; Mandrake 9.0,
	Debian)
 - Sun SPARC / Solaris (2.4 and later)
 - SGI / Irix5
 - Intel x86 / Cygwin (1.5.9-1 to .20-1)
 - Intel x86 / FreeBSD (6.0)



3. SAVI AND GEOMVIEW
====================

SaVi can optionally use Geomview for 3D rendering of Earth and satellites.
Geomview requires a unix-like operating system and an X Window display.

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/

SaVi was most recently tested with Geomview 1.8.1 and with a Geomview 1.8.2
release candidate snapshot. Geomview 1.6 or later is needed for texture mapping.
Texture mapping requires OpenGL, and is discussed further in the textfile
README-COVERAGE-TEXTUREMAPPING.

For texture mapping, SaVi can optionally use the zlib compression library to
compress texturemapping files that Geomview reads. This can be accomplished
by removing the -DNO_ZLIB flag from src/Makefile when compiling SaVi.


Recent Geomview snapshots, incorporating fixes for gcc and for Cygwin,
may be available alongside recent SaVi development snapshots from:
	http://www.ee.surrey.ac.uk/Personal/L.Wood/software/SaVi/src/unreleased/


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 content is now hosted at the University of Illinois at
Urbana-Champaign (uiuc).

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



4. INSTALLATION INSTRUCTIONS FOR SAVI
=====================================

For the remainder of this file, we shall refer to the directory
originally containing this README file, the root of the SaVi tree, as $SAVI.
That is, if you are a user and have unpacked SaVi in your home directory,
then $SAVI would be the topmost SaVi directory ~user/saviX.Y.Z
that contains this README file that you are reading.


1.) In $SAVI/src/Makefile_defs_ARCH (where ARCH is linux, debian, cygwin, sun,
    freebsd or irix) 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' in SaVi's topmost
    directory may be sufficient to compile the C files in src/ and index the
    Tcl files in tcl/.

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

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

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

2.) Return to the topmost SaVi directory $SAVI. Once in that directory,
    type e.g. 'make ARCH=linux' (or debian, or cygwin, or sun, or freebsd, or irix)
    in the topmost $SAVI directory. Typing just 'make' in the topmost directory 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_LIBRARY and TK_LIBRARY lines
    when linking dynamically.

    If running the savi script to launch SaVi generates Tcl or Tk errors,
    it is often because either the TCL_LIBRARY or TK_LIBRARY lines need to be
    corrected in that shell wrapper, or because make was not done using the
    top-level Makefile in the $SAVI directory. SaVi needs $SAVI/tcl/tclIndex
    to run. That tcl/tclIndex file must be generated by the tcl/Makefile that,
    like all other subdirectory Makefiles, is called by the top-level master
    Makefile in the same directory as this README file.



5. RUNNING THE SAVI SOFTWARE
============================

As in the previous section, we refer to the directory containing this
README 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 copy this script from the SaVi installation and run it elsewhere,
# 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.9/savi")

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



6. VERSION HISTORY OF SAVI
==========================

1.3    Includes all work done for a workshop on satellite applications and
       constellations given as a guest lecturer at the International Space
       University Summer Session. Students used SaVi in class exercises,
       July 2006.

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.



7. ACKNOWLEDGEMENTS FOR SAVI
============================

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.
Claus-Justus Heine contributed assistance with pipes and 64-bit machines.

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