dockapps/wmglobe/README

WMGlobe 1.3  -  The Whole Earth spinning on you desktop... as a dockable app
Copyright (C) 1998,99,2000,01 Jerome Dumonteil <jerome.dumonteil@linuxfr.org>
This program is licensed under the terms of the GNU GPL, see below.



Description
----------------------------------------
WMGlobe is a WindowMaker dock.app that displays the earth on an icon. It's
an adaptation of XGlobe to WMaker environnement. WMGlobe uses a map which is
rendered on a sphere by raytracing. Yes, for a 64x64 pixel result :-)




Installation
----------------------------------------
You need WindowMaker to build WMGlobe. WMGlobe needs libwraster to compile,
this lib is built by WindowMaker. No more need at run time if statically 
linked, but then, you need WindowMaker to get the full magic :-)
Warning : this version won't work with WindowMaker < 0.62
 
	tar -xvzf wmglobe-1.3.tar.gz
	cd wmglobe-1.3
	make
	
	then move wmglobe in /usr/local/bin and man page somewhere or do 
	(as root) :
	make install


If it doesn't work, look for the graphic libraries. 

The Makefile is quite crude...

WMGlobe is developped on Linux (WMaker 0.65.1 and linux 2.4.x/ix86).
If you are successful on other platforms, please tell me so.


platforms with successfull built reported (wmglobe 1.0 for older WMaker): 

NetBSD 1.3.2 / SPARC    (wmaker 0.20.3) , with Makefile adaptations for libs 
Linux 2.0.36 / RedHat 5.1 
Linux 2.0.36 / SuSE 5.3 (wmaker 0.20.3)  ,  -lungif -> -lgif 
Linux 2.0.36 / RedHat 5.2 (wmaker 0.53)
Linux 2.2.0-pre4 / Debian    :-)
FreeBSD-3.0     with -ltiff -> -ltiff34 and -lungif -> -lgif 
Solaris 2.6  / Sun Sparc (wmaker 0.20.3) , with Makefile adaptations for libs
AIX 4.2.1    / IBM RS/6000-250 (wmaker 0.50.2)
Linux 2.3.14 / Mandrake (wmaker but also blackbox !)
LinuxPPC 1999
Linux 2.2.10 / Alpha (wmglobe 1.1+)


RPM & DEBIAN linux packages coming soon. Or you can directly use the binary.

compile time problems :

Xlib.h, Xpm.h ... : 
If you compile wmglobe on a computer installed with packages (.rpm), you may 
lack of these header files. Just install the "xxx-dev.rpm" packages for XFree86
and graphics libs, or install a rpm version of wmglobe.

libwraster :
WindowMaker 0.20.3 uses a libwraster.a , so if you use it, you can execute 
the binary on a computer without WindowMaker on it, and displaying on a 
remote computer (this one using WindowMaker). WM > 0.51.0 creates a dynamic
libwraster.so, so it's necessary to have it on the computer running wmglobe 
if you buit WMGlobe with this one. Both versions of WMGlobe run on WM 0.20.3 
and 0.51.0
For wmglobe 1.2+, you need WMaker 0.62 or more recent. And wmglobe 1.0 won't
run on these recent versions of WindowMaker. You need to have wraster.h 
in the include path to compile wmglobe.
For wmglobe 1.3+, you probably need WMaker 0.64 or more recent.

