Man Linux: Main Page and Category List

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.

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

       -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_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_title title
              Set the window’s title to title.  This option implies -window.

       -xscreensaver
              Same as -vroot.