xearth(1X) xearth(1X)
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] [-dis-
play dpyname] [-version]
OPTIONS
xearth understands the following command line options and X resources:
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 com-
mand 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 de-
grees, of a viewing position that is fixed with respect to the
Earth's surface. Positive and negative values of latitude cor-
respond to positions north and south of the equator, respec-
tively. Positive and negative values of longitude correspond to
positions east and west of Greenwich, respectively.
If the position specifier keyword is sunrel, the numerical val-
ues indicate the offsets in latitude and longitude, expressed in
decimal degrees, of a viewing position that is fixed with re-
spect to the position of the Sun. Positive and negative values
of latitude and longitude are interpreted as for the fixed key-
word.
If the position specifier keyword is orbit, the numerical values
indicate the period (in hours) and orbital inclination (in deci-
mal 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 cir-
cular 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 invok-
ing 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). 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 compo-
nents, 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 longi-
tude values and the characters used to delimit specifier compo-
nents 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. Specify the
magnification of the displayed image. The diameter of the ren-
dered Earth image is factor times the shorter of the width and
height of the image (see the -size option, below). Specify the
size of the image to be rendered. The size_spec (size specifier)
consists of two components, both positive integers; these compo-
nents 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. 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 spec-
ifier) consists of two components, both integers; these compo-
nents 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. 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. Shad-
ing is enabled by default. Enable/disable labeling. If labeling
is enabled and xearth is rendering into the X root window, pro-
vide a label in the lower right-hand corner that indicates the
current date and time and current viewing and sun positions. La-
beling is disabled by default. Enable/disable markers. If mark-
ers 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.
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. 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 en-
abled by default. Set the density of the random star pattern
(see -stars, above); frequency indicates the fraction of back-
ground pixels that should be turned into "stars". The default
value of frequency is 0.002. 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 con-
trolled with the -grid1 and -grid2 options (see below). Grid
display is disabled by default. 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. 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. 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 indi-
cates total darkness and 100 indicates total illumination. This
value defaults to 100. Specify the brightness that should be
used to shade the night side of the Earth when shading is en-
abled. Pct should be an integer between 0 and 100, inclusive,
where 0 indicates total darkness and 100 indicates total illumi-
nation. This value defaults to 10. 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.
When rendering into the X root window, wait secs seconds between
updates. This value defaults to 300 seconds (five minutes).
Scale the apparent rate at which time progresses by time-
warp_factor. The default value of timewarp_factor is 1.0. In-
stead 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)). 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 re-
drawn 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. If rendering
into the X root window, enable/disable monochrome mode. Mono-
chrome mode is enabled by default on systems with one-bit frame-
buffers (see the "depth of root window" information provided by
xdpyinfo(1X) and disabled by default otherwise. 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.
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. When rendering into the X root win-
dow, 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. Run the xearth
process with priority priority (see nice(1) and setpriority(2)).
By default, xearth runs at priority 0. Instead of drawing in
the X root window, write a GIF file (eight-bit color) to stan-
dard out. Instead of drawing in the X root window, write a PPM
file (24-bit color) to standard out. Attempt to connect to the
X display named dpyname. Print what version of xearth this is.
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. xearth can also render directly into PPM and GIF files
instead of drawing in the root window; see the -ppm and -gif options.
X RESOURCES
The behavior of xearth can also be controlled using the following X re-
sources: Specify the position from which the Earth should be viewed
(see -pos, above). Specify a fixed point on the Earth's surface where
the Sun is always directly overhead (see -sunpos, above). Specify the
magnification of the displayed image (see -mag, above). Specify the
size of the image to be rendered (see -size, above). Specify that the
center of the rendered Earth image should be shifted by some amount
from the center of the image (see -shift, above). Enable/disable shad-
ing (see -shade, above). Enable/disable labeling (see -label, above).
Enable/disable markers (see -markers, above). Enable/disable stars
(see -stars, above). Set the density of the random star pattern (see
-starfreq, above). Enable/disable the display of a longitude/latitude
grid on the Earth's surface (see -grid, above). Specify the spacing of
major grid lines if grid display is enabled (see -grid1, above). Spec-
ify the spacing of dots along major grid lines if grid display is en-
abled (see -grid2, above). Specify the brightness that should be used
to shade the day side of the Earth when shading is enabled (see -day,
above). Specify the brightness that should be used to shade the night
side of the Earth when shading is enabled (see -night, above). Specify
the gamma correction xearth should use when selecting colors (see
-gamma, above). Specify the delay between updates when rendering into
the X root window (see -wait, above). Specify the apparent rate at
which time progresses (see -timewarp, above). Specify a particular
fixed time that should be used to determine the "value" of time-depen-
dent positions (see -time, above). Specify whether xearth should use
one or two pixmaps when rendering into the X root window (see -onepix
and -twopix, above). Specify whether xearth should use monochrome mode
when rendering into the X root window (see -mono and -nomono, above).
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. Use the named
font for drawing text labels (see -font, above). When rendering into
the X root window, enable/disable the automatic forking of a child
process to handle the updates (see -fork, above). 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 gener-
ate 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 im-
provements 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 appar-
ently originally generated by Brian Reid at DECWRL.
The Graphics Interchange Format(c) is the Copyright property of Com-
puServe 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 <
[email protected]>
Permission to use, copy, modify, distribute, and sell this software and
its documentation for any purpose is hereby granted without fee, pro-
vided that the above copyright notice(s) appear in all copies and that
both that copyright notice and this permission notice appear in sup-
porting 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, IN-
CLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSE-
QUENTIAL 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 PER-
FORMANCE OF THIS SOFTWARE.
AUTHOR
Kirk Johnson <
[email protected]>
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.
xearth(1X)