SaVi - live dynamic coverage texturemaps in Geomview

$Id: README-COVERAGE-TEXTUREMAP,v 1.20 2006/06/28 15:42:06 lloydwood Exp $

This README supplied with the SaVi satellite visualization software
supplements the main README textfile. This contains the following sections:

For SaVi users:

1. Using dynamic coverage texturemapping
   - introduction and how to turn this on.
2. Related command line options
   - how to configure texturemapping to suit you.
3. Troubleshooting problems
   - common problems and workarounds.
4. Enabling texturemap compression
   - how to improve performance by decreasing disk accesses.

For programmers interested in how texturemapping with Geomview works:

5. Technical details of texturemapping
6. Programming implementation notes.
7. Notes on SaVi Earthmap creation.


1. USING DYNAMIC COVERAGE TEXTUREMAPPING
========================================

Geomview can show the Earth map of satellite coverage that is drawn in
SaVi's coverage panel. This map is wrapped as a texture around Geomview's
Earth sphere, and is updated as SaVi computes new coverage maps. Support
for this requires OpenGL, and configuring and building Geomview with OpenGL.

Dynamic texturemapping of satellite coverage in Geomview requires SaVi's
coverage panel open, to reuse the map area that that coverage panel
draws and copy it to Geomview. The coverage map must be set to the default
cylindrical projection, which is the only projection that can be mapped
correctly onto Geomview's sphere. If another projection is selected, the
default static yellow-and-blue Earth map will be shown in Geomview.

To turn on dynamic texturemapping:
a. Launch SaVi from Geomview.
b. Open the coverage panel window from the View menu.
c. Turn on 'Send cylindrical map to Geomview' and 'Texturemapping'
   in the coverage panel's Rendering menu to introduce texturemapping
   of large cylindrical coverage map to Geomview's Earth sphere, so that
   Geomview shows in three dimensions what you can see in the SaVi
   coverage panel in two.
d. Animate SaVi's coverage by pressing '>>' in the coverage panel.

Geomview will now show what SaVi's coverage map shows.


RELATED COMMAND-LINE OPTIONS
============================

There are some command-line options for SaVi that relate to and can improve
the behaviour of this texturemapping:

-dynamic-texture-with-map
This option sends SaVi's entire coverage panel map, including the bitmap
Earth outline, to Geomview. This takes less computing by Geomview than
drawing the vector Earth around the sphere does, but doesn't look as good.
Try this flag only if performance feels particularly sluggish while dynamic
texturemapping.

-large-map
This option resizes the coverage panel map from 600x300 to 1024x512,
giving smoother texturemapping results in Geomview. If you have trouble
getting Geomview to render the coverage map at one size, try the other.

-map-view-height <no. of pixels>
This option can be used to provide an even larger coverage bitmap for
Geomview to texturemap, at the expense of Earth maps in SaVi's coverage
panel, as the available bitmaps are not scaled to match. Smaller maps
can also be selected to reduce the amount of computing done by SaVi and
Geomview. Texturemap compression is recommended for sending large bitmaps
to Geomview, as disk access is decreased. See section 4 of this document
for how to enable texturemap compression.


3. TROUBLESHOOTING PROBLEMS
===========================

If you see a blank golden sphere in Geomview once texturemapping has been
turned on, the textures are being loaded by Geomview, but are not being
displayed. Launching SaVi from Geomview with the -large-map option may help,
as may upgrading your OpenGL drivers and rebuilding Geomview.

If disk access is intensive, try texturemap compression to decrease
the size of temporary graphics files and improve performance. See below.


4. ENABLING TEXTUREMAP COMPRESSION
==================================

Texturemaps sent from SaVi to Geomview can be transparently compressed
using zlib where available. This increases performance by decreasing the
amount of writing to, reading from, and waiting for disk that is required.

You can tell whether compression is working by seeing if SaVi reports
creating either an uncompressed .ppm temporary file or the far smaller
.ppm.gz compressed file when SaVi's coverage panel is opened.

Transparent compression requires use of the free zlib library.
As zlib is optional and may not be present on your system , use of zlib
is disabled by default and must be explicitly enabled by you.

If the zlib library and zlib.h are not already available
on your system, zlib can be downloaded from http://www.gzip.org/zlib/
and shown to work with:
	cd zlib-1.2.3
	./configure -s
	make test
Then install zlib as superuser (or get an administrator to do so) with:
	make install

Transparent compression must be selectively enabled in the SaVi code
by editing SaVi's src/Makefile to remove the -DNO_ZLIB flag before
recompiling SaVi after first doing 'make clean'.



The following sections are only of interest to programmers.



5. TECHNICAL DETAILS OF TEXTUREMAPPING
======================================

Opening the coverage window and turning on texturemapping starts copying
coverage maps to Geomview via a temporary file, with fallback to writing
$HOME/coverage-savi.ppm or .ppm.gz if a temporary file cannot be created
in the system temporary directory.

The fallback method presumes that $HOME is a user-writable directory
(which is usually the case) and that the installation of SaVi is only
being used once for dynamic texturemapping by each person.

The large coverage panel option exists because 1024x512 seems to be
the size that Geomview is most willing to texturemap, as it matches the
size of the yellow-and-blue static Earth texturemap provided with SaVi.
This is why -large-map is suggested if problems with texturemapping are
seen.

To cope with failure of dynamic texturemapping and displaying the static
texturemap correctly, original rotation of the cylindrical map in SaVi
by 90 degrees to place the Americas central has been corrected to
match Geomview and conventional projections. The sinusoidal map still
has the Americas central, and is handled specially.

Interval decay is turned on because white areas show up in Geomview's
lighting as gold, and blue is rather cooler and matches Geomview's
default blue sphere.

The cylindrical projection requirement for texturemaps means that
commonly-available unprojected maps of that size (e.g. Living Earth
samples) cannot be used correctly to replace the static Earth.ppm.Z
texturemap; their geometry is wrong and poles become overly large,
pushing continents towards the equator. Don't use them.


6. PROGRAMMING IMPLEMENTATION NOTES
===================================

Mapping is horribly convenient because the Tcl coverage image is
effectively already a raw RGB ppm file, which we write to a scratch
file we tell Geomview to read in.

Changing Image_Width/Height and having everything rescale is convenient.
We're reusing the cylindrical projection of the coverage map (rather than
building a separate image, which would require clearer image/grid handling
in src/coverage_vis.c and would be even more of a slowdown since we'd be
rendering two separate maps). Texturemapping of non-cylindrical projections
has been disabled as incorrect and inconvenient for viewing in Geomview.

Correct image/grid handling probably requires pointer to image stored
in grid structure we're passing around, checking that the Tcl image
referenced exists, etc.


7. NOTES ON SAVI EARTHMAP CREATION
==================================

1024x512 sinusoidal pbm map was created from the 600x300 map
(scaled in gimp, made 1-bit as greyscale indexed colour, saved
as xbm, run through xbmtopbm). Cylindrical map created from same-size
Earth.ppm.Z, by using threshold in gimp before going 1-bit and xbm.

New unprojected equirectangular maps were created from maps generated
by Versamap, then screenshots had colours altered, were run through gimp's
various filters, resized and saved similarly.
	http://www.versamap.com/

New equatorial orthographic maps were created from a map generated
by Henry Bottomley's java map applet, which does a variety of interesting
projections:
	http://www.btinternet.com/%7Ese16/js/mapproj.htm


Lloyd Wood (lloydwood@users.sourceforge.net)
