Xplanet 0.73
03 Aug 2000

Xplanet is similar to Xearth, where an image of the earth is rendered
into an X window.  Azimuthal, Mercator, Mollweide, orthographic, or
rectangular projections can be displayed as well as a window with a
globe the user can rotate interactively.  The other planets and some
satellites may also be displayed.  The latest version can always be
found at http://xplanet.sourceforge.net.

Most of the algorithms are taken from "Astronomical Formulae for
Calculators" by Jean Meeus, published by Willman-Bell.  The rotational
parameters for the other planets and satellites are taken from Davies
et al. (1996), Celestial Mechanics 63, 127--148.  Orbital formulae for
Pluto are taken from Paul Schlyter's page at
http://www.m2c3.com/alpocs/tdl1999/schlyter110199/ppcomp.html 
Most of the map projection algorithms are from "Map Projections - A
Working Manual" by John P. Snyder, published by the U.S. Department of
the Interior.

Xplanet is free software, distributed according to the terms of the
GNU General Public License.  See the COPYING file for details.

Xplanet has been compiled and run on Linux, Solaris, HP-UX, FreeBSD,
and IRIX platforms.

See the INSTALL file for installation instructions.

Options need only be specified with enough characters to be
unambiguous.  Valid options to Xplanet are:

-animate
Pop up a window using OpenGL or Mesa where the user can rotate the
globe interactively.  The -markers and -label options will be ignored
in this mode.  Valid keys in this mode are:
Home/End:	      Move closer/farther
Arrow keys:	      Rotate body
+/-:		      Increase/decrease rotation speed
r:		      Reverse rotation
h:		      Toggle help screen
q:		      Quit

-background background_file
Use background_file as the background image, with the planet to be
superimposed upon it.  If no projection is explicitly specified,
orthographic is assumed, but this option may also be used with the
azimuthal and Mollweide projections.   

-blend
Use bilinear interpolation to compute the color of each pixel instead
of nearest-neighbor interpolation.  It slows down the computation, but
it can look a lot better, particularly if you're using a low
resolution map.

-body body 
Render an image of the specified planet or satellite.  Valid values
for body are mercury, venus, earth, moon, mars, jupiter, io, europa,
ganymede, callisto, saturn, titan, uranus, neptune, and pluto.  No,
Xplanet does not render Saturn's rings.

-center x,y
Place the center of the globe at (x,y).  You can use this with the
-radius option to put a small image anywhere on the screen.  If no
projection is explicitly specified, orthographic is assumed, but this
option may also be used with the azimuthal and Mollweide projections.

-cloud_image cloud_file 
Use cloud_file as the image to be overlaid.  Overlaying clouds slows
Xplanet down considerably (but it looks really nice).  New global
composite cloud maps are generated every six hours on
http://xplanet.sourceforge.net.  If you use this option a lot, you
might consider making your own day and night image maps with the
clouds already overlaid to save some time.  You can create a shell
script like the following:

	 wget http://xplanet.sourceforge.net/cloud_800.jpg
	 xplanet -image day.jpg -cloud_image cloud_800.jpg \
	 -shade 100 -output day-clouds.jpg -geometry widthxheight
	 xplanet -image night.jpg -cloud_image cloud_800.jpg \
	 -cloud_shade 30 -output night-clouds.jpg -geometry widthxheight

Where width and height are the dimensions of the image to create.  Now
you can use day-clouds.jpg and night-clouds.jpg as your day and night
images until it's time to get a new cloud map.

-cloud_shade percent 
Only shade the cloud map; do not shade the night map.  This is useful
for creating a new night map with the cloud image overlaid in the
event you're using different map files for day and night.  For an
example, see the -cloud_image option above.

-cloud_ssec cloud_file 
Just like -cloud_image but where cloud_file is an image downloaded
from the Space Science and Engineering Center (SSEC) at the University
of Wisconsin.  The latest image (updated every three hours) can be
obtained from http://www.ssec.wisc.edu/data/comp/latest_moll.gif. This
image is a 640x350 pixel Mollweide composite image with ugly pink
coastlines.  Xplanet will reproject and resize the image as well as
remove and fill in the coastlines.  As with -cloud_image, this can be
time consuming each time Xplanet runs, so consider making a new
composite yourself.  

-cloud_threshold threshold
Cloud pixel values below threshold will be ignored.  The value for
threshold should be between 0 and 255.  A value of 90 is the default.

-color colorname
Set the color for the label/markers to colorname.  The default is
"red".  Any color in the rgb.txt file may be used (usually
/usr/X11R6/lib/X11/rgb.txt).

-date string
Use the date specified instead of the current local time.  The format
of the string should be "24 Jun 1999 21:02:17" ("%d %b %Y %H:%M:%S" as
read by strptime(3)).  The time is assumed to be local time.  If
strptime is not available on your system the -date option will be
ignored.

