XPLANET(1)

💫 XPLANET 💫

okay bestie, welcome to xplanet — it lives in the General Commands Manual (section 1, periodt) and it's about to become your new obsession.

---

🌍 NAME 🌍

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

---

✨ SYNOPSIS ✨

xplanet [options]

---

🪐 DESCRIPTION 🪐

So, Xplanet is giving very much like Xearth — you know, where an image of the earth gets rendered straight into an X window? Yeah, that vibe. But here's the slay: all of the major planets and most satellites can be drawn too. Not just earth. We're talking range. 🌈

It also supports a whole bunch of different map projections, including azimuthal, Mercator, Mollweide, orthographic, and rectangular. Iconic lineup honestly.

And if you want the freshest version, it's always hanging out at http://xplanet.sourceforge.net. 🦋

---

💅 OPTIONS 💅

Little quality-of-life note first: options only need to be specified with enough characters to be unambiguous. So you don't have to type the whole thing, just enough that xplanet knows what you mean. iykyk.

Valid options to Xplanet are:

• -arc_file — specify an arc file to be plotted against the background stars. Every single line in the file has to follow this syntax:

dec1 ra1 dec2 ra2

where declination is in degrees and right ascension is in hours. Heads up: 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. And no cap: line segments shorter than spacing will not be drawn.
• -arc_thickness thickness — specify the thickness of arcs. The default is 1 pixel. Lowkey important: when you're 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. You can also hand it a color instead (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. that's the whole roster bestie 🌙

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. And this option is the same as -target. 🫶

• -center +x+y — place the center of the rendered body at pixel coordinates (x, y). The upper left corner of the screen is at (0,0). Either x or y may be negative. The default value is the center of the screen.
• -color color — set the color for the label. The default is "red". Any color in the rgb.txt file may be used. Colors may also be specified by RGB hex values; for example -color 0xff and -color blue mean the same thing, as do -color 0xff0000 and -color red. 🌈
• -config config_file — use the configuration file config_file. The format of config_file is described in README.config. See the description of -searchdir to see where xplanet looks in order to find the configuration file. 🔍
• -create_scattering_tables scattering_file — create lookup tables for Rayleigh scattering. See the README in the scattering directory for more information.
• -date YYYYMMDD.HHMMSS — use the date specified instead of the current local time. The date is assumed to be GMT.
• -date_format string — specify the format for the date/time label. This format string is passed to strftime(3). The default is "%c %Z", which shows the date, time, and time zone in the locale's appropriate date and time representation. 🕰️
• -dynamic_origin file — specify an observer location. The location is relative to the body specified with -origin (by default, this is the Sun). The last line of the file must be of the form

YYYYMMDD.HHMMSS range lat lon localtime

For example,

19951207.120000     10.328   -3.018   97.709    9.595

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

