BUGS recognized in SaVi
=======================
$Id: BUGS,v 1.131 2009/02/05 20:24:56 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. Caveats for Mac OS X users only.
   a. 10.5-specific issues
   b. Mac compilation hints
   c. Other minor Mac-specific issues

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

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.

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 yet just download
a .tle file, load it in and go.
Improving this would make SaVi much more practical.
(Sidereal time and the Earth's motion around the sun is not
simulated; noted by Tom Tessier.)

Using sinusoidal coverage map, full coverage reads from 99.6% to 99.8%
due to rounding at curved edges of map. Coverage calculations for all
projections are estimates at best, and are limited to not exceed
the 100% threshold. Calculations should really reflect degree of
coverage overlap and be consistent across all views. See
Kantsiper and Weiss, An Analytic Approach to Calculating Earth Coverage,
AAS 97-620, while they were at MIT, for an analytical integration
approach using the inclusion/exclusion principle.

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.



2. CAVEATS FOR MAC OS X USERS ONLY
==================================

a. 10.5-specific issues

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

The ./savi launch script adds -redrawn-menus on the Mac to
accommodate Leopard users. Tiger users can edit the launch script
to remove this and use the Mac menubar.

When using SaVi with Geomview on Mac OS X 10.5, the
.geomview file must also be modified to say e.g.:
    (emodule-define "SaVi" "./savi -redrawn-menus -geomview")
so that menus are drawn correctly if SaVi is launched from
Geomview's module list.


b. Mac compilation hints

SaVi and Geomview need Xcode (included in Developer Tools and
downloadable from Apple) to provide the tools that can compile
these and other programs.

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 are an extra optional
package provided on your systems disks. 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
the header files are installed:
    ./configure --with-opengl=/usr/X11R6
    make
    make install

If make 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.



c. Other minor Mac-specific issues

- With X11 rendering, Geomview does not appear to be able to control
  its background colour, which is always grey. OpenGL rendering is fine.
- Coverage colour buttons are only fully coloured when another
  application is frontmost. This is Tk's drawing behaviour on the Mac.



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://info.ee.surrey.ac.uk/Personal/L.Wood/software/SaVi/src/unreleased/
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

- 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...