-dayside
Render the image as seen from directly above the subsolar point.  If no
projection is explicitly specified, orthographic is assumed, but this
option may also be used with any projection except rectangular. 

-demfile demfile
Use demfile as the digital elevation map.  This file should be an 8
bit image, with 0 being the lowest elevation (corresponding to radius
1) and 255 being the highest elevation (corresponding to radius = 1 +
demscale, defined below).  The -blend option will be ignored if
-demfile is used.  This option implies -projection orthographic. 

-demscale demscale
Assign the highest elevation in the digital elevation map named with
the -demfile option to be at a distance of 1 + demscale from the
planet center.  The default is 0.05.  This option will be ignored if
-demfile is not used. 

-earthside
Render the image as seen from the earth. This option only works with
other planets, specified with -body.  If no projection is explicitly
specified, orthographic is assumed, but this option may also be used
with any projection except rectangular.

-font fontname
Set the font for the label/markers to fontname.  The default font is
"variable".  The command "xlsfonts" will list all of the fonts that
are available.

-fullscreen
Set the width and height of the window or output file to the size of
the root window.  This will only work if there is a DISPLAY variable
set.

-fuzz fuzz
Let the day and night hemispheres blend into one another for pixels
within fuzz degrees of the terminator.  The default value is 6.

-geometry string
Specify the window geometry using the standard X window geometry
syntax.  This option implies -window, but can also be used with
-animate or -output.  

-grid
Draw a longitude/latitude grid.  The spacing of major grid lines and
dots between major grid lines can be controlled with the -grid1 and
-grid2 options (see below).

-grid1 grid1
Specify the spacing of grid lines. 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.  This option
implies -grid.

-grid2 grid2
Specify the spacing of dots along grid lines.  Grid dots are drawn
with a 90/(grid1 x grid2) degree spacing.  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.  This option implies
-grid.

-help                
Display a list of options.

-image image_file
Use image_file as the day map image.  For the earth and moon, it is
assumed that the image goes from [-180,+90] at the top left to
[180,-90] at the bottom right.  For the other planets, the corners are
assumed to be [180, +90] and [180, -90] at top left and bottom right
respectively, where the longitude increases to the west for Mercury
and Mars and the longitude increases to the east for Venus.  This is
confusing but most images you will find adhere to this convention, so
you probably don't need to worry about it anyway. 

-label
Display a label in the upper right corner which indicates the current
time and subsolar point, and the position where the observer is
directly overhead.  For orthographic projections the illuminated
fraction is also displayed.

-labelpos string
Specify the location of the label using the standard X window geometry
syntax.  The default position is "-15+15", or 15 pixels to the left
and below the top right corner of the display.  This option implies
-label. 

-latitude latitude
Render the globe as seen from above the specified latitude (in
degrees).  The default value is 0.  Also see the -observer option.
If no projection is explicitly specified, orthographic is assumed, but
this option may also be used with any projection except rectangular.

-localtime time 
This option is equivalent to using the -longitude option with the
meridian at which the local time is the time specified.  The time can
range from 0 to 24.

-longitude longitude 
Place the observer above the specified longitude (in degrees).
Longitude is positive going east, negative going west (for earth and
moon), so for example Los Angeles is at -118 or 242.  The default
value is 0.  Also see the -observer option.  

-mapdir directory
When looking for an image, Xplanet will first look in the current
directory, then the directory specified by -mapdir, and finally the
prefix directory specified at compilation time (usually
/usr/share/xplanet or /usr/local/share/xplanet).

-markerfile markerfile 
A file containing user defined marker data to display on the globe.
The format is the same as the marker file used by xearth.  In addition
to the "align" keyword supported by xearth, Xplanet supports the
"color" and "font" keywords as in the example below: 

33.943 -118.408 "Los Angeles" align=below color=blue font=10x20 # USA 

Valid "align" values are "right", "left", "above", and "below".  Valid
values for "color" and "font" are the same as for the -color and -font
options, respectively.  Delimiters (whitespace, tabs, forward slashes,
or commas) are not permitted in any of these keyword/value pairs.
This option implies -markers.

-markers
Enable markers, as in xearth.  The default marker file is named in
auxfiles.h.

-moonside                   
Render the image as seen from the moon.  If no projection is
explicitly specified, orthographic is assumed, but this option may
also be used with any projection except rectangular.

-night_image night_file
Use night_file as the night map image.  If this option is not
specified, the night map will be a copy of the day map, modified as
described in the -shade parameter.

-nightside                   
Render the image as seen from directly above the anti-subsolar point.
If no projection is explicitly specified, orthographic is assumed, but
this option may also be used with any projection except rectangular.

-notransparency
Do not update the background pixmap for transparent Eterms and aterms.

