dockapps/wmglobe/wmglobe.1

.TH WMGlobe 1.3   "august 2001"
.SH NAME
WMGlobe - The Whole Earth spinning on you desktop... 
as a dockable app for WindowMaker
.SH SYNOPSIS
.B wmglobe
.I "[-options]"
.SH "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:-)
.SH "OPTIONS"
.TP
.B \-v
version. Currently, this should display :

WMGlobe v.1.3  12 aug 2001 <jerome.dumonteil@linuxfr.org>
.TP
.B \-h
short help
.TP
.B \-zoom \fI zoom_value\fP
Value > 1 to magnify the view, value < 1 to lower. Default: 1.0
.TP
.B \-pos \fI latitude longitude\fP
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.
.TP
.B \-sun
The point of view follows the Sun (default).
.TP
.B \-moon
The point of view follows the Moon (i.e. you see the Earth as you 
were on the Moon).
.TP
.B \-rand
New random position at every refresh of screen.
.TP
.B \-map \fI map_file\fP
Map used for the rendering. Can be JPEG, GIF, XPM
PNM, TIFF but none BMP.   
Default: use internal map of earth.
.TP
.B \-nimap \fI night_file\fP
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). 
.TP
.B \-defnimap
Use the default night map (with a custom map).
.TP
.B \-nonimap
Don't use the default night map.   
.TP
.B \-delay \fI seconds\fP
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.
.TP
.B \-dlat \fI delta_latitude\fP
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
.TP
.B \-dlong \fI delta_long\fP 
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.
.TP
.B \-light \fI light_value\fP
Level of light of the dark side when there is no
night map, from 0 to 1. 
Default: 0.25	
.TP
.B \-dawn \fI dawn_value\fP
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
.TP
.B \-bord \fI border_num\fP
0 1 or 2. There are 3 different borders for the icon. 
Default: 2
.TP   
.B \-accel \fI time_multi\fP
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
.TP
.B \-time \fI seconds\fP
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.
.TP
.B \-mk \fI latitude longitude\fP
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 :-)
.TP
.B \-fun \fI dx dy\fP
Move the earth image by dx dy pixels in the icon. See
puzzle.sh to understand why.
.TP
.B \-oz
Start in "austral" mode (for "down under" people) 
.TP
.B \-stable
Keep the globe from going over the poles.
.TP
.B \-d \fI display\fP
Select another display
.TP
.B \-w  \-shape 
Useless, since it is set by default (WMaker dockable 
application)
.SH "MOUSE OPTIONS"
.TP
.B left button
Change longitude while pressed, change longitude &
latitude if shift+left button.
.TP
.B middle button
Zoom in, shift + middle button: zoom out
.TP
.B 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...
.SH "FILES"
.TP
.B 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 below.

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.
When using a night map, make sure that day and night map have the same
dimensions.
.TP
.B Links: Where to find maps and similar softs

where to find the sources of wmglobe: 
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: (many links to map of earth)

<http://www.uni-karlsruhe.de/~uddn/xglobe>


Xearth Homepage: 

<http://www.cs.colorado.edu/~tuna/xearth/>

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

.SH "ENVIRONMENT"
.LP
WMGlobe uses the setlocale(3) function, so you LANG environment need to be ok.

You need WindowMaker 0.62 or higher to use WMGlobe. (use WMGlobe 1.0 for
older versions of WindowMaker).
.SH "SEE ALSO"
.LP
The Window Maker User Guide

The Window Maker FAQ

.SH "AUTHOR"
jerome dumonteil  <jerome.dumonteil@linuxfr.org> 

Patches,  bug  reports, and suggestions are welcome.

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

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.

/*
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


.SH "BUGS"
.LP
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.