1XPLANET(1) General Commands Manual XPLANET(1)
2
6 xplanet - render an image of a planet into an X window or file
7
9 xplanet [options]
10
13 Xplanet is similar to Xearth, where an image of the earth is rendered
14 into an X window. All of the major planets and most satellites can be
15 drawn. A number of different map projections are also supported,
16 including azimuthal, Mercator, Mollweide, orthographic, and rectangu‐
17 lar. The latest version can always be found at http://xplanet.source‐
18 forge.net.
19
22 Options need only be specified with enough characters to be unambigu‐
23 ous. Valid options to Xplanet are:
24 -arc_file
27 Specify an arc file to be plotted against the background stars.
28 Each line in the file must have the following syntax:
29 dec1 ra1 dec2 ra2
31 where declination is in degrees and right ascension is in hours.
33 This option has no effect if -projection is specified.
34 -arc_spacing spacing
37 When drawing an arc, draw line segments that are spacing degrees
38 apart. The default is 0.1 degrees. Line segments shorter than
39 spacing will not be drawn.
40 -arc_thickness thickness
43 Specify the thickness of arcs. The default is 1 pixel. When
44 drawing arcs on a planet using the arc_file option in the con‐
45 figuration file, use the arc_thickness option there too.
46 -background background_file
49 Use background_file as the background image, with the planet to
50 be superimposed upon it. A color may also be supplied (e.g.
51 -background "navy blue" or -background 0xff00ff).
52 -base_magnitude magnitude
55 A star of the specified magnitude will have a pixel brightness
56 of 1. The default value is 10. Stars will be drawn more
57 brightly if this number is larger.
58 -body body
61 Render an image of the specified planet or satellite. Valid
62 values for body are sun, mercury, venus, earth, moon, mars, pho‐
63 bos, deimos, jupiter, io, europa, ganymede, callisto, saturn,
64 mimas, enceladus, tethys, dione, rhea, titan, hyperion, iapetus,
65 phoebe, uranus, miranda, ariel, umbriel, titania, oberon, nep‐
66 tune, triton, nereid, pluto, charon, random, and major.
67 The field of view can also be centered on a satellite location
69 using "naif" or "norad", along with the satellite id. For exam‐
70 ple, "-body naif-82" will center the field of view on NAIF ID
71 -82, which is the Cassini orbiter. Xplanet must be compiled
72 with SPICE support and the required kernels must be present.
73 See the README in the spice subdirectory for more details.
74 Using "-body norad20580" will center the field of view on NORAD
75 ID 20580, which is the Hubble Space Telescope. The appropriate
76 TLE files must be present in this case. See the README in the
77 satellites subdirectory for more information.
78 Using "path" will center the field of view on the direction of
80 motion of the origin. This direction is relative to the direc‐
81 tion of motion of the body specified by -path_relative_to.
82 Earth is the default body. This option is the same as -target.
84 -center +x+y
87 Place the center of the rendered body at pixel coordinates (x,
88 y). The upper left corner of the screen is at (0,0). Either x
89 or y may be negative. The default value is the center of the
90 screen.
91 -color color
94 Set the color for the label. The default is "red". Any color
95 in the rgb.txt file may be used. Colors may also be specified
96 by RGB hex values; for example -color 0xff and -color blue mean
97 the same thing, as do -color 0xff0000 and -color red.
98 -config config_file
101 Use the configuration file config_file. The format of con‐
102 fig_file is described in README.config. See the description of
103 -searchdir to see where xplanet looks in order to find the con‐
104 figuration file.
105 -create_scattering_tables scattering_file
108 Create lookup tables for Rayleigh scattering. See the README in
109 the scattering directory for more information.
110 -date YYYYMMDD.HHMMSS
113 Use the date specified instead of the current local time. The
114 date is assumed to be GMT.
115 -date_format string
118 Specify the format for the date/time label. This format string
119 is passed to strftime(3). The default is "%c %Z", which shows
120 the date, time, and time zone in the locale's appropriate date
121 and time representation.
122 -dynamic_origin file
125 Specify an observer location. The location is relative to the
126 body specified with -origin (by default, this is the Sun). The
127 last line of the file must be of the form
128 YYYYMMDD.HHMMSS range lat lon localtime
130 For example,
132 19951207.120000 10.328 -3.018 97.709 9.595
134 The specified time is ignored and the current time is used. The
136 range is in planetary radii, and lat and lon are in degrees.
137 Localtime (in hours) is optional, but if present, it will be
138 used in place of the longitude. Only the last line of the file
139 is used. This file may be updated between renderings using a
140 script executed with the -prev_command or -post_command options.
141 -ephemeris_file filename
144 Specify a JPL digital ephemeris file (DE200, DE405, or DE406) to
145 use for computing planetary positions. Xplanet uses Bill Gray's
146 code (http://www.projectpluto.com/jpl_eph.htm), which reads both
147 big and little endian binary files. The ephemeris files found
148 at ftp://ssd.jpl.nasa.gov/pub/eph/export/unix are big endian
149 files, but you do not need to do any additional byte-swapping to
150 use them. See the description of -searchdir to see where
151 xplanet looks in order to find the ephemeris file.
152 -font fontname
155 Set the font for the label. Only TrueType fonts are supported.
156 If the -pango option is used, fontname is taken to be the font
157 family name (e.g. "Arial").
158 -fontsize size
161 Specify the point size. The default is 12.
162 -fork Detach from the controlling terminal. This is useful on MS Win‐
165 dows to run xplanet from a batch file without having to keep a
166 DOS window open. Be careful when using this option; it's easy
167 to have multiple processes running at the same time without
168 knowing it - check the Task Manager. On unix systems this is
169 pretty much the same as running xplanet in the background.
170 -fov Specify the field of view, in degrees. This option and the
173 -radius option are mutually exclusive. This option has no
174 effect if the -projection option is used.
175 -geometry string
178 Specify the image geometry using the standard X window geometry
179 syntax, [<width>{xX}<height>][{+-}<xoffset>{+-}<yoffset>] (e.g.
180 256x256-10+10 puts a window 256x256 pixels in size 10 pixels
181 away from the right side and 10 pixels below the top of the root
182 window). The root window outside of the image will be black.
183 This option may be used with -window or -output.
184 -glare radius
187 Draw a glare around the sun with with a radius of the specified
188 value larger than the sun. The default value is 28.
189 -gmtlabel
192 Same as the -label option, but show GMT instead of local time.
193 -grs_longitude lon
196 The longitude of Jupiter's Great Red Spot (GRS). A typical
197 value is 94 degrees. If this option is specified, longitudes on
198 Jupiter will be calculated in System II coordinates. By
199 default, longitudes are calculated in System III coordinates.
200 When using this option, use an image map for Jupiter where the
201 center of the GRS is at the pixel 0 column, or the left side of
202 the image.
203 -hibernate seconds
206 After the screen has been idle for the specified number of sec‐
207 onds, xplanet will sleep. This option requires xplanet to have
208 been compiled with the X Screensaver extension.
209 -idlewait seconds
212 Don't run Xplanet unless the screen has been idle for the speci‐
213 fied number of seconds. This option requires xplanet to have
214 been compiled with the X Screensaver extension.
215 -interpolate_origin_file
218 This option is only useful in conjunction with -origin_file. It
219 computes the observer position at the current time by interpo‐
220 lating between values specified in the origin file. This is
221 useful if you have spacecraft positions tabulated in an origin
222 file, but want a real time view.
223 -jdate Julian date
226 Use the specified Julian date instead of the current local time.
227 -label Display a label in the upper right corner.
230 -labelpos
233 Specify the location of the label using the standard X window
234 geometry syntax. The default position is "-15+15", or 15 pixels
235 to the left and below the top right corner of the display. This
236 option implies -label.
237 -label_altitude
240 Display the altitude above the surface instead of distance from
241 the body center in the label.
242 -label_body body
245 Use the specified body to calculate the sub-observer, sub-solar,
246 and illumination values in the label. This is useful with the
247 -separation option.
248 -label_string
251 Specify the text of the first line of the label. By default, it
252 says something like "Looking at Earth". Any instances of %t
253 will be replaced by the target name, and any instances of %o
254 will be replaced by the origin name.
255 -latitude latitude
258 Render the target body as seen from above the specified latitude
259 (in degrees). The default value is 0.
260 -light_time
263 Account for the time it takes for light to travel from the tar‐
264 get body to the observer. The default is to ignore the effects
265 of light time.
266 -localtime localtime
269 Place the observer above the longitude where the local time is
270 the specified value. 0 is midnight and 12 is noon.
271 -log_magstep step
274 Increase the brightness of a star by 10^step for each integer
275 decrease in magnitude. The default value is 0.4. This means
276 that a star of magnitude 2 is 10^0.4 (about 2.5) times brighter
277 than a star of magnitude 3. A larger number makes stars
278 brighter.
279 -longitude longitude
282 Place the observer above the specified longitude (in degrees).
283 Longitude is positive going east, negative going west (for the
284 earth and moon), so for example Los Angeles is at -118 or 242.
285 The default value is 0.
286 -make_cloud_maps
289 If there is an entry in the config file for cloud_map, xplanet
290 will output a day and night image with clouds overlaid and then
291 exit. The images will be created in the directory specified by
292 -tmpdir, or in the current directory if -tmpdir is not used.
293 The names of the output images default to day_clouds.jpg and
294 night_clouds.jpg, but may be changed by the -output option. If
295 "-output filename.extension" is specified, the output images
296 will be named "day_filename.extension" and "night_file‐
297 name.extension". The dimensions of the output images are the
298 same as the day image.
299 -marker_file
302 Specify a file containing user defined marker data to display
303 against the background stars. The format of each line is gener‐
304 ally declination, right ascension, string, as in the example
305 below:
306 -16.7161 6.7525 "Sirius"
308 For additional options which may be specified, see the
310 marker_file entry in README.config. This option has no effect
311 if -projection is specified. This option is not meant for city
312 markers; for that use the marker_file option in the configura‐
313 tion file.
314 -markerbounds filename
317 Write coordinates of the bounding box for each marker to file‐
318 name. This might be useful if you're using xplanet to make
319 imagemaps for web pages. Each line looks like:
320 204,312 277,324 Los Angeles
322 where the coordinates are for the upper left and lower right
324 corners of the box. This file gets rewritten every time xplanet
325 renders its image.
326 -north north_type
329 This option rotates the image so that the top points to
330 north_type. Valid values for north_type are:
331 body: body's north pole
333 galactic: galactic north pole
334 orbit: body's orbital north pole (perpendicular to the orbit plane)
335 path: origin's velocity vector (also see -path_relative_to option)
336 separation: perpendicular to the line of sight and the
337 target-separation target line (see -separation option)
338 The default value is "body".
340 -num_times num_times
343 Run num_times before exiting. The default is to run indefi‐
344 nitely.
345 -origin body
348 Place the observer at the center of the specified body. Valid
349 values are the same as for -target. In addition, "above",
350 "below", or "system" may be specified. Using "above" or "below"
351 centers the view on the body's primary and the field of view is
352 large enough to show the body's orbit. Using "system" places
353 the observer at the center of a random body in the same system
354 as the target body. Two bodies are in the same system if one of
355 the following is true:
356 1) target and origin have same primary
358 2) target is origin's primary
359 3) origin is target's primary
360 If the body name is preceded by a dash, the observer is placed
362 on the opposite side of the target from the specified body at a
363 distance equal to the distance between the target and body. For
364 example, -target earth -origin sun places the observer at the
365 center of the sun. If -target earth -origin -sun is used, the
366 observer is placed on a line connecting the centers of the earth
367 and sun at a distance of 1 AU farther from the sun than the
368 earth.
369 -origin_file origin_file
372 Specify a list of observer positions in origin_file. The posi‐
373 tions are relative to the body specified with -origin (by
374 default, this is the Sun). Each line should be of the form
375 YYYYMMDD.HHMMSS range lat lon localtime
377 For example,
379 19951207.120000 10.328 -3.018 97.709 9.595
381 Range is in planetary radii, and lat and lon are in degrees.
383 The date is the only required value. If the localtime (in
384 hours) is supplied, it will be used in place of the longitude.
385 For each line in the origin file, the observer is placed at the
386 specified position, relative to the body specified with -origin.
387 This option is useful for showing spacecraft flybys or orbiting
388 around a planet. Any line with a # in the first column is
389 ignored.
390 -output filename
393 Output to a file instead of rendering to a window. The file
394 format is taken from the extension. Currently .gif, .jpg, .ppm,
395 .png, and .tiff images can be created, if xplanet has been com‐
396 piled with the appropriate libraries. The image size defaults
397 to 512 by 512 pixels but this may be changed by the -geometry
398 flag. If used with the -num_times option, each output file will
399 be numbered sequentially.
400 -output_map filename
403 Output the intermediate rectangular map that is created in the
404 process of rendering the final image. It will have the same
405 dimensions as the default day map.
406 -output_start_index index
409 Start numbering output files at index. The default is 0.
410 -pango Use the Pango (http://www.pango.org) library for rendering
413 internationalized text. Pango uses Unicode for all of its encod‐
414 ing, and will eventually support output in all the worlds major
415 languages. If xplanet has not been compiled with this library
416 this option will be ignored. There appear to be memory leaks in
417 the pango library, so I don't recommend letting xplanet run
418 indefinitely with this option.
419 -path_relative_to body
422 Only used with -north path or -target path. The origin's veloc‐
423 ity vector is calculated relative to the specified body. By
424 default, this is the Sun.
425 -post_command command
428 -prev_command command
430 Run command either before or after each time xplanet renders an
431 image. On MS Windows, you may need to use unix-style paths.
432 For example:
433 xplanet.exe -prev_command ./prev.bat
435 -print_ephemeris
439 Print the heliocentric rectangular equatorial coordinates
440 (J2000) for each body xplanet knows about, and then exit.
441 -projection projection_type
444 The projection type may be one of ancient, azimuthal, bonne,
445 equal_area, gnomonic, hemisphere, lambert, mercator, mollweide,
446 orthographic, peters, polyconic, rectangular, or tsc. The
447 default is no projection. Multiple bodies will not be shown if
448 this option is specified, although shadows will still be drawn.
449 -proj_param value
452 Pass additional parameters for some projections. The only pro‐
453 jections that use this option at present are the Bonne,
454 Gnomonic, and Mercator projections. The Bonne projection is
455 conformal at the specified latitude. Higher values lead to a
456 thinner heart shape. The default is 50 degrees. The Gnomonic
457 and Mercator projections use the specified latitude as the
458 boundaries of the projection. The defaults are 45 and 80
459 degrees, respectively. This option may be used more than once
460 for future projections that require additional parameters. Only
461 the first value is used at present.
462 -quality quality
465 This option is only used when creating JPEG images. The quality
466 can range from 0 to 100. The default value is 80.
467 -radius radius
470 Specify the radius of the globe as a percent of the screen
471 height. The default value is 45% of the screen height. When
472 drawing Saturn, the radius value applies to the radius of the
473 outer ring.
474 -random
477 Place the observer above a random latitude and longitude.
478 -range range
481 Render the globe as seen from a distance of range from the
482 planet's center, in units of the planetary radius. The default
483 value is 1000. Note that if you use very close ranges the field
484 of view of the screen can be greater than 180 degrees! If you
485 want an "up close" image use the -radius option.
486 -rotate angle
489 Rotate the globe by angle degrees counterclockwise so that north
490 (as defined by the -north argument) isn't at the top. The
491 default value is 0. My friends in the Southern Hemisphere can
492 use -rotate 180 to make the earth look like it should! For non-
493 orthographic projections, the globe is rotated and then pro‐
494 jected, if that helps you visualize what to expect.
495 -save_desktop_file
498 On Microsoft Windows and Mac OS X, xplanet creates an intermedi‐
499 ate image file which is used to set the desktop. This file will
500 be created in the -tmpdir directory. By default, this image is
501 removed after the desktop has been set. Specifying this option
502 will leave the file in place.
503 -searchdir directory
506 Any files used by xplanet should be placed in one of the follow‐
507 ing directories depending on its type: "arcs", "config",
508 "ephemeris", "fonts", "images", "markers", "origin", "satel‐
509 lites", or "stars". By default, xplanet will look for a file in
510 the following order:
511 The current directory
513 searchdir
514 subdirectories of searchdir
515 subdirectories of xplanet (if it exists in the current directory)
516 subdirectories of ${HOME}/.xplanet on X11
517 subdirectories of ${HOME}/Library/Xplanet on Mac OS X
518 subdirectories of DATADIR/xplanet
519 DATADIR is set at compile time and defaults to /usr/local/share.
521 -separation body:dist
524 Place the observer at a location where the target body and the
525 separation body are dist degrees apart. For example "-target
526 earth -separation moon:-3" means place the observer at a loca‐
527 tion where the moon appears 3 degrees to the left of the earth.
528 -spice_ephemeris index
531 Use SPICE kernels to compute the position of the named body.
532 The index is the naif ID code (e.g. 599 for Jupiter). The
533 -spice_file option must be used to supply the names of the ker‐
534 nel files. This option may be used more than once for different
535 bodies.
536 -spice_file spice_file
539 Specify a file containing a list of objects to display. A file
540 containing a list of SPICE kernels to read named spice_file.krn
541 must exist along with spice_file. See the README in the "spice"
542 subdirectory for more information.
543 -starfreq frequency
546 Fraction of background pixels that will be colored white. The
547 default value is 0.001. This option is only meaningful with the
548 azimuthal, mollweide, orthographic, and peters projections.
549 -starmap starmap
552 Use starmap to draw the background stars. This file should be a
553 text file where each line has the following format:
554 Declination, Right Ascension, Magnitude
556 where Declination is in decimal degrees and Right Ascension is
558 in decimal hours. For example, the entry for Sirius is
559 -16.7161 6.7525 -1.46
561 See the description of -searchdir to see where xplanet looks in
563 order to find the star map.
564 -target target
567 Same as -body.
568 -tt Use terrestrial time instead of universal time. The two differ
571 slightly due to the non-uniform rotation of the earth. The
572 default is to use universal time.
573 -timewarp
576 As in xearth, scale the apparent rate at which time progresses
577 by factor. The default is 1.
578 -tmpdir tmpdir
581 Specify a directory that xplanet will use to place images cre‐
582 ated using -make_cloud_maps. On Microsoft Windows, xplanet will
583 write a bitmap file called xplanet.bmp to the specified direc‐
584 tory. The default is the result of the GetWindowsDirectory call
585 (C:WINDOWS on Win95). On Mac OS X, xplanet will create an
586 intermediate PNG file in order to set the background. The
587 default value is /tmp. On Windows and Mac OS X, the intermedi‐
588 ate file will be removed unless the -save_desktop_file option is
589 specified.
590 -transparency
593 Update the background pixmap for transparent Eterms and aterms.
594 This option only works under X11.
595 -transpng filename
598 Same as the -output option, except set the background to be
599 transparent when writing a PNG file.
600 -utclabel
603 Same as -gmtlabel.
604 -verbosity level
607 level output
609 < 0 only fatal error messages
610 0 non-fatal warning messages
611 1 basic information
612 2 basic diagnostics
613 3 more detailed diagnostics
614 4 very detailed diagnostics
615 The default value is 0.
617 -version
620 Display current version information, along with a list of com‐
621 pile-time options that xplanet supports.
622 -vroot Render the image to the virtual root window. Some window man‐
625 agers use one big window that sits over the real root window as
626 their background window. Xscreensaver uses a virtual root win‐
627 dow to cover the screen as well.
628 -wait wait
631 Update every wait seconds.
632 -window
635 Render the image to its own X window. The size defaults to 512
636 by 512 pixels but this may be set by the -geometry flag.
637 -window-id ID
640 When using the X11 windowing system, draw to the window with the
641 specified ID.
642 -window_title title
645 Set the window's title to title. This option implies -window.
646 -XID ID
649 Same as -window-id.
650 -xscreensaver
653 Same as -vroot.
654 XPLANET(1)