xearth - displays a shaded image of the Earth in the root
window
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]
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 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). 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. 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).
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. 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.
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. 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. 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.
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. 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.
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. 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 indicates 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
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. 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 timewarp_factor. The default
value of timewarp_factor is 1.0. Instead of using
the current time to determine the "value" of timedependent
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 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. 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(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 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. 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 standard 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.
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.
The behavior of xearth can also be controlled using the
following X resources: 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 shading
(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). Specify the spacing of dots along major
grid lines if grid display is enabled (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-dependent 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).
This version of xearth (version 0.92) supports both oneand
eight-bit framebuffers. Systems with other than oneand
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).
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 (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.
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.
xearth(1X)
[ Back ] |
