NAME
xearth - displays a shaded image of the Earth in the root window

SYNOPSIS
xearth
[ -proj proj_type]
[ -pos  pos_spec]
[ -rot  angle]
[ -sunpos sun_pos_spec]
[ -mag factor]
[ -size size_spec]
[ -shift shift_spec]
[ -shade | -noshade ]
[ -label |-nolabel ]         (*)
[ -labelpos geom]            (*)
[ -markers | -nomarkers ]    (*)
[ -markerfile file]          (*)
[ -showmarkers ]             (*)
[ -stars | -nostars ]
[ -starfreq frequency]
[ -bigstars percent]
[ -grid | -nogrid ]
[ -grid1 grid1]
[ -grid2 grid2]
[ -day pct]
[ -night pct]
[ -term pct]
[ -gamma gamma_value]        (*)
[ -wait secs]                (*)
[ -timewarp timewarp_factor] (*)
[ -time fixed_time]
[ -onepix | -twopix ]        (*)
[ -mono | -nomono ]          (*)
[ -ncolors num_colors]
[ -font font_name]           (*)
[ -fork | -nofork ]          (*)
[ -once | -noonce ]          (*)
[ -nice priority]            (*)
[ -gif ]
[ -ppm ]
[ -display dpyname]          (*)
[ -version ]

(*) Not used in Atari version


DESCRIPTION
Xearth sets the X root window to an image of the Earth, as seen from 
your favorite vantage point in space, correctly shaded for the current 
position of the Sun. By default, xearth updates the displayed image 
every five minutes. The time between updates can be changed with the '-
wait' option (see below); updates can be disabled completely by using 
the '-once'P option (see below). Xearth can also render directly into 
PPM and GIF files instead of drawing in the root window; see the '-ppm' 
and '-gif' options (below).

This man page documents version 1.0 of xearth.

OPTIONS

Xearth understands the following command line options (corresponding X 
resources can be found in the following section):


-proj proj_type
Specify the projection type xearth should use. Supported projection 
types are 'mercator' and 'orthographic'; these can either be spelled out 
in full or abbreviated to 'merc' or 'orth', respectively. Xearth uses an 
orthographic projection by default.


-pos pos_spec
Specify the position from which the Earth should be viewed. The 
'pos_spec' (position specifier) consists of a keyword, possibly followed 
by additional arguments. Valid keywords are: 'fixed', 'sunrel', 'orbit', 
and 'random'. (If you're having problems getting xearth to accept a 
position specifier as a command line argument, make sure and read the 
comments about position specifier delimiters and using explicit quoting 
in the fifth paragraph following this one.)

The position specifier keyword 'fixed' should be followed by two 
arguments, interpreted as numerical values indicating the latitude and 
longitude (expressed in decimal degrees) of a viewing position that is 
fixed with respect to the Earth's surface. Positive and negative values 
of latitude correspond to positions north and south of the equator, 
respectively. Positive and negative values of longitude correspond to 
positions east and west of Greenwich, respectively.

The position specifier keyword 'sunrel' should be followed by two 
arguments, interpreted as numerical values indicating the offsets in 
latitude and longitude (expressed in decimal degrees) of a viewing 
position that is fixed with respect to the position of the Sun. Positive 
and negative values of latitude and longitude are interpreted as for the 
'fixed' keyword.

The position specifier keyword 'orbit' should be followed by two 
arguments, interpreted as numerical values indicating the period (in 
hours) and orbital inclination (in decimal degrees) of a simple circular 
orbit; the viewing position follows this orbit. Astute readers will 
surely note that these parameters are not sufficient to uniquely specify 
a single circular orbit. This problem is solved by limiting the space of 
possible orbits to those positioned over 0 degrees latitude, 0 degrees 
longitude at time zero (the Un*x epoch, see 'time(3)').

The position specifier keyword 'random' should not be followed by any 
arguments. When this keyword is used, the viewing position is selected 
at random each time an update occurs.

