xearth
NAME
xearth - displays a shaded image of the Earth in the root
window
SYNOPSIS
xearth [-pos pos_spec ] [-sunpos sun_pos_spec ] [-mag factor
] [-size size_spec ] [-shift shift_spec ] [-shade|-noshade]
[-label|-nolabel] [-markers|-nomarkers] [-stars|-nostars]
[-starfreq frequency ] [-grid|-nogrid] [-grid1 grid1 ]
[-grid2 grid2 ] [-day pct ] [-night pct ] [-gamma
gamma_value ] [-wait secs ] [-timewarp timewarp_factor ]
[-time fixed_time ] [-onepix|-twopix] [-mono|-nomono]
[-ncolors num_colors ] [-font font_name ] [-fork|-nofork]
[-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). Xearth can also render directly into PPM and
GIF files instead of drawing in the root window; see the
-ppm and -gif options (below).
OPTIONS
Xearth understands the following command line options and X
resources:
-pos pos_spec
Specify the position from which the Earth should be
viewed. The pos_spec (position specifier) consists of
three components: a keyword (one of fixed, sunrel, or
orbit) and two numerical values. (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 fourth paragraph following this
one.)
If the position specifier keyword is fixed, the
numerical values indicate 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.
If the position specifier keyword is sunrel, the
numerical values indicate 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.
If the position specifier keyword is orbit, the
numerical values indicate 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)).
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.4 -71.1"
or
-pos 'fixed 42.4 -71.1'
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.4,-71.1
-pos fixed/42.4/-71.1
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).
-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. 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).
-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 and -night 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 in the lower right-hand corner that indicates the
current date and time and current viewing and sun
positions. Labeling is disabled by default.
-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.
At present, the list of locations for which markers are
placed consists of some three dozen major cities; no
hooks (beyond editing the source code and recompiling!)
are provided for adding to or changing this list. This
limitation will likely be addressed in a future version
of xearth.
-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.
-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 10.
-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.
-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.
-mono | -nomono
If rendering into the X root window, enable/disable
monocrhome 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.
-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 essense, automatically putting itself in
the background). Forking is disabled by default.
-nice priority
Run the xearth process with priority priority (see
nice(1) and setpriority(2)). By default, xearth runs at
priority 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:
pos (position specifier)
Specify the position from which the Earth should be
viewed (see -pos, 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).
markers (boolean)
Enable/disable markers (see -markers, above).
stars (boolean)
Enable/disable stars (see -stars, above).
starfreq (float)
Set the density of the random star pattern (see
-starfreq, 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).
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).
nice (integer)
Specify the priority at which the xearth process should
be run (see -nice, above).
MAJOR CAVEAT
This version of xearth (version 0.92) supports both one- and
eight-bit framebuffers. Systems with other than one- and
eight-bit framebuffers are only "supported" (indirectly) to
the extent that xearth can generate PPM and GIF files that
can be fed directly into your favorite image viewer (e.g.,
xv, xloadimage).
NOTES
This man page documents xearth version 0.92. There are a
number of improvements that I'd love to make, 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 DECWRL.
The Graphics Interchange Format(c) is the Copyright property
of CompuServe Incorporated. GIF(sm) is a Service Mark
property of CompuServe Incorporated.
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.
Kudos to Jef Poskanzer for his excellent PBMPLUS toolkit.
COPYRIGHT
Copyright (C) 1989, 1990, 1993, 1994 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, distribute, and sell this
software and its documentation for any purpose is hereby
granted without fee, provided that the above copyright
notice(s) appear in all copies and that both that copyright
notice and this permission notice appear in supporting
documentation. 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.