Mac Garmin Tools: csv2gpx

(This is part of the documentation for Mac Garmin Tools. If you don't know what those are or how you got here, see the homepage.)

csv2gpx

This droplet converts .csv files to .gpx files which are the files in a format used by all sorts of GPS devices and software. Drop six .csv files on it and you'll get six .gpx files. It will stop and ask for various kinds of user input depending on what it finds inside the files it's converting.

The .gpx files will by created in the same directory as the .csv files you dropped on it. You can view the resulting files using a text editor and exit them before using them with other software.


Format for the .csv file

The droplet exists to convert .csv files and you will need one of those to make it do anything. Many different spreadsheet and database applications can produce fields in .csv (comma-separated variable) format. This application takes files in that format which have at least three columns: longitude, latitude, and name. Warning: longitude and latitude are in reverse order from the way they're normally seen. A typical file might look like this:

1.3746867,52.23424,Pat's house,green shutters
1.292874,53.123878,Jay's house,on the corner

You can enclose any field in double-quotes ("), but not put the entire line as one big quoted field. If a field is in quotes you can put newline characters in it but don't do this with any of the first three fields on a line. For text fields it's actually better to use '<br>' to break lines.

Blank lines in the file will be ignored, as will lines that start with the slash (/) or semicolon (;) characters. You can use this to put informative header lines at the beginning of a file.

Text in these files should be encoded as ISO Latin 1. This will matter to you only if you need to include unusual characters like accented characters (e.g. ü) or other characters not found in the 26 character American alphabet (e.g. ß).


Information taken from outside the .csv file

Before the program processes your .csv file it looks for extra files on the disk and asks the user for some extra information and uses those things to produce a .template (CSV template) file. Then it uses that file to convert the information in the .csv file into a .gpx file.

So you might run the program once then, if you want to adjust the results, modify the template using a text editor, then run the program again. This time, because the template file already exists, it won't ask questions, it will just use it to create the .gpx file.

GPX is a very large, very flexible file format. To see which fields you can usefully specify for use with POIs in Garmin devices, see the documentation for gpx2gpi.

Files

The program looks for other files in the same folder as the .csv file which it thinks you might want it to use. It looks for files with the same name but a different extension to the .csv file:

extensionfile typeuse
.bmpbitmap imageUsed as an icon for the point.
.jpeg or .jpgJPEG imageShown on the page for the point. You can scroll and zoom the image.
.wavWAV audio fileA 'speaker' button appears on the page for the point. Press the button to play the sound.
.mp3MP3 audio fileA 'speaker' button appears on the page for the point. Press the button to play the sound.

Information from the user

Alerts

Some Garmin units have the ability to set a proximity alert: when you get closer than a certain distance to the point, the unit will beep, or flash a message on the display or something like that. nüvi units can also handle a speed alert: you specify a speed in addition to a proximity and the unit will beep only if you exceed that speed within that distance of the point. The application will show you this dialog before processing the file.

Fields

.csv files must have at least three fields per line: longitude, latitude and the name of the point. They can have more fields in if you want. For any field after the third the program will stop and ask you what the field represents. It will offer you a choice of some of the things that it knows how to do with the field. It will use your replies when it creates the template file which it later uses to create the .gpx file.

If you know GPX and you want some special field the program doesn't handle, pick 'comment', let the software run, then modify the template yourself to make the GPX look how you want it. Once you've done that you can run the program again and it'll use your template to make the .csv file.