Using XPlanet for a rotating background on OS X

xplanet is an open source project that renders images of heavenly bodies. The popular use for this program is to put a background image of the rotating Earth on the desktop of a Linux box, including the cloud overlay. For OS X, it’s not quite so straightforward, but, with a little tweaking, the same effect can be achieved.

This process is based heavily on a two year old blog post by mikael. The changes I’ve made are minor, and based mostly on the different tools I use.

Install Xplanet

Xplanet can be installed via Homebrew with a simple brew install xplanet command.

Configure Xplanet

Homebrew’s version of xplanet will use $HOME/Library/Xplanet as a data directory. Make this directory, and therein create a config file containing:

[earth]
map=day.jpg
night_map=night.jpg
cloud_map=clouds.jpg

Don’t worry about the files, we’ll create them in a moment.

Grab and process the day and night pictures

You can use any files you’d like for these, but I use these from NASA:

Day image
Night image

The day image will need to be called day.jpg, and placed in the same .xplanet directory where the config file is located.

The night image will need to be converted to JPEG (load it up in Preview.app and export it) and called night.jpg. It also needs to be placed in the same .xplanet directory where the config file is located.

Optionally resize the images

As the cloud data we’ll use is 2048×1024, things will go a lot faster if your day.jpg and night.jpg are also that resolution. Preview.app can do the resizing for you.

The Script

Now we write a script to put everything together. This script needs to do a few things:

Get the cloud data (xplanet provides this, but there may be better providers)
Clean out the output directory
Make the new image via xplanet

Here is the current version of my script:

#!/bin/bash
#
# manipulate XPlanet (installed via homebrew) to make an
# earth-from-space image suitable for a desktop background.
#
# This script is run periodically via launchd (com.eafarris.xplanet)

# Based on pantburk.info/?blog=78

CONFIG=$HOME/Library/Xplant/config
OUTPUTDIR=$HOME/Pictures/xplanet
CLOUDURL=xplanet.sourceforge.net/clouds/clouds_2048.jpg
CLOUDIMAGE=$HOME/Library/Xplanet/clouds.jpg

# get cloud image
/usr/bin/curl -L $CLOUDURL > $CLOUDIMAGE

# clean out the output directory
rm -f $OUTPUTDIR/*

# make the background
/usr/local/bin/xplanet -config $CONFIG \
  --quality 95 \
  -verbosity 0 \
  --num_times 1 \
  --output $OUTPUTDIR/$RANDOM.jpg \
  --geometry 2560x1440 \
  --projection rectangular

Not much to it at all. The main things to see:

Full paths to the executables for curl and xplanet. Besides good scriptwriting practice, when launchd launches a task it does so without a PATH set. So the job will silently fail if we don’t tell it where these executables are. rm gets a pass because it’s a bash built-in.
the -L switch to curl. This allows curl to follow the 302 that sourceforge gives, leading to an actual host in their CDN.
The use of $RANDOM. This is a bash construct that produces a random number. This is perfect for our use. OS X requires a different filename to switch desktop backgrounds.

You can put this script wherever you like, but I like $HOME/Library/Scripts for this.

Before first run

You’ll need to create the $HOME/Pictures/xplanet directory, where the random-number-named file will live.
If you’re not blessed with a 27" Thunderbolt Display, you may want to change the output resolution of the final image by matching the --geometry parameter to match your screen resolution.

Trial Run

Run the script from the terminal and make sure you’ve got a random-number-named JPEG file in your Pictures/xplanet directory, and that it looks good. If everything’s working, it should look really good.

The launchd plist

This is all very nice, but we need a mechanism to run this script periodically. While you could use cron, and this would be the traditional *nix way to do it, OS X would prefer that you use the launchd mechanism. launchd plists are not hard to write. Here’s the one I use for this, which I’ve named com.eafarris.xplanet.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.eafarris.xplanet</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>/Users/eafarris/Library/Scripts/xplanet.sh</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Minute</key>
    <integer>23</integer>
  </dict>
</dict>
</plist>

The main thing to see here is the second <string></string> argument to the <array> argument, which must include the full pathname of the script we created earlier.

The other thing to note is the StartCalendarInterval section. As written, this will trigger the script to run at 23 past each hour. Once an hour is probably overkill, but will work fine for our purposes.

This script must be placed in your $HOME/Library/LaunchAgents directory. Create this if it doesn’t exist.

Load the launchd plist:

The launchd daemon needs to know that you’re serious about this job you’ve created. launchctl takes care of this:

launchctl load -w /Users/eafarris/Library/LaunchAgents/com.eafarris.xplanet.plist

Of course, use your own full path and name for this file.

Once we’ve got an image

Either as the result of your first run, or, if everything proceeded perfectly, as the result of waiting until your StartCalendarInterval has passed, your xplanet directory should have a file in it. Now we can tell OS X to use your background.

In System Preferences->Desktop and Screen Saver preference pain, hit the “+” button to add your xplanet folder to the possible folders. Then check the “Change Picture” box and set it to “every hour.”

If all goes well, you should notice the sun illuminating different parts of the Earth on your desktop as your day goes by. xplanet has many other options; its man page is worth a look if you’re in to those types of things. (Among other things, you can pick the planet of your choosing). Also, with a script like this one you have the full power of the *nix command line graphics tools at your disposal, including fetching other graphics from the Internet via curl, and the whole ImageMagick suite for adding things like borders, text, and other special effects.

os x
open source
scripting