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, Mollweide, 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 projection is explicitly specified, orthographic is assumed, but this option may also be used with the azimuthal, mollweide, and peters 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, 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. 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_ssec option below.

-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" 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 "xlsfonts" will list all of the fonts that are available on X11. If a TrueType font is specified, this option implies -truetype.

-fontdir directory
    Specify the directory to find the TrueType font to use.

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

-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; 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. If this option is not specified, the day map will default to body.jpg (e.g. earth.jpg).

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

-labelname
    Display the body's name in the label. This option implies -label.

-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 then in the directory specified at compilation time.

-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 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", 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 -fontsize 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 specified, Xplanet assumes the two coordinates given in the marker file are latitude and then longitude. 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. Delimiters (whitespace, tabs, forward slashes, or commas) are not permitted in any of these keyword/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 latitude 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.gif transparent={255,255,255}
    This draws the image "smile.gif" 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. 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 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, a default night map will be used for the earth. If this file is not found, 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 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. 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 projection, the radius value is the value of the semimajor (horizontal) axis as a percent of the screen width. When drawing Saturn in an orthographic projection, the radius value applies to the radius of 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 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 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 projection 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 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.

-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 display and want to use TrueType fonts in the marker file. At present, you can't mix X11 and TrueType fonts.

-version
    Display version information.

-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 -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 subdirectory "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). The value of $PREFIX is set at compilation time in auxfiles.h. On a Unix system it is usually /usr/local/share/xplanet, and on Windows it is usually C:WINDOWSe 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.

-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

FILES

/usr/local/bin/xplanet
/usr/local/bin/xplanetbg
/usr/local/bin/tkxplanet
/usr/local/bin/tzcoord.pl
/usr/local/man/man1/xplanet.1
/usr/local/man/man1/xplanetbg.1
/usr/local/man/man1/tkxplanet.1
/usr/local/man/man1/tzcoord.pl.1
/usr/local/share/xplanet/rgb.txt
/usr/local/share/xplanet/fonts/helr____.ttf
/usr/local/share/xplanet/images/body.jpg
/usr/local/share/xplanet/markers/body
where body is the name of the appropriate body, specified in the -body
option.

The default prefix /usr/local/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.Zundel@stud.uni-karlsruhe.de> and Hari Nair for the Debian GNU/Linux system (but may be used by others).