Whereabouts

Abstract

The “Whereabouts” Python script is a helper tool to handle geolocated data more easily. Practically all conversions of GPS-related data can be done with GPSBabel, but it has too much options, and I grew tired of figuring out how to achieve what I wanted it to do. Besides, I like the output of GPS Visualizer, and GPSBabel just adds too much information. After playing with the options for a while, I found a set of option that produced something pretty close to what I wanted, and I took it from there.

Main tasks for Whereabouts

When developing “Whereabouts”, I hade the following use scenarios in mind:

Take a track from my Garmin handheld GPS device, and translate it into something Google Earth will read. Note that my GPS device already creates a track log in gpx format, straight on the µ-SD card. I prefer to transfer this file, rather than read the track-log from the device.

This mode will reate a single track, that is: separate parts of the file will be glued together, to compensate for loss of reception or the tea-break.
Take one or more tracks from the dutch “Fietsrouteplanner” (bicycle route builder) in gpx format, and turn it into a Google Earth file.

In this mode, the script will produce a single file with multiple tracks in it.
Take a file from Google Earth, and create a gpx file with multiple tracks, but with each track containing no more than n points, with n=500 for my device.
Transfer a track to my Garmin GPS device.

Macintosh users may find the droplets that are listed below useful to perform these tasks without having to use the command-line.

Bonus features

Google Earth has no method of calculating the length of a track, at least not easily. There are some web tools available to claculate this length, but it should be classified as a missing feature. Since my tool is rewriting the output kml file from GPSBabel anyway, it was not very hard to calculate the total length of the tracks and add that information to the description of the track. It actually became trivial after I found some code by Chris Veness to do the calculation. All I had to do was translate from JavaScript into Python. Since I’m a metric kind of guy, you'll get the length in kilometres.

A second feature has to do with processing kml to kml. Since I can add useful information to a track, it makes sense to process kml to kml, for instance to combine several files, or just to add lengths. However, processing by GPSBabel will strip out the descriptions you might have added to the tracks. My script will try to transfer kml commands to the output kml file.

For symmetry reasons in the code, you can use any combination of kml, kmz, gdb and gpx input files, and produce gpx, kml or kmz from them. MapSource files (gdb) can be produced, but this is not recommended. Because most kml files will come compressed into kmz files, support for this is added to the script, a plain GPSBabel will not handle these files.

Installation

You’ll need to have the following software installed to use the script:

Python

The script is written in Python, so you’ll need to have that installed. The script only uses standard components, so no further additions to the Python installation are needed. Mac OS X has this installed by default.

GPSBabel

The basic translation is done through GPSBabel. On Mac OS X and Linux/Unix the $PATH environment variable will be searched to find gpsbabel, so if you can use it from the command-line, Whereabouts will find it. I suggest you it install in /usr/local/bin. On Microsoft Windows you will need to supply the full path to the script. I have never tested the script on Windows, so let know how that works out.

The droplets for use with Mac OS X include GPSBabel, so there is no need to install this separately, the applications are ready for use out of the box.

Place the “Whereabouts.py” script somewhere in your path. Oh, the full package is available from my website.

Command line options

The tool has the following command line options:

--version: Print the version number and exit.
--help: Print basic help and exit.
--verbose: For debugging proposes. It produces two output files for kmz and kml output. The first one is the original output from GPSBabel, the second one is the filtered version. Progress is printed to standard out, inluding the gpsbabel command line.
--outdir=DIR: Place output in DIR. The default is to place the output in the same directory as the input.
--gpsbabel=TOOL: Use gpsbabel located at the full path TOOL. You’ll need to add this on Windows.
--combine: If this flag is present, all partial tracks in the input file will be combined into a single track. This is useful to combine parts of a track that were separated due to loss of reception, or a tea-break. A single output file will be produced for each input file. If the flag is not present, the tracks will be compined into a single file.
--length=LENGTH: Limit the length of the tracks in the output file to LENGTH. Useful for exporting to GPX prior to transfering the tracks to a GPS device, as they usually set a limit on the length of a track. See you user manual for the limits of your particular track.
--delete-waypoints: Remove all waypoints.
--gpx: Produce gpx.
--kml: Produce kml, this is the default.
--compress: When used in combination with --kml, this will produce kmz.
--gdb: Produce MapSource GDB (not recommended).
--device-upload: Send the tracks and waypoints to the connected usb GPS-device made by Garmin.
--device-download: Retrieve the tracks and waypoints from the connected usb GPS-device made by Garmin.

You can put as many gpx, kml, kmz and gdb files on the command line as you want.

Macintosh Droplets

In the package five ready to use droplets are included for use with Mac OS X. These contain the gpsbabel binary, and the Whereabouts python script, so there is no need to install anything else. Drop the files you want to work with onto the applications, and the desired conversion takes place. The five droplets perform the four numbered actions listed in the introduction.

Import GPX Track: Translate an input file into kmz, stitching all parts together into a single track, listed as task 1.
Make KMZ: Translate a series of input files into kmz, adding the length of the track in the description of each track. If a length description is already there, it is updated. This is task 2 in the introduction.
Make GPX for GPS: Make a gpx file from whatever is dropped on the application, limiting the length of each track to 500 points. This is task 3 in the introduction.
Export GPS: Make a gpx file from whatever is dropped on the application, without limiting the length of each track. My new GPS can handle practically unlimited tracks.
Send to GPS Device: Send the tracks and waypoints in the file(s) that is (are) dropped on this script straight to the connected Garmin USB device. This is a new and experimental feature, listed as task 4 in the introduction. Since I only use RoadTrip to upload my tracks, I might as well integrate this in the Finder. The script also offers a download option, but I have not written a script for this. I find it more efficient to copy the track-log from the SD card using the direct data-link. Note that this works with Garmin USB devices from the eTrex and GPSMap series, not those from the latest Oregon and Colorado series. For those devices the method of transfer is simpler: mount the device, and copy the GPX files using the Finder.

The droplets were made with Platypus, the shell scripts are included in the distrobution package.

Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public Licence for more details.

You should have received a copy of the GNU General Public Licence along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

The GNU General Public Licence can be found on the website of the Free Software Foundation. A copy is included in the full Whereabouts package.

Contact

Send comments, bug fixes and suggestions to .

Python is a registered trademark of the Python Software Foundation.
Google Earth is a trademark of Google Inc.
Garmin is a trademark of Garmin Ltd.
Mac OS is a trademark of Apple Inc., registered in the U.S. and other countries. Finder is a trademark of Apple, Inc.
Linux is the trademark of Linus Torvalds, registered in the U.S. and other countries.
UNIX is a registered trademark of The Open Group.
Microsoft and Windows are trademarks of Microsoft Inc., registered in the U.S. and other countries.