SaVi - live dynamic coverage texturemaps in Geomview
Lloyd Wood, January 2005.

$Id: README-COVERAGE-TEXTUREMAP,v 1.15 2005/02/27 00:23:08 lloydwood Exp $

USING DYNAMIC COVERAGE TEXTUREMAPPING
=====================================

Launch SaVi from geomview. Open the coverage panel window from the
View menu and 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 you in three dimensions what you can see
in the SaVi coverage panel in two.

This requires the coverage panel open, as we're reusing the map
area that the coverage panel draws; the coverage map must also
be set to the default cylindrical projection that can be mapped
onto Geomview's sphere correctly.

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

SaVi 1.2.5 improved the rendering in Geomview considerably, by relying
on Geomview to draw its vector outline of the Earth over coverage data.
SaVi 1.2.6 made dynamic texturemapping user-selectable via the Rendering
menu in the coverage panel, replacing the -dynamic-texture command-line
flag.

The remaining -dynamic-texture-with-map flag restores older behaviour
of texturemapping the entire coverage map, including its bitmap Earth
outline, so that the vector outline is not needed and is unused. This
requires less computational power from Geomview than drawing the vector
Earth over an outline-free texturemap, but doesn't look as good.
Try this only when performance feels particularly sluggish while
dynamic texturemapping is on.


TEXTUREMAP COMPRESSION
======================

Texturemaps sent from SaVi to Geomview can be transparently compressed
using zlib where available; you can tell whether compression is working
by seeing if SaVi creates either an uncompressed .ppm temporary file or
the far smaller .ppm.gz compressed file when the coverage panel is opened.

Transparent compression requires use of the free zlib library.
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.1
	./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 'make clean'.


TECHNICAL DETAILS
=================

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 seemed to be
the only size that Geomview was willing to texturemap, which is why
-large-map (also good for viewing maps on megapixel displays or saving
high-quality maps) is suggested. If texturemapping is not working as
expected, the standard Earth.ppm.Z texturemap should appear in Geomview
as a fallback.

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.

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.


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 jolly handy.
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're
rendering two separate maps). Texturemapping of non-cylindrical projections
has been disabled as 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.


NOTES ON MAP 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 (L.Wood@ee.surrey.ac.uk)
