GPXTrackMap workflow

In this tutorial, we'll see how to prepare a gpx track for presentation on your website using GPXTrackMap. We'll be using Garmin BaseCamp (here: on Windows) to edit the track file, and add in waypoints. In the final result, you can click the Waypoint icon (the photo symbol) on the map to pop up some more information for your users, with links and images.

This is a "live preview" of what it will look like in the end: 

 

 

I assume you have BaseCamp installed, have your maps installed, and you have downloaded your recorded track from your GPS device onto your PC.

( There are several ways how to transfer the recorded GPX tracks from your device to your PC. You can do it directly in BaseCamp - i usually do it simply with the Explorer and copy the .gpx files over to my "work directory", and then import them into BaseCamp. This is not primarily a BaseCamp tutorial, though - no matter how you do it, you should finally see something like on the next page.)

All right, let's start with "cleaning up" the track.

 

Cleaning up the track

The best way to record tracks (that you plan to publish) with your GPS device, is to record them "cleanly" in the first place:

• Immediatly before you start your trip, clear the current track in your GPS device.
• During your trip, when you're at a "place to remember", add a Waypoint in your device, and give it a useful Waypoint name
• As soon as you have finished the trip, save the current track, and give it a meaningful Track name.

As you can see below, i didn't do any of that in this case: the track is named "MRZ-29-11..." by my Oregon, because i didn't rename it; i forgot to clear the track before i started my trip; and there are no waypoints (yet).

"A trip to go into the trashcan", then? - NO. Fortunatly we can correct all of that in BaseCamp:

 

 

First of all we'll rename the track to something useful and recognizable: Right-click the track in the lower pane on the left and choose "Rename", or just click on it and press F2:

 

 

Next, let's zoom in on the start our track. In my case, this is what it looks like:

 

 

...this is typical for what you get if you don't clear the track in your GPS device immediatly before you start the trip you want to record, so let's do some cleanup here: Let's get rid of the extra Trackpoints (before and after the "actual" trip) that we don't want in our final track.

To do this, double-click the track in the lower left pane. A new form will pop up where you can see some statistics, and the complete list of coordinates of the track. Let's first set the track color to red so we can see it better on the map:

 

 

The track i want to publish was actually recorded on March 28th, but since there's trackpoints in there from another, previous trip, BaseCamp happily reports "2 days.." as track time.

So, in order to clean up the start of the track, we need to locate the first trackpoint that we want to have in our final track. If you double-click on a line, BaseCamp will show that point on the map; you can also use the timestamps to find the "real" start.

In my example, trackpoint #68 is the first one i want to keep, so i:

• click on trackpoint #67
• scroll up til trackpoint #1 and SHIFT-click that (#1..#67 turn grey)
• press the DEL key (or right-click and choose Delete from the popup menu)

OK, the start is now "clean", let's do the same for the end of the track:

Locate the last point you want to keep, click the one below that, then scroll all the way down to the very last line in the file, shift-click it and DELete the extra trackpoints you don't want.

After the cleanup, the statistics do make some sense, and the start and end points are about where they should be:

 

 

