Provided by: xplanet_1.3.1-3build1_amd64 bug

NAME

       xplanet - render an image of a planet into an X window or file

SYNOPSIS

       xplanet [options]

DESCRIPTION

       Xplanet  is  similar  to Xearth, where an image of the earth is rendered into an X window.
       All of the major planets and most satellites can be drawn.   A  number  of  different  map
       projections  are  also  supported, including azimuthal, Mercator, Mollweide, orthographic,
       and    rectangular.     The    latest    version    can     always     be     found     at
       http://xplanet.sourceforge.net.

OPTIONS

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

       -arc_file
              Specify an arc file to be plotted against the background stars.  Each line  in  the
              file must have the following syntax:

              dec1 ra1 dec2 ra2

              where  declination  is in degrees and right ascension is in hours.  This option has
              no effect if -projection is specified.

       -arc_spacing spacing
              When drawing an arc, draw line  segments  that  are  spacing  degrees  apart.   The
              default is 0.1 degrees.  Line segments shorter than spacing will not be drawn.

       -arc_thickness thickness
              Specify  the  thickness  of  arcs.  The default is 1 pixel.  When drawing arcs on a
              planet using the arc_file option in the configuration file, use  the  arc_thickness
              option there too.

       -background background_file
              Use  background_file  as  the  background image, with the planet to be superimposed
              upon it.  A color may also be supplied (e.g. -background "navy blue" or -background
              0xff00ff).

       -base_magnitude magnitude
              A  star  of the specified magnitude will have a pixel brightness of 1.  The default
              value is 10.  Stars will be drawn more brightly if this number is larger.

       -body body
              Render an image of the specified planet or satellite.  Valid values  for  body  are
              sun,  mercury,  venus,  earth,  moon,  mars,  phobos,  deimos, jupiter, io, europa,
              ganymede, callisto, saturn, mimas, enceladus, tethys, dione, rhea, titan, hyperion,
              iapetus, phoebe, uranus, miranda, ariel, umbriel, titania, oberon, neptune, triton,
              nereid, pluto, charon, random, and major.

              The field of view can also be centered on a  satellite  location  using  "naif"  or
              "norad", along with the satellite id.  For example, "-body naif-82" will center the
              field of view on NAIF ID -82, which  is  the  Cassini  orbiter.   Xplanet  must  be
              compiled  with  SPICE  support  and  the required kernels must be present.  See the
              README in the spice subdirectory for more details.  Using "-body  norad20580"  will
              center  the  field  of view on NORAD ID 20580, which is the Hubble Space Telescope.
              The appropriate TLE files must be present in this case.   See  the  README  in  the
              satellites subdirectory for more information.

              Using  "path"  will  center  the  field  of  view on the direction of motion of the
              origin.  This direction is  relative  to  the  direction  of  motion  of  the  body
              specified by -path_relative_to.

              Earth is the default body.  This option is the same as -target.

       -center +x+y
              Place  the center of the rendered body at pixel coordinates (x, y).  The upper left
              corner of the screen is at (0,0). Either x or y may be negative.  The default value
              is the center of the screen.

       -color color
              Set  the color for the label.  The default is "red".  Any color in the rgb.txt file
              may be used.  Colors may also be specified by RGB hex values;  for  example  -color
              0xff and -color blue mean the same thing, as do -color 0xff0000 and -color red.

       -config config_file
              Use  the configuration file config_file.  The format of config_file is described in
              README.config.  See the description of -searchdir to see  where  xplanet  looks  in
              order to find the configuration file.

       -create_scattering_tables scattering_file
              Create  lookup  tables  for  Rayleigh scattering.  See the README in the scattering
              directory for more information.

       -date YYYYMMDD.HHMMSS
              Use the date specified instead of the current local time.  The date is  assumed  to
              be GMT.

       -date_format string
              Specify  the  format  for  the  date/time  label.   This format string is passed to
              strftime(3).  The default is "%c %Z", which shows the date, time, and time zone  in
              the locale's appropriate date and time representation.

       -dynamic_origin file
              Specify  an observer location.  The location is relative to the body specified with
              -origin (by default, this is the Sun).  The last line of the file must  be  of  the
              form

              YYYYMMDD.HHMMSS range lat lon localtime

              For example,

              19951207.120000     10.328   -3.018   97.709    9.595

              The  specified  time  is  ignored  and  the  current time is used.  The range is in
              planetary radii, and lat and lon are in degrees.  Localtime (in hours) is optional,
              but  if  present, it will be used in place of the longitude.  Only the last line of
              the file is used.  This file may be  updated  between  renderings  using  a  script
              executed with the -prev_command or -post_command options.

       -ephemeris_file filename
              Specify  a JPL digital ephemeris file (DE200, DE405, or DE406) to use for computing
              planetary      positions.       Xplanet      uses      Bill       Gray's       code
              (http://www.projectpluto.com/jpl_eph.htm),  which  reads both big and little endian
              binary       files.        The        ephemeris        files        found        at
              ftp://ssd.jpl.nasa.gov/pub/eph/export/unix  are  big  endian  files, but you do not
              need to do any additional byte-swapping  to  use  them.   See  the  description  of
              -searchdir to see where xplanet looks in order to find the ephemeris file.

       -font fontname
              Set  the  font  for  the  label.  Only TrueType fonts are supported.  If the -pango
              option is used, fontname is taken to be the font family name (e.g. "Arial").

       -fontsize size
              Specify the point size.  The default is 12.

       -fork  Detach from the controlling terminal.  This is useful on MS Windows to run  xplanet
              from  a batch file without having to keep a DOS window open.  Be careful when using
              this option; it's easy to have multiple processes running at the same time  without
              knowing  it - check the Task Manager.  On unix systems this is pretty much the same
              as running xplanet in the background.

       -fov   Specify the field of view, in degrees.  This option  and  the  -radius  option  are
              mutually exclusive.  This option has no effect if the -projection option is used.

       -geometry string
              Specify   the   image  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).  The root window outside of the image will be black.  This
              option may be used with -window or -output.

       -glare radius
              Draw  a  glare around the sun with with a radius of the specified value larger than
              the sun.  The default value is 28.

       -gmtlabel
              Same as the -label option, but show GMT instead of local time.

       -grs_longitude lon
              The longitude of Jupiter's Great Red Spot (GRS).  A typical value  is  94  degrees.
              If  this option is specified, longitudes on Jupiter will be calculated in System II
              coordinates.  By default, longitudes are  calculated  in  System  III  coordinates.
              When using this option, use an image map for Jupiter where the center of the GRS is
              at the pixel 0 column, or the left side of the image.

       -hibernate seconds
              After the screen has been idle for the specified number of  seconds,  xplanet  will
              sleep.   This  option requires xplanet to have been compiled with the X Screensaver
              extension.

       -idlewait seconds
              Don't run Xplanet unless the screen has been  idle  for  the  specified  number  of
              seconds.  This option requires xplanet to have been compiled with the X Screensaver
              extension.

       -interpolate_origin_file
              This option is only useful in  conjunction  with  -origin_file.   It  computes  the
              observer  position at the current time by interpolating between values specified in
              the origin file.  This is useful if you have spacecraft positions tabulated  in  an
              origin file, but want a real time view.

       -jdate Julian date
              Use the specified Julian date instead of the current local time.

       -label Display a label in the upper right corner.

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

       -label_altitude
              Display  the altitude above the surface instead of distance from the body center in
              the label.

       -label_body body
              Use the specified body to calculate the sub-observer, sub-solar,  and  illumination
              values in the label.  This is useful with the -separation option.

       -label_string
              Specify  the  text  of  the first line of the label.  By default, it says something
              like "Looking at Earth".  Any instances of %t will be replaced by the target  name,
              and any instances of %o will be replaced by the origin name.

       -latitude latitude
              Render the target body as seen from above the specified latitude (in degrees).  The
              default value is 0.

       -light_time
              Account for the time it takes for light to travel  from  the  target  body  to  the
              observer.  The default is to ignore the effects of light time.

       -localtime localtime
              Place the observer above the longitude where the local time is the specified value.
              0 is midnight and 12 is noon.

       -log_magstep step
              Increase the brightness  of  a  star  by  10^step  for  each  integer  decrease  in
              magnitude.   The  default  value  is 0.4.  This means that a star of magnitude 2 is
              10^0.4 (about 2.5) times brighter than a star of  magnitude  3.   A  larger  number
              makes stars brighter.

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

       -make_cloud_maps
              If  there  is  an entry in the config file for cloud_map, xplanet will output a day
              and night image with clouds overlaid and then exit.  The images will be created  in
              the  directory  specified by -tmpdir, or in the current directory if -tmpdir is not
              used.   The  names  of  the   output   images   default   to   day_clouds.jpg   and
              night_clouds.jpg,   but  may  be  changed  by  the  -output  option.   If  "-output
              filename.extension"   is   specified,   the   output   images   will    be    named
              "day_filename.extension"  and  "night_filename.extension".   The  dimensions of the
              output images are the same as the day image.

       -marker_file
              Specify a  file  containing  user  defined  marker  data  to  display  against  the
              background  stars.  The  format  of  each  line  is  generally  declination,  right
              ascension, string, as in the example below:

              -16.7161 6.7525 "Sirius"

              For additional options which  may  be  specified,  see  the  marker_file  entry  in
              README.config.  This option has no effect if -projection is specified.  This option
              is not meant for  city  markers;  for  that  use  the  marker_file  option  in  the
              configuration file.

       -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.
              This file gets rewritten every time xplanet renders its image.

       -north north_type
              This option rotates the image so that the top points to north_type.   Valid  values
              for north_type are:

              body:        body's north pole
              galactic:    galactic north pole
              orbit:       body's orbital north pole (perpendicular to the orbit plane)
              path:        origin's velocity vector  (also see -path_relative_to option)
              separation:  perpendicular to the line of sight and the
                           target-separation target line (see -separation option)

              The default value is "body".

       -num_times num_times
              Run num_times before exiting.  The default is to run indefinitely.

       -origin body
              Place  the observer at the center of the specified body.  Valid values are the same
              as for -target.  In addition, "above",  "below",  or  "system"  may  be  specified.
              Using  "above"  or  "below" centers the view on the body's primary and the field of
              view is large enough to show the body's orbit.  Using "system" places the  observer
              at  the  center of a random body in the same system as the target body.  Two bodies
              are in the same system if one of the following is true:

               1) target and origin have same primary
               2) target is origin's primary
               3) origin is target's primary

              If the body name is preceded by a dash, the observer is placed on the opposite side
              of  the  target from the specified body at a distance equal to the distance between
              the target and body.  For example, -target earth -origin sun places the observer at
              the  center  of  the  sun.   If -target earth -origin -sun is used, the observer is
              placed on a line connecting the centers of the earth and sun at a distance of 1  AU
              farther from the sun than the earth.

       -origin_file origin_file
              Specify a list of observer positions in origin_file.  The positions are relative to
              the body specified with -origin (by default, this is the Sun).  Each line should be
              of the form

              YYYYMMDD.HHMMSS range lat lon localtime

              For example,

              19951207.120000     10.328   -3.018   97.709    9.595

              Range  is in planetary radii, and lat and lon are in degrees.  The date is the only
              required value.  If the localtime (in hours) is supplied, it will be used in  place
              of  the longitude.  For each line in the origin file, the observer is placed at the
              specified position, relative to the body specified with -origin.   This  option  is
              useful  for showing spacecraft flybys or orbiting around a planet.  Any line with a
              # in the first column is ignored.

       -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,
              if xplanet has been compiled  with  the  appropriate  libraries.   The  image  size
              defaults  to  512  by  512 pixels but this may be changed by the -geometry flag. If
              used with the -num_times option, each output file will be numbered sequentially.

       -output_map filename
              Output the intermediate rectangular map that is created in the process of rendering
              the final image.  It will have the same dimensions as the default day map.

       -output_start_index index
              Start numbering output files at index.  The default is 0.

       -pango Use  the Pango (http://www.pango.org) library for rendering internationalized text.
              Pango uses Unicode for all of its encoding, and will eventually support  output  in
              all the worlds major languages.  If xplanet has not been compiled with this library
              this option will be ignored.  There appear to be memory leaks in the pango library,
              so I don't recommend letting xplanet run indefinitely with this option.

       -path_relative_to body
              Only  used  with  -north  path  or  -target  path.  The origin's velocity vector is
              calculated relative to the specified body.  By default, this is the Sun.

       -post_command command

       -prev_command command
              Run command either before or after each time  xplanet  renders  an  image.   On  MS
              Windows, you may need to use unix-style paths.  For example:

              xplanet.exe -prev_command ./prev.bat

       -print_ephemeris
              Print  the  heliocentric  rectangular  equatorial coordinates (J2000) for each body
              xplanet knows about, and then exit.

       -projection projection_type
              The projection type may be one of ancient, azimuthal, bonne, equal_area,  gnomonic,
              hemisphere,   lambert,   mercator,   mollweide,  orthographic,  peters,  polyconic,
              rectangular, or tsc.  The default is no projection.  Multiple bodies  will  not  be
              shown if this option is specified, although shadows will still be drawn.

       -proj_param value
              Pass  additional  parameters  for  some projections.  The only projections that use
              this option at present are the Bonne,  Gnomonic,  and  Mercator  projections.   The
              Bonne  projection  is conformal at the specified latitude.  Higher values lead to a
              thinner heart shape.  The  default  is  50  degrees.   The  Gnomonic  and  Mercator
              projections  use  the  specified latitude as the boundaries of the projection.  The
              defaults are 45 and 80 degrees, respectively.  This option may be  used  more  than
              once  for  future  projections  that require additional parameters.  Only the first
              value is used at present.

       -quality 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
              Specify  the  radius  of  the globe as a percent of the screen height.  The default
              value is 45% of the screen height.  When drawing Saturn, the radius  value  applies
              to the radius of the outer ring.

       -random
              Place the observer above a random latitude and longitude.

       -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 greater than 180 degrees!
              If you want an "up close" image use the -radius option.

       -rotate angle
              Rotate the globe by angle degrees counterclockwise so that north (as defined by the
              -north  argument)  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!  For
              non-orthographic  projections,  the  globe  is  rotated and then projected, if that
              helps you visualize what to expect.

       -save_desktop_file
              On Microsoft Windows and Mac OS X, xplanet creates an intermediate image file which
              is  used  to  set the desktop.  This file will be created in the -tmpdir directory.
              By default, this image is removed after the desktop has been set.  Specifying  this
              option will leave the file in place.

       -searchdir directory
              Any  files  used  by  xplanet  should be placed in one of the following directories
              depending on its type: "arcs", "config", "ephemeris", "fonts", "images", "markers",
              "origin",  "satellites",  or  "stars".  By default, xplanet will look for a file in
              the following order:

              The current directory
              searchdir
              subdirectories of searchdir
              subdirectories of xplanet (if it exists in the current directory)
              subdirectories of ${HOME}/.xplanet on X11
              subdirectories of ${HOME}/Library/Xplanet on Mac OS X
              subdirectories of DATADIR/xplanet

              DATADIR is set at compile time and defaults to /usr/local/share.

       -separation body:dist
              Place the observer at a location where the target body and the separation body  are
              dist  degrees  apart.   For example "-target earth -separation moon:-3" means place
              the observer at a location where the moon appears 3 degrees  to  the  left  of  the
              earth.

       -spice_ephemeris index
              Use SPICE kernels to compute the position of the named body.  The index is the naif
              ID code (e.g. 599 for Jupiter).  The -spice_file option must be used to supply  the
              names  of  the  kernel files.  This option may be used more than once for different
              bodies.

       -spice_file spice_file
              Specify a file containing a list of objects to display.  A file containing  a  list
              of  SPICE  kernels  to  read named spice_file.krn must exist along with spice_file.
              See the README in the "spice" subdirectory for more information.

       -starfreq frequency
              Fraction of background pixels that will be colored white.   The  default  value  is
              0.001.  This option is only meaningful with the azimuthal, mollweide, orthographic,
              and peters projections.

       -starmap starmap
              Use starmap to draw the background stars.  This file should be a  text  file  where
              each line has the following format:

              Declination, Right Ascension, Magnitude

              where  Declination  is  in decimal degrees and Right Ascension is in decimal hours.
              For example, the entry for Sirius is

              -16.7161  6.7525 -1.46

              See the description of -searchdir to see where xplanet looks in order to  find  the
              star map.

       -target target
              Same as -body.

       -tt    Use terrestrial time instead of universal time.  The two differ slightly due to the
              non-uniform rotation of the earth.  The default is to use universal time.

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

       -tmpdir tmpdir
              Specify   a  directory  that  xplanet  will  use  to  place  images  created  using
              -make_cloud_maps.  On Microsoft Windows, xplanet will write a  bitmap  file  called
              xplanet.bmp  to  the  specified  directory.   The  default  is  the  result  of the
              GetWindowsDirectory call (C:WINDOWS on Win95).  On Mac OS X, xplanet will create an
              intermediate  PNG  file in order to set the background.  The default value is /tmp.
              On Windows and Mac  OS  X,  the  intermediate  file  will  be  removed  unless  the
              -save_desktop_file option is specified.

       -transparency
              Update  the  background pixmap for transparent Eterms and aterms.  This option only
              works under X11.

       -transpng filename
              Same as the -output option, except  set  the  background  to  be  transparent  when
              writing a PNG file.

       -utclabel
              Same as -gmtlabel.

       -verbosity level

              level      output
              < 0        only fatal error messages
              0          non-fatal warning messages
              1          basic information
              2          basic diagnostics
              3          more detailed diagnostics
              4          very detailed diagnostics

              The default value is 0.

       -version
              Display current version information, along with a list of compile-time options that
              xplanet supports.

       -vroot Render the image to the virtual root window.  Some  window  managers  use  one  big
              window   that   sits  over  the  real  root  window  as  their  background  window.
              Xscreensaver uses a virtual root window to cover the screen as well.

       -wait wait
              Update every wait seconds.

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

       -window-id ID
              When using the X11 windowing system, draw to the window with the specified ID.

       -window_title title
              Set the window's title to title.  This option implies -window.

       -XID ID
              Same as -window-id.

       -xscreensaver
              Same as -vroot.

                                                                                       XPLANET(1)