Scripts to Run and Update

Three files drive Xplanet’s behavior. I introduced xp.def and xplanet.sh earlier which I use, and there’s also xp.conf which is Xplanet’s configuration file.

Definitions

File Location: ~/.xplanet/config/xp.def

PATH="/Users/$USER/perl5/bin${PATH:+:${PATH}}"; export PATH;
PERL5LIB="/Users/$USER/perl5/lib/perl5${PERL5LIB:+:${PERL5LIB}}"; export PERL5LIB;
PERL_LOCAL_LIB_ROOT="/Users/$USER/perl5${PERL_LOCAL_LIB_ROOT:+:${PERL_LOCAL_LIB_ROOT}}"; export PERL_LOCAL_LIB_ROOT;
PERL_MB_OPT="--install_base \"/Users/$USER/perl5\""; export PERL_MB_OPT;
PERL_MM_OPT="INSTALL_BASE=/Users/$USER/perl5"; export PERL_MM_OPT;

XPLANET_BIN=
XPLANET_HOME=/Users/$USER/.xplanet

XPLANET_CONFIG=$XPLANET_HOME/config
XPLANET_PROJECTION=rectangular
XPLANET_GEOMETRY=2560x1440
XPLANET_LONGITUDE=-100.0000

EARTH_MAP_PRE=world/world
#EARTH_MAP_PRE=world.topo/world.topo
#EARTH_MAP_PRE=world.topo.bathy/world.topo.bathy

Discussed earlier, this is a definitions file I use to feed into the script.

The first part includes the perl specific definitions required to use TotalMarker. This came from the Mozilla::CA module the setup script installs. You can remove this section if you never plan to update the marker files or download the cloud image using TotalMarker.

The next section, sets the locations of the Xplanet binary and the home directory which xplanet.sh needs to work correctly.

That’s followed with parameter definitions. Xplanet will uses these settings when it runs. You can use, ignore, add to, or edit these parameters.

The last section are the locations of the three earth map types mentioned earlier.

Projections

Xplanet offers a total of 16 different projections you can specify and are shown below. Edit XPLANET_PROJECTION in xp.def with your preferred projection.

xplanet projections

Script to Start and Update Xplanet

File Location: ~/.xplanet/config/scripts/xplanet.sh

I covered the installation and most of the setup function in xplanet.sh. The other available functions start/stop Xplanet or update the marker files with TotalMarker. The marker files are updated by simply passing through the function into the TotalMarker script which does the heavy work.

start

$XPLANET_BIN \
-searchdir=$XPLANET_HOME \
-config=$XPLANET_CONFIG/xp.conf \
-projection=$XPLANET_PROJECTION \
-longitude=$XPLANET_LONGITUDE \
-labelpos=+10-45 \
-date_format="%D at %r" \
-color=green2 \
-fork

The start function – the stop function is self explanatory and unneeded so I won’t cover it – starts Xplanet. This is an example of a start command which sets the config file, xp.conf (covered below), mixes parameters from the definitions file as well as a few that are fixed in the install script: labelpos, date_format, color, and fork.

I’m unsure if the fork is a controversial statement or not. From the comments I’ve received, including from Hari, it seems others prefer outputting to a file and having macOS pic up the file. If that what you prefer the edit out the -fork with -num_time 1 -geometry $XPLANET_GEOMETRY -output $XPLANET_OUTPUT.

Why fork then? The issue with outputting to a file in macOS is that while the image gets updated, macOS will only pick up the change if the filename changes. That requires additional work: removing the existing image and adding a time stamp to the output file name to ensure it’s a different filename.

Additionally, Xplanet does a great job of normalizing the layers of map images to your screen ratio regardless of whether the -geometry option is used. I try to use high quality map images that do not take up more than 10 MB without a care to the image dimensions. Xplanet will spend a bit more time – we’re talking about a few seconds – normalizing the dimensions, but the output is a high quality image when it renders the map.

For this reason, I also do not use an external tool like convert to match image layers to a uniform screen ratio using the ImageMagick utility. I feel like the image loses too much in translation during this process. Less is more. Xplanet is the only program that touch the images.

Forking will only draw the image to the primary monitor and does not save it. The next update will render a new drawn image. If you want to save the output, then you must to use the -geometry option.

xp.def parameterizes a few of the available options. A more complete list of command line options is available in the programs README file (available in the Homebrew’s cellar directory) and also available here.

Config File

File Location: ~/.xplanet/config/xp.conf

Xplanet calls xp.conf to understand which planetary bodies to display and how to represent those bodies.  This is an example config file. Xplanet also ships with examples that you can access at /usr/local/share/xplanet/config. Any changes to this file require an Xplanet restart.

[earth]
"Earth"
map=earth.png
night_map=lights.tiff
cloud_map=clouds-4096.jpg
cloud_threshold=45
cloud_gamma=.75
bump_map=bump.png
bump_scale=2
specular_map=specular.png

marker_file=earth
marker_file=quake
marker_file=volcano
marker_file=storm arc_file=storm
marker_file=updatelabel

In addition to the maps and marker links the script has set, I included the cloud_threshold, cloud_gamma, and bump_scale settings.  There are many other options you can include in the config file which are documented in the /usr/local/share/xplanet/config/README file or online.

Marker Updates

/usr/bin/perl $TM -<MARKER>

All marker updated take the above form. The main script simply passes the marker to update into the TotalMarker script.


That sums up the main script that will control how Xplanet runs. At this point, everything is set and Xplanet should be fully operational from the command line
~/.xplanet/config/script/xplanet.sh quake
~/.xplanet/config/script/xplanet.sh storm
~/.xplanet/config/script/xplanet.sh start
~/.xplanet/config/script/xplanet.sh stop

 

5 Responses to Scripts to Run and Update

Leave a Reply to Xplanet Blog Cancel reply

Your email address will not be published. Required fields are marked *