- src/Makefile uses $MACH to clean and remove binaries. But Cygwin
  identifies itself as linux (which is a lie as far as -ltcl84 vs
  Linux's -ltcl8.4 libraries for linking are concerned), so that
  savi-cygwin.bin is skipped. Can we use $ARCH somehow?

- Just typing 'make' on Solaris looks for Makefile_defs_sun4, as that
  is what $ARCH holds. There are probably similar gotchas for the
  various irix platforms.

- 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 script
  on case-insensitive file systems (Mac OS X, Windows). This may lead
  to confusion, particularly if src/Makefile is ever made to build in
  the savi directory.

- Improve open/close filehandling and catch errors.

- We should really be using snprintf instead of sprintf.

- We should examine jerkiness when used with Geomview, particularly
  under Cygwin. utils.c::millisleep() calls select() without reference
  to the state of the pipe to Geomview; how can this be made smarter?
  Should we sleep after gv_end()/gv_stop() ceases nesting?



b. SCALABILITY

- Scaling up.
  Can SaVi detect available CPU power and e.g. scale number of
  segments in drawn orbit circles/number of sides to a coverage cone
  appropriately for Geomview? A slider or command switch giving some
  control over this would be very useful. Scaling up the number of
  segments when drawing highly-elliptical orbits has been done, but
  ORBIT_SEGMENTS defined in include/constants.h needs to be passed
  to Tcl as a variable.
  More use of Geomview binary format (discussed below) may help.

- Scaling down.
  Geomview rendering is optional; you can conserve CPU by running
  SaVi standalone. SaVi 1.2 and later don't do Geomview calculations
  when run standalone, although 1.0 did.
  Why shouldn't Tk and a graphical display also be optional?
  You do need a Tcl parser - that's essential - but we
  can execute scripts to build satellites and get results; we can
  make use of command-line switches, and we can pipe graphics to
  stdout for a variety of uses, including building web cgis
  (a la Chris Meenan's footprint generator).



c. SCRIPTABILITY

As well as scripts that get results there needs to be a
scriptable interface to record tracefiles. Scriptable recording of
satellite-related values over time periods would be very useful;
the self-scheduling Tcl procedure model that is used in the
network simulator ns (see below) may be worth emulating.

Having Tcl/C interaction daisy-chained as keywords off the 'satellites'
keyword is awkward, particularly for Geomview interaction, where a
'geomview' keyword would seem more intuitive. Perhaps a 'C' keyword?



d. USER INTERFACE

A user manual has been written and placed in the manual/ directory,
but more detail is needed.

The Tk procedures in tcl/tcl_utils.tcl (inherited from dsTool)
are straightforward to use, but are not that efficient in
using screen real estate. This makes SaVi cluttered, even on a
1024x768 display. SaVi 1.2 has improved things, but this still
needs more work.

* Main panel:
  A realtime push-hold button next to Time Interval would be useful;
  removes Rendering menu (->Geomview menu) when Geomview is not present.
  Move current time into reworked playbar line instead?
  Cutting to remove a satellite jumps to end of (long) list, unless start
  of list is shown.

* Coverage panel:
  Some wasted space here. When -large-map is selected the playbar
  at end is drawn below the bottom of a 1024x768 screen, which
  is a problem if you can't move windows from available edges.
  Reaching the coverage angle options also becomes tricky.

* Edit satellite:
  Layout can be improved.
  Apply button was removed since values do update live - but does
  that also hold for older versions of Tcl?
  There's no easy way to select multiple satellites so that
  you can change a checkbox setting for all of them.
  Panel can be left open when inappropriate, e.g. when a new
  constellation is loaded in. Should switch to editing a new
  satellite.


Create overriding 'Show all {satellites | orbits | coverage }'
checkboxes that, when checked, force related checkbox (in satellite
Edit parameters) on and the feature visible for all satellites.
When checked off, disable the feature for all satellites. These would
be entries on the Rendering menu, under 'Real-time mode'.

Update all Earth maps to track more recent political boundaries.

Provide menu of colour choices for highlights etc.



e. COVERAGE VIEW IMPROVEMENTS

Now that we have satellite names, an option to show them in the
coverage view would be useful.

If we close the coverage view window, we could be asked again on
re-opening what size map we want. This means freeing memory
and resetting pointers to null of maps and foreground, and also
pixelPtr and c_grid. And not crashing when we do this.

What is the diversity/decay value of the pixel that we have clicked?
Report it next to fisheye lat/long coords. Unlike coords, this
will need to be updated in real time. If fisheye is open, then we
likely already know it from within the red circle, and can just
repeat it in coverage?

'Use Earth map' checkbox could also control Geomview continents via
use_fancy_earth. Would we have to turn both of these on when opening
the coverage panel?

Look at drawing SaVi logo on coverage maps - this makes most sense
in corners of spherical and sinusoidal maps, but area used would
need to be discounted from coverage calculations

Longitude calculation for spherical fisheye clicks are inaccurate.
Edge calculation methods have visible differences (as does
sinusoidal). Area calculation hasn't been attempted; calculations
of areas in general for all projections are poor estimates anyway.

When choosing new colour shades after animating forwards then
stopping, the satellites move on an interval unexpectedly as
the map is updated with new colours. Is this due to computed
coverage finally being shown by tk_update()?

Project groundtracks for the next n hours only projects forwards in
time, even if the simulator is currently being run backwards - is
this the least confusing approach? Enter negative number to project
backwards.

When altering the coverage map and tiling, remember to run the
Teledesic (840) simulation to check that the top and bottom
of the map are visible as a single line of uncovered (blue or
white) pixels in cylindrical view. Tk does require a unit offset.

Add option to fade groundtracks to background over time, just
as interval decay works for coverage areas.

Coverage areas of the selected satellite(s) can be shown in
different shades - possibly shades of green.

Add optional latitude/longitude lines.

Earth outline on sinusoidal map is drawn using different algorithm
to backdrop. Overlap is poor; both should be drawn on the
cached map, rather than on each coverage map drawn. This matters
less when the backdrop is set to black to match the outline.

How much work would be required to enable multiple coverage windows
to be spawned, so that multiple projections could be seen, and
any available cylindrical projection used for texturemapping if
desired? Probably a lot.

Opening the coverage window when animating means that the coverage
playbar is not immediately updated with playbar status, and
playbars only sync when the next playbar button is pressed.



f. FISHEYE VIEW IMPROVEMENTS

Now that the fisheye window is resizable, having controls partially
obscured at small sizes is messy. Can this be improved? (Not resizing
the window when recording tracks would be a deliberate choice, given the
complexity of the alternative.)

Add slider to select size of fisheye crosshairs; will need to adjust
text positioning slightly. Can we add this on buttonbar?

How much work would be required to enable multiple fisheye windows
to be spawned? Probably a lot, if pass times are to be recorded in the
SL list structures on a per-view basis.

-debug outputs information about satellite positions, but it's verbose,
showing angle to all satellites, even those below the horizon, and lots
of debugging information for visible satellites. A decent log format for
visible satellites and their angles above the horizon is needed.

Saving bitmaps would be nice to have as an option. Postscript can always
be converted to a bitmap via GhostScript:
gs -dNOPAUSE -sDEVICE=png256 -r300x300 -sOutputFile=out.png -q -dBATCH out.ps
but Ghostscript is a tad unwieldy, and since you'll end up cropping the
results anyway.... it's simpler to just take a screen capture.



g. GEOMVIEW INTERACTION

Now that we have satellite names, an option to show them in Geomview
would be useful. This would be even harder than showing in the coverage
view - look at how The Orrery renders fonts and text.

Look at altering sleep code to give longer sleeps when Geomview
is running and animating, so that more CPU time is devoted to
Geomview and overall performance is made more responsive.

Geomview's light source positioning appears to be buggy at present,
as shown by savi -geomview -sun-lighting.

With Geomview 1.8.1, the large list structures used in writing footprints
and cones cause complaints about not being able to seek back far enough
in pipe. This is related to how piping is handled, and the piping code
rewrite by Claus-Justus Heine in Geomview 1.8.2 release candidates for
the 1.9 releases appears to have fixed this.
An alternative to the oogl used in:
footprints.c::write_footprints_geom()
cones.c::write_cones_geom()
would be good to have for remaining Geomview 1.8.1 users.
Footprints and cones are off by default to avoid this problem.

Geomview binary format is only used in one place at present (the
default satellite marker if the architecture permits it), but
offers a scaling advantage. Note that e.g. Geomview 1.8.0 (Linux,
some glibc) has problems with handling binary format; selecting
a more complicated marker type than the default green dot avoids
use of binary format entirely, but an explicit option would be
better.

Rotation of satellite markers as they approach the poles is inaccurate;
detailed satellite solar panels should be at right angles to the ecliptic
and rotate to follow the sun (if there's a sun...), rather than pointing
east-west, in order to get maximum sunlight. That's reality; for
visualization, having panels at right angles to the planes
increases visibility - when the planes are drawn.
Could use inclination of orbit.

Make this unwieldy SaVi/Geomview combination run in root window under
Xscreensaver, in long tradition of overdone OpenGL hacks. To do that,
more command switches must be passed to SaVi through Geomview.

Can central blue sphere rendering be rotated so that lat/long
lines map to barely-visible rendering of sphere segments?
Can we draw latitude/longitude lines that rotate with the
central body as an option? This would be like Geomview's
'Draw Unit Sphere Projection' Camera menu option, but rotating
with the Earth.

Replace equatorial plane with more detailed sectored concentric
circles.

Can Geomview postscript output be improved and made useful by
tweaking SaVi's oogl? This probably requires work on Geomview.

Translucent surfaces (e.g. yellow selection cubes) may not
be that visible in some renderers.

Add a 'Sky view' rendering option that combines the following:
  - switches Geomview to spherical geometry, so we're looking
    out from the centre of the Earth;
  - turns off central body, so that we look through outline
    continents.
  - turns on footprints, turns off spotbeams.



h. DYNAMIC TEXTUREMAPPING WITH GEOMVIEW

Dynamic texturemapping is described in the file
README-COVERAGE-TEXTUREMAP
which can be found in the same directory as this BUGS file.

Dynamic satellite coverage passing over the poles shows an interesting
'circle' effect where coverage diversity appears to be evaluated once
for the entire around-the-pole circular region. This may be dependent
on Geomview rendering options.

Coverage texturemap is not immediately updated when turning 'project
groundtracks forward in time' on or of, so it is out of sync with
coverage window until next animation step.

For the now-legacy scratchfile method, these are unlikely to be carried
out:

- SaVi should write to and tell Geomview to read from multiple tmpfiles
alternately, so that SaVi is writing one tmpfile while Geomview is
reading from the other. This would improve handling of large
uncompressed texturemaps by preventing interruption of reads as the
read file is overwritten by the next texturemap iteration.
(This property is arguably a failing in unix filesystem design.)

- gcc 3.3.5 (Debian) and 3.4.4 (FreeBSD) complain about our texturemap
tmpfile strategy:
In function `coverage_tempfile_created':
: warning: the use of `tmpnam' is dangerous, better use `mkstemp'



i. VARIOUS

Constellation generation tools should be working at a higher level -
generating constellation to match input properties for behaviour and
characteristics, rather than just taking orbital parameters without
calculating parameters needed to give a desired outcome.

Implement per-satellite coverage angles, as a property of each satellite
when it is created, like the name. But global coverage properties for
constellations are useful, and the global slider will be hard to give
up - how do we do both? Do we need to store half-angle/mask setting on
a per-satellite basis?

Improve time display, so that groundtrack drawing has useful
'elapsed time', and the time that the fisheye and coverage
displays are stopped can be easily read from their respective
windows. Average coverage display needs to count number of intervals
sampled, since time between intervals can be changed.

Implement a -start <+/- seconds> switch, so that a simulation can
be loaded at a specific point. Also -coverage, -fisheye, -edit to open
up the various windows on startup; can these be scripted?

Allow switching between a set of default values for various planets
(e.g. Venus, Earth, Mars) with matching surface maps, and even a default
Constellations menu for each planet. Accurate gravitational models for
each planet would be useful. Maps for each planet can be obtained from
e.g. Stuart Levy's The Orrery for Geomview, or from
James Hastings-Trew at http://planetpixelemporium.com/
JHT's maps are unprojected, so require
STSPHERE CYLINDRICAL 1 0 0 0
rather than { : numesh_h } in oogl/earth.oogl, which means at least
Geomview 1.9.0 for support. They're large, even once run through
jpegtopnm and compressed, so would have to be optional.

A way of drawing coverage on an opaque sphere just over the
planet map (but just under e.g. the Earth boundary vectors) would
be useful, so that colourful maps could be combined with coverage
and diversity.

Makefiles, header files and #include dependencies could be much better.
There's no attempt to optimise with judicious use of inlines as we're
ANSI compliant, but since we spend most of our time in the Tcl interpreter,
gains would be minimal and we can't inline functions in other files anyway.
Adding -O2 in src/Makefile (and turning off -g debug) has produced a
smaller and faster executable.



j. INTERACTION WITH OTHER 3D RENDERERS

Are there other 3D renderers with piped input for which SaVi could
add support?



k. INTERACTION WITH OTHER SIMULATORS

network simulator ns - http://www.isi.edu/nsnam/

SaVi could generate output in a format suitable for Lloyd Wood's perl
ns satplotscripts. This really requires working intersatellite-link
functionality to be useful; satellite positions alone doesn't give
much unless you need a postscript map.

ns could write the simplest SaVi format that describes satellites
(the simple Tcl scripts that SaVi saves files as...) to allow SaVi
to show where ns satellites are. Over time the ns and SaVi simulations
will diverge, since SaVi has the more complex orbital model -
a simple model could be made an option in SaVi.

As of ns 2.1b8, the default ns output format for Lloyd Wood's perl ns
satplotscripts describes long/lat position, but does not include
orbital information such as altitude, making it useless for SaVi as
it stands. A new format is needed.



4. REMAINING INTEGRATION WORK FROM UNRELEASED SAVI 1.1
======================================================

This work requires detailed knowledge of relevant geometry,
satellite requirements, SaVi and Geomview in order to build on
Patrick Worfolk's efforts.

- Intersatellite link simulation in SaVi and Geomview - although
  this really needs a good scripting interface, and must also
  consider visibility, handoff, and configuration.



5. REMAINING ITEMS FROM THE ORIGINAL SAVI 1.0 WISHLIST
======================================================

- Ability to input satellite positions correctly in two-line-element
  format, allowing multiple satellites with different epoch
  times to be simulated correctly simultaneously.

- Incorporation of actual time into program so that the evolution
  of real satellites can be monitored.

- Full incorporation of NORAD SGP4/SDP4 propagation models for
  NORAD two-line element sets for added realism.


Lloyd Wood <lloydwood@users.sourceforge.net>
