 |
Index for
Section 1X |
|
 |
Alphabetical
listing for X |
|
 |
Bottom of
page |
|
xearth(1X)
X11R6
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]
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 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.
-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 essence, 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.
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
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.
|
Index for
Section 1X |
|
|
Alphabetical
listing for X |
|
 |
Top of
page |
|