manpagez: man pages & more
man xplanet(1)
Home | html | info | man
xplanet(1)                                                          xplanet(1)


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


       xplanet [options]


       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  rectangu-
       lar.   The latest version can always be found at http://xplanet.source-


       Options need only be specified with enough characters to  be  unambigu-
       ous.  Valid options to Xplanet are:

              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  con-
              figuration 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, pho-
              bos,  deimos,  jupiter,  io, europa, ganymede, callisto, saturn,
              mimas, enceladus, tethys, dione, rhea, titan, hyperion, iapetus,
              phoebe,  uranus,  miranda, ariel, umbriel, titania, oberon, nep-
              tune, 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 exam-
              ple, "-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  direc-
              tion 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

       -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  con-
              fig_file  is described in README.config.  See the description of
              -searchdir to see where xplanet looks in order to find the  con-
              figuration 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 (, which reads both
              big  and  little endian binary files.  The ephemeris files found
              at  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 Win-
              dows 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.

              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  sec-
              onds,  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 speci-
              fied  number  of  seconds.  This option requires xplanet to have
              been compiled with the X Screensaver extension.

              This option is only useful in conjunction with -origin_file.  It
              computes  the  observer position at the current time by interpo-
              lating 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.

              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.

              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.

              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.

              Account  for the time it takes for light to travel from the tar-
              get 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

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

              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_file-
              name.extension".   The  dimensions  of the output images are the
              same as the day image.

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

              -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  configura-
              tion file.

       -markerbounds filename
              Write  coordinates  of the bounding box for each marker to file-
              name.  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  indefi-

       -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

       -origin_file origin_file
              Specify  a list of observer positions in origin_file.  The posi-
              tions 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

       -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  com-
              piled  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  (  library  for  rendering
              internationalized text. Pango uses Unicode for all of its encod-
              ing, 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 veloc-
              ity  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  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  pro-
              jections  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.

              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 pro-
              jected, if that helps you visualize what to expect.

              On Microsoft Windows and Mac OS X, xplanet creates an intermedi-
              ate 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 follow-
              ing   directories  depending  on  its  type:  "arcs",  "config",
              "ephemeris", "fonts",  "images",  "markers",  "origin",  "satel-
              lites", or "stars".  By default, xplanet will look for a file in
              the following order:

              The current directory
              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 loca-
              tion 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 ker-
              nel files.  This option may be used more than once for different

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

              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  cre-
              ated using -make_cloud_maps.  On Microsoft Windows, xplanet will
              write a bitmap file called xplanet.bmp to the  specified  direc-
              tory.  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  intermedi-
              ate file will be removed unless the -save_desktop_file option is

              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.

              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.

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

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

       -wait wait
              Update every wait seconds.

              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.

              Same as -vroot.


xplanet 1.3.1 - Generated Fri Apr 29 08:45:29 CDT 2016
© 2000-2021
Individual documents may contain additional copyright information.