• -ephemeris_file filename — specify a JPL digital ephemeris file (DE200, DE405, or DE406) to use for computing planetary positions. Xplanet uses Bill Gray's code (http://www.projectpluto.com/jpl_eph.htm), which reads both big and little endian binary files. The ephemeris files found at ftp://ssd.jpl.nasa.gov/pub/eph/export/unix are big endian files, but you do not need to do any additional byte-swapping to use them. See the description of -searchdir to see where xplanet looks in order to find the ephemeris file.
• -font fontname — set the font for the label. Only TrueType fonts are supported. If the -pango option is used, fontname is taken to be the font family name (e.g. "Arial"). 🎀
• -fontsize size — specify the point size. The default is 12.
• -fork — detach from the controlling terminal. This is useful on MS Windows to run xplanet from a batch file without having to keep a DOS window open. > ⚠️ Be careful when using this option; it's easy to have multiple processes running at the same time without knowing it — check the Task Manager. On unix systems this is pretty much the same as running xplanet in the background. 💀
• -fov — specify the field of view, in degrees. This option and the -radius option are mutually exclusive. This option has no effect if the -projection option is used. 🚫
• -geometry string — specify the image geometry using the standard X window geometry syntax, [<width>{xX}<height>][{+-}<xoffset>{+-}<yoffset>] (e.g. 256x256-10+10 puts a window 256x256 pixels in size 10 pixels away from the right side and 10 pixels below the top of the root window). The root window outside of the image will be black. This option may be used with -window or -output.
• -glare radius — draw a glare around the sun with with a radius of the specified value larger than the sun. The default value is 28. ☀️
• -gmtlabel — same as the -label option, but show GMT instead of local time.
• -grs_longitude lon — the longitude of Jupiter's Great Red Spot (GRS). A typical value is 94 degrees. If this option is specified, longitudes on Jupiter will be calculated in System II coordinates. By default, longitudes are calculated in System III coordinates. When using this option, use an image map for Jupiter where the center of the GRS is at the pixel 0 column, or the left side of the image. 🌀
• -hibernate seconds — after the screen has been idle for the specified number of seconds, xplanet will sleep. ⚠️ This option requires xplanet to have been compiled with the X Screensaver extension.
• -idlewait seconds — don't run Xplanet unless the screen has been idle for the specified number of seconds. ⚠️ This option requires xplanet to have been compiled with the X Screensaver extension.
• -interpolate_origin_file — this option is only useful in conjunction with -origin_file. It computes the observer position at the current time by interpolating between values specified in the origin file. This is useful if you have spacecraft positions tabulated in an origin file, but want a real time view. 🛰️
• -jdate Julian date — use the specified Julian date instead of the current local time.
• -label — display a label in the upper right corner.
• -labelpos — specify the location of the label using the standard X window geometry syntax. The default position is "-15+15", or 15 pixels to the left and below the top right corner of the display. This option implies -label. 📍
• -label_altitude — display the altitude above the surface instead of distance from the body center in the label.
• -label_body body — use the specified body to calculate the sub-observer, sub-solar, and illumination values in the label. This is useful with the -separation option.
• -label_string — specify the text of the first line of the label. By default, it says something like "Looking at Earth". Any instances of %t will be replaced by the target name, and any instances of %o will be replaced by the origin name. 💬
• -latitude latitude — render the target body as seen from above the specified latitude (in degrees). The default value is 0.
• -light_time — account for the time it takes for light to travel from the target body to the observer. The default is to ignore the effects of light time. ⚡
• -localtime localtime — place the observer above the longitude where the local time is the specified value. 0 is midnight and 12 is noon. 🌗
• -log_magstep step — increase the brightness of a star by 10^step for each integer decrease in magnitude. The default value is 0.4. This means that a star of magnitude 2 is 10^0.4 (about 2.5) times brighter than a star of magnitude 3. A larger number makes stars brighter. ⭐
• -longitude longitude — place the observer above the specified longitude (in degrees). Longitude is positive going east, negative going west (for the earth and moon), so for example Los Angeles is at -118 or 242. The default value is 0. 🌎

---

okay that's the first chunk bestie, there's more coming so don't go anywhere 🧚

• -make_cloud_maps — okay so if your config file has an entry for cloud_map, xplanet is gonna spit out a day image AND a night image with clouds layered on top, then dip out and exit. 🌥️ Where do they go? Into the directory you set with -tmpdir, or the current directory if you didn't bother with -tmpdir. The output image names default to day_clouds.jpg and night_clouds.jpg, but bestie you can change that with -output. And here's the cute part: if you do -output filename.extension, the images get named day_filename.extension and night_filename.extension. The dimensions? Same as the day image, no cap. 💅
• -marker_file — this one lets you specify a file full of your own marker data to display against the background stars. ✨ Each line's format is generally declination, right ascension, string, like this:

-16.7161 6.7525 "Sirius"

Wanna know about the extra options you can throw in there? Go read the marker_file entry in README.config. Heads up tho: this option does absolutely nothing if -projection is specified, and it is not for city markers — for those, use the marker_file option in the configuration file instead. 💖

• -markerbounds filename — writes the coordinates of the bounding box for every marker into filename. Super handy if you're using xplanet to make imagemaps for web pages, iykyk. Each line looks like:

204,312 277,324 Los Angeles

where those coordinates are the upper left and lower right corners of the box. And bestie, this file gets rewritten every single time xplanet renders its image. Every. Time. 🔄

• -north north_type — this rotates the whole image so the top points toward north_type. Valid values 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 it num_times times and then exit. The default is to run indefinitely, so like, forever, no chill. 😌
• -origin body — places the observer at the center of the specified body. Valid values are the same as for -target, and on top of those you can also say "above", "below", or "system". Using "above" or "below" centers the view on the body's primary and makes the field of view big enough to show the body's orbit. Using "system" puts 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 these is true:
  1. target and origin have same primary
  2. target is origin's primary
  3. origin is target's primary

And now for the plot twist 🌀 — if the body name is preceded by a dash, the observer gets 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 puts the observer at the center of the sun. But if you use -target earth -origin -sun, 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. Iconic behaviour honestly.

