Tutorial: Building Plain-Text Waypoint Files by Hand

1: The bare essentials
2: A little more information
3: Building more interesting "desc" fields
4: Adding colors
5: Adding symbols in Google Maps & Google Earth
6: Resizing & colorizing points
7: Adding points without coordinates (e.g., addresses)
8: Adding URLs
9: Adding thumbnails and photos
10: Summary

This document will show you how to build plain-text (tab- or commma-separated) files that can be used to make maps with GPS Visualizer. It's actually very easy to get started, but there are some powerful features that you might not be aware of. After reading this, you should have a better understanding of what GPS Visualizer can do and how you can take advantage of it.

For most of the examples on this page, I've created very simple JPEG maps. They're not very fancy, but this document isn't about spectacular maps, it's about massaging data into a mappable format. Unless otherwise noted, all the information here also applies to creating Google Maps, Google Earth files, etc. Once you have a nice, clean data file, you can do anything you want with it.

1: The bare essentials

All you really need is a collection of coordinates, or even just one pair of coordinates; adding a "name" to each point is not necessary, but very helpful (and it lets GPS Visualizer know that you're uploading waypoints rather than a sequence of trackpoints).

For this example, I'll use the tallest Cascade Range volcanoes in southern Washington and Northern Oregon. The easiest way to organize your data is using a spreadsheet, like Microsoft Excel. On the left, below, is a screen shot of an Excel worksheet, and on the right is the same data in simple, comma-separated format.

To make a map from data like this, just cut and paste the data from Excel or your text editor into the text area on GPS Visualizer's map form. (When you copy data from Excel, it gets pasted with tabs, which will work fine but might look strange.) If you prefer, you can also save the file as tab-delimited text (.txt) or a comma-separated values (.csv) and then upload the file to GPS Visualizer.

For now, let's use the standard map form with the default settings, but with the output format set to JPEG and the size set to 300 for simplicity's sake. (Go ahead and try it using the data in the box above.) After clicking the "Draw a map" button, the resulting graphic should look like the map on the left.

Here's the most important thing I can emphasize about creating plain-text data files for GPS Visualizer: Having a sensible "header row" above your data is VERY important. The order of the fields is NOT important. Spaces between fields and capitalization of the header row aren't important either. So "name,latitude,longitude" is identical to "NAME, latitude , Longitude." These "not important" factors are a big part of what makes this program so powerful: chances are, if a human could read your data and make sense of it, so can GPS Visualizer. Include as many or as few fields as you want; as long as a waypoint contains information that might let you plot it on a map, GPS Visualizer will try.

2: A little more information

Now, let's add a "description" field to each point (usually abbreviated as "desc"). For now, we'll put the full name of the mountain, along with the state it's in. So Rainier's description is "Mount Rainier, Washington."

We'll also add a field that contains the height of each mountain. I'll call it "alt" to keep it short, but you could also use "altitude" or "elevation." NOTE: if no units are specified, GPS Visualizer will think your numbers are metric (meters for elevation, km/h for speed, etc.); but, in this example, we have our elevation data in feet, so we need to call the field "alt (feet)" or "alt (ft)".

(Click here to pre-fill the map form with this data.)

There's something very important to notice about this comma-separated data: the items in the "desc" column MUST be enclosed in quotes because there is a comma inside each description. Without the quotes, everything would be shifted back one column, and the altitude of the first two points would be listed as "Washington"!

Voila. If you think the text is too small, you can always increase the "text size" box in the map form. (This will only affect JPEG/PNG and SVG maps, though, not Google Maps or Google Earth.) Also, if you don't mind dealing with SVG files, you might try that, as they look much cleaner than JPEGs.

3: Building more interesting "desc" fields

The nice thing about storing your raw data in a spreadsheet like Excel is that you can manipulate the fields as needed. This is especially helpful for the description field. Let's say we want to display the height of each mountain on the map. All we have to do is concoct a simple Excel formula that reads the "alt" field and adds it to the end of the existing "desc" field. Since the column with the formulas in it will need to be called "desc" in order for GPS Visualizer to recognize it, we'll rename the original "desc" column to "full name," which GPS Visualizer will ignore.

In the screen shot below, you can see the formula in cell C2 laid bare for the world to see; in cells C3 through C5, the results of the formula are visible.

(Click here to pre-fill the map form with this data.)

Maybe we should have just put the altitude by itself in the description field; it's getting a little messy. Oh well, there's no harm in experimenting.

Note that if your output format supports HTML in waypoint names or descriptions (i.e., you are creating a Google Map or Google Earth KML file), you can build descriptions that contain HTML formatting, which can be very, very useful. You could conceivably include an entire table of information in the description of each point.

4: Adding colors

Each of your points can have its own color, defined by a "color" field. In our example data, we'll assign red to peaks over 14,000 feet high, green to peaks that are at least 11,000 feet, and blue to the rest.

(Click here to pre-fill the map form with this data.)

Colors can be either "named" HTML color values (blue, green, red, black, fuchsia, olive, skyblue, papayawhip, etc.) or hex-formatted RGB values (#0000FF, #82B3CE, etc.).

And yes, "papayawhip" is really a recognized HTML color.

5: Adding symbols in Google Maps & Google Earth

Now we're going to turn away from those simple JPEG maps for a moment, because in JPEG, PNG, and SVG maps, you have no control over what kind of marker ("symbol") appears for each waypoint; it's always a circle. In Google Maps and Google Earth, however, you can use a different marker style, either for all points or each point individually.

Here's GPS Visualizer's list of available pre-defined symbols in Google Maps:

And, for Google Earth:

	airport
	camera
	circle
	diamond
	google
	googleblank
	googlemini
	pin
	square
	triangle

	airport
	blankcircle
	camera
	camera_circle
	circle
	flag

	square
	pushpin
	pushpin_circle
	star
	star_gold
	triangle

So, let's make a Google Map using triangles and squares. We'll say that triangles represent volcanoes that have erupted in historic time (Rainier & Hood), and squares are volcanoes that have been dormant longer (Adams & Jefferson).

(Click here to pre-fill the Google Maps form with this data.)

The map on the left is a live, interactive Google Map; note that if you put your mouse pointer over one of the markers, the name shows up. If you click on a marker, an info window pops up with the name of the point in bold at the top, and the description below. (This is where including HTML in a description could come in handy.)

Custom icons in Google Maps

GPS Visualizer now accepts absolute URLs in the "symbol" field for Google Maps, and it will try its best to make your custom symbols display properly without you doing any extra work. (However: if you also supply an "icon_size" field that contains something like "12x20", you'll make GPS Visualizer's task a little easier.) More info will be coming soon.

If you need to, you can also define a whole set of custom markers in various colors, but for each new marker you need to create the main graphic, a 1% transparent version of it, and a "shadow" (although the shadow is optional), and then repeat the process for however many different colors you want available. Then you have to add some JavaScript code to the guts of your map page that defines certain parameters of the new icon. It's powerful, but a pain to set up; contact me if you want to give it a try.

Custom icons in Google Earth

Google Earth makes it very easy to incorporate custom icons into your maps: all you need to supply is the URL of the icon graphic (even photograph thumbnails will work), and GE will take care of the rest. Google Earth can even colorize them if you supply a "color" field.

Google Earth also has hundreds of "standard" icons that you can easily use. To see all of them, click here; to find the URL of one of the icons on that page, right-click on the graphic and choose the appropriate command to find its URL. (In Firefox, it's "Copy image location.")

6: Resizing & colorizing points

Using the "quantitative data" input form, you can have GPS Visualizer resize or colorize your waypoints based on a field (or fields) of your choice. It's not hard to do, but this feature is important enough to warrant its own tutorial.

7: Adding points without coordinates (e.g., addresses)

It's possible to specify the location of a waypoint using information other than coordinates: address, city, state, ZIP code, country, airport code, etc.

NOTE: If your entire data file is a collection of addresses, you will find it MUCH easier and more efficient in the long run to use GPS Visualizer's Batch Geocoder to add coordinates to your points before proceeding; then you can skip this section altogether.

As always, the header row on your data is important, and preserving the structure of the columns is crucial: you can't put an airport code in the "latitude" column or a city name under "airport." In this next example, I've added Seattle and Portland to the file, using two different methods. For Seattle, I've supplied a city and state; for Portland, just its airport code. The unknown fields are left blank. (In the .csv data file on the right, that means multiple commas with nothing between them.)

(Click here to pre-fill the Google Maps form with this data.)

The resulting map is just as you'd expect: a yellow pin on Seattle, and an orange airport icon just northeast of Portland (at the location of PDX, Portland's airport).

If you want to retrieve the coordinates of points for which you don't know the latitude and longitude, send your data through GPS Visualizer's geocoding utilities rather than the map form. This is helpful because then, in the future, you can format those rows the same as the rest, and GPS Visualizer won't have to work so hard to locate your waypoints.

As I mentioned, much more information is available in the Address Tutorial; if you're planning to do a lot of address-to-coordinate conversion, I highly encourage you to read it.

What to do when it doesn't work

Entering an address or a city and state to find a location is far from an exact science. When you enter an address in the United States, GPS Visualizer first attempts to find it in a local database containing geocoding information from the U.S. Census Bureau; this database is not 100% accurate, and you may find addresses plotted on the wrong side of the street or worse. C'est la vie. If the Census database doesn't work, the Google and/or Yahoo geocoding Web services are consulted (click here to read more about GPS Visualizer's data sources). But sometimes, it's still not right. When that happens, you may have to enter the coordinates into your file by hand; there is an entire section in the Address Tutorial on how to do that.

8: Adding URLs to waypoints

Further documentation coming soon. Suffice it to say that if your input data includes a "url" field, the point's info window will contain a link to that URL. (For SVG maps, the marker itself becomes a link.)

9: Adding thumbnails and photos to waypoints

More information will be coming soon, but you can see an example here. Suffice to say that in Google Maps and Google Earth, you can do a lot with fields in your input file named "thumbnail", "photo", and (optionally) "thumbnail_width".

10: Summary

Here's a list of the fields that are important in terms of how GPS Visualizer handles your waypoints. Alternate names are separated by slashes; for example, you can specify latitude with "lat" or "latitude."

name self-explanatory

desc/description can contain almost anything, especially if your goal is Google Maps or Google Earth files

latitude/lat ideally should be decimal degrees, but degrees-minutes-seconds format also works as long as the parts are separated; UTM doesn't work at all

longitude/lon/long see note under "latitude"

time/date try to use a non-ambiguous time format, like yyyy-mm-dd hh:mm:ss; if you submit "04/05/06," the computer doesn't know what that means

alt/altitude/elevation will be interpreted as meters unless "(ft.)" or "(feet)" is included in the field name

speed/velocity will be interpreted as km/h unless "(mph)" or "(m/s)" is included in the field name

airport 3- or 4-letter airport code; used in place of latitude & longitude

color named HTML color or hex value

sym/symbol/icon/style Google Maps or Google Earth only; see "Adding symbols" above

icon_size Google Maps only; the size in pixels of a custom (remote) icon in "width,height" format; this will speed up processing of your map because GPS Visualizer doesn't have to go out and "inspect" the icon graphic.

radius in pixels

scale a ratio (0.5 = half-size, 2.0 = double-sized)

opacity from 0 to 1

rotation degrees clockwise (same units as a "heading" would be); only used in Google Earth

hotspot two numbers joined by a comma (x & y; y=0 is the bottom of the icon); used for custom placemark icons, and only in Google Earth

url turns your waypoint into a link; see #8 above

label Google Maps only; puts a "permanent" label on the map rather than just a tooltip.

shortdesc Google Maps with marker lists only; if you have your map generate a marker list that includes descriptions, the "shortdesc", if it exists, will be used in place of the normal "desc" in the list.

thumbnail the URL of a graphic; in Google Maps, it becomes part of the mouse-over; in Google Earth, it becomes the icon for that point (see #9 above)

thumbnail_width Google Maps only: sets the displayed width, in pixels, of the thumbnail graphic specified in the "thumbnail" field

photo the URL of a larger photo; in Google Maps & Google Earth, it becomes part of the description of the point

photo_width Google Maps only: sets the displayed width in the info window, in pixels, of the image specified in the "photo" field

address, city, state, country/nation used in place of latitude & longitude

zip/zipcode/postcode used in place of latitude & longitude

folder Google Maps (with a "marker list") & Google Earth only; you can create collapsible/hideable sub-folders of waypoints and/or tracks if you provide the name of a folder.

gv_track_number Google Maps only; you can make a waypoint "belong" to a track so that when the track is hidden, the waypoint goes with it.

gv_marker_options

Google Maps only; very dangerous! If you want to set extra options for markers on Google Maps, you can include them here -- but if you get the syntax wrong, your entire map could fail to display.

variable	example	description
dd	dd:true	Adds or suppresses a "driving directions" form in the marker's info window; overrides the global "dd" option. (Note that with true/false options, you must NOT include quotes!)
dd_lon & dd_lat	dd_lat:45.6789, dd_lon:-123.4567	Sometimes, you want the driving directions for a point to end up at a slightly different location than the point itself; use dd_lat and dd_lon to supply coordinates for the driving directions form. Both coordinates must be present to have any effect.
icon_anchor	icon_anchor:[7,15]	Relative X and Y coordinates of the "anchor" of the marker's icon. Numbers increase rightward and downward.
label_offset	label_offset:[3,-2]	Relative offset, in X and Y pixels of a marker's "permanent" label. Numbers increase rightward and downward; overrides the global "label_offset" option. Frankly, it's probably better to edited this manually after the map is created.
window_width	window_width:250	Width, in pixels, of the info window that pops up when you click a point; overrides the global "info_widow_width" option.
zoom_level	zoom_level:15	Sets the zoom level for this marker when its name or icon is clicked in the marker list; only has an effect if a marker list exists and if gv_options['marker_list_options']['zoom'] is set to true. Overrides the global zoom_level setting in marker_list_options.
nolist	nolist:true	If you want to exclude a marker from an auto-generated marker list, use nolist:true. (nolist:false has no effect on anything).
[others]		Some fields that can be included as separate columns in your input data can also be included as part of gv_marker_options, which may be easier if there are only a handful of points that need special treatment. For example: label, shortdesc, thumbnail, photo, thumbnail_width, icon_size, scale.