TEXTUREMAPPING IN GEOMVIEW from SaVi
====================================
$Id: README-COVERAGE-TEXTUREMAP,v 1.43 2015/01/12 07:55:56 lloydwood Exp $

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

For SaVi and Geomview 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 continents. 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 'Show coverage in 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 5 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 5 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 5 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.8
	./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 will tell you whether compression support has been included 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 1.9.5 and later:
     - 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 very 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.

The continents mask Earthmaps used for the unprojected duochrome
shaded land and sea maps were resized from
 http://naturalearth.springercarto.com/ne3_data/16200/masks/water_16k.png

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)
