BUGS recognized in SaVi
=======================
$Id: BUGS,v 1.252 2017/06/10 07:35:57 lloydwood Exp $

This list of BUGS describes caveats and problems with
use of the SaVi satellite visualization software.

This document contains the following sections:

1. Caveats in use of SaVi. Be aware of these.

2. Platform-specific issues.
   a. Mac OS X
       i. Mac compilation hints
          -- for SaVi
          -- for Geomview
       ii. 10.5 (Leopard)-specific issues
          -- for SaVi
          -- for Geomview
       iii. Other minor Mac-specific issues
          -- for SaVi
          -- for Geomview
   b. Cygwin on Microsoft Windows
          -- for SaVi
          -- for Geomview

3. A detailed SaVi wishlist. Notes on issues in these SaVi releases.
   a. Coding and build issues
   b. Scalability
   c. Scriptability
   d. User interface
   e. Coverage view improvements
   f. Fisheye view improvements
   g. Geomview interaction
   h. Dynamic texturemapping with Geomview
   i. Various
   j. Interaction with other 3D renderers
   k. Interaction with the network simulator ns
   l. Desirable constellations to simulate

4. Remaining integration work from unreleased SaVi 1.1.

5. Remaining items from the original SaVi 1.0 wishlist.



1. CAVEATS IN USE OF SAVI
=========================

Changing default simulation parameters (central body radius,
gravity, etc.) can cause unexpected behaviour; scripts generally
describe satellites in circular orbits via an altitude above the
body's surface. Use at own risk. If simulating a different planet
to Earth, we should force the -orbit-model J0 flag to avoid
simulating Earth's oblateness and environment. J0/J2 should be
selectable in the params dialog. Any changes should reset time
to zero - with a warning.

Two-line-element (TLE or 'elset') reading and constellation code
in tcl/constellations.tcl still needs considerable work. Reading
.tle files is experimental. This is not guaranteed for multiple
satellites of different epochs, so you can't really just expect to
download a .tle file, load it in and go.
Improving this and introducing clock time would make SaVi far more
practical.
(Sidereal time and the Earth's motion around the sun is not
simulated; noted by Tom Tessier.)

Selection: selected satellite is not visible as selected in Geomview
until a marker type is first selected or satellite orbital elements
are edited. Operations on multiple satellites (e.g. Cut) only work
on the last satellite selected.

Sunlight is approximated by having the sun orbit the Earth as a
distant satellite with the appropriate year-long period. This
should not be done as a J2 calculation, but should at least be J0.
Geomview's lighting rendering needs to be fixed to match this
coverage footprint.



2. PLATFORM-SPECIFIC ISSUES
===========================

a. MAC OS X

i. Mac compilation hints

-- for SaVi

SaVi and Geomview need Xcode (included in Developer Tools with the
Mac OS X system installer copy, or downloadable from Apple) to provide
the tools that can compile these and other programs.

As of Mac OS X 10.7, Xcode is now an app available from the Mac App
Store. As well as downloading and installing the Xcode app, it may be
necessary to explicitly enable command-line tools so that e.g. gcc
is available. The command line tools must be selected in:
Xcode > Preferences > Downloads > Components > Command Line Tools

Simply typing 'make' in a Terminal window may generate a dialog to
install the app and necessary command-line tools. Alternatively,
the command-line tools can be installed by typing:
    xcode-select --install

Although recent releases of Mac OS X include Tcl/Tk headers, they do
not include the X11 headers that Tk needs to compile. One way to
get these headers is to install the XQuartz package from
http://www.xquartz.org/
The XQuartz copies of X11 headers are looked for during compilation.

The Tcl/Tk libraries shipped with Mac OS X releases have some
user-interface problems and are prone to crashing. It is preferable
to install a later ActiveTcl release from
    http://www.activestate.com/activetcl
and then choose to build with that instead; to do so, uncomment the
second, commented, TCL_LIBS = line in src/Makefile_defs_macosx
before compiling savi by typing
    make ARCH=macosx

Mac Tcl issues fixed in ActiveTcl include:
- Mac OS X 10.5 Leopard menu problems
- accelerator key crashes
- coverage panel angle slider crashing Tcl due to a busy event loop
  when texturemapping, cone and footprint drawing are on.

-- for Geomview

On Mac OS X 10.8 or later, you will need to install XQuartz from
http://www.xquartz.org/ to provide an X11 environment.