(As you can see by the average speed, i'm not in for the Tour de France - i just like to go cycling my way through nice landscapes, and enjoy the nature - "you'll see more, the less you move" :-)

 Next, let's get rid of redundant waypoints inside our track, so our gpx file will become smaller - and the website page with our track will load faster in the end.

 

Filtering out unnecessary Trackpoints

For my personal taste, there are still a bit too many trackpoints left (as you can see in the statistics, or by looking at the little black dots on your track).

One thing that's important to understand is this:

Having (too) many trackpoints doesn't make your track better - it only makes it bigger (larger file size = bigger download, and more time the plugin needs to calculate the Track Information, and render the diagrams = valuable server time).

So let's reduce the number of track points to a reasonable amount:

Click the "Filter..." button and set the maximum number of points to keep:

 

 

This is not an exact setting - i entered 300, but after applying the filter i had only 206 trackpoints left. Anyway, i'm quite happy with the result: as you can see looking at the tiny black dots, there are trackpoints where you need them (turns, corners, crossings etc.), but BaseCamp removed a lot of really unnecessary trackpoints (see the long straight in the circle). So it does a pretty good job here:

 

 

If you are not happy with your results, just use "Edit" / "Undo" from the menu and try again with different numbers of trackpoints. There is no "golden rule" here as to how many trackpoints you should keep: It greatly depends on the overall length (distance) of the track, the travel speed (walking / cycling / by car), and the recording frequency of your GPS device, so you'll really have to just try it out.

Next, let's add in a Waypoint, and see what we can do with it.

Editing the track: adding in Waypoints

Waypoints ("WPT" tags) are -basically- just positions, or pairs of coordinates. They can have timestamps, symbols, and some more additional information attached to them. They are not a part of your track, but you can include them in a GPX track file.

Think of it this way: When you have a printed map hung up your wall, and you push a pin into it - the exact position where you do this on the map: that is a Waypoint.

There are (at least) two ways to add Waypoints in BaseCamp: 

1. With the "hand" tool, click a trackpoint on the track (a circle and a popup will appear). Then click on the grey double arrow and select "Create Waypoint"

 

 

2. Using the "New Waypoint" tool, click on the map where you want the waypoint to be:

 

 

However you do it, this is the result:

 

 

Now either double-click the entry in the leftmost list, or click the name of the waypoint on the map to bring up the waypoint properties editor. Here you can change the name of the Waypoint and give it a custom symbol (we'll get back to that later). I want to include a photo in the popup, and it really is a scenic place, so i choose that symbol.

(Note the little hint window saying "Scenic Area" - remember that text, we're going to need it later on!)

 

 

As you can see, BaseCamp also holds a timestamp for the creation date of the waypoint.

The plugin can show the waypoint name, the elevation, that timestamp and the description (from the "Notes" tab, see below) in waypoint popups. If you have created the waypoint during your trip, it will already have the correct timestamp, and also the correct elevation. When you add the waypoints afterwards - like i'm doing here - the bad news is: BaseCamp won't let you edit the timestamp. I have no idea why they did this (you can e.g. edit the elevation) - so you'll probably want to disable the timestamp display in the plugin options. (You can edit the timestamp by directly editing the GPX file, but not in BaseCamp).

To find out the correct elevation (altitude) of your waypoint, select the track and locate the trackpoint in the Track editor (the one we used before to clean up the track). Here you can see the elevation of the Trackpoint where you put your Waypoint on - just enter that same value in the Waypoint properties: in my example "440 m".

 Next we're going to enter a description for the waypoint.

Editing the track: waypoint descriptions

To have text in the waypoint popups, you can enter that in the "Notes" tab of the Waypoint editor:

 

 

The bad news is: BaseCamp will only allow plain text here - no formatting ( bold / italic / underline ), no links in the text, and no images. You can add Web Links with the button below (and the plugin can show them, too), but you can't give them "human-readable" names.

(The reason for all those limitations probably lies in the fact that GPX is an XML format, so having HTML tags in the description would break the XML structure. The way around this - putting the description in a #CDATA tag - is currently not supported in BaseCamp.)

However, i used a "workaround" so that you can at least do some basic formatting, and include links and images in the waypoint popups in the plugin. It is basically a subset of BBCode: the main "trick" is to use square brackets [ ] instead of html < > tag markers.

BBCode Examples:

• This will give [b]bold[/b] text.
• This way you can have [i]italics[/i] (slanted) text.
• You can also [u]underline[/u] text.
• This is [quote]quoted text[/quote]
• For preformatted text you can use [code]the code syntax[/code].
• You can include links like this: [url=http://en.wikipedia.org/wiki/High_Fens]High Fens[/url]
• ...and finally images like this: [img]http://software.frankingermann.de/images/steinbach.jpg[/img]

(You should scale your images so they will fit into the popup window; in the plugin options you can set the maximum width and height of the popups accordingly.)

So, the "spiced up" version of our waypoint description finally looks like this:

 

 

You can of course have multiple Waypoints, but for this tutorial one example should do.

Next, we'll finally upload and publish the track.

Publishing the track

First we'll have BaseCamp export the track as a GPX file, including the waypoint(s). There are again different ways of doing this, one way is this:

Click an item in the lower left list, then hit Ctrl+A to select all items there:

 

 

Here you can actually select "by hand" which of the waypoints will go into the GPX file. In this simple case, we want them all - there is only one waypoint anyway.

Next, choose "File" / "Export" / "Export Selection" from the menu. Give it a "decent, server-friendly name": The Plugin has to access the GPX file in two ways:

• by directly reading the file from disk on the server (to read out the waypoint infos etc.)
• by accessing it through its URL (for the OpenLayers API to read and render the track onto the map)

So it's a good idea to use only small case letters, dashes "-", underscores "_" and digits, but NO blanks, and no other "funny" characters. I called my track "vennrunde.gpx", which meets all of those criteria.

 

Uploading the GPX file

Well, i assume you know how to do that - anyway, here is a neat trick how you can do the upload with JCE if you have that installed.

So, let's assume you have the file ready in the images/gpxtracks folder on your server.

 

Embedding the track in an article

Open a new article (or edit an existing one) in your Joomla installation, and enter the GPXTrackMap invocation code like this:

{gpxtrackmap}vennrunde.gpx{/gpxtrackmap}

(Note: don't copy-paste the above text; it includes html markup tags!) 

Save and Close the article. Now let's go to the plugin options and set the waypoints the way we want them.

  

Plugin Waypoint Options

In the backend, go to "Extensions" / "Plugin Manager", click the entry "Content - GPXTrackMap" and open the Plugin Waypoint Options on the slider "Waypoints":

(Note: this is a screenshot of V1.2.3 of the plugin)

 

 

The most important setting here is the first one: Set "Show waypoints" to "yes". The next two don't matter, as we'll be using symbols (icons) for the waypoints. I set the timestamp format to "0", which disables the display of the timestamp (as mentioned before, it is anyway not the correct timestamp.) 

The waypoint (WPT) description is turned on, and also the BBCode, so the formatting, the link and the image in the popup will work.

 

 

WPT Symbol mappings

In the Symbol mappings, we're telling the plugin which icon file to show for which waypoint symbol. I don't know whether it is allowed to use the Garmin symbol icons, so for the time being i rather use my own. The syntax for entries here is:

<SymbolName>=<PathToIconFile>,<Width>,<Height>[,<LeftOffset>,<TopOffset>]

You can enter multiple mappings like this:

<SymbolName1>|<SymbolName2>=<PathToIconFile>,<Width>,<Height>

for example:

Flag, blue|Flag, green=%GPXDIR%/myflagicon.png,16,16

so you can enter multiple symbol names separated by a "|" pipe character. (I would have liked to separate them with a "," comma, but some of the BaseCamp symbols already have a comma in their name, hence the "|" pipe.)

In the filenames, you can use the placeholders %GPXDIR%, %PLUGINDIR% and %TEMPLATEDIR% as described here. 

One little problem here is that you need to know which symbol NAME BaseCamp writes into the GPX file - it only shows the symbol, but not the symbol name. (BaseCamp does show the symbol name in the Waypoint properties editor, when you hover with the mouse over the symbol icon - like in the screenshot above - so you may want to remember that and write it down when you edit the waypoint in BaseCamp.) 

The GPX file on the other hand only includes the name, but not the symbol itself... so, if you're not sure, simply open up the GPX file with a text editor (like Notepad++), and see what's in the <sym> tag:

(Note: if you use a text editor to directly edit your GPX files, make sure it supports the UTF-8 encoding!)

 

This is the exact text that you have to enter in the Symbol mappings before the "=" equal sign: "Scenic Area". Note that this is case sensitive: "Scenic Area" is not the same as "scenic area".

 

 

Waypoint symbol placement

By default, the plugin will show the waypoint symbol centered on the coordinates of the waypoint (like BaseCamp does that, too). If you use symbols that "point" to a position that's not in the center of the symbol, or you don't want the symbol to cover the exact position of the waypoint, you can use the optional, extended "[,<LeftOffset>,<TopOffset>]" syntax for the mappings. Here you can specify where the "hot spot" of your symbol is.

 

In the above example i used one of the standard track markers that come with the plugin. They are 24x24 px, and they all "point" to a position in the lowermost center of the symbol. The image shows the bounding box of the symbol in red, and the exact coordinate of the waypoint is at the intersection of the yellow lines. To position the symbol this way, you need to write this into the symbol mappings:

Scenic Area=%PLUGINDIR%/markers/marker4-white.png,24,24,12,24

So, the offset setting of ",12,24" will shift the symbol "hot spot" 12 pixels left and 24 pixels down from the top left corner of the symbol ( which is at 1,1 ). If you had a symbol like a standard mouse pointer that points to the upper left corner, you would use "1,1" as offsets. If you had an arrow that points to the lower right corner, you would use the same values for the offsets as you use for the width and height of the symbol.

 Now save the Plugin options and go back to your article in the frontend to see the outcome.

Let's see the final result now...

 

The final result

Wow, this turned out to be quite a long tutorial - this shouldn't scare you, though.

The basic steps of preparing and uploading a new track are actually done pretty fast, once you know how it works.

The whole Waypoint stuff is optional: you don't have to add or edit Waypoints (if you don't want or need them).

 So, this is the final result when you click on the foto icon:

(Note: this is just a screenshot of what you should be seeing "interactively", on the very first page of this tutorial.)

 

  

I hope this tutorial could give you some useful info on how to prepare and edit your GPS tracks for publishing them with the GPXTrackMap plugin.

If you have questions, please ask them in the Forum, so others can participate - Thanks!

Have fun traveling, recording, and publishing your tracks!  - Frank