[r186]: trunk / xplanet.1 Maximize Restore History

Download this file

xplanet.1    662 lines (575 with data), 22.4 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
.TH XPLANET 1
.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
.\" other parms are allowed: see man(7), man(1)
.SH NAME
xplanet \- render an image of a planet into an X window or file
.SH SYNOPSIS
.B xplanet
.I "[options]"
.SH DESCRIPTION
.B 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.
.SH OPTIONS
Options need only be specified with enough characters to be
unambiguous. Valid options to Xplanet are:
.TP
.B \-arc_file
Specify an arc file to be plotted against the background stars. Each
line in the file must have the following syntax:
.nf
.sp
dec1 ra1 dec2 ra2
.sp
.fi
where declination is in degrees and right ascension is in hours. This
option has no effect if \-projection is specified.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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).
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-create_scattering_tables scattering_file
Create lookup tables for Rayleigh scattering. See the README in the
scattering directory for more information.
.TP
.B \-date YYYYMMDD.HHMMSS
Use the date specified instead of the current local time. The date is
assumed to be GMT.
.TP
.B \-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.
.TP
.B \-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
.nf
.sp
YYYYMMDD.HHMMSS range lat lon localtime
.sp
.fi
For example,
.nf
.sp
19951207.120000 10.328 \-3.018 97.709 9.595
.sp
.fi
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.
.TP
.B \-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.
.TP
.B \-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").
.TP
.B \-fontsize size
Specify the point size. The default is 12.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-gmtlabel
Same as the \-label option, but show GMT instead of local time.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-jdate Julian date
Use the specified Julian date instead of the current local time.
.TP
.B \-label
Display a label in the upper right corner.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-latitude latitude
Render the target body as seen from above the specified latitude (in
degrees). The default value is 0.
.TP
.B \-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.
.TP
.B \-localtime localtime
Place the observer above the longitude where the local time is the
specified value. 0 is midnight and 12 is noon.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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:
.nf
.sp
\-16.7161 6.7525 "Sirius"
.sp
.fi
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.
.TP
.B \-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:
.nf
.sp
204,312 277,324 Los Angeles
.sp
.fi
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.
.TP
.B \-north north_type
This option rotates the image so that the top points to north_type.
Valid values for north_type are:
.nf
.sp
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)
.sp
.fi
The default value is "body".
.TP
.B \-num_times num_times
Run num_times before exiting. The default is to run indefinitely.
.TP
.B \-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:
.nf
.sp
1) target and origin have same primary
2) target is origin's primary
3) origin is target's primary
.sp
.fi
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.
.TP
.B \-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
.nf
.sp
YYYYMMDD.HHMMSS range lat lon localtime
.sp
.fi
For example,
.nf
.sp
19951207.120000 10.328 \-3.018 97.709 9.595
.sp
.fi
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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-output_start_index index
Start numbering output files at index. The default is 0.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-post_command command
.TP
.B \-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:
.nf
.sp
xplanet.exe \-prev_command ./prev.bat
.sp
.fi
.TP
.B \-print_ephemeris
Print the heliocentric rectangular equatorial coordinates (J2000) for
each body xplanet knows about, and then exit.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-quality quality
This option is only used when creating JPEG images. The quality can
range from 0 to 100. The default value is 80.
.TP
.B \-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.
.TP
.B \-random
Place the observer above a random latitude and longitude.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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:
.nf
.sp
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
.sp
.fi
DATADIR is set at compile time and defaults to /usr/local/share.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-starmap starmap
Use starmap to draw the background stars. This file should be a text
file where each line has the following format:
.nf
.sp
Declination, Right Ascension, Magnitude
.sp
.fi
where Declination is in decimal degrees and Right Ascension is in
decimal hours. For example, the entry for Sirius is
.nf
.sp
\-16.7161 6.7525 \-1.46
.sp
.fi
See the description of \-searchdir to see where xplanet looks in order
to find the star map.
.TP
.B \-target target
Same as \-body.
.TP
.B \-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.
.TP
.B \-timewarp
As in xearth, scale the apparent rate at which time progresses by
factor. The default is 1.
.TP
.B \-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.
.TP
.B \-transparency
Update the background pixmap for transparent Eterms and aterms. This
option only works under X11.
.TP
.B \-transpng filename
Same as the \-output option, except set the background to be
transparent when writing a PNG file.
.TP
.B \-utclabel
Same as \-gmtlabel.
.TP
.B \-verbosity level
.nf
.sp
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
.sp
.fi
The default value is 0.
.TP
.B \-version
Display current version information, along with a list of compile-time
options that xplanet supports.
.TP
.B \-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.
.TP
.B \-wait wait
Update every wait seconds.
.TP
.B \-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.
.TP
.B \-window-id ID
When using the X11 windowing system, draw to the window with the
specified ID.
.TP
.B \-window_title title
Set the window's title to title. This option implies \-window.
.TP
.B \-XID ID
Same as -window-id.
.TP
.B \-xscreensaver
Same as \-vroot.