graphic libs : 
you can use libgif or libungif. If your version of WindowMaker is built 
without support for some graphic type, you don't need it (just remove it
from the makefile). 
This problem may happen with RedHat 5.2, if you get this kind of message, 
just add a libtiff to your system :
/usr/local/lib/libwraster.so: undefined reference to `TIFFReadDirectory'
...
make: *** [wmglobe] Error 1


compile time options : 
You can modify the file wmgoption.h where many options are set up in defines :

To disable the builtin default map, just comment out the line in wmgoptions.h
#define DEFMAPOK
to remove the shift+left/left method of rotate earth, uncomment the lines
#define MOUSE_LAT_FULL 

you can also suppress some options screen in wmgoption.h (or even suppress
new features of wmglobe 1.2)




Maps 
----------------------------------------
Like XGlobe, WMGlobe needs a longitude/latitude map to work. By default, 
it uses a low quality built-in map of earth. But you will probably want 
to use better ones.

You can get maps usable with WMGlobe on the net. See the LINKS chapter.

using custom maps :
- For the image to be mapped correctly, position 0<>North 0<>West must be in
  the center of the image and the latitude must be linear from 90<39>N to 90<39>S.
- You can safely use a night map of different size than the day map.

By the way, you can use maps of Mars, Luna ... and text.



Configuration options
----------------------------------------

Configuration is done through command line options.
	
-v			version
-h			short help

-zoom zoom_value	Value > 1 to magnify the view, value < 1 to lower.
			Default : 1.0	

-pos latitude long.	Initial viewing fixed at this position, don't follow
			the sun rotation. Accepted values in the form 
			45<34>12'36 or 45.21 or 45:12:36 
			Default : the initial position is "under" the sun, and
			the point of view follows the sun.

-sun                    The point of view follows the Sun (default).

-moon                   The point of view follows the Moon (i.e. you see the
                        Earth as you were on the Moon).
			
-rand			New random position at every refresh of screen

-map     map_file	Map used for the rendering. Can be JPEG, GIF, XPM
			PNM, TIFF but none BMP 
			Default : use internal map of earth.
			
-nimap   night_file	Map used for the dark side of the earth. Must be of
			the same width x height as the day side map. 
			Default : if the default internal day map is used, use
			a default internal night file (see -nonimap option). 
			
-defnimap		Use the default night map (with a custom map).

-nonimap		Don't use the default night map.			

-delay   seconds	Time in seconds between each calculation of a new 
			position. Limited to 0.04 at compile time (25 frames
			per second should be enough). The sun position move 
			only once per minute, so if you use wmglobe without
			-dlong or -accel option, the CPU cost of WMGlobe is
			*very* low. The use of very low value for -delay plus
			-dlong and -accel can be CPU costly (but very nice...)
			Default : 1.0 sec.

-dlat   delta_latitude	Move the point of view by delta_lat degrees per second,
			with a value of 6 the earth make a full rotation in 
			one minute. The value can be formated as -pos option.
			Default : 0<>0'0
			
-dlong  delta_long	Move the point of view by delta_long degrees per 
			second. With a value of -0<>0'15" the earth make a full 
			rotation in 24 hours toward the west. By default, 
			-dlong and -dlat are null. If they are used, the view
			follow their values. Going back to "follow sun" mode
			in parameters screen put -dlat and -dlong to zero.

-light  light_value	Level of light of the dark side when there is no
			night map, from 0 to 1. 
			Default : 0.25 		

-dawn   dawn_value	Level of continuity for dawn limit, from 0 to 1. With
			a value of 1, the border line between night and day is
			at maximum contrast.
			Default : 0.2

-bord   border_num	0 1 or 2. There are 3 different borders for the icon. 
			Default : 0
			
-accel  time_multi	Time warp factor. With -accel 24, the sun make a full
			rotation in one hour (or the earth, I'm not sure).
			Default : 1.0

-time   seconds		Time to display in seconds since 01-01-1970 (see the
			date command). Necessary if you need to be sure that
			WMGlobe is Y2K compliant without changing system time.
			Negative values for dates before 1970 accepted.
			Default : not set, use current time.

-mk latitude long.      Put a fixed marker at latitude/longitude. 
                        -mk sun : put a marker under the Sun position.
			-mk moon : put a marker under the Moon.
                        5 markers can be defined simultaneously, so you can
			use wmglobe to predict when Moon will meet the Sun :-)
			
-fun dx dy		Move the earth image by dx dy pixels in the icon. See
			puzzle.sh to understand why.

-oz			Start in "austral" mode (for "down under" people) 

-stable			Keep the globe from going over the poles.

-d display		Select another display

-w  -shape		Useless, since it is set by default (WMaker dockable 
			application)

mouse :
left button		Change longitude while pressed, change longitude &
			latitude if shift+left button.

middle button		Zoom in, shift + middle button : zoom out

right button		Displays 7 screens of parameters. On every screen, just
			clic with left or right button on the figures to change
			their value. The TIME screen shows an approximation
			of date and time of the earth zone currently displayed,
			using GMT time + longitude offset, it's close to the 
			real local time by one or two hours. Others options 
			don't need more help. Intuitive they said...
			


Links : Some sites dealing with WindowMaker 
-------------------------------------------

Official Window Maker Website :
http://www.windowmaker.org/

The Dock App Warehouse :
http://www.bensinclair.com/dockapp/



Links : Where to find maps and similar softs
--------------------------------------------
where to find the sources of wmglobe :
http://perso.linuxfr.org/jdumont/wmg/wmglobe-1.0.tar.gz

the web page of WMGlobe (made by Sylvestre Taburet) :
http://perso.linuxfr.org/jdumont/wmg/


where to find maps and similar softs :

Earth image by a cgi :
http://www.fourmilab.ch/cgi-bin/uncgi/Earth

two softs running under X :
XGlobe Homepage: http://www.uni-karlsruhe.de/~uddn/xglobe
(the recent 0.2 version brings a very nice map of earth)

Xearth Homepage: http://www.cs.colorado.edu/~tuna/xearth/


For the maps XGlobe doc says :

<EFBFBD> WHERE TO GET MAPS:

1. LivingEarth Inc.

http://livingearth.com/LE/LivEarthImg.html
http://livingearth.com/LE/BrillEarthImg.html

Livingearth Inc. has some nice (day and night) images on their web pages.
With these you can test the -nightmap option of XEarth. Unfortunately
they are pretty low-res (400x200).
You can find a higher-resolution (but heavily compressed) version of this
day map at the "Earth View" page: 

http://www.fourmilab.ch/cgi-bin/uncgi/Earth

Check "No night" and set display to "map", then save the image.


2. NOAA NGDC Marine Geology & Geophysics

http://www.ngdc.noaa.gov:80/mgg/image/mggd.gif

This image is definitely not "photo-realistic" but nonetheless pretty
interesting. It also has a rather high resolution. <20>



Todo
----------------------------------------
- add interface module to allow plugins
- test on different platforms, better makefile
- changing map "on the fly", map generator, clouds generator...
- must work on every current WindowMaker platform (hug...)
- rewrite some ugly things in the code
- see how to minimize CPU load
- feature : load a local detailed map of some part of the globe when zooming
  (country maps, city maps)
- maybe port to other window manager



Bugs
----------------------------------------
- Wmglobe depends on WindowMaker version
- The Makefile
- if you use the  --enable-single-icon compile time option of WindowMaker,
  you can not display more than one WMGlobe.
- WMGlobe hopes that an overflow of a long integer dont generate an error
  and that LONG_MAX +1 = LONG_MIN . This happens with high values of -accel 
  when the date go over year 2038. The expected result is wmglobe
  continuing smoothly from 1901.
- Using WMGlobe at high speed through a LAN may induce some load on the net.


License
----------------------------------------
WMGlobe is Copyright (C) 1998,99,2000,2001 by Jerome Dumonteil and licensed 
through the GNU General Public License. 
Read the COPYING file for the complete GNU license.



Credits
----------------------------------------
Original idea, tests, logos : Sylvestre Taburet <Sylvestre.Taburet@free.fr>

WindowMaker 0.62 fix : Charles G Waldman <cgw@fnal.gov>

The code in 'sunpos.cpp' is taken from Xearth by Kirk Lauritz Johnson.
(Actually, it uses now the 1.1 version of Xearth)

/*
 * sunpos.c
 * kirk johnson
 * july 1993
 *
 * code for calculating the position on the earth's surface for which
 * the sun is directly overhead (adapted from _practical astronomy
 * with your calculator, third edition_, peter duffett-smith,
 * cambridge university press, 1988.)
 *
 *
 * Copyright (C) 1989, 1990, 1993, 1994, 1995 Kirk Lauritz Johnson
 *
 * Parts of the source code (as marked) are:
 *   Copyright (C) 1989, 1990, 1991 by Jim Frost
 *   Copyright (C) 1992 by Jamie Zawinski <jwz@lucid.com>
 *
 * Permission to use, copy, modify and freely distribute xearth for
 * non-commercial and not-for-profit purposes is hereby granted
 * without fee, provided that both the above copyright notice and this
 * permission notice appear in all copies and in supporting
 * documentation.
 */

The rendering engine is taken from XGlobe by Thorsten Scheuermann
XGlobe Homepage: http://www.uni-karlsruhe.de/~uddn/xglobe

Raster graphics library by Alfredo K. Kojima, & stuff of Window Maker 
<http://windowmaker.org> by A. K. Kojima, Dan Pascu, Matthew Hawkins & team



Feedback
----------------------------------------
For your questions, bugs, remarks, please contact our representative on 
planet Earth : jerome dumonteil <jerome.dumonteil@linuxfr.org>