• -origin_file origin_file — specify a list of observer positions in origin_file. These positions are relative to the body specified with -origin (and by default, that's 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 — everything else is optional bestie. If the localtime (in hours) is supplied, it'll 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 is so useful for showing spacecraft flybys or orbiting around a planet. 🛰️ And any line with a # in the first column gets ignored, periodt.

• -output filename — outputs to a file instead of rendering to a window. The file format gets 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 you can change that with the -geometry flag. And if you use it with the -num_times option, each output file gets numbered sequentially. 🔢
• -output_map filename — outputs the intermediate rectangular map that gets created along the way while rendering the final image. It'll have the same dimensions as the default day map. 🗺️
• -output_start_index index — start numbering output files at index. The default is 0. ✨
• -pango — use the Pango (http://www.pango.org) library for rendering internationalized text. Pango uses Unicode for all of its encoding, and will eventually support output in all the worlds major languages. If xplanet hasn't been compiled with this library, this option will just be ignored, no drama. ⚠️ But real talk: there appear to be memory leaks in the pango library, so the author doesn't recommend letting xplanet run indefinitely with this option. Don't leave it running overnight bestie.
• -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 — prints the heliocentric rectangular equatorial coordinates (J2000) for each body xplanet knows about, and then exits. Data dump and done. 📊
• -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. Heads up: multiple bodies will not be shown if this option is specified, although shadows will still be drawn. 🎨
• -proj_param value — passes 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 — but only the first value is used at present. Foreshadowing, we love to see it.
• -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 — specifies 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 — places the observer above a random latitude and longitude. Chaos mode activated. 🎲
• -range range — renders 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 — rotates 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 gets 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:
  1. The current directory
  2. searchdir
  3. subdirectories of searchdir
  4. subdirectories of xplanet (if it exists in the current directory)
  5. subdirectories of ${HOME}/.xplanet on X11
  6. subdirectories of ${HOME}/Library/Xplanet on Mac OS X
  7. subdirectories of DATADIR/xplanet

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

• -separation body:dist — places 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 — bestie, this is how you hand xplanet a whole custom sky 💫 it uses starmap to draw the background stars, and starmap needs to be a plain text file where every single line goes like this:

Declination, Right Ascension, Magnitude

where Declination is in decimal degrees and Right Ascension is in decimal hours 🎀 so for example, the entry for Sirius is literally:

-16.7161  6.7525 -1.46

and if you're sitting there like "ok but where does it even look for the star map tho" — go read the description of -searchdir, it's all in there 🔍

• -target target — same as -body, no notes 💅
• -tt — use terrestrial time instead of universal time. the two differ slightly because the earth just will not rotate uniformly (so rude of it 😭). 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 — tell xplanet where to drop the images it creates with -make_cloud_maps 🖼️ on Microsoft Windows, xplanet will write a bitmap file called xplanet.bmp to the directory you specify, and the default is whatever the GetWindowsDirectory call returns (C:WINDOWS on Win95). on Mac OS X, xplanet creates an intermediate PNG file in order to set the background, and the default value is /tmp. on Windows and Mac OS X the intermediate file gets removed unless you pass the -save_desktop_file option ✨
• -transparency — updates the background pixmap for transparent Eterms and aterms. heads up: this option only works under X11 👑
• -transpng filename — same as the -output option, except it sets the background to be transparent when writing a PNG file 🦋
• -utclabel — same as -gmtlabel, that's it that's the whole thing 💖
• -verbosity level — this is your little volume knob for how much xplanet yaps at you 🗣️ here's the whole vibe:
  • level < 0 — only fatal error messages
  • level 0 — non-fatal warning messages
  • level 1 — basic information
  • level 2 — basic diagnostics
  • level 3 — more detailed diagnostics
  • level 4 — very detailed diagnostics

the default value is 0.

• -version — displays the current version information, along with a list of compile-time options that xplanet supports 📜 lowkey useful, ngl
• -vroot — renders 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, and Xscreensaver uses a virtual root window to cover the screen as well 🌈
• -wait wait — update every wait seconds ⏰
• -window — renders the image to its own X window. the size defaults to 512 by 512 pixels, but you can set that with the -geometry flag 🪟
• -window-id ID — when you're using the X11 windowing system, draw to the window with the specified ID 🎯
• -window_title title — sets the window's title to title. this option implies -window 🏷️
• -XID ID — same as -window-id ✨
• -xscreensaver — same as -vroot 💅

---

and that's a wrap on the whole XPLANET(1) page bestie 🫶 this was the XPLANET(1) manual page — source and version and date all baked into that little footer line, so shoutout to the page itself for the receipts 📖✨ go render something iconic, periodt 🌍💖