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]

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 option (see below). Xearth can also render directly
into PPM and GIF files instead of drawing in the root win-
dow; 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. Sup-
ported projection types are mercator and orthographic;
these can either be spelled out in full or abbreviated
to merc or orth, respectively. Xearth uses an ortho-
graphic 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 indi-
cating 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 nega-
tive values of longitude correspond to positions east
and west of Greenwich, respectively.

The position specifier keyword sunrel should be fol-
lowed 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 indi-
cating 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 suffi-
cient 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"

-pos ’fixed 42.33 -71.08’

to make things work. If you’d rather not have to expli-
citly quote things, you can use forward slashes or com-
mas 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 ren-
dered 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 nega-
tive latitude and longitude values and the characters
used to delimit specifier components apply to Sun posi-
tion 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 mag-
nification 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 inter-
preted 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 pro-
ducing 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 inter-
preted as the offsets (in pixels) in the X and Y direc-
tions.

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 loca-
tion 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. Sup-
ported 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 argu-
ment; this is the default behavior. The built-in set of
marker data can be examined either by using the -show-
markers 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 dis-
tance 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 discon-
tinuity (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 correc-
tion, 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 DISTRI-
BUTION, 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 pix-
map 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 num_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 num_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.

X RESOURCES
The behavior of xearth can also be controlled using the fol-
lowing X resources:

proj (projection type)
Specify the projection type xearth should use (see
-proj, above).

pos (position specifier)
Specify the position from which the Earth should be
viewed (see -pos, above).

rot (float)
Specify the viewing rotation (see -rot, above).

sunpos (sun position specifier)
Specify a fixed point on the Earth’s surface where the
Sun is always directly overhead (see -sunpos, above).

mag (float)
Specify the magnification of the displayed image (see
-mag, above).

size (size specifier)
Specify the size of the image to be rendered (see
-size, above).

shift (shift specifier)
Specify that the center of the rendered Earth image
should be shifted by some amount from the center of the
image (see -shift, above).

shade (boolean)
Enable/disable shading (see -shade, above).

label (boolean)
Enable/disable labeling (see -label, above).

labelpos (geometry)
Specify where the label should be drawn (see -labelpos,
above).

markers (boolean)
Enable/disable markers (see -markers, above).

markerfile (file name)
Specify a file from which user-defined marker data
(locations and names) should be read (see -markerfile,
above).

stars (boolean)
Enable/disable stars (see -stars, above).

starfreq (float)
Set the density of the random star pattern (see -star-
freq, above).

bigstars (int)
Set the percentage of stars that are double width (see
-bigstars, above).

grid (boolean)
Enable/disable the display of a longitude/latitude grid
on the Earth’s surface (see -grid, above).

grid1 (integer)
Specify the spacing of major grid lines if grid display
is enabled (see -grid1, above).

grid2 (integer)
Specify the spacing of dots along major grid lines if
grid display is enabled (see -grid2, above).

day (integer)
Specify the brightness that should be used to shade the
day side of the Earth when shading is enabled (see
-day, above).

night (integer)
Specify the brightness that should be used to shade the
night side of the Earth when shading is enabled (see
-night, above).

term (integer)
Specify the shading discontinuity at the terminator
(see -term, above).

gamma (float)
Specify the gamma correction xearth should use when
selecting colors (see -gamma, above).

wait (integer)
Specify the delay between updates when rendering into
the X root window (see -wait, above).

timewarp (float)
Specify the apparent rate at which time progresses (see
-timewarp, above).

time (integer)
Specify a particular fixed time that should be used to
determine the "value" of time-dependent positions (see
-time, above).

twopix (boolean)
Specify whether xearth should use one or two pixmaps
when rendering into the X root window (see -onepix and
-twopix, above).

mono (boolean)
Specify whether xearth should use monochrome mode when
rendering into the X root window (see -mono and
-nomono, above).

ncolors (integer)
Specify the number of colors xearth should use (see
-ncolors, above). The ncolors resource is only used
when rendering into the X root window -- the number of
colors to use when rendering into a GIF file can only
be specified using the -ncolors command line option.

font (font name)
Use the named font for drawing text labels (see -font,
above).

fork (boolean)
When rendering into the X root window, enable/disable
the automatic forking of a child process to handle the
updates (see -fork, above).

once (boolean)
When rendering into the X root window, disable/enable
updates for the displayed image (see -once, above).

nice (integer)
Specify the priority at which the xearth process should
be run (see -nice, above).

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 pro-
perty 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 ver-
sion 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.

Portions of the xearth source code, as marked, are:

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 Lem-
pel Zev Welch (LZW) compression technique employed in the
CompuServe GIF image file format as well as in other for-
mats. 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 MERCHANTABIL-
ITY AND FITNESS, IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAM-
AGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TOR-
TIOUS 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.