Components of a position specifier are delimited by either whitespace, 
forward slashes (/), or commas. Note that using whitespace to separate 
position specifier components when invoking 'xearth' from a shell may 
require explicit quoting to ensure the entire position specifier is 
passed as a single argument. For example, if you want to use spaces to 
delimit components and are using a "typical" shell, you'd need to use 
something like:


    -pos "fixed 42.33 -71.08"


or


    -pos 'fixed 42.33 -71.08'


to make things work. If you'd rather not have to explicitly quote 
things, you can use forward slashes or commas instead of spaces to 
separate components, as shown below.


    -pos fixed,42.33,-71.08
    -pos fixed/42.33/-71.08


If a position specifier is not provided, 'xearth' uses a default 
position specifier of "sunrel 0 0" (such that the entire day side of the 
Earth is always visible).


-rot angle
Specify a rotated viewing position such that the north is not "straight 
up" in the center of the rendered image. Positive values of 'angle' 
rotate the rendered image counterclockwise; negative values rotate the 
rendered image clockwise. The default value of 'angle' is 0.


-sunpos sun_pos_spec
Specify a fixed point on the Earth's surface where the Sun is always 
directly overhead. The sun_pos_spec (Sun position specifier) consists of 
two components, both numerical values; these components are interpreted 
as the latitude and longitude (in decimal degrees) of the point where 
the Sun is directly overhead.

The details provided for position specifiers (see above) about the 
interpretation of positive and negative latitude and longitude values 
and the characters used to delimit specifier components apply to Sun 
position specifiers as well.

By default, xearth calculates the actual position of the Sun and updates 
this position with the progression of time.


-mag factor
Specify the magnification of the displayed image. When the orthographic 
projection is in use, the diameter of the rendered Earth image is 
'factor' times the shorter of the width and height of the image (see the 
-size option, below). For the mercator projection, the width of the 
rendered image is factor times the width of the image (see the -size 
option, below). The default magnification factor is 1.


-size 'size_spec
Specify the size of the image to be rendered. The 'size_spec' (size 
specifier) consists of two components, both positive integers; these 
components are interpreted as the width and height (in pixels) of the 
image.

The details provided for position specifiers (see above) about the 
characters used to delimit specifier components apply to size specifiers 
as well.

When rendering into the X root window, these values default to the 
dimensions of the root window. When producing a PPM or GIF file instead 
of drawing in the X root window (see the -ppm and -gif options, below), 
both values default to 512.


-shift 'shift_spec'
Specify that the center of the rendered Earth image should be shifted by 
some amount from the center of the image. The shift_spec (shift 
specifier) consists of two components, both integers; these components 
are interpreted as the offsets (in pixels) in the X and Y directions.

The details provided for position specifiers (see above) about the 
characters used to delimit specifier components apply to shift 
specifiers as well.

By default, the center of the rendered Earth image is aligned with 
the center of the image.


-shade | -noshade
Enable/disable shading. When shading is enabled, the surface of the 
Earth is shaded according to the current position of the Sun (and the 
values provided for the -day, -night, and -term options, below). When 
shading is disabled, use flat colors (green and blue) to render land and 
water. Shading is enabled by default.


-label | -nolabel
Enable/disable labeling. If labeling is enabled and xearth is rendering 
into the X root window, provide a label that indicates the current date 
and time and current viewing and sun positions. The position of the 
label can be controlled using the -labelpos option (see below). Labeling 
is disabled by default.


-labelpos geom
Specify where the label should be drawn. If labeling is enabled and 
xearth is rendering into the X root window, 'geom' is interpreted as the 
"position" part an X-style geometry specification (e.g., {+-}<xoffset>{+-
}<yoffset>; positive and negative values of xoffset denote offsets from 
the left and right edges of the display, respectively; positive and 
negative values of yoffset denote offsets from the top and bottom edges 
of the display, respectively) indicating how the label should be 
positioned. The label position defaults to "-5-5" (i.e., five pixels 
inside the lower right-hand corner of the display).


