xearth(1) MachTen Programmer’s Manual xearth(1)

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 time-
warp_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 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. Sup-
ported projection types are mercator and ortho-
graphic; 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 argu-
ments. 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 fol-
lowed by two arguments, interpreted as numerical
values indicating the latitude and longitude
(expressed in decimal degrees) of a viewing posi-
tion that is fixed with respect to the Earth’s sur-
face. Positive and negative values of latitude cor-
respond to positions north and south of the equa-
tor, 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 lon-
gitude (expressed in decimal degrees) of a viewing
position that is fixed with respect to the position
of the Sun. Positive and negative values of lati-
tude and longitude are interpreted as for the fixed
keyword.

The position specifier keyword orbit should be fol-
lowed by two arguments, interpreted as numerical
values indicating the period (in hours) and orbital
inclination (in decimal degrees) of a simple circu-
lar orbit; the viewing position follows this orbit.
Astute readers will surely note that these parame-
ters are not sufficient to uniquely specify a sin-
gle circular orbit. This problem is solved by lim-
iting the space of possible orbits to those posi-
tioned 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
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 compo-
nents 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 pro-
gression 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 merca-
tor 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 compo-
nents, 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 speci-
fier 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) con-
sists of two components, both integers; these com-
ponents 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 speci-
fier 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 pro-
vided 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 label-
ing 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, respec-
tively) indicating how the label should be posi-
tioned. The label position defaults to "-5-5"
(i.e., five pixels inside the lower right-hand cor-
ner 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 sur-
face. 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" com-
ponents. In this version of xearth, the only sup-
ported "key" is "align", which can be used to con-
trol 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 suit-
able 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 approx-
imately 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, inclu-
sive, 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 correc-
tion 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 origi-
nal 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 time-
warp_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 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 prac-
tice, 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 pro-
vide 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 render-
ing 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
following 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 -marker-
file, above).

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

starfreq (float)
Set the density of the random star pattern (see
-starfreq, 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 posi-
tions (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, dis-
able/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 prop-
erty 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 every-
thing 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, sug-
gestions, 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
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 dis-
tributed, 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 MER-
CHANTABILITY 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.

MIT LCS (not for general release) 13