README for SaVi - SATELLITE CONSTELLATION SIMULATION AND VISUALIZATION ====================================================================== $Id: README 206 2023-04-29 02:18:02Z lloydwood $ 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 - Optional packages enhancing SaVi are also described. 3. SaVi and Geomview - SaVi's optional use of Geomview for 3D rendering is outlined. 4. Installation instructions for SaVi - how to compile SaVi from source. Read and follow this section. 5. Running the SaVi software - how to launch SaVi, with or without Geomview. Read this section. 6. Command-line switches for SaVi - things that can be selected when launching SaVi. 7. Contributing to SaVi - notes for programmers. 8. Version history of SaVi - a brief overview of major developments in SaVi. 9. 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 publically available. We require that use of any images produced by this software credits SaVi and The Geometry Center. A webpage user manual for SaVi is in the manual/ directory. Lloyd Wood, the current SaVi maintainer, welcomes suggestions, patches and improvements to SaVi. Lloyd can be contacted at: lloydwood@users.sourceforge.net See the SaVi webpages: http://savi.sourceforge.net/ http://lloydwood.users.sourceforge.net/Personal/L.Wood/software/SaVi/ http://www.geom.uiuc.edu/projects/visualization/savi.html Support for SaVi is provided via the savi-users mailing list: https://lists.sourceforge.net/lists/listinfo/savi-users SaVi is not a completely 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 the savi-users mailing list. SaVi is originally Copyright (c) 1995-1997 by The Geometry Center. SaVi is also Copyright (c) 2001-2023 by Lloyd Wood. See the textfile COPYRIGHT for full details. 2. REQUIREMENTS FOR SAVI ======================== SaVi requires: - an ANSI C compiler, e.g. gcc from http://gcc.gnu.org/ - most recently tested and built with gcc 11.2, 8.3, 7.5 and 6.4. previously tested with gcc 5.4, 4.9 back to 4.0, 3.4 to 3.2, and 2.95. or clang from http://clang.llvm.org/ - tested and builds with Apple LLVM 9.0.0 / clang-900. previously tested with clang 3.1. - Tcl and Tk, from http://www.tcl.tk/ - most recently tested with Tcl/Tk 8.6 releases and ActiveTcl 8.6.4. Use of the Http package for loading TLEs from the web demands a minimum of Tcl/Tk 8.0. Use of the 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 should be able to add these by installing the tk-devel and tcl-devel packages (Red Hat, Fedora) or the tcl-dev and tk-dev packages (Debian, Ubuntu). The savi wrapper script in this directory, and the Makefile_defs_ files in the src/ directory, assume that Tcl/Tk 8.5 are available, and will need to be edited if other versions are used. On RedHat/Fedora/CentOS etc. try: sudo yum install tk-devel On Ubuntu/Debian etc. try: sudo apt-get install tk-dev SaVi can optionally use, and is far more useful with, these recommended packages: - Geomview, discussed below, for three-dimensional animations. - most recently tested with Geomview 1.9.5. On Ubuntu/Debian etc. try: sudo apt-get install geomview - gifsicle, from http://lcdf.org/gifsicle/ for saving animations of satellite coverage. - most recently tested with LCDF Gifsicle 1.92. On Ubuntu/Debian etc. try: sudo apt-get install gifsicle - lynx, from https://lynx.browser.org/ for handling https or other downloads of TLEs (elsets) - most recently tested with lynx 2.9.0 On Ubuntu/Debian etc. try: sudo apt-get install lynx SaVi may also optionally use, but does not in any way require: - the jpegtopnm utility, from the netpbm package available at http://netpbm.sourceforge.net/ for Geomview to uncompress and display the detailed Earth map that is included with SaVi. On RedHat/Fedora/CentOS etc. try: sudo yum install netpbm On Ubuntu/Debian etc. try: sudo apt-get install netpbm - the zlib compression library, from http://www.zlib.net/ for compressing texturemap images sent to Geomview. - most recently tested with zlib 1.2.11. zlib is most useful with Geomview. To build with zlib to compress dynamic texturemaps that are sent to Geomview, edit src/Makefile to remove the -DNO_ZLIB flag. On RedHat/Fedora/CentOS etc. try: sudo yum install zlib-devel On Ubuntu/Debian etc. try: sudo apt-get install zlib1g-dev SaVi has been successfully compiled and run on the following architectures and unix-like operating systems: - Intel x86 and PowerPC / Macintosh OS X (10.12.6, 10.11.6, 10.9.5, 10.7.2, 10.6.8, 10.5.8, 10.4.11) Mac users - you must read the BUGS file! A section there discusses Mac-specific problems and workarounds for those problems. - Intel x86 / Windows running Cygwin (most recently tested with 3.3.5, previously Cygwin 3.0.7, 2.9.0, 1.7.10 to .29 and 1.5.9-1 to .25-11) Cygwin users - Insight Tcl/Tk 8.4 was replaced by a more conventional unix port of 8.5 in October 2011. If you are still using Insight and haven't updated, build with: make ARCH=cygwin84 instead of cygwin. - Intel x86 / Windows 10 Anniversary Update Install Windows Subsystem for Linux from the Microsoft Store, then install Ubuntu. For X display you can install and run the Xming web server from http://xming.sf.net/ and then launch bash and type: sudo apt-get install savi sudo apt-get install geomview set DISPLAY=:0 geomview -run savi - Intel x86 / Linux (Ubuntu 20 back to 8; CentOS 6.5, Fedora 12; Red Hat 6.x, 7.x and Enterprise 3.0; Mandrake 9.0; Mandriva One 2010) - Intel x86 / FreeBSD (6.0, 8.1) - Sun SPARC / Solaris (2.4 and later, 10) - SGI / Irix5 SaVi is 64-bit clean. 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 requires Geomview. Geomview is available from: http://www.geomview.org/ http://geomview.sourceforge.net/ On Ubuntu/Debian etc., where these packages are maintained: sudo apt-get install geomview sudo apt-get install savi geomview -run savi will save you the effort of compiling Geomview or SaVi. SaVi was most recently tested with Geomview 1.9.5. SaVi supports 3D texturemapping of the Earth sphere to Geomview, if OpenGL is supported. If this is not viewable, due to graphics drivers or other problems, try turning off OpenGL use with: geomview -noopengl -run savi OpenGL and texturemapping are discussed in further detail in README-COVERAGE-TEXTUREMAPPING, also accessible from SaVi's Help menu. Discussion of maintaining and building Geomview on various platforms can be found in the geomview-users mailing list archives: http://lists.sourceforge.net/lists/listinfo/geomview-users Instructions for building Geomview under Microsoft Windows with Cygwin are available from: http://savi.sourceforge.net/install/ 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). Contracted work with Geomview can be undertaken by Geometry Technologies: http://www.geomtech.com/ 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 now reading. This is a shorthand; $SAVI is determined by the $SAVI/savi script that launches SaVi. 1.) In $SAVI/src/Makefile_defs_ARCH (where ARCH is linux, cygwin, macosx, sun, freebsd, irix or ubuntu) 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 definitions 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: - ensure that the variables are set to give the locations and correct versions of the Tcl/Tk libraries and header include files. - ensure that the CC variable is set to an available 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 cygwin, or macosx, or sun, or freebsd, or irix, or ubuntu) 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. 4.) SaVi allows binaries for multiple architectures to co-exist on a shared filesystem, by running the appropriately-named binary: bin/SaVi-$ARCH.bin The most recently compiled executable is also available as: bin/SaVi To save disk space on filesystems used by only one architecture and avoid messages saying which binary copy was selected to be run, you can rm bin/SaVi-*.bin, leaving the single bin/SaVi executable. This has the advantage of displaying just 'SaVi' as the process name. This is very useful for Mac OS X, where that name is shown in the menubar. 5. RUNNING THE SAVI SOFTWARE ============================ As in the previous section, we refer to the directory containing this README file as $SAVI. Always launch SaVi using the savi script in this directory. Do not run the binary executable directly. 1.) To run SaVi standalone, without needing Geomview, in the $SAVI directory type: ./savi Or from any other directory, $SAVI/savi where $SAVI is the path of the savi directory. 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, where it will have appeared. Or invoke directly: geomview -run ./savi [flags]