-observer x,y
Place the observer above longitude x, latitude y.  This option is
equivalent to -longitude x -latitude y.  A perl script named
"tzcoord.pl" is supplied with xplanet.  You can use it to find the
position of any location in the zone.tab file (usually in
/usr/share/zoneinfo).  For example,
xplanet -observer `tzcoord.pl Sydney`
will draw a globe centered over Sydney.

-output filename
Output to a file instead of rendering to a window.  The file format is
taken from the extension. Currently  .gif, .jpg, .ppm, .png, and .tiff
images can be created.

-projection projection_type
The projection type may be one of azimuthal, mercator, mollweide,
orthographic, or rectangular.

-radius radius 
Render the globe with a radius of radius percent of the screen height.
The default value is 50% of the screen height.  If no projection is
explicitly specified, orthographic is assumed, but this option may
also be used with the azimuthal and Mollweide projections.  If used
with the Mollweide projection, the radius value is the value of the
semimajor (horizontal) axis as a percent of the screen width.

-random
Place the observer at a random location.  If no projection is
explicitly specified, orthographic is assumed, but this option may
also be used with any projection except rectangular.

-range range
Render the globe as seen from a distance of range from the planet's
center, in units of the planetary radius.  The default value is 1000.
Note that if you use very close ranges the field of view of the screen
can be a lot greater than 180 degrees!  If you want an "up close" image
use the -radius option.  This option implies -projection orthographic. 

-root
Render to the root window.  This is the default mode.

-rotate angle 
Rotate the globe by angle degrees counterclockwise so that north isn't
at the top.  The default value is 0.  My friends in the Southern
Hemisphere can use -rotate 180 to make the earth look like it should!
If no projection is explicitly specified, orthographic is assumed, but
this option may also be used with any projection except rectangular.
For non-orthographic projections, the globe is rotated and then
projected, if that helps you visualize what to expect.

-shade shade
If -night_image is not specified, set the brightness of the night map
to shade percent of the day map.  If shade is 100, the day and night
maps will be identical.  The default value is 30.

-starfreq frequency
Fraction of background pixels that will be colored white.  The default
value is 0.001. If no projection is explicitly specified, orthographic
is assumed, but this option may also be used with the azimuthal and
Mollweide projections.

-sunrel del_lon,del_lat 
Place the observer directly above (subsolar longitude + del_lon,
subsolar latitude + del_lat).  If no projection is explicitly
specified, orthographic is assumed, but this option may also be used
with any projection except rectangular.

-swap
Swap the red and blue planes in the image.  This option only works 
with the -output option and is useful on big-endian machines.  

-terminator terminator
Place the observer above the specified terminator.  Valid values are
morning or evening.  For non-rectangular projections, the image will
be rotated so the terminator is approximately vertical.  This can be
combined with the -rotate option to orient the terminator any way you
want. 

-version
Display version information.

-window
Render the image to its own X window.  

If no options are specified, the program defaults to -root
-rectangular.  If no image is specified with the -image option,
Xplanet looks in the directory specified with the -mapdir option and
then the directory specified at compilation time (usually
/usr/share/xplanet or /usr/local/share/xplanet) for the file to use as
the day map.  This file should be named body.extension, where body can
be one of the values accepted by the -body option, above.  The
extension of the file by default is jpg but this can also be set at
compilation time.  See the INSTALL file for more details on the
configuration options.

Xplanetbg runs Xplanet every five minutes or other specified interval
(taken from the -wait option, where the time between updates is
specified in seconds).  I did it this way instead of adding -wait as
an option to Xplanet since letting Xplanet run all of the time would
take up a lot of memory.  Otherwise Xplanetbg has the same options as
Xplanet without the -animate option, but with the additional options
below: 

-nice priority
Adjust the priority at which Xplanet runs.  On most systems a priority
of 0 is normal and a value of 19 is the lowest priority. 

-num_times num_times
Number of times Xplanetbg will execute Xplanet.  Without this option
Xplanetbg will run Xplanet indefinitely.  

-orbit orbit_spec
Successive positions of an orbit according to orbit_spec are used as
viewing positions.  orbit_spec has the form <duration>:<inclination>
where duration is the length of one orbit in hours and inclination is
the initial direction from the position specified via the latitude and
longitude options.  Inclinations of 90 or 270 degrees will result in
a movement towards the north or south pole respectively. 

-output filename 
Base name of the output file(s) to create.  If this option is used
with -num_times, the specified number of files will be created, each
with a unique filename.  As an example, if the options "-num_times 100
-output earth.jpg" are given the files earth001.jpg through
earth100.jpg will be created.  If -output is used without -num_times,
the output file will be overwritten each time xplanet executes.
Currently .gif, .jpg, .ppm, .png, and .tiff images can be created.

-timewarp factor
As in xearth, scale the apparent rate at which time progresses by
factor.  The default is 1.

-wait
Time between updates in seconds.

Hari Nair
hari@alumni.caltech.edu
