Table of Contents
Gpx2Map is a tool for converting GPX eXchange (GPX) format XML documents into two dimensional maps that show the GPX file's way-points, tracks and routes.
Gpx2Map was designed to be extensible. Map data is downloaded from a map source and new map sources can be added to the program either as part of the Gpx2Map distribution, or as dynamically loaded extensions.
At present, Gpx2Map comes with one map source that downloads data from TerraServer USA. TerraServer USA provides various types of USGS. The map data is freely redistributable and comes in various styles and resolutions.
Gpx2Map is distributed under the GNU Public License. Please see the file LICENSE contained in either the source or binary distributions for details on the terms of this license.
Gpx2Map can be downloaded from SourceForge.net.
Note: You need not download the "argslib" package. That library is included in both the source and binary releases of Gpx2Map.
Gpx2Map requires that you've previously installed a Java Virtual Machine, compatible with Sun's Java 2 Runtime Environment, version 1.5 or newer. Gpx2Map has be tested against Sun's Java 2 Runtime Environment, version 1.5.0_03.
To install Gpx2Map under Windows:
Download the ZIP archive (.zip) version of Gpx2Map.
Select a location for the program on your hard drive and extract the contents of the archive there. Under the latest versions of Windows you can simply double-click the archive's icon and then drag the enclosed folder to the destination you've selected.
To install Gpx2Map under Linux or another unix-like operating system:
Download the tarball (.tar.gz) version of Gpx2Map.
Select a location for the program on your file system and copy/move the tarball there.
In the directory where the tarball is located, execute: tar xvf gpx2map-1.0.2.tar.gz
GUI: To start the Gpx2Map graphical user interface, open the folder where Gpx2Map is stored. Under the bin directory, double-click the Gpx2Map GUI icon.
CLI: To start the Gpx2Map command line interface, open a command prompt in the folder where Gpx2Map is stored. Change to the bin directory and run Gpx2Map.exe. See the command line interface documentation for details on the necessary command line switches.
Both the GUI and CLI versions of Gpx2Map are executed via the same shell script under Linux and other unix-like operating systems. Simply run the gpx2map shell script from the Gpx2Map bin directory. With no command line arguments, or with only the --locale argument, the GUI will be started. For a list of all command line switches, see the command line interface section of the manual.
The Gpx2Map graphical user interface is divided into several tabs. These are:
General - basic parameters that must be given for the generation of any new map.
Map Source - allows the selection of a map source and configuration of parameter specific to that source. Also allows you to configure the directory used to cache map source data.
Formatting - allows you to configure how the map is formatted, including the map boundaries, margin and fonts used.
Markers & Lines - allows you to choose what style of markers are used for way-points, tracks and routes as well as what color is used to render those items.
Along the bottom of the user interface are several buttons:
The ? (question mark) button displays information about Gpx2Map.
The Save Settings button causes all of the user interfaces settings to be stored. These settings are loaded whenever Gpx2Map is started. Note, that even the GPX file name is stored, so if you click Save Settings after generating a map you'll be storing the source GPX filename as well as the output map filename along with all the other settings.
The Execute button generates a map with the given settings. If required information (such as the source GPX filename) is missing an error message will be displayed.
The general tab has general options that must be set before any image can be generated. Specifically these are the source GPX filename and the output image filename.
You may select which types of GPS data are used from the GPX file. Gpx2Map will prevent you from ignoring all three types of data.
The map source tab allows you to configure which map source to use. In Gpx2Map 1.0, only one map source is packaged with the application: the TerraServer USA map source. It is, however, possible to write a custom map source.
Each map source has an optional set of parameters. These are displayed below the map source list box. See the description of the map source for an explanation of its parameters.
The cache directory is not map source-specific. Gpx2Map will create a subdirectory under the given cache directory for each map source that you use.
The TerraServer USA map source retrieves map tiles from TerraServer USA. The TerraServer USA web site supports three different map types in various resolutions from 0.25 to 512 meters per pixel (mpp):
USGS Digital Orthophoto Quadrangles (Type 1)
Type 1 maps are aerial photographs and support resolutions from 1 to 512 mpp.
USGS Digital Raster Graphics (Type 2)
Type 2 maps are scanned topographic maps and support resolutions from 2 to 512 mpp.
USGS Urban Area (Type 4)
Type 4 maps are high-resolution natural color maps that support resolutions from 0.25 to 512 mpp. Type 4 maps, however, are only available for urban areas.
TerraServer USA maps are available in the following resolutions (based on map type):
Table 3.1. TerraServer USA Map Resolutions
| Type 1 (Aerial) | Type 2 (Topo) | Type 4 (Urban) | Resolution (Meters Per Pixel) |
|---|---|---|---|
| X | 0.25 | ||
| X | 0.5 | ||
| X | X | 1 | |
| X | X | X | 2 |
| X | X | X | 4 |
| X | X | X | 8 |
| X | X | X | 16 |
| X | X | X | 32 |
| X | X | X | 64 |
| X | X | X | 128 |
| X | X | X | 256 |
| X | X | X | 512 |
The formatting tab controls the basic format of the map, including margins, map boundaries, and the font used to display way-point, route and track labels.
Map boundaries may be determined by tracks, routes, way-points, all GPS data or fixed latitude/longitude coordinates. For the first four selections, a bounding box that encompasses the select type of data is computed and used to determine the map boundaries. This means that, for example, if tracks are selected, it is guaranteed that all tracks described in the GPX file will be visible on the output image, but some routes or way-points may be off the map. If coordinates are selected, it is possible that none of the data in the GPX file will be visible on the map.
Latitude and longitude coordinates are entered as decimal degrees north of the equator and east of the prime meridian.
Note that if your GPX file does not contain, for instance, way-points, you may not use way-points to determine the boundaries of your map image. The same is true if the file contains way-points, but you've chosen to ignore them via the General tab.
Once the map's boundaries are determine, the map margin is applied to increase the size of the map. Margins may be specified in either meters or pixels. A margin of 0 meters (or pixels) would cause each point's marker to be cut in half. Unfortunately, margins in Gpx2Map 1.0 are not terribly precise. If you require precision, specify a larger-than-desired value for the margin and use an image editor to crop the image as necessary.
The markers & lines tab controls the rendering of way-, track- and route-point markers and lines. Markers for each type of point may be selected individually.
Samples of each marker style are sown below.
Tracks and routes may optionally be labeled with their name, which is obtained from the GPX file. Way-points are always labeled.
The GPX file format allows a single track to be divided into multiple segments. The Join Track Segments option causes a line to be drawn from the end of each segment in a track to the beginning of the next segment.
Table 3.2. Sample Markers
| Marker Type | Sample Figure |
|---|---|
| Box | Figure 3.5, “Box Marker Sample” |
| Diamond | Figure 3.6, “Diamond Marker Sample” |
| Dot | Figure 3.7, “Dot Marker Sample” |
| Plus | Figure 3.8, “Plus Marker Sample” |
| Triangle | Figure 3.9, “Triangle Marker Sample” |
| X | Figure 3.10, “X Marker Sample” |
| File | Figure 3.11, “File Marker Sample” |
Figure 3.11. File Marker Sample
This sample was created using a GIF file with transparency. Note that the marker color does not alter the image's contents, but that it is used to draw track lines. Gpx2Map overlays the image on the line.
When starting the Gpx2Map GUI, you can control the locale that Gpx2Map uses with the --locale switch.
gpx2map [--locale=<lang[_COUNTRY]>]
The locale is specified using a simple syntax: the two-letter language code in lowercase, optionally followed by the two-letter country code in uppercase. For example, en_US specifies the U.S. English locale, de_DE specifies the German language locale as used in Germany, and de_CH specifies the German language locale as used in Switzerland. In Gpx2Map 1.0, the only available locale is U.S. English.
The following options configure Gpx2Map in
gpx2map --gpsdata=<file>[,<file>...] [--map-source=<source-name>]
[--output=<file>] [--cache-dir=<dir>] [--ignore-waypoints]
[--ignore-tracks] [--ignore-routes]
[--bounding=<track|route|waypoints|all|rect:NWLT,NWLN,SELT,SELN>]
[--margin=<N>[m|p]] [--track-color=<color>]
[--track-label=<true|false>] [--trackpoint-style=<style-name>]
[--trackpoint-radius=<N>] [--join-track-segments=<true|false>]
[--waypoint-color=<color>] [--waypoint-style=<style-name>]
[--waypoint-radius=<N>] [--route-color=<color>]
[--route-label=<true|false>] [--routepoint-style=<style-name>]
[--routepoint-radius=<N>] [--font-name=<font-name>]
[--font-name=<font-name>] [--help]
gpx2map --print-colors [--help]
gpx2map --print-styles [--help]
The --gpsdata , --print-colors , and --print-styles arguments select what action Gpx2Map will take. The --print-colors prints a complete list of known colors that may be used with the --track-color , --route-color , and --waypoint-color switches. The --print-styles argument prints a complete list of marker styles that may be used with the --trackpoint-style , --routepoint-style , and --waypoint-style switches. The --gpsdata argument causes Gpx2Map to generate a map image based on the given GPX data file(s).
- --bounding<track|route|waypoints|all|rect:NWLT,NWLN,SELT,SELN>
Sets mechanism used to determine the map's boundaries: GPS tracks, GPS routes, GPS way-points, all GPS entities, or fixed border coordinates.
Possible choices (default is all):
track[s]
waypoints[s]
route[s]
all
rect:NWLat,NWLon,SELat,SELon , where NWLat, NWLon, SELat, and SELon are the map boundary's northwest latitude/longitude and southeast latitude/longitude.
- --cache-dir=<dir>
Sets the map tile cache directory. Defaults to a .cache directory in Gpx2Map's install directory.
- --font-name=<font-name>
Set font for rendering way-, track-, and route-point labels.
- --font-size=<font-size>
Set font size of way-, track-, and route-point labels. Defaults to 30.
- --gpsdata=<file>[,<file>...]
Loads GPX data from one or more files and plots it on a map. Requires the --map-source switch.
- --help
Prints all Gpx2Map arguments. The list includes with map source-specific options, if a map source is specified via the --map-source switch.
- --ignore-routes
Ignore route data in the give GPX file(s).
- --ignore-tracks
Ignore track data in the give GPX file(s).
- --ignore-waypoints
Ignore way-point data in the give GPX file(s).
- --join-track-segments=<true|false>
Causes track segments, within a single track, to be joined by a line. Enabled by default.
- --map-source=<source-name>
Configures the map source plug-in. Defaults to terraserver_usa, the only option shipped with Gpx2Map 1.0.
- --margin=<N>[m|p]
Sets the distance from the map boundary to the edge of the map to N meters (m) or pixels (p).
- --output=<file>
Sets the output PPM file name. Defaults to map.ppm.
- --print-colors
Prints a list of colors that may be used with the --track-color , --route-color , and --waypoint-color switches.
- --print-styles
Prints a list of marker styles that may be used with the --trackpoint-style , --routepoint-style , and --waypoint-style switches.
- --route-color=<color>
Select color for route-points and lines. Choices include crayon, HTML, X11, and Netpbm colors. You may also specify RGB hex triplets in HTML format(e.g., #rrggbb). Use --print-colors to generate a list of all available named colors.
- --route-label=<true|false>
Label routes with track name. Disabled by default.
- --routepoint-radius=<N>
Sets the radius of route-point markers, in pixels. The file marker style ignores this parameter. Requires the use of --routepoint-style . Defaults to 5 pixels.
- --routepoint-style=<style-name>
Selects the style of route-point markers.
Possible choices (default is box):
box
dot
diamond
x
triangle
plus
file:<filename>, where <filename> is the name of a GIF, JPEG or NetPBM image to use as a marker.
- --track-color=<color>
Select color for track-points and lines. Choices include crayon, HTML, X11, and Netpbm colors. You may also specify RGB hex triplets in HTML format(e.g., #rrggbb). Use --print-colors to generate a list of all available named colors.
- --track-label=<true|false>
Labels tracks with track name. Disabled by default.
- --trackpoint-radius=<N>
Sets the radius of track-point markers, in pixels. The file marker style ignores this parameter. Requires the use of --trackpoint-style . Defaults to 5 pixels.
- --trackpoint-style=<style-name>
Selects the style of track-point markers. See the --routepoint-style for a list of available choices.
- --waypoint-color=<color>
Select color for way-points. Choices include crayon, HTML, X11, and Netpbm colors. You may also specify RGB hex triplets in HTML format(e.g., #rrggbb). Use --print-colors to generate a list of all available named colors.
- --waypoint-radius=<N>
Sets the radius of way-point markers, in pixels. The file marker style ignores this parameter. Requires the use of --waypoint-style . Defaults to 5 pixels.
- --waypoint-style=<style-name>
Selects the style of way-point markers. See the --routepoint-style for a list of available choices.
Gpx2Map can be extended to provide additional map sources. Additional map sources may be contributed back to the Gpx2Map project or may be kept separate.
The following list enumerates the basic steps involved in adding a new map source to Gpx2Map. Unless otherwise specified all classes are from the us.zuercher.gpx2map.source package. Note that some restrictions on implementing new map sources are detailed only in the JavaDoc reference.
Set up a Gpx2Map build environment and build Gpx2Map. See the BUILDING file in the source release.
Choose a package name for your map source. Map sources that will be contributed to Gpx2Map should be placed in a new package within us.zuercher.gpx2map.source. Map sources that will remain external to Gpx2Map may be in any package.
Create a class that implements MapSource. You may find it helpful to to extend either AbstractTiledUrlMapSource or AbstractedCachedMapSource. In addition, the JavaDownloader and JavaConverter classes may be useful for downloading map tiles and converting them to NetPBM format. See also us.zuercher.gpx2map.image and its child packages.
Your MapSource implementation may specify its configurable properties by return a list of MapSourcePropertyChoice. These properties will automatically become command line parameters and GUI options without any further work on your part.
Create a subclass of SourceFactory named Factory in your package. Gpx2Map will use this factory class to instantiate instances of your map source. It finds the factory class by reflection, so the factory's name must be Factory.
Implement the abstract method newMapSource() to instantiate a new instance of your MapSource.
Implement the abstract method getMapSourceDescriptor() to return a description of your MapSource.
During development, you can add your new map source package to the class path, and then add a Java system property -Dus.zuercher.gpx2map.source=package.name to your JVM arguments. Gpx2Map will automatically add your map source to the list of available map sources.
If you're contributing a new map source to Gpx2Map, you can test how things will appear by adding your map source to the list of built-in map sources contained in the method SourceFactory.generateBuiltInSources().
The Gpx2Map project welcomes externally authored map sources! Please let us know, via SourceForge's feature/bug tracking system if you're developing a new map source. If you need assistance, that's also the place to ask. Since Gpx2Map is a young project, it is not at all out of the question to refactor the map source API to make new map sources easier to implement.
Submitted map sources should be compatible with Gpx2Map's licensing: the Gnu Public License.
Also, please be sure that the map data is free for use by Gpx2Map end users and that there is at least a reasonable chance that the map data providers won't mind if they aren't already providing the map data as a service unto itself.