TEXTUREMAPPING in Geomview from SaVi
====================================
$Id: README-COVERAGE-TEXTUREMAP,v 1.36 2009/01/11 16:59:17 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 static Earthmap texturemapping
   - introduction and how to turn this on.
2. Using dynamic coverage texturemapping
   - introduction and how to turn this on.
3. Related command line options
   - how to configure texturemapping to suit you.
4. Troubleshooting problems
   - common problems and workarounds.
5. Enabling texturemap compression
   - how to improve performance by decreasing disk accesses.

For programmers interested in how texturemapping with Geomview works:

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



1. USING STATIC EARTHMAP TEXTUREMAPPING
=======================================

Geomview can show detailed maps of the Earth's continens. Support for this
requires configuring and building Geomview with OpenGL - see the README.
Mac OS X Leopard users will also want to see the linker hint in BUGS.

To show these detailed maps, launch SaVi from Geomview and select either
a. Use simple Earth map
b. Use detailed Earth map
from SaVi's Rendering menu. Coverage footprints can be shown as vector
circles over these texturemaps by turning on 'Show footprints'.

The simple Earth map is SaVi's traditional blue-and-gold texture. This
map is a cylindrical projection in oogl/Earth.ppm.gz, and is loaded by
oogl/earth.oogl. This map works with Geomview 1.6 and later, and uses
Geomview's traditional texture mesh defined in oogl/numesh.oogl.

The detailed Earth map comes from NASA's Blue Marble project. This map
is unprojected, in oogl/blue_marble_land_shallow_topo_2048.jpeg, and is
loaded by earth_fancy.oogl and checked for by src/gv_init.c. This map
requires Geomview 1.9 or later, as it uses the new STSPHERE method for
texturemapping. Geomview requires the jpegtopnm utility, from the netpbm
package available at http://netpbm.sourceforge.net/, in its path to
unpack this image into a less space-efficient format.

(Note that STSPHERE uses CYLINDRICAL for unprojected maps and RECTANGULAR
for cylindrical projections. By using numesh.oogl rather than the newer
STSPHERE RECTANGULAR, texturemapping supports older pre-1.9 Geomview
releases that can only texturemap from cylindrical maps.)



2. USING DYNAMIC COVERAGE TEXTUREMAPPING
========================================

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

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 a particular projection.
Geomview 1.9.0 and later support cylindrical and unprojected projections.
Geomview earlier than 1.9.0 supports the cylindrical projection only,
when used with the simple Earth map.
If another projection is selected that cannot be texturemapped to
Geomview, the default static simple 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 full map to Geomview' in the coverage panel's Rendering
   menu to introduce texturemapping of the 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.



3. 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 pipe use or disk access is decreased. See section 4 of
this document for how to enable texturemap compression.

-dynamic-texture-to-file
This moves SaVi from streaming images directly to Geomview (which works
with all Geomview versions 1.9.0 and above) to the older method of
writing out a temporary scratchfile for Geomview to read. SaVi will
automatically use this method with older versions of Geomview (before
1.9.0) for backward compatibility. This is less accurate than streaming
images.

-uncompressed
If SaVi has been compiled with zlib support (see section 4 below), this
can be set to force uncompressed textures, ignoring zlib. Performance will
vary between compressed and uncompressed images depending on your
system and whether disk scratchfiles are in use.

-gzip-compressed-textures
If SaVi has been compiled with zlib support (see section 4 below), this
can be set to force writing the textures with their gzip headers, which
less recent versions of Geomview (before 1.9.5) need. SaVi will
automatically use this method with older versions of Geomview (before
1.9.5) for backward compatibility.



4. TROUBLESHOOTING PROBLEMS
===========================

If you see a blank golden sphere in Geomview once texturemapping has been
turned on, Geomview has attempted to load the texture, but is not displaying
the texture. Look for error messages in the console window where Geomview
was run. Launching SaVi from Geomview with the -large-map option may help,
as may upgrading your OpenGL drivers and rebuilding Geomview.

If you are using the older disk scratchfile method and disk access is
intensive, try texturemap compression to decrease the size of temporary
graphics files and improve performance. See below. Upgrading Geomview
to avoid the disk scratchfile method is recommended.



5. 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 pipe or disk that is
required.

You can tell whether compression is working by SaVi's status messages.

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.zlib.net/
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'.

SaVi's Help/about SaVi... dialog will tell you whether compression
support has been included in SaVi by the compiler.

SaVi's support for texturemapping varies depending on the version of
Geomview used, with the default being the newest method. Older
methods are supported via command-line options described earlier.
Geomview 1.8.x
 - compressed and uncompressed texturemaps must be written to disk
   to be read by Geomview. This is slow and jerky.
   Only the cylindrical coverage projection is supported.
Geomview 1.9.x
 - compressed and uncompressed texturemaps may be piped to Geomview
   directly, for a significant performance improvement.
   Cylindrical and unprojected coverage projections are supported.
   * Geomview 1.9.0 to 1.9.4
     - piped compressed texturemaps are handled by spawning a gzip
       process to uncompress them.
   * Geomview later than 1.9.4
     - Geomview handles decompression internally rather than spawning
       gzip to uncompress, for a minor performance improvement.
       Texturemaps may also be piped to Geomview using zlib's
       compress2 (.zlib) directly without added gzip (.gz) headers,
       which greatly simplifies coding.


The following sections are only of interest to programmers.



6. TECHNICAL DETAILS OF TEXTUREMAPPING
======================================

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.

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.

Images are sent down a pipe to Geomview, inline with oogl commands.
For the older disk method, 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 disk 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.



7. PROGRAMMING IMPLEMENTATION NOTES
===================================

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

Changing Image_Width/Height and having everything rescale is convenient.
We're reusing the existing projection in 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 other projections
has been disabled as incorrect and inconvenient for viewing in Geomview.
Note that the cylindrical map is RECTANGULAR as far as Geomview's STSPHERE
setting knows, while unprojected is known as CYLINDRICAL to STSPHERE.

More correct image/grid handling for multiple grids would probably require
a pointer to the image stored in grid structure we're passing around,
checking that the Tcl image referenced exists, etc.


8. 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 and orthographic spherical maps were
created from maps generated by Versamap, then screenshots were turned
to greyscale, resized, set threshold in gimp, then saved as xbm before
being processed as above.
	http://www.versamap.com/

Some maps used in previous versions of SaVi were created from maps
generated by Henry Bottomley's java map applet, which does a variety
of interesting projections:
	http://www.btinternet.com/%7Ese16/js/mapproj.htm

The blue-and-gold Earthmap in oogl/Earth.ppm.gz used for simple static
texturemapping was originally created by the Geometry Center for the Orrery,
another Geomview module, and tweaked.

NASA's Blue Marble project at http://visibleearth.nasa.gov/ has created
detailed Earth texturemaps for more accurate Earth rendering.

Lloyd Wood (lloydwood@users.sourceforge.net)
