Content-type: text/html Man page of xearth

xearth

Section: (1X)
Updated:
Index Return to Main Contents
 

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: 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 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 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.
 

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: 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).
 

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 <[email protected]>

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 <[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.


 

Index

NAME
SYNOPSIS
OPTIONS
DESCRIPTION
X RESOURCES
MAJOR CAVEAT
NOTES
COPYRIGHT
AUTHOR

This document was created by man2html, using the manual pages.
Time: 02:42:57 GMT, October 02, 2010