GPXToGoogleMapDoc.nb

Using GPXToGoogleMap

GPXToGoogleMap is a Mathematica package and command which translates GPX files into Google Map format. It is compatible with versions 5.1 and 5.2 of Mathematica; a V6 package is on the way. You can download the latest version here:
http://facstaff.unca.edu/mcmcclur/GoogleMaps/GPXToGoogleMap/

To use the web pages generated by this package, you need an active internet connection and a web browser, which is compatible with Google Maps. Some experience with GPX and Google Maps would also be helpful.

Basic usage

Once installed in a Mathematica packages directory, we can load the package as usual.

Needs["GPXToGoogleMap`"]

GPXToGoogleMap will read GPX files and write HTML, Javascript, and GIF files. You can set the locations of both the read and write directories to be the same as the directory containing the current notebook as follows.

dir = DirectoryName[ToFileName["FileName" /.
NotebookInformation[EvaluationNotebook[]]]];
$Path = Union[$Path, {dir}];
SetDirectory[dir];

Now suppose a GPX file, such as GPXToGoogleMapDemo.gpx, is in this directory. Note that the demo is a valid GPX file, but contains some embedded HTML which might fool some web browsers. Be sure to save it as source, if you want to download it. To generate a Google Map from the file, simply execute the following command.

GPXToGoogleMap["GPXToGoogleMapDemo.gpx"]

There should now be two new files in the current directory: a Javascript file defining the Google Map and an HTML file displaying the map. If you open the HTML file in your web browser, you should see a basic web page containing a Google Map with two paths from The Great Smoky Mountain National Park to The Shenandoah National Park. One path follows the Blue Ridge Parkway and the other follows the interstate, as suggested by a Google directions search. There are also a number of icons representing route points and clustered waypoints as described below. If all the tracks in your GPX file happen to contain elevation data, then GPXToGoogleMap can generate elevation profiles as well. These will be rendered as GIF images.

It's easy to render a Google Map for every GPX file in a directory. For example, I generated all the mountain biking maps on my cycling in Asheville page as follows:

dir = "/Users/markmcclure/Sites/GoogleMaps/Biking/Mountain";
$Path = Union[$Path, {dir}];
SetDirectory[dir];

SetOptions[GPXToGoogleMap, USGSMaps -> True, GoogleMapKey ->
"ABQIAAAA8TnNJmMI5cG1uGgbzWfGDRRRm4UhWX_5qi7OjD-TylbMNFnxWhS_p5u4e5ekhBOuOogw9B4flB0zhA"];

