TEXTUREMAPPING IN GEOMVIEW from SaVi ==================================== $Id: README-COVERAGE-TEXTUREMAP 207 2023-04-29 02:19:35Z lloydwood $ 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 alter performance by decreasing the amount of data piped. 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. The detailed Earth map is freely available from NASA's Blue Marble project. This unprojected map is in oogl/blue_marble_land_shallow_topo_2048.jpeg and is loaded by oogl/earth_fancy.oogl and checked for by src/gv_init.c. 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. Since that is a Geomview dependency, Geomview use is optional with SaVi, and use of the detailed Earth map is optional with Geomview, SaVi only includes the compact .jpeg file. 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. 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, launch SaVi from Geomview. From the Rendering menu, select "Use generated coverage map' to open the Coverage panel and send its map to Geomview, so that Geomview shows in three dimensions what you can see in the SaVi coverage panel in two. Animate SaVi's coverage by pressing '>>'. 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 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 can be decreased. See section 5 of this document for how to enable texturemap compression. -uncompressed If SaVi has been compiled with zlib support (see section 5 below), this can be set to force uncompressed textures, ignoring zlib. Performance may vary between compressed and uncompressed images depending on your system. -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. 5. ENABLING TEXTUREMAP COMPRESSION ================================== Texturemaps sent from SaVi to Geomview can be transparently compressed using zlib where available. This can alter performance by decreasing the amount of writing to, reading from, and waiting for pipe that is required. You can tell whether compression is working by SaVi's status messages in the console window where savi was launched. 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.11 ./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 can tell you whether compression support was included when building SaVi in its About dialog from the Help menu. SaVi's support for texturemapping varies depending on the version of Geomview used, with the default being the newest method available for that version of Geomview. Older methods can be supported via command-line options described earlier. Geomview 1.9.x - static and dynamic texturemaps are supported. Compressed and uncompressed texturemaps may be piped to Geomview directly. Cylindrical and unprojected coverage projections are supported. * 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. * Geomview 1.9.0 to 1.9.4: - piped compressed texturemaps are handled by spawning a gzip process to uncompress them. Geomview 1.8.x - dynamic coverage texturemaps were last supported in SaVi 1.4.8, where a temporary scratchfile using the cylindrical projection was written to and read from disk repeatedly. That legacy method is no longer available. Static Earth texturemaps were last supported in SaVi 1.4.9, where numesh.oogl was used instead of the STSPHERE command. That legacy method is no longer available. 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. Coverage images are sent down a pipe to Geomview, inline with oogl commands. 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 Geomview 1.9's STSPHERE uses CYLINDRICAL for unprojected maps and RECTANGULAR for cylindrical projections, which is backwards. (Geomview 1.8.1 does not support STSPHERE, and required the older oogl/numesh.oogl to support only cylindrical projections.) 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)