XPLANET(1)XPLANET(1)NAME
tkxplanet, xplanet, xplanetbg - render an image of a
planet into an X window
SYNOPSIS
tkxplanet
xplanet [options]
xplanetbg [options]
DESCRIPTION
This manual page documents briefly the tkxplanet, xplanet,
and xplanetbg commands.
Xplanet is similar to Xearth, where an image of the earth
is rendered into an X window. Azimuthal, Mercator, Moll
weide, orthographic, Peters, 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.
Xplanetbg spawns an Xplanet process every five minutes or
other user-specified interval to update the image.
TkXplanet is a Tcl/Tk front end to xplanet.
OPTIONS
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 pro
jection is explicitly specified, orthographic is
assumed, but this option may also be used with the
azimuthal, mollweide, and peters projections.
1
XPLANET(1)XPLANET(1)-blend Use bilinear interpolation to compute the color of
each pixel instead of nearest-neighbor interpola
tion. 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 satel
lite. Valid values for body are mercury, venus,
earth, moon, mars, jupiter, io, europa, ganymede,
callisto, saturn, titan, uranus, neptune, pluto,
and random.
-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_gamma gamma
Apply a gamma correction to the cloud image before
overlaying. Each pixel's brightness is adjusted
according to: new_value = 255 *
[(old_value/255)^(1/gamma)]
-cloud_image cloud_file
Use cloud_file as the image to be overlaid. Over
laying 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_ssec option below.
2
XPLANET(1)XPLANET(1)-cloud_ssec cloud_file
Just like -cloud_image but where cloud_file is an
image downloaded from the Space Science and Engi
neering Center (SSEC) at the University of Wiscon
sin. 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 rectan
gular.
-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 eleva
tion 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
3
XPLANET(1)XPLANET(1)
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 speci
fied, orthographic is assumed, but this option may
also be used with any projection except rectangu
lar.
-font fontname
Set the font for the label/markers to fontname.
The default font is "variable" for X11 or
"helr____.ttf" when using the FreeType library.
Either X11 or TrueType fonts may be specified if
support for each is compiled in. The command "xls
fonts" will list all of the fonts that are avail
able on X11. If a TrueType font is specified, this
option implies -truetype.
-fontdir directory
Specify the directory to find the TrueType font to
use. This option may be given more than once.
-fontsize size
Specify the pointsize. The default is 12. This
option only works with TrueType fonts.
-fullscreen
Set the width and height of the window or output
file to the size of the root window. On X11, this
will only work if there is a DISPLAY variable set.
This option implies -window but also can be used
with -output.
-fuzz fuzz
Let the day and night hemispheres blend into one
another for pixels within fuzz degrees of the ter
minator. The default value is 6.
-geometry string
Specify the window geometry using the standard X
window geometry syntax,
[<width>{xX}<height>][{+-}<xoffset>{+-}<yoffset>]
(e.g. 256x256-10+10 puts a window 256x256 pixels in
size 10 pixels away from the right side and 10 pix
els below the top of the root window). This option
implies -window, but can also be used with -animate
or -output.
-gmtlabel
Same as the -label option, but show GMT instead of
local time.
4
XPLANET(1)XPLANET(1)-greatarcfile filename
Use the coordinates in filename to plot arcs of
great circles. Each line should have the following
syntax:
lat1 lon1 lat2 lon2
where all values are in degrees. In addition, the
keywords "color" and "spacing" are supported as in
the example below:
33.9 -118.4 52.3 4.8 color=SpringGreen spacing=0.5 # LAX-AMS
Valid values for "color" are the same as for the
-color option. The value for spacing defines the
distance between dots on the great arc. The
default is 0.1 degree. Delimiters (whitespace,
tabs, foward slashes, or commas) are not permitted
in any of these keyword/value pairs. Anything
after the # character is ignored.
-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; com
bined with the default grid1 value of 6, this cor
responds to placing grid dots on a one degree spac
ing. 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 bot
tom 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. If this option is not spec
ified, the day map will default to body.jpg (e.g.
earth.jpg).
5
XPLANET(1)XPLANET(1)-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 over
head. For orthographic projections the illuminated
fraction is also displayed.
-labelname
Display the body's name in the label. This option
implies -label.
-labelpos string
Specify the location of the label using the stan
dard X window geometry syntax. The default posi
tion 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 speci
fied by -mapdir, and then in the directory speci
fied at compilation time. This option may be spec
ified more than once in order to search multiple
directories.
-markerbounds filename
Write coordinates of the bounding box for each
marker to filename. This might be useful if you're
using xplanet to make imagemaps for web pages.
Each line looks like:
204,312 277,324 Los Angeles
6
XPLANET(1)XPLANET(1)
where the coordinates are for the upper left and
lower right corners of the box.
-markerfile markerfile
Specify a file containing user defined marker data
to display on the map. The format of each line is
generally latitude, longitude, string, as in the
example below:
33.943 -118.408 "Los Angeles" # USA
Anything after a # is ignored.
In addition, Xplanet supports the "align", "color",
"font", "fontsize", "image", "position", "radius",
and "transparent" keywords. If used, keywords must
follow the text string.
The "align" keyword is used to place the marker
string in relation to the marker itself. Valid
"align" values are "right", "left", "above",
"below", or "center". If the "align" keyword is
not specified, Xplanet will attempt to place the
marker string so as not to overlap other markers.
Valid values for "color", "font", and "fontsize"
are the same as for the -color, -font, and -font
size options, respectively. If TrueType fonts are
specified with an X11 display, be sure to specify
-truetype on the command line. At present, you
can't mix X11 and TrueType fonts.
Valid values for "image" are either "none" or the
name of an image file. If the "image" keyword is
not specified, Xplanet will draw a circular marker.
Xplanet looks for image files in the same places it
looks for map files.
Valid values for "position" are "pixel", "sun", or
"moon". If the "position" keyword is not speci
fied, Xplanet assumes the two coordinates given in
the marker file are latitude and then longitude.
The "radius" keyword is used to place the marker at
the specified distance from the planet's center, in
units of the planetary radius. A radius value of 1
places the marker at the planet's surface.
The "transparent" keyword is only meaningful in
conjunction with "image". The format must be
"transparent={R,G,B}" where the RGB values range
from 0 to 255. Any pixels with this color value
will be considered to be transparent.
7
XPLANET(1)XPLANET(1)
Delimiters (whitespace, tabs, forward slashes, or
commas) are not permitted in any of these key
word/value pairs (except for with "transparent", as
shown above). The text string may be enclosed in
either quotes ("") or braces ({}).
Some sample marker file entries are given below:
33.943 -118.408 "Los Angeles" align=below color=blue font=10x20 # USA
33.943 -118.408 {Los Angeles} align=below color=blue font=10x20 # USA
Each of these will draw a circular marker at lati
tude 33.943, longitude -118.408, with a text label
"Los Angeles" below it, colored blue and using font
10x20.
20 10 "This is xplanet" image=none position=pixel
This draws the string "This is xplanet" at pixel
coordinates y=20, x=10, with no marker. (0,0) is
the upper left corner of the screen. If y or x is
negative, it is taken to be the number of pixels
from the bottom or right side of the screen,
respectively.
position=sun image=smile.png transparent={255,255,255}
This draws the image "smile.png" at the subsolar
point. Any pixels with the RGB values
{255,255,255} will be considered transparent.
Using "position=moon" will draw the image at the
sublunar point.
-1.12479 251.774 radius=1.09261 {HST}
This draws a circular marker for the Hubble Space
Telescope above latitude -1.12479, longitude
251.774 degrees, at a distance of 1.09261 earth
radii from the center of the earth and labels it
"HST".
This option implies -markers. The -markerfile
option may be used more than once if you want to
use more than one marker file.
-markers
Enable markers, as in xearth.
-moonside
Render the image as seen from the moon. If no pro
jection 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, a default night map will
be used for the earth. If this file is not found,
8
XPLANET(1)XPLANET(1)
or for the other planets, 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 explic
itly 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. Cur
rently .gif, .jpg, .ppm, .png, and .tiff images can
be created. The image size defaults to 512 by 512
pixels but this may be changed by the -geometry
flag.
-projection projection_type
The projection type may be one of ancient,
azimuthal, hemisphere, mercator, mollweide, peters,
orthographic, or rectangular.
-quality
This option is only used when creating JPEG images.
The quality can range from 0 to 100. The default
value is 80.
-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 projec
tion, the radius value is the value of the semima
jor (horizontal) axis as a percent of the screen
width. When drawing Saturn in an orthographic pro
jection, the radius value applies to the radius of
9
XPLANET(1)XPLANET(1)
the outer ring.
-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 ortho
graphic.
-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 visu
alize what to expect.
-satfile satfile
Specify a file containing a list of satellites to
display. A file containing NORAD two line element
(TLE) sets named satfile.tle must exist along with
satfile. A good source of TLEs is
www.celestrak.com. A sample TLE entry for the
International Space Station looks like this:
ISS (ZARYA)
1 25544U 98067A 01286.44085648 .00059265 00000-0 81723-3 0 5959
2 25544 51.6394 213.7002 0007838 194.2620 314.2054 15.56596996165535
Each line in satfile must begin with a satellite ID
number (e.g. 25544 for the ISS). Each ID must
exist in the associated TLE file.
Valid additional keywords are "align", "altcirc",
"color", "font", "fontsize", "image", "position",
"radius", "spacing", "trail", and "transparent".
The usage for most of these is identical to the
usage for the -greatarcfile and -markerfile
10
XPLANET(1)XPLANET(1)
options. In addition, a string to be plotted with
the marker may be enclosed in either double quotes
(""), or braces ({}). If a string is not supplied,
the marker will take the name of the satellite sup
plied in the TLE file.
The "altcirc" keyword draws altitude circles on the
surface of the earth. The format is "alt
circ=angle", where a circle is drawn bounding the
area where the satellite is greater than angle
degrees above the horizon. For example, altcirc=0
draws a circle bounding the region where the satel
lite is above the horizon, while altcirc=45 draws a
circle bounding the region where the satellite is
more than 45 degrees above the horizon. This may
be specified more than once.
The "trail" keyword is used to specify an orbit
trail. The format must be
"trail={ground|orbit,length,interval}", where
length and interval are each in minutes. Specify
ing "orbit" is only meaningful for the orthographic
projection.
A few sample entries are given below:
25544
This draws a marker with the string "ISS (ZARYA)"
for the International Space Station.
25544 "The Space Station"
This draws a marker with the string "The Space Sta
tion" for the International Space Station.
25544 "" image=iss.png transparent={0,0,0} altcirc=0
This draws iss.png at the current position of the
International Space Station. No text string is
drawn. A curve containing the area where the
International Space Station is above the horizon is
drawn.
25544 "" image=iss.png transparent={0,0,0} altcirc=0 altcirc=45 trail={orbit,10,2}
As the previous example, but also draw the orbit
trail for the last ten minutes, calculated every
two minutes. A second altitude circle bounding the
region where the International Space Station is
more than 45 degrees above the horizon is also
drawn.
The -satfile option may be given more than once in
order to use multiple satellite files.
-sattrackid id
Set the observer latitude and longitude to be those
11
XPLANET(1)XPLANET(1)
of the specified satellite. The -satfile option
must also be used for -sattrackid to work. For
example, -sattrackid 25544 will place the observer
above the latitude and longitude of the Interna
tional Space Station.
-shade shade
If the night image file is not found, 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 projec
tion is explicitly specified, orthographic is
assumed, but this option may also be used with the
azimuthal, mollweide, and peters projections.
-sunrel del_lon,del_lat
Place the observer directly above (subsolar longi
tude + 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-rect
angular 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.
-transpng
Set the background to be transparent when writing a
PNG file. This option doesn't work properly with
X11 fonts, so use truetype fonts with an X display.
-truetype
Use TrueType fonts. This option is only useful
with X11, where X11 fonts are used by default. You
will need to use this if you are using an X11 dis
play and want to use TrueType fonts in the marker
file. At present, you can't mix X11 and TrueType
fonts.
-version
Display version information.
12
XPLANET(1)XPLANET(1)-window
Render the image to its own X window. The size
defaults to 512 by 512 pixels but this may be set
by the -geometry flag.
-xscreensaver
Use this option when running xplanet/xplanetbg from
xscreensaver.
If no options are specified, the program defaults to -root
-projection rectangular.
Xplanet searches for files in the following order:
TrueType fonts: First look in fontdir (if the -fontdir
option is used), then in the current directory, then in a
subdirectory "fonts" of the current directory, and finally
in $PREFIX/fonts. The default font is helr____.ttf. Note
that TrueType fonts are only used if an X11 display is not
available, a TrueType font is specified with the -font
option, or the -truetype option is specified.
image files: First look in mapdir (if the -mapdir option
is used), then in the current directory, then in a subdi
rectory "images" of the current directory, and finally in
$PREFIX/images. The default name is body.jpg (e.g.
earth.jpg, neptune.jpg). The extension of the file by
default is jpg but this can also be set at compilation
time.
marker files: First look in the current directory, then in
a subdirectory "markers" of the current directory, and
finally in $PREFIX/markers. The default marker file name
is body (e.g. earth, neptune).
satellite files: First look in the current directory, then
in a subdirectory "satellites" of the current directory,
and finally in $PREFIX/satellites.
The value of $PREFIX is set at compilation time in aux
files.h. On a Unix system it is usually /usr/free
ware/share/xplanet, and on Windows it is usually C:\WIN
DOWS\Desktop. See the INSTALL file for more details on
the configuration options.
Xplanetbg runs Xplanet every five minutes or other speci
fied 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 addi
tional options below:
13
XPLANET(1)XPLANET(1)-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 num
ber 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.
-post_command command
Run the specified command after each execution of
Xplanet.
-prev_command command
Run the specified command before each execution of
Xplanet.
-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.
SEE ALSO
The latest version may be found at
http://xplanet.sourceforge.net
14
XPLANET(1)XPLANET(1)FILES
/usr/freeware/bin/xplanet
/usr/freeware/bin/xplanetbg
/usr/freeware/bin/tkxplanet
/usr/freeware/bin/tzcoord.pl
/usr/freeware/man/man1/xplanet.1
/usr/freeware/man/man1/xplanetbg.1
/usr/freeware/man/man1/tkxplanet.1
/usr/freeware/man/man1/tzcoord.pl.1
/usr/freeware/share/xplanet/rgb.txt
/usr/freeware/share/xplanet/fonts/helr____.ttf
/usr/freeware/share/xplanet/images/body.jpg
/usr/freeware/share/xplanet/markers/body
where body is the name of the appropriate body, specified in the -body
option.
The default prefix /usr/freeware/share/xplanet is set in
auxfiles.h and may be changed if desired.
AUTHOR
xplanet was written by Hari Nair <hari@alumni.caltech.edu>
This manual page was written by Detlev Zundel <Detlev.Zun
del@stud.uni-karlsruhe.de> and Hari Nair for the Debian
GNU/Linux system (but may be used by others).
15