-markers | -nomarkers
Enable/disable markers. If markers are enabled and xearth is rendering 
into the X root window, display small red circles and text labels 
indicating the location of interesting places on the Earth's surface. 
Markers are enabled by default.


-markerfile file
Specify a file from which user-defined marker data (locations and names) 
should be read. Each line in the marker data file consists of three 
required components: the latitude and longitude (expressed in decimal 
degrees) followed by the text of the label that should be used. 
Individual components are delimited by either whitespace, forward 
slashes (/), or commas. Components that need to include delimiter 
characters (e.g., a multi-word label) should be enclosed in double 
quotes. For example, a line in a typical marker data file might look 
something like:


    42.33 -71.08 "Boston, MA"    # USA


Everything between a `#' character and the end of a line, inclusive, is 
a considered to be a comment. Blank lines and lines containing only 
comments are allowed.

In addition to the three required components, xearth supports optional 
following "key=value" components. In this version of xearth, the only 
supported "key" is "align", which can be used to control where marker 
labels are drawn in relation to the marker proper. Supported alignment 
values are "left", "right", "above", and "below"; the default behavior 
(if no alignment is specified) is "align=right".

The marker data file is reread every time xearth redraws an image into 
the X root window. In this way, the marker positions and labels can be 
dynamic (e.g., given appropriate data sources, markers could be used to 
encode hurricane positions, where earthquakes have happened recently, 
temperatures at fixed locations, or other forms of "real-time" data).

Xearth includes a built-in set of marker data for 76 major locations 
around the world. The built-in data can be selected by specifying "built-
in" for the 'file' argument; this is the default behavior. The built-in 
set of marker data can be examined either by using the -showmarkers 
option (see below) or by reading the BUILT-IN file included with the 
'xearth' source distribution (see OBTAINING THE XEARTH SOURCE 
DISTRIBUTION, below).


-showmarkers
This option indicates that xearth should load the marker data (whether 
built-in or user-specified), print a copy of it to standard out in a 
form suitable for use with the -markers option (see above), and then 
exit.


-stars | -nostars
Enable/disable stars. If stars are enabled, the black background of 
"space" is filled with a random pattern of "stars" (individual white 
pixels). The fraction of background pixels that are turned into stars 
can be controlled with the '-starfreq' option (see below). Stars are 
enabled by default.


-starfreq frequency
Set the density of the random star pattern (see -stars, above); 
'frequency' indicates the fraction of background pixels that should be 
turned into "stars". The default value of 'frequency' is
0.002.


-bigstars percent
Set the percentage of double-width stars (see -stars, above); by 
default, all stars are a single pixel, but this option can be used to 
create some stars that are composed of two horizontal pixels.  This 
provides a slightly less uniform look to the "night sky".


-grid | -nogrid
Enable/disable the display of a longitude/latitude grid on the Earth's 
surface. The spacing of major grid lines and dots between major grid 
lines can be controlled with the '-grid1' and '-grid2' options (see 
below). Grid display is disabled by default.


-grid1 grid1
Specify the spacing of major grid lines if grid display (see -grid, 
above) is enabled; major grid lines are drawn with a 90/grid1 degree 
spacing. The default value for 'grid1' is 6, corresponding to 15 degrees 
between major grid lines.


-grid2 grid2
Specify the spacing of dots along major grid lines if grid display (see -
grid, above) is enabled. Along the equator and lines of longitude, grid 
dots are drawn with a 90/(grid1 x grid2) degree spacing. The spacing of 
grid dots along parallels (lines of latitude) other than the equator is 
adjusted to keep the surface distance between grid dots approximately 
constant. The default value for 'grid2' is 15; combined with the default 
'grid1' value of 6, this corresponds to placing grid dots on a one 
degree spacing.


-day pct
Specify the brightness that should be used to shade the day side of the 
Earth when shading is enabled. 'Pct' should be an integer between 0 and 
100, inclusive, where 0 indicates total darkness and 100 indicates total 
illumination. This value defaults to 100.


-night pct
Specify the brightness that should be used to shade the night side of 
the Earth when shading is enabled. Pct should be an integer between 0 
and 100, inclusive, where 0 indicates total darkness and 100 indicates 
total illumination. This value defaults to 5 (if this seems overly dark, 
you may want to double-check that appropriate gamma correction is being 
employed; see -gamma, below).


-term pct
Specify the shading discontinuity at the terminator (day/night line). 
'Pct' should be an integer between 0 and 100, inclusive. A value of x 
indicates that the shading should immediately jump x percent of the 
difference between day and night shading values (see -day and -night, 
above) when crossing from the night side to the day side of the 
terminator. Thus a value of 0 indicates no discontinuity (the original 
xearth behavior), and a value of 100 yields a maximal discontinuity 
(such that the entire day side of the earth is shaded with the -day 
shading value). This value defaults to 1.


-gamma gamma_value
When xearth is rendering into the X root window, adjust the colors 
xearth uses by a gamma value. Values less than 1.0 yield darker colors; 
values greater than 1.0 yield brighter colors. The default 'gamma_value' 
is 1.0, appropriate for use on systems with built-in gamma correction. 
For systems without built-in gamma correction, appropriate gamma values 
are often in the 2.3 to 2.6 range.

See the GAMMA-TEST file included with the xearth source distribution for 
information about a simple test that allows you to directly estimate the 
gamma of your display system (see OBTAINING THE XEARTH SOURCE 
DISTRIBUTION, below).


-wait secs
When rendering into the X root window, wait secs seconds between 
updates. This value defaults to 300 seconds (five minutes).


-timewarp timewarp_factor
Scale the apparent rate at which time progresses by 'timewarp_factor'. 
The default value of timewarp_factor is 1.0.


-time fixed_time
Instead of using the current time to determine the "value" of time-
dependent positions (e.g., the position the sun), use a particular 
'fixed_time' (expressed in seconds since the Un*x epoch (see time(3)).


-onepix | -twopix
Specify whether xearth should use one or two pixmaps when rendering into 
the X root window. If only one pixmap is used, partial redraws may be 
visible at times in the root window (when areas of the root window are 
exposed and redrawn during the time xearth is rendering the next image). 
If two pixmaps are used, xearth uses them to double-buffer changes such 
that partial redraws are (almost?) never seen. Using only one pixmap has 
the advantage of using quite a bit less memory in the X server; this can 
be important in environments where server-side memory is a fairly 
limited resource. Two pixmaps is the default.


-mono | -nomono
If rendering into the X root window, enable/disable monochrome mode. 
Monochrome mode is enabled by default on systems with one-bit 
framebuffers (see the "depth of root window" information provided by 
xdpyinfo(1)) and disabled by default otherwise.


-ncolors Inum_colors
If rendering into the X root window or a GIF output file, specify the 
number of colors that should be used. (If markers are enabled (see -
markers, above), the actual number of colors used may be one larger than 
'num_colors'.) The default value of 'Inum_colors' is 64.

When rendering into the X root window, the maximum allowable value for 
'num_colors' is 1024. In practice, using values of 'num_colors' larger 
than twice the number of distinct shades of red, green, or blue 
supported by your hardware is likely to provide little additional 
benefit, or, in some cases, produce "banding" effects in the image. 
Thus, on systems that can support 256 distinct shades of red, green, or 
blue (eight bits per component), the largest practical value of 
num_colors is around 512. Similarly, on systems that support only five 
or six bits per component (e.g., many systems with 16-bit displays), the 
largest practical value of 'num_colors' is probably around 64.

When rendering into a GIF output file, the maximum allowable value for 
'num_colors' is 256.


-font font_name
If rendering into the X root window, use 'font_name' for drawing text 
labels (see -label and -markers, above). By default, xearth uses the 
"variable" font.


-fork | -nofork
When rendering into the X root window, enable/disable forking. If 
forking is enabled, xearth forks a child process to handle all rendering 
calculations and screen updates (in essence, automatically putting 
itself in the background). Forking is disabled by default.


-once | -noonce
Disable/enable updates. If updates are enabled and xearth is rendering 
into the X root window, xearth updates the displayed image periodically 
(the time between updates can be controlled via the -wait option, 
above). If updates are disabled, xearth only renders an image once and 
then exits. Updates are enabled by default.


-nice priority
Run the xearth process with priority priority (see nice(1) and 
setpriority(2)). By default, xearth runs at the priority of the process 
that invoked it, usually 0.


-gif
Instead of drawing in the X root window, write a GIF file (eight-bit 
color) to standard out.


-ppm
Instead of drawing in the X root window, write a PPM file (24-bit color) 
to standard out.


-display dpyname
Attempt to connect to the X display named dpyname.


-version
Print what version of xearth this is.


OBTAINING THE XEARTH SOURCE DISTRIBUTION
The latest-and-greatest version of xearth should always be available via 
a link from the xearth WWW home page (URL http://cag-
www.lcs.mit.edu/~tuna/xearth/index.html), or, for the web-deprived, via 
anonymous ftp from cag.lcs.mit.edu in /pub/tuna.

NOTES
There are a number of improvements that I'd love to make to xearth, but 
I really should be working on my thesis instead of hacking on this.

The map information used in xearth was derived from the "CIA World Data 
Bank II map database," as taken from some "cbd" files that were 
apparently originally generated by Brian Reid at DEC WRL.

The Graphics Interchange Format(c) is the Copyright property of 
CompuServe Incorporated. GIF(sm) is a Service Mark property of 
CompuServe Incorporated.

Thanks to Robert Berger for allowing me to include his nifty gamma 
measurement image and associated text in the xearth source distribution.

Thanks to Jamie Zawinski for suggesting that I look at his xscreensaver 
package for a good example of how to use the resource and command line 
option parts of Xt; his code saved me piles of lossage.

Thanks to Chris Metcalf for the -bigstars stuff, a pile of general 
source code cleaning, and spell checking everything carefully.

Thanks to Chris Hayward, Chris Metcalf, Sherman Mui, Dan Rich, and 
Leonard Zubkoff for giving the pre-release of version 1.0 a test drive.

Kudos to Jef Poskanzer for his excellent PBMPLUS toolkit. 

Finally, thanks to everybody that sent encouragement, suggestions, and 
patches. Apologies to the many people whose good ideas didn't make it 
into this release.

COPYRIGHT
Copyright (C) 1989, 1990, 1993, 1994, 1995 by Kirk Lauritz Johnson

Portions of the xearth 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.

Unisys Corporation holds worldwide patent rights on the Lempel Zev Welch 
(LZW) compression technique employed in the CompuServe GIF image file 
format as well as in other formats. Unisys has made it clear, however, 
that it does not require licensing or fees to be paid for freely 
distributed, non-commercial applications (such as xearth) that employ 
LZW/GIF technology. Those wishing further information about licensing 
the LZW patent should contact Unisys directly at (lzw_info@unisys.com) 
or by writing to


  Unisys Corporation
  Welch Licensing Department
  M/S-C1SW19
  P.O. Box 500
  Blue Bell, PA 19424


The author makes no representations about the suitability of this 
software for any purpose. It is provided "as is" without express or 
implied warranty.

THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO 
EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR 
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF 
USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR 
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 
PERFORMANCE OF THIS SOFTWARE.

AUTHOR

  Kirk Johnson <tuna@cag.lcs.mit.edu>
  MIT Laboratory for Computer Science


Patches, bug reports, and suggestions are welcome, but I can't guarantee 
that I'll get around to doing anything about them in a timely fashion.