GPXToGoogleMap[#, InitialMapType -> Topo]& /@
Select[FileNames[], StringTake[#,-4] == ".gpx" &];

The options are explained below.

File types

Google Maps

The main Google Map site is http://maps.google.com/. You can place a Google Map on your own web page using the Google Maps API described at http://www.google.com/apis/maps/documentation/. There are standard procedures for implementing paths and markers on the map. The point of the GPXToGoogleMap package is to efficiently automate the procedure when the data is already in GPX format.

GPXToGoogleMap produces Javascript compatible with version 2 of the Google Maps API. Google frequently releases intermediate revisions; the most recent version, as of August 15, 2007, is 2.85.

HTML

GPXToGoogleMap produces HTML compliant with the XHTML version 1.0 standard. A link is included at the bottom of the generated page to the W3C Validation Service which allows you to validate the HTML. Of course, the page can only validate properly if any HTML embedded in the GPX file (as described below) validates as well.

GPX

GPX is a widely used format to store data obtained from gps devices; the definitive reference is http://www.topografix.com/gpx.asp. Quite a few GPX files are freely available for download at GPXchange. If you have data, but it's not in GPX format, there's a good chance you can convert it using GPSBabel or its web interface.

There are three major types of elements which may be described in a GPX document: tracks (trk), waypoints, (wpt), and routes (rte). The purpose of these elements, and their translation via GPXToGoogleMap, is described below.

GPX tracks

A track is simply a sequence of points defined by latitude, longitude pairs typically used to represent a path graphically on a map. Other data, such as elevation, may or may not be present as well. If elevation data is present for all of the tracks, then GPXToGoogleMap will also generate elevation profiles for these tracks. Since a track in a GPX file may be very long, they will be represented using and encoded polyline. This process is described in detail on my polyline encoding page.

GPX waypoints

A waypoint is defined by a latitude, longitude pair and typically has more data associated with it, such as a name and description. Since a GPX file might contain hundreds or even thousands of waypoints, GPXToGoogleMap uses clustering to place them efficiently. A large red icon indicates a large marker group, a medium sized yellow icon represents a few markers, and a small green icon represents a single marker. GPXToGoogleMap also uses information from the name and desc elements of the waypoints to set up the marker tooltips and HTML.

GPX routes

A route is a sequence of route points from one location to another. The route points usually have directional information associated with them, so a route is a good way to represent driving directions. GPXToGoogleMap represents route points using a green start icon, a yellow pause icon, or a red finish icon. The corresponding directions can be obtained by clicking on the icon.

GPX extensions

GPX 1.1 allows elements of other XML schema to be embedded via the GPX extensions element. This allows you to embed HTML into a GPX file in a way that GPXToGoogleMap can understand. An example is GPXToGoogleMapDemo.gpx, which can be used to generate the main GPXToGoogleMap page. To use this feature, you should set up a metadata element at the top of your file with the following structure:

The title of your web page will then be dictated by the title element, HTML from the first html element will appear before the Google map and the HTML from the second html element will appear after the Google map.

Options

GPXToGoogleMap has a number of options.

Options[GPXToGoogleMap]

These come in several categories.

Basic Google Map and HTML options

These include CenterInfo, GoogleMapKey, InfoString, InitialMapType, MapSize, MapTypeControl, Output, StartStopMarkers, USGSMaps, and ZoomLevel. All these affect the appearance or behavior of the generated Google Map and how it fits in the web page. Many of these relate directly to some feature described in the Google Maps API documentation.

CenterInfo: When set to True, the lat/lng center of the map will be displayed just below the map. Convenient when you want to add markers. Default is False.

GoogleMapKey: If you want to display your Google Maps on a server, you need to sign up for a Google Map key as explained at http://www.google.com/apis/maps/signup.html. Once you have a key, you can insert it using the GoogleMapKey option. The value should be a string. Since Google Map Key's are typically quite long an complicated, you might consider using SetOptions as follows:

SetOptions[GPXToGoogleMap,
GoogleMapKey -> "StrangeCrazyString"];

Default is the empty string so you'll definitely need to set it, if you want to make your map public.

InfoString: When set to True, information about the GPX source file is displayed. Default is True.

InitialMapType: Set this to Normal, Satellite, or Hybrid according to which Google Map type you want to initially appear. If you set USGSMaps → True, then Topo and Aerial are also possibilities. Default is Normal.

MapSize: Determines the size in pixels of the Google Map in the page. Default is {800,500}.

MapTypeControl: May be Large, Small, or None depending on the type of GMapControl you want in your map. Default is Large.

Output: This indicates which types of output to generate: HTML, Javascript, or Elevation. For example, Output → {HTML, Javascript}. Suppresses the elevation profiles. Output → Javascript is handy if you've edited the HTML and just want to regenerate the map. Default is All, which is equivalent to {Elevation,HTML,Javascript}.

StartStopMarkers: True indicates that markers should be placed at the beginning and ending of tracks. False suppresses the markers. Default is True.

USGSMaps: If you set USGSMaps → True, two new map types provided by the US Geological Survey will be provided via the TerraService. Note that the server is somewhat slower than Google's and the coverage is restricted to the US. If your GPS data is in the US and “outdoorsy”, however, the results are quite nice. Default is False.

ZoomLevel: Determines the initial zoom level setting of the Google Map. The default of Automatic chooses the zoom level to just fit the data.

Polyline encoding options

There are three options that affect the translation of the GPX tracks to encoded polylines.

PolylineEncodingOptions /. Options[GPXToGoogleMap]

These options, along with the fundamentals of the algorithm, are described in detail on my polyline encoding page. The algorithm generally works well with the defaults and you may very well never need to fiddle with them. The most likely change would be to set VerySmall to the even smaller value of 0.000001 to escape the disappearing polyline bug as described on the potential pitfalls of encoded polylines subpage.

Clustering options

The Google Maps API allows specification of marker appearance, marker tooltips, and info window text and HTML. Using the GMarkerManager class, we can also specify at what zoom levels markers appear and disappear. This last point is particularly important, since the performance of a Google Map will generally degrade significantly when more than a hundred or so markers appear at one time. Tools from the Statistics`ClusterAnalysis` package allow us to automate the process and display maps with thousands of markers. There are four options affecting this process.

ClusterOptions /. Options[GPXToGoogleMap]

ClusterThreshold indicates how many total markers should be present before clustering starts. Default is 50.

SmallTol indicates how close is too close at the maximum zoom level of 17 in a normal Google Map. The measurement is in terms of degrees of latitude or longitude. For example, markers with identical latitudes and whose longitudes differ by less than SmallTol will be clustered at all zoom levels. The default works 0.0005 well for data that is spread out over a two dimensional area. I find that a smaller value, say around, 0.0002 works well if the data is distributed along a path.

BreakFactor affects how quickly marker clusters split. Increasing the break factor slows down the splitting process. Default is 2.

MarkerBreaks allows precise specification of the levels at which the markers split. Setting MarkerBreaks → {4,6,10}, for example, causes the markers to split at precisely those zoom levels.

Elevation profile options

If all the tracks in the GPX file contain elevation data, then GIF images of the elevation profiles are generated as well. These images are generated by the Mathematica package function FilledListPlot as defined in the Graphics`FilledPlot` package. GPXToGoogleMap accepts all of the options accepted by FilledPlot and uses these when generating the elevation profiles. The default options of FilledListPlot are as follows.

Options[FilledListPlot]

Note that GPXToGoogleMap changes two of these defaults.

changedOptions = Intersection[
  First /@ Options[GPXToGoogleMap],
  First /@ Options[FilledListPlot]];
Rule @@@ Transpose[{changedOptions,
  changedOptions /. Options[GPXToGoogleMap]}]

As a result, the elevation profile has default aspect ratio 1/4 and you don't see the elevation profile until you view the web page.

The appearance of the elevation profile can also be affected by the ProfileStep option. The elevation profiles can be quite rough. ProfileStep restricts how frequently we should sample the data when creating the elevation profile. A larger value will smooth the profile out a bit.

Created by Mathematica (August 15, 2007)