xmars(1) MIT LCS xmars(1)
(not for general release)
NAME
xmars - displays a shaded image of the Red Planet in the root window
SYNOPSIS
xmars [-proj proj_type ] [-pos pos_spec ] [-rot angle ] [-sunpos
sun_pos_spec ] [-mag factor ] [-size size_spec ] [-shift shift_spec ]
[-shade|-noshade] [-label|-nolabel] [-labelpos geom ]
[-markers|-nomarkers] [-markerfile file ] [-showmarkers]
[-stars|-nostars] [-starfreq frequency ] [-bigstars percent ]
[-grid|-nogrid] [-grid1 grid1 ] [-grid2 grid2 ] [-day pct ] [-night pct
] [-term pct ] [-gamma gamma_value ] [-wait secs ] [-timewarp
timewarp_factor ] [-time fixed_time ] [-onepix|-twopix] [-mono|-nomono]
[-ncolors num_colors ] [-font font_name ] [-fork|-nofork]
[-once|-noonce] [-nice priority ] [-gif] [-ppm] [-display dpyname ]
[-version]
DESCRIPTION
Xmars sets the X root window to an image of Mars, as seen from your
favorite vantage point in space, correctly shaded for the current
position of the Sun. By default, xmars updates the displayed image
every five minutes. The time between updates can be changed with the
-wait option (see below); updates can be disabled completely by using
the -once option (see below). Xmars can also render directly into PPM
and GIF files instead of drawing in the root window; see the -ppm and
-gif options (below).
This man page documents version 1.0 of xmars.
OPTIONS
Xmars understands the following command line options (corresponding X
resources can be found in the following section):
-proj proj_type
Specify the projection type xmars should use. Supported
projection types are mercator and orthographic; these can either
be spelled out in full or abbreviated to merc or orth,
respectively. Xmars uses an orthographic projection by default.
-pos pos_spec
Specify the position from which the planet should be viewed. The
pos_spec (position specifier) consists of a keyword, possibly
followed by additional arguments. Valid keywords are: fixed,
sunrel, orbit, and random. (If you're having problems getting
xmars 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 fifth paragraph
- 1 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
following this one.)
The position specifier keyword fixed should be followed by two
arguments, interpreted as numerical values indicating the
latitude and longitude (expressed in decimal degrees) of a
viewing position that is fixed with respect to the planet'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 the Prime Meridian, respectively.
The position specifier keyword sunrel should be followed by two
arguments, interpreted as numerical values indicating 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.
The position specifier keyword orbit should be followed by two
arguments, interpreted as numerical values indicating 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)).
The position specifier keyword random should not be followed by
any arguments. When this keyword is used, the viewing position is
selected at random each time an update occurs.
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 xmars 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.33 -71.08"
or
-pos 'fixed 42.33 -71.08'
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.
- 2 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
-pos fixed,42.33,-71.08
-pos fixed/42.33/-71.08
If a position specifier is not provided, xmars uses a default
position specifier of "sunrel 0 0" (such that the entire day side
of the planet is always visible).
-rot angle
Specify a rotated viewing position such that the north is not
"straight up" in the center of the rendered image. Positive
values of angle rotate the rendered image counterclockwise;
negative values rotate the rendered image clockwise. The default
value of angle is 0.
-sunpos sun_pos_spec
Specify a fixed point on the planet'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, xmars 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. When the
orthographic projection is in use, the diameter of the rendered
planet image is factor times the shorter of the width and height
of the image (see the -size option, below). For the mercator
projection, the width of the rendered image is factor times the
width of the image (see the -size option, below). The default
magnification factor is 1.
-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
- 3 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
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 planet 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 planet image is aligned
with the center of the image.
-shade | -noshade
Enable/disable shading. When shading is enabled, the surface of
the planet is shaded according to the current position of the Sun
(and the values provided for the -day, -night, and -term options,
below). Shading is enabled by default.
-label | -nolabel
Enable/disable labeling. If labeling is enabled and xmars is
rendering into the X root window, provide a label that indicates
the current date and time and current viewing and sun positions.
The position of the label can be controlled using the -labelpos
option (see below). Labeling is disabled by default.
-labelpos geom
Specify where the label should be drawn. If labeling is enabled
and xmars is rendering into the X root window, geom is
interpreted as the "position" part an X-style geometry
specification (e.g., {+-}<xoffset>{+-}<yoffset>; positive and
negative values of xoffset denote offsets from the left and right
edges of the display, respectively; positive and negative values
of yoffset denote offsets from the top and bottom edges of the
display, respectively) indicating how the label should be
positioned. The label position defaults to "-5-5" (i.e., five
pixels inside the lower right-hand corner of the display).
- 4 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
-markers | -nomarkers
Enable/disable markers. If markers are enabled and xmars is
rendering into the X root window, display small red circles and
text labels indicating the location of interesting places on the
planet's surface. Markers are enabled by default.
-markerfile file
Specify a file from which user-defined marker data (locations and
names) should be read. Each line in the marker data file consists
of three required components: the latitude and longitude
(expressed in decimal degrees) followed by the text of the label
that should be used. Individual components are delimited by
either whitespace, forward slashes (/), or commas. Components
that need to include delimiter characters (e.g., a multi-word
label) should be enclosed in double quotes. For example, a line
in a typical marker data file might look something like:
19.33 -33.55
Everything between a `#' character and the end of a line,
inclusive, is a considered to be a comment. Blank lines and lines
containing only comments are allowed.
In addition to the three required components, xmars supports
optional following "key=value" components. In this version of
xmars, the only supported "key" is "align", which can be used to
control where marker labels are drawn in relation to the marker
proper. Supported alignment values are "left", "right", "above",
and "below"; the default behavior (if no alignment is specified)
is "align=right".
The marker data file is reread every time xmars redraws an image
into the X root window. In this way, the marker positions and
labels can be dynamic (e.g., given appropriate data sources,
markers could be used to encode sandstorm positions, where
landings have happened recently, temperatures at fixed locations,
or other forms of "real-time" data).
Xmars includes a built-in set of marker data for a few features
around the planet. The built-in data can be selected by
specifying "built-in" for the file argument; this is the default
behavior. The built-in set of marker data can be examined either
by using the -showmarkers option (see below) or by reading the
BUILT-IN file included with the xmars source distribution (see
OBTAINING THE XMARS SOURCE DISTRIBUTION, below).
-showmarkers
This option indicates that xmars should load the marker data
(whether built-in or user-specified), print a copy of it to
- 5 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
standard out in a form suitable for use with the -markers option
(see above), and then exit.
-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.
-bigstars percent
Set the percentage of double-width stars (see -stars, above); by
default, all stars are a single pixel, but this option can be
used to create some stars that are composed of two horizontal
pixels. This provides a slightly less uniform look to the "night
sky".
-grid | -nogrid
Enable/disable the display of a longitude/latitude grid on the
planet'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.
- 6 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
-day pct
Specify the brightness that should be used to shade the day side
of the planet 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 planet 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 5 (if this seems overly dark, you may want to
double-check that appropriate gamma correction is being employed;
see -gamma, below).
-term pct
Specify the shading discontinuity at the terminator (day/night
line). Pct should be an integer between 0 and 100, inclusive. A
value of x indicates that the shading should immediately jump x
percent of the difference between day and night shading values
(see -day and -night, above) when crossing from the night side to
the day side of the terminator. Thus a value of 0 indicates no
discontinuity (the original xmars behavior), and a value of 100
yields a maximal discontinuity (such that the entire day side of
the planet is shaded with the -day shading value). This value
defaults to 1.
-gamma gamma_value
When xmars is rendering into the X root window, adjust the colors
xmars 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, appropriate for use on systems with
built-in gamma correction. For systems without built-in gamma
correction, appropriate gamma values are often in the 2.3 to 2.6
range.
See the GAMMA-TEST file included with the xmars source
distribution for information about a simple test that allows you
to directly estimate the gamma of your display system (see
OBTAINING THE XMARS SOURCE DISTRIBUTION, below).
-wait secs
When rendering into the X root window, wait secs seconds between
updates. This value defaults to 300 seconds (five minutes).
- 7 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
-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 xmars 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
xmars is rendering the next image). If two pixmaps are used,
xmars 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. Two pixmaps is the default.
-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(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.
When rendering into the X root window, the maximum allowable
value for num_colors is 1024. In practice, using values of
num_colors larger than twice the number of distinct shades of
red, green, or blue supported by your hardware is likely to
provide little additional benefit, or, in some cases, produce
"banding" effects in the image. Thus, on systems that can support
256 distinct shades of red, green, or blue (eight bits per
component), the largest practical value of num_colors is around
512. Similarly, on systems that support only five or six bits per
component (e.g., many systems with 16-bit displays), the largest
practical value of num_colors is probably around 64.
- 8 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
When rendering into a GIF output file, the maximum allowable
value for num_colors is 256.
-font font_name
If rendering into the X root window, use font_name for drawing
text labels (see -label and -markers, above). By default, xmars
uses the "variable" font.
-fork | -nofork
When rendering into the X root window, enable/disable forking. If
forking is enabled, xmars 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.
-once | -noonce
Disable/enable updates. If updates are enabled and xmars is
rendering into the X root window, xmars updates the displayed
image periodically (the time between updates can be controlled
via the -wait option, above). If updates are disabled, xmars only
renders an image once and then exits. Updates are enabled by
default.
-nice priority
Run the xmars process with priority priority (see nice(1) and
setpriority(2)). By default, xmars runs at the priority of the
process that invoked it, usually 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 xmars this is.
X RESOURCES
The behavior of xmars can also be controlled using the following X
- 9 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
resources:
proj (projection type)
Specify the projection type xmars should use (see -proj, above).
pos (position specifier)
Specify the position from which the planet should be viewed (see
-pos, above).
rot (float)
Specify the viewing rotation (see -rot, above).
sunpos (sun position specifier)
Specify a fixed point on the planet'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 planetary 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).
labelpos (geometry)
Specify where the label should be drawn (see -labelpos, above).
markers (boolean)
Enable/disable markers (see -markers, above).
- 10 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
markerfile (file name)
Specify a file from which user-defined marker data (locations and
names) should be read (see -markerfile, above).
stars (boolean)
Enable/disable stars (see -stars, above).
starfreq (float)
Set the density of the random star pattern (see -starfreq,
above).
bigstars (int)
Set the percentage of stars that are double width (see -bigstars,
above).
grid (boolean)
Enable/disable the display of a longitude/latitude grid on the
planet'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 planet when shading is enabled (see -day, above).
night (integer)
Specify the brightness that should be used to shade the night
side of the planet when shading is enabled (see -night, above).
term (integer)
Specify the shading discontinuity at the terminator (see -term,
above).
gamma (float)
Specify the gamma correction xmars should use when selecting
- 11 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
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 xmars should use one or two pixmaps when
rendering into the X root window (see -onepix and -twopix,
above).
mono (boolean)
Specify whether xmars should use monochrome mode when rendering
into the X root window (see -mono and -nomono, above).
ncolors (integer)
Specify the number of colors xmars 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).
once (boolean)
When rendering into the X root window, disable/enable updates for
the displayed image (see -once, above).
- 12 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
nice (integer)
Specify the priority at which the xmars process should be run
(see -nice, above).
OBTAINING THE XMARS SOURCE DISTRIBUTION
xmars is merely a hack applied to xearth. The latest-and-greatest
version of xearth should always be available via a link from the
xearth WWW home page (URL http://cag-
www.lcs.mit.edu/~tuna/xearth/index.html), or, for the web-deprived,
via anonymous ftp from cag.lcs.mit.edu in /pub/tuna.
NOTES
There are a number of improvements that I'd love to make to xearth,
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 DEC WRL.
The Graphics Interchange Format(c) is the Copyright property of
CompuServe Incorporated. GIF(sm) is a Service Mark property of
CompuServe Incorporated.
Thanks to Robert Berger for allowing me to include his nifty gamma
measurement image and associated text in the xearth source
distribution.
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.
Thanks to Chris Metcalf for the -bigstars stuff, a pile of general
source code cleaning, and spell checking everything carefully.
Thanks to Chris Hayward, Chris Metcalf, Sherman Mui, Dan Rich, and
Leonard Zubkoff for giving the pre-release of version 1.0 a test
drive.
Kudos to Jef Poskanzer for his excellent PBMPLUS toolkit.
Finally, thanks to everybody that sent encouragement, suggestions, and
patches. Apologies to the many people whose good ideas didn't make it
into this release.
COPYRIGHT
Copyright (C) 1989, 1990, 1993, 1994, 1995 by Kirk Lauritz Johnson
- 13 - Formatted: April 19, 2024
xmars(1) MIT LCS xmars(1)
(not for general release)
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>
Copyright (C) 1997 by Steve Hosgood <steve@equiinet.com> (the Xmars hack)
Permission to use, copy, modify and freely distribute xearth and xmars
for non-commercial and not-for-profit purposes is hereby granted
without fee, provided that both the above copyright notice and this
permission notice appear in all copies and in supporting
documentation.
Unisys Corporation holds worldwide patent rights on the Lempel Zev
Welch (LZW) compression technique employed in the CompuServe GIF image
file format as well as in other formats. Unisys has made it clear,
however, that it does not require licensing or fees to be paid for
freely distributed, non-commercial applications (such as xearth or
xmars) that employ LZW/GIF technology. Those wishing further
information about licensing the LZW patent should contact Unisys
directly at (lzw_info@unisys.com) or by writing to
Unisys Corporation
Welch Licensing Department
M/S-C1SW19
P.O. Box 500
Blue Bell, PA 19424
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.
- 14 - Formatted: April 19, 2024
