<html>
<head>
<title>GPX - GPS Exchange Format</title>
</head>
<body bgcolor="#ffffff">
<h1>GPX - GPS Exchange Format</h1>
(Starting with GDAL 1.5.0)<p>
GPX (the GPS Exchange Format) is a light-weight XML data format for the interchange of GPS data (waypoints, routes, and tracks) between applications and Web services on the Internet.<p>
OGR has support for GPX reading (if GDAL is build with <i>expat</i> library support) and writing.<p>
Version supported are GPX 1.0 and 1.1 for reading, GPX 1.1 for writing.<p>
The OGR driver supports reading and writing of all the GPX feature types :
<ul>
<li><i>waypoints</i> : layer of features of OGR type wkbPoint</li>
<li><i>routes</i> : layer of features of OGR type wkbLineString</li>
<li><i>tracks</i> : layer of features of OGR type wkbMultiLineString</li>
</ul>
It also supports reading of route points and track points in standalone layers (<i>route_points</i> and <i>track_points</i>), so
that their own attributes can be used by OGR.<p>
In addition to its GPX attributes, each route point of a route has a <i>route_fid</i>
(foreign key to the FID of its belonging route)
and a <i>route_point_id</i> which is its sequence number in the route.<br>
The same applies for track points with <i>track_fid</i>, <i>track_seg_id</i> and <i>track_seg_point_id</i>.
All coordinates are relative to the WGS84 datum (EPSG:4326).<p>
If the environment variable GPX_ELE_AS_25D is set to YES, the elevation element will
be used to set the Z coordinates of waypoints, route points and track points.<p>
The OGR/GPX reads and writes the GPX attributes for the waypoints, routes and tracks.<p>
By default, up to 2 <i><link></i> elements can be taken into account by feature.
This default number can be changed with the GPX_N_MAX_LINKS environment variable.<p>
<h2>Encoding issues</h2>
Expat library supports the following built-in encodings :
<ul>
<li>US-ASCII</li>
<li>UTF-8</li>
<li>UTF-16</li>
<li>ISO-8859-1</li>
</ul>
If your GPX file is not encoded in one of the previous encodings, it will not be parsed by the
GPX driver. You may convert it into one of the supported encoding with the <i>iconv</i> utility
for example and change accordingly the <i>encoding</i> parameter value in the XML header.<br>
Note : Windows-1252 differs only on a small range of characters with ISO-8859-1.
Patching the <i>encoding</i> parameter value to ISO-8859-1 may be enough to make it work...<p>
<h2>Extensions element reading</h2>
If the <i><extensions></i> element is detected in a GPX file, OGR will expose the content
of its sub elements as fields. Complex content of sub elements will be exposed as an XML blob.
<p>
The following sequence GPX content :
<pre>
<extensions>
<navaid:name>TOTAL RF</navaid:name>
<navaid:address>BENSALEM</navaid:address>
<navaid:state>PA</navaid:state>
<navaid:country>US</navaid:country>
<navaid:frequencies>
<navaid:frequency type="CTAF" frequency="122.900" name="CTAF"/>
</navaid:frequencies>
<navaid:runways>
<navaid:runway designation="H1" length="80" width="80" surface="ASPH-G">
</navaid:runway>
</navaid:runways>
<navaid:magvar>12</navaid:magvar>
</extensions>
</pre>
will be interpreted in the OGR SF model as :
<pre>
navaid_name (String) = TOTAL RF
navaid_address (String) = BENSALEM
navaid_state (String) = PA
navaid_country (String) = US
navaid_frequencies (String) = <navaid:frequency type="CTAF" frequency="122.900" name="CTAF" ></navaid:frequency>
navaid_runways (String) = <navaid:runway designation="H1" length="80" width="80" surface="ASPH-G" ></navaid:runway>
navaid_magvar (Integer) = 12
</pre>
<p><br>
Note : the GPX driver will output content of the extensions element only if it is found in the first records of the GPX file.
If extensions appear later, you can force an explicit parsing of the whole file with the <b>GPX_USE_EXTENSIONS</b> environment variable.
<p>
<h2>Creation Issues</h2>
On export all layers are written to a single GPX file. Update of existing
files is not currently supported.<p>
If the output file already exits, the writing will not occur. You have to delete the existing file first.<p>
Supported geometries :
<ul>
<li>Features of type wkbPoint/wkbPoint25D are written in the <i>wpt</i> element.</li>
<li>Features of type wkbLineString/wkbLineString25D are written in the <i>rte</i> element.</li>
<li>Features of type wkbMultiLineString/wkbMultiLineString25D are written in the <i>trk</i> element.</li>
<li>Other type of geometries are not supported.</li>
</ul>
<p>
For route points and tracks points, if there is a Z coordinate, it is used to fill the elevation element
of the corresponding points.<p>
The GPX writer supports the following <i>layer</i> creation options:
<ul>
<li> <b>FORCE_GPX_TRACK</b>:
By default when writting a layer whose features are of type wkbLineString, the GPX driver
chooses to write them as routes.
<br>If FORCE_GPX_TRACK=YES is specified, they will be written
as tracks.</li><p>
<li> <b>FORCE_GPX_ROUTE</b>:
By default when writting a layer whose features are of type wkbMultiLineString, the GPX driver
chooses to write them as tracks.
<br>If FORCE_GPX_ROUTE=YES is specified, they will be written
as routes, provided that the multilines are composed of only one single line.</li><p>
</ul>
<p>
The GPX writer supports the following <i>dataset</i> creation options:
<ul>
<li> <b>GPX_USE_EXTENSIONS</b>:
By default, the GPX driver will discard attribute fields that do not match the GPX XML definition (name, cmt, etc...).<br>
If GPX_USE_EXTENSIONS=YES is specified, extra fields will be written inside the<i><extensions></i> tag.</li><p>
<li> <b>GPX_EXTENSIONS_NS</b>:
Only used if GPX_USE_EXTENSIONS=YES and GPX_EXTENSIONS_NS_URL is set.<br>
The namespace value used for extension tags. By default, "ogr".</li><p>
<li> <b>GPX_EXTENSIONS_NS_URL</b>:
Only used if GPX_USE_EXTENSIONS=YES and GPX_EXTENSIONS_NS is set.<br>
The namespace URI. By default, "http://osgeo.org/gdal".</li><p>
</ul>
<p>
Waypoints, routes and tracks must be written into that order to be valid against the XML Schema.
<p>
When translating from a source dataset, it may be necessary to rename the field names from the source dataset to the expected GPX attribute names, such as <name>, <desc>, etc...
This can be done with a <a href="drv_vrt.html">OGR VRT</a> dataset, or by using the "-sql" option of the ogr2ogr utility.
</li>
<h2>Issues when translating to Shapefile</h2>
When translating the <i>track_points</i> layer to a Shapefile, the field names "track_seg_id" and "track_seg_point_id" are
truncated to 10 characters in the .DBF file, thus leading to duplicate names. To avoid this, starting with GDAL 1.6.1,
you can define the GPX_SHORT_NAMES configuration option to TRUE to make them be reported respectively as "trksegid" and "trksegptid",
which will allow them to be unique once translated to DBF. The "route_point_id" field of <i>route_points</i> layer will also be renamed to "rteptid".
But note that no particular processing will be done for any extension field names.<p>
To translate a GPX file to a set of shapefiles :
<pre>
ogr2ogr --config GPX_SHORT_NAMES YES out input.gpx
</pre>
<h2>Example</h2>
<li>The ogrinfo utility can be used to dump the content of a GPX datafile :
<pre>
ogrinfo -ro -al input.gpx
</pre>
</li>
<p><br>
<li>The ogr2ogr utility can be used to do GPX to GPX translation :
<pre>
ogr2ogr -f GPX output.gpx input.gpx waypoints routes tracks
</pre>
<br>
Note : in the case of GPX to GPX translation, you need to specify the layer names,
in order to discard the route_points and track_points layers.
</li>
<p><br>
<li>Use of the <i><extensions></i> tag for output :
<pre>
ogr2ogr -f GPX -dsco GPX_USE_EXTENSIONS=YES output.gpx input
</pre>
which will give an output like the following one :
<pre>
<?xml version="1.0"?>
<gpx version="1.1" creator="GDAL 1.5dev"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ogr="http://osgeo.org/gdal"
xmlns="http://www.topografix.com/GPX/1/1"
xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
<wpt lat="1" lon="2">
<extensions>
<ogr:Primary_ID>PID5</ogr:Primary_ID>
<ogr:Secondary_ID>SID5</ogr:Secondary_ID>
</extensions>
</wpt>
<wpt lat="3" lon="4">
<extensions>
<ogr:Primary_ID>PID4</ogr:Primary_ID>
<ogr:Secondary_ID>SID4</ogr:Secondary_ID>
</extensions>
</wpt>
</gpx>
</pre>
</li>
<li>Use of -sql option to remap field names to the ones allowed by the GPX schema !
<pre>
ogr2ogr -f GPX output.gpx input.shp -sql "SELECT field1 AS name, field2 AS desc FROM source_layer"
</pre>
</li>
<h2>See Also</h2>
<ul>
<li> <a href="http://www.topografix.com/gpx.asp">Home page for GPX format</a><p>
<li> <a href="http://www.topografix.com/GPX/1/1/">GPX 1.1 format documentation</a><p>
</ul>
</body>
</html>
