Xplanet 0.43
Dec 06 1999

Xplanet is similar to Xearth, where an image of the earth is rendered
into an X window.  Both mercator and orthographic projections can be
displayed as well as a window with a globe the user can rotate
interactively.  The other terrestrial planets may also be displayed.
The latest version can be found at
http://www.alumni.caltech.edu/~hari/xplanet

Most of the algorithms are taken from "Astronomical Formulae for
Calculators" by Jean Meeus, published by Willman-Bell.  The rotational
parameters for the other terrestrial planets are taken from "Practical
Ephemeris Calculations" by Oliver Montenbruck, published by
Springer-Verlag.  Rotational parameters for the Moon are taken from
Davies et al. (1996), Celestial Mechanics 63, 127--148.

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.  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.  This option implies --orthographic. 

--blend
When computing the orthographic projection, take an area weighted
average of the four pixels nearest the intersection of the line of
sight and the globe.  This is similar to the GL_LINEAR option when
texture mapping in OpenGL.  It slows down the computation, but it can
look a lot better, particularly if you're using a low resolution map.
This option implies --orthographic. 

--body body
Render an image of the specified planet:
body       planet
< 0        random
0          earth
1          Mercury
2          Venus
3          moon
4          Mars

--center x,y
Place the center of the globe at (x,y).  You can use this with the
--radius option to put a small globe anywhere on the screen.  

--cloud_image cloud_file
Use cloud_file as the image to be overlaid.  Overlaying clouds slows
Xplanet down considerably (but it looks really nice).  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.

--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.  This
option implies --orthographic.

--demfile dem_file
Use dem_file 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.  

--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.  This option implies
--orthographic. 

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

--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 spacing
Draw a longitude/latitude grid.  The gridlines will be spaced every
90/spacing degrees.  A grid value of 6 will space longitude/latitude
lines every 15 degrees.

--gridspace spacing
Number of dots per 90 degrees of longitude/latitude.  The default is
90, so if --grid is specified without --gridspace, one dot per degree
will be used.

--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 left corner which indicates the current
time and subsolar point.  For orthographic projections the position
where the observer is directly overhead and the illuminated fraction
are 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.
This option implies --orthographic.

--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 
Render the globe as seen from 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.  If displaying a
mercator projection, the image will be centered on the meridian
specified.  For an orthographic projection, the observer will be above
the meridian specified.

--marker_file marker_file
A file containing user defined marker data to display on the globe.
The format is the same as the marker file used by xearth.  An example
from the xearth man page is:
  42.33 -71.08 "Boston, MA"    # USA
If no marker_file is specified, the program defaults to the file named
in auxfiles.h.  This option implies --markers.

--markers
Enable markers, as in xearth.

--mercator                
Render the image as a mercator (flat) projection.  This is the default.

--moonside                   
Render the image as seen from the moon.  This option implies
--orthographic.  

--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.
This option implies --orthographic.

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

--observer x,y
Place the observer at longitude x, latitude y.  This option is
equivalent to --longitude x --latitude y.

--orthographic
Render the image as an orthographic projection.

--output filename
Output to a file instead of rendering to a window.  The file format is
taken from the extension (such as .jpg, .ppm, .png, .tiff, etc.).  The
extension supplied must be one recognized by imlib.  If no extension
is given .ppm will be assumed.

--radius radius 
Render the globe with a radius of radius percent of the screen height.
The default value is 50% of the screen height.  This option implies
--orthographic.

---random
View the globe from a random position.  This option implies
--orthographic.

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

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

--rotate angle 
Rotate the rendered 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!  This option implies --orthographic.

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

--star_den density
Fraction of background pixels that will be colored white.  The default
value is 0.001.  This option implies --orthographic.

--sunrel del_lon,del_lat
Place the observer directly above (subsolar longitude + del_lon,
subsolar latitude + del_lat).

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

--version
Display version information.

--window
Render the image to its own X window.  

An image file must be specified.  If none is specified with the
--image option, Xplanet looks in the directory specified in auxfiles.h
for the file to use as the day map.  This file should be named
body.ppm, where body can be mercury, venus, earth, moon, or mars.  The
.ppm extension may be changed to another file type when configuring
the package before compilation.  If no options are specified, the
program defaults to --root --mercator.

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: 

--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.  The extension supplied must be one recognized by imlib.  If
no extension is given .ppm will be assumed.  

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