To build Geomview on Mac OS X, you must first install a Motif clone
such as Lesstif (available via www.geomview.org's Downloads section).
In Lesstif's directory you will need to
    configure
    make
    sudo make install
and okay the sudo with a password to place Motif files where Geomview
expects to find them.

Geomview works well with OpenGL, but the OpenGL header files needed
are not included in Xcode by default. They were an extra optional
package provided with the Mac OS X system installer. Building Geomview
with
    ./configure --without-opengl
    make
is a fast way to get started, but the OpenGL rendering is recommended
for coverage texturemapping. To build Geomview with OpenGL once
these optional header files are installed:
    ./configure --with-opengl=/usr/X11R6
    make

and then optionally to make Geomview available from the command line
everywhere:
    sudo make install


ii. 10.5 (Leopard)-specific issues

-- for SaVi

The Tk 8.4.7 supplied with Mac OS X 10.5 (Leopard) has problems
displaying SaVi's menubar.

To work around this, menu buttons can be put in each SaVi window with:
    savi -redrawn-menus
This is not required on Mac OS X 10.6 (Snow Leopard) or 10.4 (Tiger),
where the Mac menubar can be used correctly.

The ./savi launch script attempts to detect 10.5, and adds the
-redrawn-menus flag to make SaVi usable for Leopard users.
This avoids having to add the parameter at the command line each
time SaVi is launched.

Installing ActiveTcl, uncommenting the TCL_LIBS line before compiling,
as described above, and removing the -redrawn-menus flag from the
./savi launch script is the preferred way to work around the user
interface problems of the Tk supplied with 10.5.

-- for Geomview

If doing make of Geomview fails to link at end with a
'cycle in dylib re-exports with /usr/X11/lib/libGL.dylib'
error, use the following single-line, no-breaks command:
export LDFLAGS="-Wl,-dylib_file,/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib:,/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib"
then repeat the previous instructions. This problem is caused by a
linking bug in Leopard.


iii. Other minor Mac-specific issues

-- for SaVi

- Menu shortcuts are disabled on the Mac unless -redrawn-menus is
  used. This is to prevent a freeze on using a keypress to open
  a window (seen in 10.6 with Tk 8.5.7). 10.7 is unaffected,
  and shortcuts can be enabled for ActiveTcl by editing disable_mac
  in tcl/utils.tcl.
- On compilation, two binaries are produced: bin/SaVi-macosx.bin and
  bin/SaVi. You can rm bin/SaVi-macosx.bin to get just 'SaVi' in the
  menubar as the application name.
- Under the Tcl/Tk supplied with 10.5, coverage colour buttons are
  only fully coloured when another application is frontmost.
- Under the Tcl/Tk supplied with 10.6, menu highlight colours are
  incorrect; highlighted text remains black.

-- for Geomview

- With X11 rendering, Geomview does not appear to be able to control
  its background colour, which is always grey. OpenGL rendering is
  fine.


b. CYGWIN ON MICROSOFT WINDOWS

32-bit Cygwin and the newer 64-bit Cygwin can coexist on a Windows PC.
32-bit Cygwin has better Geomview interaction, and so is preferable for SaVi.

If both 32-bit and 64-bit Cygwin are installed:
- Depending on which XWin the Start menu Cygwin-X folder launches,
  the other can be launched when that is not running by launching
  the appropriate terminal, then typing
    startx -- -multiwindow -clipboard &

- The Task Manager will indicate whether 32-bit or 64-bit Xwin.exe
is running.

- uname -a in a terminal indicates whether that terminal is
32-bit or 64-bit; x86_64 is 64-bit.

-- for SaVi

When expanding the coverage window to show a tiled coverage map, there
can be two lines of pixels, one to the left of the map, one to the right,
where coverage is not drawn on the background. Satellites and maps
are drawn correctly. Oddly, this only appears under the 32-bit
Cygwin, not in the newer 64-bit Cygwin.
This has not been seen on any platform other than 32-bit Cygwin.

-- for Geomview

The SaVi/Geomview combination does not yet appear functional under
the new 64-bit Cygwin introduced in March 2013, though 32-bit Cygwin
is fine. Geomview experiences OpenGL and piping problems under
64-bit Cygwin.  Use 32-bit Cygwin!

Under 64-bit Cygwin, you can try building Geomview with:
MOTIFLIBS='-lDtPrint -lMrm -lXm -lXt -lXmu -lXp -lXext -lX11 -lSM -lICE'
./configure --with-motif=/usr --with-opengl=/usr CPPFLAGS="-DglBindTextureEXT=glBindTexture -DglDeleteTexturesEXT=glDeleteTextures"
make



3. A DETAILED SAVI WISHLIST
===========================

This is an additional wishlist of improvements for SaVi
originally accumulated during work for the SaVi 1.2 release during
October-November 2001, and kept up-to-date with later development.

Development takes place at:
http://personal.ee.surrey.ac.uk/Personal/L.Wood/software/SaVi/src/
http://savi.sourceforge.net/

Many suggestions (such as the user interface and fisheye
modifications) should be straightforward if you have some Tcl/Tk/C
experience and the spare time and interest. Others are difficult.



a. CODING AND BUILD ISSUES

- make install is needed. That should probably match the current debian
  package. Early creation of it may have been able to prevent the previous
  package problems caused by maintainers unfamiliar with the savi tree,
  described below.

- Binary packages are not created by the SaVi authors. You can always
  download SaVi from http://savi.sf.net/ and compile it to get
  all the files created for SaVi.

- The savi-1.4.3 package available from getdeb.net from December 2009 onward
  (and available in Ubuntu's Synaptic package manager) initially removed the
  textfiles and manual from SaVi. This package installed SaVi under
  /usr/share/savi, while the COPYRIGHT file was edited, renamed 'copyright'
  and placed under /usr/share/doc/savi. This broke SaVi's help
  system by removing all help information. Packaging was fixed in later
  revisions. These packages were not initially compiled using zlib, although
  and making zlib a package dependency is straightforward. More details
  are in the PACKAGING textfile.

- Cygwin support isn't seamless, and may need some editing of
  tcl/Makefile to support the version of Tcl Cygwin uses.
  This caveat only appears to apply to very old versions of Cygwin;
  not Cygwin 1.5.6-1 and later.

- Under cygwin, specifying -mno-cygwin to gcc in src/Makefile in
  order to build using MinGW generates errors. We're a long way from a
  standalone Windows executable.

- $HOST or $HOSTNAME? One or both have the machine info we need
  for the compile version info preserved in Help/About...

- gv_utils.c warning: implicit declaration of functions fileno and fdopen
  because they're POSIX, not ANSI C, even though they're normally in stdio.h;
  could set -std=gnu99 flag to relax restriction if this mattered.

- The executable bin/SaVi (named for viewing the process name, e.g. in
  the Mac OS X menubar) is considered the same name as the savi scri                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      